Order API endpoints

Update order state

Changed on Aug 6, 2026

Use this endpoint to accept/cancel an order or mark an order as ready for pickup.

Unavailable Items

When cancelling an order due to item unavailability (e.g. ITEM_PERMANENTLY_NOT_AVAILABLE or ITEM_TEMPORARILY_UNAVAILABLE), you can optionally provide the list of unavailable items in the unavailable_items field.

This data is used to drive future decisions such as automatically snoozing items that are temporarily out of stock, preventing them from appearing on the menu until they are available again.

Example request body:

{
  "state": "cancelled",
  "cancellation_reason": "ITEM_TEMPORARILY_UNAVAILABLE",
  "unavailable_items": [
    {
      "item_id": "item-123",
      "item_type": "item"
    },
    {
      "item_id": "modifier-456",
      "item_type": "modifier_option"
    }
  ]
}

put/orders/{order_id}

Request

Base URL
https://apigateway.careemdash.com/pos/api/v1
Auth
OAuth 2
Client credentials
Token URLhttps://identity.careem.com/token
Scopespos
TypeScript
https://skmtc.dev/careemnow/apis/careem-pos-api/docs/orders/:order_id/put.ts
A function with typed inputs. Its response is checked against the schema.

Path parameters

order_idinteger required

Headers

Authorizationstring required

User-Agentstring required

Brand-Idstring

Branch-Idstring required

Request body

state'accepted' | 'ready' | 'cancelled' required

The state of the order.

We've recently introduced the ready state, which enables partners' to achieve more accurate tracking of their orders.

Please select cancellation reason from the predefined list. These reasons are case-sensitive.

Example request

{
  "state": "cancelled",
  "cancellation_reason": "ITEM_TEMPORARILY_UNAVAILABLE",
  "unavailable_items": [
    {
      "item_id": "item-123",
      "item_type": "item"
    }
  ]
}

Response

Order state updated successfully

idstring required

The id of the order

status'pending' | 'accepted' | 'cancelled' | 'delivered' required

The current status of the order

notesstring

Customer notes

cancellation_reasonstring required

The cancellation reason. This field is populated when the order is cancelled

created_atstring required

Time RFC3339 format in UTC in which the brand has been updated

updated_atstring required