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

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		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.

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.		Yes	No	Yes	Between 1 and 1000000, inclusive
sale_price	integer	Optional promotional or discounted price in cents. Must be ≤ base_price.		Recommended	No	Recommended	1. Must be < base_price 2. Between 1 and 1000000, inclusive
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.		No	No	No
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.