What is Upload Item Overrides per Site?

The Site-Specific Item Overrides Upload endpoint lets you override item attributes for an individual site. A single upload can set any combination of supported overrides for one or more items at one site. Currently three attributes can be overridden:

• price_info — sets a site-specific price for the item.
• country_of_origin — sets a site-specific country of origin for the item.
• time_schedules — restricts the hours during which the item can be ordered at the site.

This is the preferred endpoint for site-specific overrides, including price: the standalone /prices endpoint is being deprecated in its favour.

Note: This endpoint is being rolled out gradually and is enabled per brand. Until it is enabled for your brand it returns 404 Not Found. Please contact your technical integration manager or account manager to have it enabled for your brand before using it in production.

How to use

Uploading overrides involves a few steps:

Steps:

1. Correctly set up webhooks for the Catalogue API in the Developer Portal
2. Call this endpoint. Successful requests receive an upload_url (a pre-signed S3 URL) and an upload_id for tracking
3. PUT your overrides JSON directly to the upload_url. The body must conform to the UpdateOverridesRequest schema
4. When processing is complete, or a problem occurs, a webhook notification is sent containing the upload_id

Points to Note

1. upload_url expires 3600 seconds after being issued.
2. upload_url must be called with a single PUT request — it cannot be reused for multiple uploads.

Example — combining all three override types. Item 789 gets a price (with a per-context override), a country of origin, and a schedule that only lists Monday — so it's orderable for breakfast on Mondays only, and not sold at all Tuesday–Sunday; item 456 gets only a country of origin:

{
  "version": "update-overrides-v1",
  "items": [
    {
      "id": "789",
      "price_info": {
        "price": 1200,
        "overrides": [
          { "id": "breakfast-bundle", "type": "ITEM", "price": 800 }
        ]
      },
      "country_of_origin": ["SE"],
      "time_schedules": [
        { "day_of_week": "MON", "time_periods": [{ "local_start_time": "07:00", "local_end_time": "11:00" }] }
      ]
    },
    {
      "id": "456",
      "country_of_origin": ["FR", "BE"]
    }
  ]
}

Full-replace behaviour

Each upload replaces all overrides for the site. Items not included in the upload have their overrides removed, and for items that are included, any override field not provided is cleared.

Example — a field silently cleared on the next upload. Upload 1 sets both a price and a country of origin for item 789:

{ "version": "update-overrides-v1", "items": [{ "id": "789", "price_info": { "price": 1200 }, "country_of_origin": ["SE"] }] }

Upload 2 updates only the price, without repeating country_of_origin:

{ "version": "update-overrides-v1", "items": [{ "id": "789", "price_info": { "price": 1300 } }] }

After upload 2, item 789 has price 1300 and no country-of-origin override — omitting the field cleared it, even though the item itself was still included in the upload. To change the price while keeping the country of origin, upload 2 must repeat "country_of_origin": ["SE"].

Example — removing all overrides for a site. Send an empty items array:

{ "version": "update-overrides-v1", "items": [] }

Validation Rules

• version must be update-overrides-v1.
• items entries each need a unique id that exists in the latest processed catalogue. Submit the complete intended override state for the site in a single upload; omit items that should not have site-specific overrides, and send an empty items array to remove all overrides for the site.
• At least one of price_info, country_of_origin, time_schedules must be set per item.
• price_info.price must be a non-negative integer (required when price_info is present).
• price_info.overrides (optional) allows per-modifier price overrides.
• country_of_origin entries are free-form strings, unique, with total length across entries not exceeding 500 characters.
• time_schedules[].day_of_week must be one of MON, TUE, WED, THU, FRI, SAT, SUN, with no duplicates.
• time_periods must contain at least one entry; local_start_time/local_end_time must be HH:MM, local_end_time after local_start_time, and periods within the same day must not overlap.

Important Usage Guidelines

• Persistent across catalogue uploads: overrides are not cleared when you upload a new catalogue. If an item is removed from the catalogue, its overrides are removed with it.
• No read endpoint: there is no GET for overrides.
• One site per upload: for bulk updates, issue separate upload requests per site_id.
• Schedules use the site's local timezone: local_start_time / local_end_time are interpreted in the site's local timezone — you do not convert times yourself.

Rate Limit