Product API overview

POST /v2/data_ingestion/catalog/product/submission

Use the product API to create new and update existing products. When you create a new product, it takes 1-3 business days for the new product to be displayed in the storefront. After you update a product, it is displayed in your storefront in a few hours.

Attributes

note

The request must include at least one attribute field in addition to the identifier fields (lookup_code or retailer_reference_code), or the update fails.

Field	Type	Required	Description
lookup_code	string	conditional	The unique code that represents each of your products (such as PLU or UPC). For scannable barcodes: the code provided should be the code on the product itself. If you have a group of lookup_codes tied to a single product, add a retailer_reference_code. Include a check digit on all UPCs to ensure we have a full UPC to correlate to what we have in our system. This helps provide the most accurate information for this product. Required if retailer_reference_code is not provided.
retailer_reference_code	string	conditional	An internal item code used to identify products or to group a series of lookup_code values to the same product. Required if lookup_code is not provided.
additional_images_url	JSON	no	An array of JSON objects defining secondary product images. For more information, see Additional images specifications and Image specifications.
brand_name	string	no	The customer-facing product brand name. 100-character limit. This is a static field that is only applied when you create a product. For products shared across retailers, this brand name is provided by the brand owner. For in-house and private label products, you can update this value through Instacart Platform Portal. For national brand products, brand owners can update this value through coordination with a content service provider (CSP).
ca_prop65_text	string	no	US retailers only. Required text compliant with California law.
code_set_version	integer	no	The catalog code set version to use when matching the submitted code to a product. If not provided, defaults to the current catalog version.
department	string	no	The department in which the product is displayed.
generated_at	string	no	The date and time when the data was generated, in ISO 8601 format. For example, 2025-01-15T14:30:00Z.
item_details	string	no	Additional item details or custom content.
item_name	string	yes|no	The name of the product on the storefront. 100-character limit. Do not use abbreviations. This is a static field that is only required when creating the product for the first time. Items in Instacart’s Universal Catalog can inherit data from trusted sources, such as content service providers (CSPs) and consumer packaged goods (CPG) partners. This value is used as a method for matching PLU items to correct products and to create new products specific to a retailer.
kosher	boolean	no	Whether the product is kosher.
locale_code	string	no	The locale code for this product's content, used for localized storefronts. For example, en-CA for English (Canada) or fr-CA for French (Canada).
organic	boolean	no	Whether the product is organic.
remote_image_url	string	no	Primary image of the product. For more information, see Image specifications.
retailer_oms_eligible	boolean	no	Whether the retailer uses OMS integration.
size	string	no	The numerical amount of a unit within the pack. To define the associated unit of measure, use the size_uom field. Note: For alcoholic products and non-alcoholic beverages the size provided must be a volume measurement. For example, for a 12 fl oz soda can, enter "12".
size_uom	string	no	Unit of measure for the amount within the pack (size). Default is ‘each’. This is a static field that is only required when creating the product for the first time. Items in Instacart’s Universal Catalog can inherit data from trusted sources, such as content service providers (CSPs) and consumer packaged goods (CPG) partners. Note: For alcoholic products and non-alcoholic beverages the size provided must be a volume measurement. For example, for a 12 fl oz soda can, enter "fl oz".
sold_dimension_uom	string	no	The unit of measure for sold_height, sold_length, and sold_width. Required when any sold dimension field is provided. The value must be one of the following: meter/meters/m, centimeter/centimeters/cm, millimeter/millimeters/mm, yard/yards/yd, foot/feet/ft, inch/inches/in.
sold_height	number	no	The height of the product as sold. Requires sold_dimension_uom, sold_length, and sold_width.
sold_length	number	no	The length of the product as sold. Requires sold_dimension_uom, sold_height, and sold_width.
sold_weight	number	no	The weight of the product as sold. Requires sold_weight_uom.
sold_weight_uom	string	no	The unit of measure for sold_weight. Required when sold_weight is provided. The value must be one of the following: mg, gram/g, kilogram/kg, pound/lb/lbs, ounces/oz.
sold_width	number	no	The width of the product as sold. Requires sold_dimension_uom, sold_height, and sold_length.
surface	string	no	The Instacart platform surface on which to apply this product data. The value must be one of the following: - in_store (In-store shopping context, including Caper Cart) - marketplace (Instacart Marketplace — delivery and pickup) - storefrontpro (Storefront Pro, the white-label retailer storefront platform) - connect (Item data is used to power Connect API calls. Use this value when the item is sold through an Instacart Connect integration.)
variant	JSON object	no	A complex object that describes variations of the product. For more information, see Variant specifications.
vegan	boolean	no	Whether the product is vegan.
vegetarian	boolean	no	Whether the product is vegetarian.

Before you send your files, consider using a JSON validator.

Example

{
  "lookup_code": "1234567890",
  "retailer_reference_code": "ABC",
  "department": "catering",
  "item_name": "Cobb Salad",
  "item_details": "Chopped iceberg lettuce, crumbled bacon, black forest ham, turkey, blue cheese crumbles, chopped tomatoes, black olives and chopped egg. Served with house ranch dressing.",
  "retailer_oms_eligible": true,
  "remote_image_url": "https://your-website.com/url-link-to-cobb-salad-image.png"
}