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.

danger

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
idpathstringRequiredA unique identifier for this menu item, defined by the retailer.

Request​

FieldTypeRequiredDescription
namestringRequiredThe name of the item, as displayed on the storefront. Must be unique.
codestringOptionalThe 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.
descriptionstringOptionalDescription of the item in Markdown format. HTML is not supported.
categorystringRequiredThe 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)OptionalOptionally display this item in other categories in the storefront.
departmentstringRequiredThe department of the item within the site (e.g. Deli). The value must match the name of an existing department in FoodStorm.
visibilitystringRequiredDefault 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_typestringRequiredThe 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_unitsnumberOptionalMinimum units when ordered. When weight.type is "Approx", this field is not supported.
max_unitsnumberOptionalMaximum units when ordered. When weight.type is "Approx", this field is not supported.
alcoholbooleanRequiredWhen the item is alcoholic, set to true. Default is false.
imagesArray(string)RequiredArray of URLs to publicly accessible images. Provide the highest resolution available. FoodStorm will autoscale the images for web display.
tagsArray(string)OptionalArray of dietary tag strings. For the list of valid values, see the "Tags values" table at the end of this section.
ingredientsstringOptionalList of ingredients in Markdown format. HTML is not supported.
warningsstringOptionalList of warnings for the item in Markdown format. HTML is not supported.
cut_offCut_OffRequiredThe cutoff time details.
availabilityAvailabilityOptionalThe availability details for the item.
weightWeightRequiredThe weight details for the item.
selectionsSelectionsOptionalThe selections details for the item.

Cut_Off Object​

FieldTypeRequiredDescription
typestringRequiredOne 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).
timestringOptionalWhen cut_off.type = "FixedTime", the cut-off time at the site. Format is HH:mm.
days_beforeintegerOptionalWhen cut_off.type = "FixedTime", the lead time in days.
minutesintegerOptionalWhen cut_off.type = "Rolling", the lead time in minutes.

Availability Object​

FieldTypeRequiredDescription
days_of_weekArray(integer)OptionalArray 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_timestringOptionalRestrict ordering before the specified time of day. Format is HH:mm. By default, the item can be ordered whenever the site opens.
to_timestringOptionalRestrict ordering after the specified time of day. Format is HH:mm. By default, the item can be ordered until the site closes.
date_range_typestringOptionalOne 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_datestringOptionalThe available/unavailable from date. This is a calendar date in the site's time zone, not UTC.
to_datestringOptionalThe available/unavailable to date. This is a calendar date in the site's time zone, not UTC.

Weight Object​

FieldTypeRequiredDescription
typestringRequiredOne 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).
approxnumberOptionalRequired when weight.type is "Approx". The approximate weight.
approx_tonumberOptionalOptional when weight.type is "Approx". The upper approximate weight range.

Selections Object​

FieldTypeRequiredDescription
templatestringOptionalThe selection template to use. The value must match the name of an existing selection template in FoodStorm.
selectionsArray(Selection)OptionalWhen a selection template is not in use, specify the available selections for this item.

Selection Object​

FieldTypeRequiredDescription
namestringRequiredThe name of the selection. Letters and numbers only. Special characters are not supported, including colons (:) and ampersands (&).
typestringRequiredOne of "SingleSelection" (the user must select a single option) or "MultipleSelection" (the user can select multiple options).
descriptionstringOptionalDescriptive text for the selection. The text is displayed on the storefront.
max_selectionsintegerOptionalWhen type = "MultipleSelection", an optional limit on the maximum number of options that can be selected. Omit value for no maximum.
optionsArray(Option)OptionalThe options that can be selected.

Option Object​

FieldTypeRequiredDescription
namestringRequiredThe name of the option.
imagestringOptionalAn image for the option. Provide the highest resolution available. FoodStorm will autoscale the images for web display.
surchargenumberOptionalThe surcharge for this option. By default, there is no surcharge.
defaultbooleanRequiredSet to true to have this option selected by default.

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
          }
        ]
      }
    ]
  }
}'

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