List UberEats promotions

POST/management/promotions/fetchUberEatsPromotions

List the UberEats promotions your organization's storefronts are running, with cursor pagination.

If Uber Eats refuses the call (for example, because the promotions scope is withdrawn), it fails with a typed dependency error naming the scope, never an empty page, which would falsely claim your storefronts are running no promotions.

PER STORE, ONLY UBEREATS' FIRST PAGE. UberEats' own list takes no paging parameter, so for each store this lists the promotions on the first page UberEats serves, and a promotion past that page is not listed. states and promotionIds filter that set, and page pages through it across your stores.

ORDER. Store by store, in the order of storeIds (or of your organization's Uber Eats stores when you omit it); within one store, newest createdAt first, then promotionId. A promotion with no createdAt comes last in its store.

A SHARED STOREFRONT IS LISTED ONCE. When several of your stores are connected to the same Uber Eats storefront, its promotions are listed once, under one of those stores' ids.

WITH NO storeIds, stores that are not connected to an Uber Eats storefront are skipped, and so is a store Uber Eats cannot list; naming such a store in storeIds is a 404.

Failures beyond the document-wide codes: 404 when any storeId is not a store of your organization — an unknown id and another tenant's id are indistinguishable by design.

Safe to retry: this operation is read-only and idempotent.

Request

application/json

required

storeIdsstring[]
Only promotions on these stores. Omit for every Uber Eats store in your organization.
promotionIdsstring[]
Only these promotions, by UberEats promotionId.
statesstring[]
Only promotions in these states.
Possible values: [completed, active, pending, revoked, expired, deleted]
pagePageRequest
Page size and cursor. page.limit defaults to 50 and above 100 is a 400.

{
  "storeIds": [
    "<storeIds>"
  ],
  "promotionIds": [
    "<promotionIds>"
  ],
  "states": [
    "completed"
  ],
  "page": {
    "limit": 50,
    "cursor": "<cursor>"
  }
}

Responses

200 — A page of the matching promotions, and the cursor for the next page.

Headers

x-mealco-tx-idstringoptional
The correlation id for this call, echoed on every response — a 200 exactly as much as a 400, 401 or 500. Quote it when reporting a problem and we can find every log line for the request, in every service it touched. You may also send your own x-mealco-tx-id on the request and we adopt it, so your correlation id becomes ours. Not marked required for one reason: a request whose JSON body is malformed is rejected before it reaches an operation, so no id exists yet and that single response carries neither this header nor the txId field of the error body. Everything that reaches an operation carries it.

promotionsUberEatsPromotion[]
The matching promotions.
nextCursorstring
Pass back as page.cursor for the next page. Absent on the last page.

About Promotions

Promotions on the connected delivery platforms. Organization-scoped like every other section: the organization is the one the API key authenticates and no request field can name another.

Four operations cover the whole Uber Eats promotion lifecycle: fetchUberEatsPromotions (list), fetchUberEatsPromotion (get one, by id), createUberEatsPromotion and revokeUberEatsPromotion. There is no update and no pause on the platform, so a promotion is immutable once created.

The operations are named for the platform because the platforms differ materially: DoorDash exposes no promotion write API to integrations, and Grubhub no promotions surface at all — for both, promotion attribution arrives on the order instead (see the Orders section).

createUberEatsPromotion and revokeUberEatsPromotion are writes — a read-only API key is refused with 403.

Money is an integer in the currency's minor unit everywhere in this section — 1250 is $12.50.