Skip to main content

Create or update items

PUT /v1/items/{id}

Creates or updates a menu item in the FoodStorm OMS. You must include all item properties and values in the request. After you use this endpoint to create or update an item, all future updates to that item must be done by using this API; you can't use the FoodStorm user interface to update the item.

warning

When updating an existing item, specify all properties. An unspecified property is interpreted as having an empty value and any pre-existing value for that property is deleted.

For more information and best practices about items, see Items.

Security​

NameInDescription
AuthorizationheaderStandard Authorization header using the Bearer scheme. Example: "bearer {token}"

Parameters​

NameInTypeRequiredDescription
idpathstringRequired

A unique identifier for this menu item, defined by the retailer.

Request​

FieldTypeRequiredDescription
namestringRequired

The name of the item, as displayed on the storefront. Must be unique.

codestringOptional

The code for this item. The code can be the same as or different from the item_id. The code can be used for barcode scanning.

descriptionstringOptional

Description of the item in Markdown format. HTML is not supported.

categorystringRequired

The storefront category to display this item in. The value must match the name of an existing category in FoodStorm, e.g. Turkeys.

alias_categoriesArray(string)Optional

Optionally display this item in other categories in the storefront.

departmentstringRequired

The department of the item within the site (e.g. Deli). The value must match the name of an existing department in FoodStorm.

visibilitystringRequired

Default visibility of the item, but can be overridden at the site level. One of "VisibleShoppingCart" (visible within the OMS and on the storefront), "Visible" (visible within the OMS only), or "Hidden" (hidden for the OMS and the storefront).

unit_typestringRequired

The unit type of the item, such as “each”, “oz”, or “lb”. When weight.type is "Open" or "Approx", the unit type must be a valid weight type (e.g. “lb”).

min_unitsnumberOptional

Minimum units when ordered. When weight.type is "Approx", this field is not supported.

max_unitsnumberOptional

Maximum units when ordered. When weight.type is "Approx", this field is not supported.

alcoholbooleanRequired

When the item is alcoholic, set to true. Default is false.

imagesArray(string)Required

Array of URLs to publicly accessible images. Provide the highest resolution available. FoodStorm will autoscale the images for web display.

tagsArray(string)Optional

Array of dietary tag strings. For the list of valid values, see the "Tags values" table at the end of this section.

ingredientsstringOptional

List of ingredients in Markdown format. HTML is not supported.

warningsstringOptional

List of warnings for the item in Markdown format. HTML is not supported.

cut_offHashRequired

The cutoff time details.

availabilityHashOptional

The availability details for the item.

weightHashRequired

The weight details for the item.

selectionsHashOptional

The selections details for the item.

Cut_Off Object​

FieldTypeRequiredDescription
typestringRequired

One of "Default" (the system default cutoff), "FixedTime" (a fixed time of day cutoff), or "Rolling" (cut off based on a rolling lead time in minutes).

timestringOptional

When cut_off.type = "FixedTime", the cut-off time at the site. Format is HH:mm.

days_beforeintegerOptional

When cut_off.type = "FixedTime", the lead time in days.

minutesintegerOptional

When cut_off.type = "Rolling", the lead time in minutes.

Availability Object​

FieldTypeRequiredDescription
days_of_weekArray(integer)Optional

Array of days when the item can be ordered. Integer values are: 0 (Sunday), 1 (Monday), 2 (Tuesday), and so on. By default, the item can be ordered on any day.

from_timestringOptional

Restrict ordering before the specified time of day. Format is HH:mm. By default, the item can be ordered whenever the site opens.

to_timestringOptional

Restrict ordering after the specified time of day. Format is HH:mm. By default, the item can be ordered until the site closes.

date_range_typestringOptional

One of "Available" (the item is available during this date range) or "Unavailable" (the item is not available during this date range). Note: To enable quantity limits to be applied, set to "Available" and set the availability dates.

from_datestringOptional

The available/unavailable from date. This is a calendar date in the site's time zone, not UTC.

to_datestringOptional

The available/unavailable to date. This is a calendar date in the site's time zone, not UTC.

Weight Object​

FieldTypeRequiredDescription
typestringRequired

One of "Fixed" (for items sold by unit/each), "Open" (for open weighted items, e.g. deli meats), or "Approx" (for items with an approx weight, e.g. turkeys).

approxnumberOptional

Required when weight.type is "Approx". The approximate weight.

approx_tonumberOptional

Optional when weight.type is "Approx". The upper approximate weight range.

Selections Object​

FieldTypeRequiredDescription
templatestringOptional

The selection template to use. The value must match the name of an existing selection template in FoodStorm.

selectionsArray(Selection)Optional

When a selection template is not in use, specify the available selections for this item.

Selection Object​

FieldTypeRequiredDescription
namestringRequired

The name of the selection. Letters and numbers only. Special characters are not supported, including colons (:) and ampersands (&).

typestringRequired

One of "SingleSelection" (the user must select a single option) or "MultipleSelection" (the user can select multiple options).

descriptionstringOptional

Descriptive text for the selection. The text is displayed on the storefront.

max_selectionsintegerOptional

When type = "MultipleSelection", an optional limit on the maximum number of options that can be selected. Omit value for no maximum.

optionsArray(Option)Optional

The options that can be selected.

Option Object​

FieldTypeRequiredDescription
namestringRequired

The name of the option.

imagestringOptional

An image for the option. Provide the highest resolution available. FoodStorm will autoscale the images for web display.

surchargenumberOptional

The surcharge for this option. By default, there is no surcharge.

defaultbooleanRequired

Set to true to have this option selected by default.

upsellbooleanOptional

Set to true to have this item displayed as an upsell option in the FoodStorm UI.

tags values​

TagDescription
celCelery
dfDairy Free
eEggs
fFish
gGluten
gfGluten Free
hHalal
kKosher
kdKosher Dairy
kmKosher Meat
kpKosher Pareve
lLupin
lgLow Gluten
low_fatLow Fat
mMilk
molMollusks
muMustard
nNuts
organicOrganic
pPeanuts
sSoy
sdSulphur Dioxide
seSesame
shShellfish
sugar_freeSugar Free
vVegetarian
vgVegan

Request Examples​

curl --request PUT \
  --url 'https://connect.instacart.com/v1/items/{id}' \
  --header 'Accept: application/json' \
  --header 'Authorization: string' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "string",
  "code": "string",
  "description": "string",
  "category": "string",
  "alias_categories": [
    "string"
  ],
  "department": "string",
  "visibility": "Visible",
  "unit_type": "string",
  "min_units": 1,
  "max_units": 1,
  "alcohol": true,
  "images": [
    "string"
  ],
  "tags": [
    "string"
  ],
  "ingredients": "string",
  "warnings": "string",
  "cut_off": {
    "type": "Default",
    "time": "23:00",
    "days_before": 1,
    "minutes": 1
  },
  "availability": {
    "days_of_week": [
      1
    ],
    "from_time": "09:00",
    "to_time": "19:00",
    "date_range_type": "Available",
    "from_date": "2023-01-01",
    "to_date": "2023-01-02"
  },
  "weight": {
    "type": "Fixed",
    "approx": 1,
    "approx_to": 1
  },
  "selections": {
    "template": "string",
    "selections": [
      {
        "name": "string",
        "type": "SingleSelection",
        "description": "string",
        "max_selections": 1,
        "options": [
          {
            "name": "string",
            "image": "string",
            "surcharge": 1,
            "default": true,
            "upsell": true
          }
        ]
      }
    ]
  }
}'

Response Examples​

200 Success

{
 // Empty
}

4XX Errors

Error responses return either a single error or multiple errors.

HTTP CodeCauseError MessageError CodeError Meta
400Item Category Not Found""""Not applicable
Last updated on