List your orders

GEThttps://api.nexgapp.com/v1/ordersLive

Returns orders placed with the merchant your key is bound to, newest first: guest orders from nexgapp.com and, once booking ships, service bookings made through the API.

You never send a merchant id. The key decides the merchant, so a key can never read another merchant’s orders. The stage is the one the merchant console shows, read from the order rather than worked out again.

Poll this endpoint to keep your system in step with NexG. Each call costs 3 tokens; at the default 60 tokens a minute, polling once a minute leaves plenty of room for catalogue reads.

Authentication: API key with merchant_read, bound to your merchant
Rate limit cost: 3 tokens
Caching: Never cached
Available since: 22 October 2026

curl "https://api.nexgapp.com/v1/orders" \
  -H "X-Api-Key: $NEXG_API_KEY"

Response · 200 OK

{
  "ok": true,
  "data": {
    "items": [
      {
        "order_id": "0f1e2d3c-4b5a-4697-8a8b-9c0d1e2f3a4b",
        "reference": "NX-261110-0003",
        "service": "",
        "quantity": 3,
        "stage": "preparing",
        "payment_method": "mpesa_stk",
        "payment_status": "paid",
        "currency": "KES",
        "total_cents": 161625,
        "scheduled_for": null,
        "pickup_label": null,
        "dropoff_label": "Rhapta Road, Westlands, Nairobi",
        "created_at": "2026-11-10T09:42:17.204+00:00"
      }
    ],
    "next_cursor": null
  },
  "meta": {
    "api_version": "v1",
    "limit": 25
  }
}

Query parameters

cursorquery · stringOptional
The next_cursor from the previous page, passed back unchanged. Leave it out for the first page. A cursor this endpoint did not issue is refused with 400.
limitquery · integerOptional
Results per page, 1 to 100. Defaults to 25. A value outside that range is refused with 400.

Any other query parameter is refused with 400 invalid_request.

Headers

X-Api-Keyheader · stringRequired
A key bound to your merchant, with merchant_read. Or send it as Authorization: Bearer <key>.

Response

Order data.items[]

order_iduuid
NexG’s id for the order. Store it.
referencestring
The reference people read, such as NX-261110-0003. Store it too.
servicestring
The API service code for a service booking; an empty string for other orders.
quantityinteger
Units on the order: passengers for a transfer, items for a basket.
stagestring
Where the order is: placed, confirmed, preparing, ready, picked_up, arriving, delivered, cancelled, disputed or refunded. The same stage the merchant console shows.
payment_methodstring
mpesa_stk, card, bank_transfer, cash_on_delivery, charge_to_room or on_account.
payment_statusstring
pending, authorised, paid, collected, failed, refunded or partially_refunded.
currencystring
Always KES.
total_centsinteger
The order total in cents (KES 1,616.25 is 161625), fixed when it was placed.
scheduled_fortimestamp or null
When it is booked for, if it was scheduled.
pickup_labelstring or null
Where it is collected from, for a ride or a courier.
dropoff_labelstring or null
Where it is going.
created_attimestamp
When it was placed.

Errors

Every error has the same shape; see Errors. Branch on error.code and the HTTP status, never on the message.

400invalid_request
Both X-Api-Key and Authorization were sent, or Authorization is not a Bearer key.
401not_found
The key is unknown, revoked or expired, or its merchant cannot use the API right now. All of these get the same answer on purpose.
403not_found
No key was sent, or the key does not have merchant_read.
429rate_limited
Your token bucket is empty. Wait the number of seconds in the Retry-After header.
503internal_error
NexG could not check the key or the rate limit. Retry with backoff.
400invalid_request
A query parameter is not one this endpoint accepts, or fails validation. error.fields names it.
403not_found
NexG refused the read for this key, for example because it is not bound to a merchant.
500internal_error
NexG could not read the orders.
500internal_error
Something unexpected failed on NexG’s side. NexG logs the X-Request-Id: quote it if you report the failure.

Good to know

The city, category and q parameters other list endpoints take are accepted here and ignored.
Merchant keys work only while the merchant may operate: not while it is paused, suspended or delisted, and not while its application is waiting for approval.