Syncing orders

Orders from every channel arrive in one format. This guide shows how to load them and keep them in sync.

The order object

{
  "id": "ord_01J9QW3T8M",
  "version": 3,
  "merchant_id": "mer_7Hq2Lw8Z",
  "location_id": "loc_2Xf9K",
  "channel": "delivery_app_a",
  "channel_connection_id": "chc_5Rm1Pa",
  "channel_ref": "CH-88213",
  "type": "delivery",
  "status": "accepted",
  "status_history": [
    { "status": "placed", "at": "2026-10-04T12:01:05Z" },
    { "status": "accepted", "at": "2026-10-04T12:02:10Z" }
  ],
  "items": [
    {
      "name": { "en": "Chicken Burger", "ar": "برجر دجاج" },
      "sku": "CB-01",
      "quantity": 2,
      "unit_price": { "amount": 2500, "currency": "SAR" },
      "modifiers": [
        {
          "name": { "en": "Extra cheese", "ar": "جبنة إضافية" },
          "quantity": 1,
          "unit_price": { "amount": 300, "currency": "SAR" }
        }
      ],
      "notes": "No onion"
    }
  ],
  "totals": {
    "subtotal": { "amount": 5600, "currency": "SAR" },
    "delivery_fee": { "amount": 900, "currency": "SAR" },
    "tax": { "amount": 975, "currency": "SAR" },
    "total": { "amount": 7475, "currency": "SAR" }
  },
  "payment": { "method": "online", "paid": true },
  "created_at": "2026-10-04T12:01:05Z",
  "updated_at": "2026-10-04T12:02:10Z",
  "extensions": {}
}

• channel_ref is the order number shown on the channel. Display it to staff; they’ll need it when talking to the channel or the customer.
• Amounts are in minor units: 7475 means 74.75 SAR.
• Fields a channel doesn’t provide are null, never made up. GET /v1/channels tells you which fields each channel supplies.
• extensions holds channel-specific extras. You can ignore it safely.

Statuses

placed ──▶ accepted ──▶ preparing ──▶ ready ──▶ picked_up ──▶ delivered
   │           │            │           │
   └▶ rejected └────────────┴───────────┴──▶ cancelled

Not every channel reports every step. Be ready for an order to skip from accepted straight to delivered.

The sync loop

1. When a merchant connects, load recent orders:

   GET /v1/orders?created_from=2026-10-01T00:00:00Z&limit=100

   Follow next_cursor until it is null.

2. Then rely on webhooks.

   • order.created carries the full order.
   • order.status_changed carries the new status and version.
   • order.updated means items, notes or totals changed. Fetch the order again.

3. Ignore stale updates. Keep the highest version you’ve seen for each order, and drop anything lower. Webhooks are not guaranteed to arrive in order.

4. Recover after downtime with the Events API, from the last event you processed:

   GET /v1/events?after=evt_01J9C2X4RS&types=order.*

5. Optional safety net. Every few minutes, list GET /v1/orders?updated_since=<last updated_at you stored> to catch anything missed.

Filtering

Parameter	Example
location_id	loc_2Xf9K
channel	A channel ID from GET /v1/channels
status	accepted
updated_since	2026-10-04T09:00:00Z
created_from / created_to	ISO 8601 times, UTC