Reference

Catalog Management API Payload

Example JSON Payload

Click to expand JSON Payload Example

{
  "scope": {
    "business_ids": [
      "string"
    ]
  },
  "items": [
    {
      "merchant_supplied_item_id": "string",
      "name": "string",
      "description": "string",
      "product_traits": [
        "ALCOHOL"
      ],
      "other_identifiers": [
        {
          "identifier_type": "UPC",
          "identifier_value": "string"
        }
      ],
      "images": [
        {
          "url": "string",
          "sort_id": 0
        }
      ],
      "size": {
        "details": {
          "dimensions": {
            "length": {
              "value": 2.50,
              "unit": "inch"
            },
            "width": {
              "value": 1.25,
              "unit": "inch"
            },
            "height": {
              "value": 4.50,
              "unit": "inch"
            }
          },
          "weight": {
            "value": 1.12,
            "unit": "lbs"
          },
          "volume": {
            "value": 3.10,
            "unit": "oz"
          },
          "product_specific_size_definition": {
            "value": "string",
            "description": "string"
          }
        },
        "pack_size_details": {
          "count_per_pack": 0,
          "per_item_size_details": {
            "dimensions": {
              "length": {
                "value": 0,
                "unit": "inch"
              },
              "width": {
                "value": 0,
                "unit": "inch"
              },
              "height": {
                "value": 0,
                "unit": "inch"
              }
            },
            "weight": {
              "value": 0,
              "unit": "lbs"
            },
            "volume": {
              "value": 0,
              "unit": "oz"
            },
            "product_specific_size_definition": {
              "value": "string",
              "description": "string"
            }
          }
        }
      },
      "weighted_item_info": {
        "average_weight_per_each": 0,
        "average_weight_measurement_unit": "ea",
        "shop_by_measurement_unit": "kg",
        "price_by_measurement_unit": "kg"
      },
      "brand_info": {
        "name": "string"
      },
      "program_eligibility": [
        "SNAP"
      ],
      "item_categorizations": [
        {
          "category": {
            "name": "string",
            "sub_category": {}
          }
        }
      ],
      "product_attributes": [
        {
          "attribute_name": "string",
          "attribute_value": {
            "single_select_string": "string"
          }
        },
        {
          "attribute_name": "string",
          "attribute_value": {
            "multi_select_string": [
              "string"
            ]
          }
        },
        {
          "attribute_name": "string",
          "attribute_value": {
            "single_select_bool": true
          }
        },
        {
          "attribute_name": "string",
          "attribute_value": {
            "multi_select_bool": [
              true
            ]
          }
        }
      ]
    }
  ]
}

Overview of Parameters

The Required column indicates fields required for catalog approval. The API itself validates only scope, items, and items[].merchant_supplied_item_id — a payload missing any other field returns 202 and is ingested incomplete.

Parameter Name	Type	Description	Accepted Values	Required
merchant_supplied_item_id	string	Merchant supplied ID to identify an item uniquely within business across all stores. Every item can be shopped by customer must be represented as an unique item	-	Yes
name	string	Item name provided without any additional attributes (size, brand) OR Item name provided exactly as how it should be uploaded into catalog (including brand, size info) - in the following order: brand > item name > size.	-	Yes
description	string	Description provided in HTML or plain text	-	No
product_traits	Array of strings	Specifies the type of product(s)	"ALCOHOL," "MEDICATION," "WEIGHTED"	No
other_identifiers	Array of objects	Other identifiers associated with the item. UPC = UPC provided per SKU	-	No
images	Array of objects	Images of the item	-	Yes
size	object	Size of the item	-	No
weighted_item_info	object	Attributes related to items sold by weights	-	No
brand_info	object	Brand of the item if applicable	-	No
item_categorizations	Array of objects	SKU path received in separate fields in L1 - L5 category. Must be granular (e.g. Not 'Makeup' but instead 'Bronzer'). Not enforced by the API schema, but required for catalog approval.	-	Yes
product_attributes	Array of objects	Structured product metadata used for filtering, merchandising, and compliance (e.g. restriction_types for restricted items). attribute_value accepts one of single_select_bool, multi_select_double, or multi_select_string	See Supported Attributes	No
program_eligibility	Array of strings	Programs the item is eligible for. Values are case-sensitive and enum-closed — an unsupported or lowercase value (e.g. "snap") fails the entire request, not just the item.	"SNAP," "HSA," "FSA"	No

remarque

product_attributes names and values are not validated against the supported list at write time. An unrecognized attribute_name or an unrecognized value is silently discarded — the request still returns a 202, but the attribute never lands on the item, with no error surfaced to the caller.

Object Tables

Values for dimensions, weight, and volume must not exceed two decimal places.

Other Identifiers Object

Parameter Name	Type	Description	Accepted Values	Required
identifier_type	string	Type of identifier	"UPC," "PLU"	No
identifier_value	string	Identifier value	-	No

Images Object

Parameter Name	Type	Description	Accepted Values	Required
url	string	Item image URL in JPG or PNG format, min resolution (1400 x 800px), aspect ratio 16:9, max size 2MB. The URL must use https://, be publicly accessible, end with .jpg, .jpeg, or .png, and contain no query parameters.	-	Yes
sort_id	integer	Order in which images should be displayed	-	No

Size Object

Parameter Name	Type	Description	Accepted Values	Required
details	object	Size details of the item	-	No
pack_size_details	object	Item size details per pack	-	No

Size Details Object

Parameter Name	Type	Description	Accepted Values	Required
dimensions	object	Dimension of the product	-	No
weight	object	Weight of the product	-	No
volume	object	Volume of the product	-	No
product_specific_size_definition	object	Product-specific size definition	-	No

Dimensions Object

Parameter Name	Type	Description	Accepted Values	Required
length	object	Length of the product	-	No
width	object	Width of the product	-	No
height	object	Height of the product	-	No

Weight Object

Parameter Name	Type	Description	Accepted Values	Required
value	number	Weight value of the product	-	No
unit	string	Unit of weight (lbs, gm)	"lbs," "gm"	No

Volume Object

Parameter Name	Type	Description	Accepted Values	Required
value	number	Volume value of the product	-	No
unit	string	Unit of volume (oz)	"oz"	No

Product-Specific Size Definition Object

Parameter Name	Type	Description	Accepted Values	Required
value	string	Value of the product-specific size definition	-	No
description	string	Description of the product-specific size	-	No

Pack Size Details Object

Parameter Name	Type	Description	Accepted Values	Required
count_per_pack	number	Number of items per pack	-	No
per_item_size_details	object	Size details per item in the pack	-	No

Per Item Size Details Object

Parameter Name	Type	Description	Accepted Values	Required
dimensions	object	Dimension of the product	-	No
weight	object	Weight of the product	-	No
volume	object	Volume of the product	-	No
product_specific_size_definition	object	Product-specific size definition	-	No

Weighted Item Info Object

Required for items sold by weight. See Weighted Items for the full setup, including how each type maps to the purchase_type sent on orders.

Parameter Name	Type	Description	Accepted Values	Required
average_weight_per_each	number	Average weight per each item or pack	-	No
average_weight_measurement_unit	string	Unit of measurement (ea, kg, lb, gm, oz)	"ea", "kg," "lb," "gm," "oz"	No
shop_by_measurement_unit	string	How the item is shown to customers	"ea", "kg," "lb," "gm," "oz"	No
price_by_measurement_unit	string	The unit the item is priced by — the unit, not the price. Per-unit prices are set on the Inventory API as base_price_per_measurement_unit	"ea", "kg," "lb," "gm," "oz"	No

Brand Info Object

Parameter Name	Type	Description	Accepted Values	Required
name	string	Name of the brand	-	No

Category Object

Parameter Name	Type	Description	Accepted Values	Required
name	string	Name of the category. Required if category is present — see Item Categorizations	-	Conditional
sub_category	object	Recursive object allowing for multiple levels of category data. Supplied inside category, not alongside it — three levels are expected in most verticals and four in some	-	Conditional

Recommended for Alcohol Items

Attribute	Type	Description	Payload JSON Snippet	Required
Alcoholic item flag	array of strings	Flag alcohol items	..."product_traits": ["ALCOHOL"],...	Required
Item size and unit of measurement	string	Indicate size of item	..."size": {"details": {"product_specific_size_definition": {"value": "750","description": "ml"} } }...	Required
Container type (with pack size)	object	Indicate type of container (along with pack size)	..."product_attributes": [ { "attribute_name": "item_count", "attribute_value": { "multi_select_string": [ "6pk cans" ] } }]...	Recommended
Pack size	object	Indicate number of items in each pack as sold	..."size": {"pack_size_details": {"count_per_pack": 6} }...	Recommended
Product volume and unit of measurement (only ounces "oz" accepted)	number	Indicate overall volume sold	..."size": {"details": {"volume": {"value": 12,"unit": "oz"} } }...	Recommended
Bottle deposit fee eligible	boolean	Flag items as eligible for bottle deposit fee	..."product_attributes": [ { "attribute_name": "is_package_fee_eligible", "attribute_value": { "single_select_bool": true } }]...	Recommended
CBD flag	boolean	Flag CBD items	..."product_attributes": [ { "attribute_name": "restriction_types", "attribute_value": { "multi_select_string": ["CBD"] } }]...	Required for CBD items