Reference

Example Payload

{
  "items": [
    {
      "merchant_supplied_item_id": "string",
      "item_availability": "ACTIVE",
      "balance_on_hand": 0,
      "last_sold_datetime": "string",
      "price_info": {
        "base_price": 0,
        "sale_price": 0,
        "tax_rate": 0,
        "bottle_fee_deposit": 0,
        "base_price_per_measurement_unit": 0
      },
      "location": {
        "aisle": "string",
        "zone": "string",
        "shelf": "string",
        "side": "string",
        "additional_details": "string",
        "coordinates": {
          "x": 0,
          "y": 0
        }
      },
      "item_special_hours": [
        {
          "day_index": "MON",
          "start_time": "string",
          "end_time": "string",
          "start_date": "string",
          "end_date": "string"
        }
      ]
    }
  ]
}

Parameter Details

Reading the Required columns. Yes means the field is required for the request to have its intended effect — not that the API rejects the request without it. Only merchant_supplied_item_id is validated: a request missing any other field passes validation and returns 200 with operation_status: QUEUED, then silently does less than you asked. Recommended means the item still works without the field, but the listing is degraded.

Parameter Name	Variable Type	Description	Possible Values	Required for POST	Required for PATCH	Required for PULL	Validation
merchant_supplied_item_id	string	The MSID used for the item in the Item Management endpoint		Yes	Yes	Yes	Must not be blank or null
item_availability	string	Item availability status	"ACTIVE" "INACTIVE"	Yes	No	Yes	Must be one of the enumerated values
balance_on_hand	integer	Current stock level for the item		Recommended	No	Recommended
last_sold_datetime	string	DateTime in ISO8601 format of when the item was last sold at the store		Recommended	No	Recommended
price_info	object	Holds different pricing parameters. Required for a POST or PULL to have its intended effect — see Pricing		Yes	No	Yes
location	object	Default location of the item in the store		No	No	No
item_special_hours	object	Special hours when the item will be available		No	No	No
program_eligibility	Array of strings	Program eligibility of the item	"SNAP," "HSA," "FSA"	No	No	No

Pricing

The price_info object defines all pricing-related attributes for a store-specific item. All price values are expressed in cents (e.g., $12.99 = 1299). For weighted items, per-unit prices are supported.

price_info and a price are key fields to ingest, and are strongly recommended on every POST and PULL. An item that is not already on the menu is not added without a price: the request returns 200, and the item never appears. Nothing in the response signals this. On a PATCH against an item that already has a price, price_info is genuinely optional.

The rule the pipeline enforces is that a price and a measurement price cannot both be missing. Either field satisfies it, so which one you send depends on the item:

• Non-weighted items — base_price, plus sale_price when the item is on promotion.
• Weighted items — base_price_per_measurement_unit, plus sale_price_per_measurement_unit when on promotion. base_price is not the field to use for these; see Weighted Items.

Validation applied after the response

The 200 acknowledges the request; the feed is validated afterwards, and a row that fails is dropped without a second response. The rules below account for the overwhelming majority of dropped rows, so check your payload against them before investigating elsewhere:

Rule	What it means
[price, measurementPrice] price and measurement price can not be missing at the same time	Send base_price or base_price_per_measurement_unit. One of the two is required; sending both is fine
[isInStock] isInStock is required	Send item_availability
[price] price unitAmount is required if price is provided	A price object must carry an amount — don't send an empty price

Parameter Name	Variable Type	Description	Possible Values	Required for POST	Required for PATCH	Required for PULL	Validation
base_price	integer	Regular price in cents for non-weighted items. For an item on promotion this is the strikethrough price. Weighted items use base_price_per_measurement_unit instead.		Yes (non-weighted)	No	Yes (non-weighted)	Integer only — a decimal such as 4.50 is rejected. Values outside 1–1000000 are accepted by the API but are not supported
sale_price	integer	The price the customer pays, in cents. Supplying sale_price without base_price is accepted.		Recommended	No	Recommended	Integer only. A value above base_price is accepted by the API but not supported
tax_rate	number	Percent tax rate applied at the item level. Send as a decimal percentage (e.g., 8 = 8%, 5.5 = 5.5%). Do not send as 0.08 or 0.055.		No	No	No	Between 0 and 25, inclusive
bottle_fee_deposit	integer	Deposit or container fee in cents (e.g., 125 = $1.25).		No	No	No	Between 0 and 4000, inclusive
base_price_per_measurement_unit	integer	Base price in cents per measurement unit (e.g., per kg, lb) for weighted items — the equivalent of base_price for an item sold by weight. See Weighted Items.		Yes (weighted)	No	Yes (weighted)
sale_price_per_measurement_unit	integer	Promotional price in cents per measurement unit for weighted items — the equivalent of sale_price for an item sold by weight.		Recommended	No	Recommended	Integer only. A value above base_price_per_measurement_unit is accepted by the API but not supported
loyalty_price	integer	Special pricing in cents for loyalty customers.
loyalty_price_per_measurement_unit	integer	Loyalty price per unit in cents for weighted items.

"price_info": {
  "base_price": 1299,
  "sale_price": 1099,
  "tax_rate": 7.5,
  "bottle_fee_deposit": 125
}

Location

The location object represents physical metadata for the item inside the store. These values help optimize Dasher routing and in-store picking flows. All fields are optional.

Field	Type	Description
aisle	string	Store aisle (e.g., "5").
zone	string	Store zone or section code (e.g., "Back Wall").
shelf	string	Shelf identifier (e.g., "Middle").
side	string	Shelf side or orientation (e.g., "Left", "Right").
section	string	Broad store area (e.g., "Frozen Foods").
additional_details	string	Free-form notes (e.g., "Near checkout freezer").
coordinates	object	Optional spatial coordinates for robotic or precision picking systems.
raw_text	string	Raw location string supplied by merchant.

"location": {
  "aisle": "A4",
  "shelf": "Middle",
  "zone": "Back Wall",
  "section": "Cold Beverages"
}

Item Special Hours

The item_special_hours array allows you to control when an item is orderable at a specific store — independent of the store's overall operating hours. This is useful for time-sensitive products such as breakfast-only items, alcohol sales, or limited-time menus.

Each element in the array defines a recurring weekly time block or a temporary date-bound override.

Field	Type	Required	Description
day_index	string	Yes	Day of the week. One of: "MON", "TUE", "WED", "THU", "FRI", "SAT", "SUN".
start_time	string	Conditional	Start time in local store time, formatted as HH:MM:SS (24-hour). Required unless using date-only range.
end_time	string	Conditional	End time in local store time, formatted as HH:MM:SS. Required unless using date-only range.
start_date	string	No	ISO-8601 date string indicating when this override begins.
end_date	string	No	ISO-8601 date string indicating when this override ends.

Examples

Lunch-only item (Mon–Fri)

"item_special_hours": [
  { "day_index": "MON", "start_time": "11:00:00", "end_time": "14:00:00" },
  { "day_index": "TUE", "start_time": "11:00:00", "end_time": "14:00:00" },
  { "day_index": "WED", "start_time": "11:00:00", "end_time": "14:00:00" },
  { "day_index": "THU", "start_time": "11:00:00", "end_time": "14:00:00" },
  { "day_index": "FRI", "start_time": "11:00:00", "end_time": "14:00:00" }
]

Limited-time item every Saturday until a specific date

"item_special_hours": [
  {
    "day_index": "SAT",
    "start_time": "10:00:00",
    "end_time": "18:00:00",
    "end_date": "2025-09-30"
  }
]

Best Practices

• Times are evaluated in local store time.
• If item_special_hours is omitted, the item follows the store's general hours.
• Combine start_date/end_date with day/time to define temporary seasonal periods.
• Omit a day entirely to make the item unavailable that day.
• Items cannot be ordered outside store operating hours even if special hours exist.