Item API overview

POST /v2/data_ingestion/catalog/item/submission

Use the item API to update or set the item-level attributes of a product at a specific store location. When you update an item, the change can take around two to three hours before it is displayed on the storefront.

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.
`store_identifier`	string	yes	The store ID where this item is located. This value is equivalent to the `location_code` column in the inventory file.
`retailer_reference_code`	string	conditional	An internal item code used to group a series of `lookup_codes` to a single item. For scannable barcodes, provide the code found on the product itself. Required if `lookup_code` is not provided.
`alcoholic`	boolean	no	Whether the item contains alcohol.
`available`	boolean	no	Whether the item is available for purchase.
`available_for_cart`	boolean	conditional	Whether the item can be purchased using a Caper Cart. Required for Caper.
`baked_good_baggable`	boolean	no	Whether a loose bakery item can be mixed with other bakery items in a single bag or box without needing to be weighed as an individual unit. Not intended for items that can be purchased in predefined packs, such as half-dozen donut boxes.
`balance_on_hand`	integer	no	The number of this item in this store.
`blackout_times`	JSON	no	Blackout period data for this item. Used to control when an item is unavailable. For more information, see Blackout period specifications.
`cancel_lead_time`	integer	no	The lead time, in minutes, required before an order containing this item can be cancelled.
`caper_browsable`	boolean	no	Whether the item is browsable in the Caper cart interface. Specifically, it controls whether an item appears in the produce search — unset items are not browsable even if in-stock.
`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.
`configurable_products`	JSON	no	Variant data for this item. For more information, see Configurable products specifications.
`cost_unit`	string	no	Indicates how a product is sold: by unit or by weight unit (`each`, `lb`, `g`, `kg`).
`generated_at`	string	no	The date and time when the data was generated, in ISO 8601 format. For example, `2025-01-15T14:30:00Z`.
`in_assortment`	boolean	no	Whether the item is visible on your storefront. Set to `TRUE` to show temporarily unavailable items with an out-of-stock badge. Set to `FALSE` to hide items from search results — useful for controlling the visibility of seasonal or discontinued products.
`in_store_price`	number	conditional	The item's per-unit or per-weight-unit price with no markup. Required for Caper.
`is_catering`	boolean	no	Whether an item is available as a catered item.
`is_hot`	boolean	no	Whether the item is a hot food item.
`item_tax_data`	JSON	no	Tax information for this item. For more information, see Item tax data specifications.
`location_data`	JSON	no	Store location data for this item. For more information, see In-store product locations.
`order_lead_time`	integer	no	The lead time, in minutes, required to support item fulfillment.
`pack_item_id`	string	conditional	The identifier that links this item to its parent pack configuration. Must match the `config_option_item_id` of the corresponding pack option. Used by Instacart to verify that the correct product was resolved during pack lookup. Required when `sold_in_pack_only` is `true`.
`par_weight`	number	no	Average weight per unit for a loose-weight product (for example, apples) typically sold in bulk. For more information, see Additional dimensions.
`price`	number	no	The price per pound or per unit. This distinction is noted in the `cost_unit` field. If selling in the US, provide the price in USD. If selling in Canada, provide the price in CAD.
`promotion`	JSON	no	Promotion data for this item. For more information, see Promotion specifications.
`quantity_required`	boolean	conditional	Whether a quantity must be entered when the customer is adding PLU items to the cart. This typically applies to produce items that are sold per unit. Required for Caper.
`restriction_forced_verification`	boolean	no	Whether the item causes the cart to require verification by a store associate before the customer can check out. A value of `TRUE` can be used as a virtual security tag.
`restriction_minimum_age`	integer	no	The minimum age required to purchase the item. Used in the management and display of age-verification workflows.
`restriction_security_tag`	boolean	no	Whether the item has a physical EAS (Electronic Article Surveillance) tag that needs to be inspected or removed at checkout.
`retailer_flyer_data`	JSON	no	Flyer deal data for this item. For more information, see Retailer flyer data specifications.
`retailer_specific_metadata`	JSON	no	Used to pass values through the Instacart catalog to be picked up by other services, such as OMS or Storefront Pro.
`sale_end_at`	string	no	The date and time when the sale price ends, in ISO 8601 format. For example, `2025-01-15T14:30:00Z`.
`sale_price_cents`	integer	no	The sale price of the item in cents. For example, `499` represents $4.99.
`sale_start_at`	string	no	The date and time when the sale price begins, in ISO 8601 format. For example, `2025-02-15T14:30:00Z`.
`sold_in_pack_only`	boolean	no	Whether the item is only available for purchase as part of a pack.
`stock_level`	string	no	The relative amount of the product currently in stock. The value must be one of the following: - `A` (Available) - `L` (Low stock) - `O` (Out of stock) - `N` (Not tracked)
`surface`	string	no	The Instacart platform surface on which to apply this item 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.)
`tare_packaging`	JSON	no	Packaging data for this item. For more information, see Tare packaging specifications.
`tare_weight`	number	no	For an item sold by weight, the amount to subtract from the total weight when calculating the price. This is typically the weight of a container or packaging.
`unata_available`	boolean	no	Whether the item availability on Storefront Pro is handled separately from Marketplace. Defaults to the value set for `available`.
`usa_snap_eligible`	boolean	no	Whether the item is eligible for purchase with SNAP benefits in the US.

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

Example

{
  "lookup_code": "1234567890",
  "store_identifier": "1234",
  "available": true,
  "price": 5.99
}

Attributes​

Example​

Attributes

Example