Skip to main content

Item API request overview

POST /v2/data_ingestion/catalog/item/submission

Use the Item API to specify item-level attributes for a product at a specific store location. When you update an item, most changes appear on the storefront within 90 minutes.

Creating new items​

For an item to be displayed on your storefront, the item must meet the minimum catalog requirements. When you are configuring an item to be displayed at a store for the first time, your Item API request must provide the attributes: lookup_code, available, price, cost_unit, and store_identifier.

To provide the remaining attributes to satisfy the minimum requirements, use the Product API.

Parameters​

The request body accepts the following parameters.

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.

FieldTypeRequiredDescription
lookup_codestringconditional

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_identifierstringyesThe store ID where this item is located. This value is equivalent to the location_code column in the inventory file.
retailer_reference_codestringconditionalAn 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.
alcoholicbooleannoWhether the item contains alcohol.
availablebooleannoWhether the item is available for purchase. Required when creating a new item.
available_for_cartbooleanconditionalWhether the item can be purchased using a Caper Cart. Required for Caper.
baked_good_baggablebooleannoWhether 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_handintegernoThe number of this item in this store.
blackout_timesJSONnoBlackout period data for this item. Used to control when an item is unavailable. For more information, see Blackout period specifications.
cancel_lead_timeintegernoThe lead time, in minutes, required before an order containing this item can be cancelled.
caper_browsablebooleannoWhether 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_versionintegernoThe catalog code set version to use when matching the submitted code to a product. If not provided, defaults to the current catalog version.
configurable_productsJSONnoVariant data for this item. For more information, see Configurable products specifications.
cost_unitstringnoIndicates how a product is sold: by unit or by weight unit (each, lb, g, kg). Required when creating a new item.
generated_atstringnoThe date and time when the data was generated, in ISO 8601 format. For example, 2025-01-15T14:30:00Z.
in_assortmentbooleannoWhether 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_pricenumberconditionalThe item's per-unit or per-weight-unit price with no markup. Required for Caper.
is_cateringbooleannoWhether an item is available as a catered item.
is_hotbooleannoWhether the item is a hot food item.
item_tax_dataJSONnoTax information for this item. For more information, see Item tax data specifications.
location_dataJSONnoStore location data for this item. For more information, see In-store product locations.
order_lead_timeintegernoThe lead time, in minutes, required to support item fulfillment.
pack_item_idstringconditionalThe 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_weightnumbernoAverage weight per unit for a loose-weight product (for example, apples) typically sold in bulk. For more information, see Additional dimensions.
pricenumbernoThe price per pound or per unit. This distinction is noted in the cost_unit field. This value is equivalent to the cost_price_per_unit column in the inventory file. If selling in the US, provide the price in USD. If selling in Canada, provide the price in CAD. Required when creating a new item.
promotionJSONnoPromotion data for this item. For more information, see Promotion specifications.
quantity_requiredbooleanconditionalWhether 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_verificationbooleannoWhether 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_ageintegernoThe minimum age required to purchase the item. Used in the management and display of age-verification workflows.
restriction_security_tagbooleannoWhether the item has a physical EAS (Electronic Article Surveillance) tag that needs to be inspected or removed at checkout.
retailer_flyer_dataJSONnoFlyer deal data for this item. For more information, see Retailer flyer data specifications.
retailer_specific_metadataJSONnoUsed to pass values through the Instacart catalog to be picked up by other services, such as OMS or Storefront Pro.
sale_end_atstringnoThe date and time when the sale price ends, in ISO 8601 format. For example, 2025-01-15T14:30:00Z.
sale_price_centsintegernoThe sale price of the item in cents. For example, 499 represents $4.99.
sale_start_atstringnoThe date and time when the sale price begins, in ISO 8601 format. For example, 2025-02-15T14:30:00Z.
sold_in_pack_onlybooleannoWhether the item is only available for purchase as part of a pack.
stock_levelstringnoThe 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)
surfacestringnoThe 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_packagingJSONnoPackaging data for this item. For more information, see Tare packaging specifications.
tare_weightnumbernoFor 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_availablebooleannoWhether the item availability on Storefront Pro is handled separately from Marketplace. Defaults to the value set for available.
usa_snap_eligiblebooleannoWhether 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
}