Build a Product Catalog

To use across transfers and payment links, utilize the product API to create a product catalog. For each product, you can specify an image, title, description, and base price. You can also include additional option groups like size and color, each with their own images and price modifiers.

For example, a cafe has a product catalog with drinks on their menu. Each drink product has an option group for alternative milk choices, which adds a price modifier to the overall cost.

Create a Product

To create a new product for the catalog, pass the accountID and specify a title and base price. You can also specify a description, image, and option groups. The example below creates a lunch special with an option group that has price modifications for alternative milks. You can upload and store images with Moov.

Example Request

curl -X POST "https://api.moov.io/accounts/{accountID}/products" \
  -H "Authorization: Bearer {token}" \
  --data '{\n    "basePrice": {\n      "currency": "USD",\n      "valueDecimal": "14.95"\n    },\n    "title": "Monday lunch special 1",\n    "description": "Sandwich, chips, latte",\n    "images": [\
      {\
        "imageID": "bbdcb050-2e05-43cb-812a-e1296cd0c01a"\
      }\
    ],\n    "optionGroups": [\
      {\
        "description": "Alternative milk options",\
        "name": "Milk options",\
        "options": [\
          {\
            "description": "Fancy brand oat milk",\
            "images": [\
              {\
                "imageID": "bbdcb050-2e05-43cb-812a-e1296cd0c01a"\
              }\
            ],\
            "name": "Oat milk",\
            "priceModifier": {\
              "currency": "USD",\
              "valueDecimal": "1.00"\
            }\
          },\
          {\
            "description": "Fancy brand almond milk",\
            "images": [\
              {\
                "imageID": "bbdcb050-2e05-43cb-812a-e1296cd0c01b"\
              }\
            ],\
            "name": "Almond milk",\
            "priceModifier": {\
              "currency": "USD",\
              "valueDecimal": "1.00"\
            }\
          }\
        ]\
      }\
    ]\n  }'\

If you want to use a product you've created, you'll need to use the product API to retrieve product data and map it to lineItems when creating transfers and payment links. You may also create freeform line items during transfers or payment initiations.

Manage Products

Once a product catalog is created, you can retrieve, update, and disable products.

List Products

You can list all active products or retrieve a single active or disabled product.

Example Request to List Products

curl -X GET "https://api.moov.io/accounts/{accountID}/products" \
  -H "Authorization: Bearer {token}" \

Example Request to Retrieve a Product

curl -X GET "https://api.moov.io/accounts/{accountID}/products/{productID}" \
  -H "Authorization: Bearer {token}" \

Update a Product

Every part of a product and its options can be updated, initiating a complete replacement of the product model. While only the title and base price are required, any omitted fields will be removed from the model.

Example Request to Update a Product

curl -X PUT "https://api.moov.io/accounts/{accountID}/products/{productID}" \
  -H "Authorization: Bearer {token}" \
  --data '{\n    "basePrice": {\n      "currency": "USD",\n      "valueDecimal": "15.05"\n    },\n    "title": "Monday lunch special 1",\n    "description": "Sandwich, chips, latte",\n    "images": [\
      {\
        "imageID": "bbdcb050-2e05-43cb-812a-e1296cd0c01a"\
      }\
    ],\
    "optionGroups": [\
      {\
        "description": "Alternative milk options",\
        "name": "Milk options",\
        "options": [\
          {\
            "description": "Fancy brand soy milk",\
            "images": [\
              {\
                "imageID": "bbdcb050-2e05-43cb-812a-e1296cd0c01a"\
              }\
            ],\
            "name": "Oat milk",\
            "priceModifier": {\
              "currency": "USD",\
              "valueDecimal": "1.05"\
            }\
          },\
          {\
            "description": "Fancy brand coffee milk",\
            "images": [\
              {\
                "imageID": "bbdcb050-2e05-43cb-812a-e1296cd0c01b"\
              }\
            ],\
            "name": "Almond milk",\
            "priceModifier": {\
              "currency": "USD",\
              "valueDecimal": "1.05"\
            }\
          }\
        ]\
      }\
    ]\n  }'\

Disable a Product

A disabled product remains in the system for historical and reporting purposes. To disable a product, pass the accountID and productID.

Example Request to Disable a Product

curl -X DELETE "https://api.moov.io/accounts/{accountID}/products/{productID}" \
  -H "Authorization: Bearer {token}" \

Upload and Store Images

Use the images API to upload a PNG, JPG, or WebP image, and supply alt-text through the metadata field. Duplicate images and images larger than 16MB will be rejected. When you upload an image, you'll receive an imageID, which can be used when creating or updating a product.

Example Request to Upload an Image

curl -X POST "https://api.moov.io/accounts/{accountID}/images" \
  -H "Authorization: Bearer {token}" \
  --data '{\n    "image": "00010101011111000101010110",\n    "metadata": {\n      "altText": "Blue oat milk carton by Fancy Brand"\n    }\n  }'\

Visit the images guide for more information.