Get one order

GEThttps://api.nexgapp.com/v1/orders/{id}Live

Returns one order placed with the merchant your key is bound to. The order is the same object List your orders returns, so one parser reads both.

An id that belongs to another merchant gets the same 404 as an id that does not exist, so a key cannot find out which order ids are real.

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

curl "https://api.nexgapp.com/v1/orders/0f1e2d3c-4b5a-4697-8a8b-9c0d1e2f3a4b" \
  -H "X-Api-Key: $NEXG_API_KEY"

Response · 200 OK

{
  "ok": true,
  "data": {
    "order": {
      "order_id": "0f1e2d3c-4b5a-4697-8a8b-9c0d1e2f3a4b",
      "reference": "NX-261110-0003",
      "service": "",
      "quantity": 3,
      "stage": "delivered",
      "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"
    }
  },
  "meta": {
    "api_version": "v1"
  }
}

Path parameters

idpath · uuidRequired
The order_id, from List your orders.

Headers

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

Response

Order data.order

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
The id is not a UUID.
403not_found
NexG refused the read for this key, for example because it is not bound to a merchant.
404not_found
Your merchant has no order with that id.
500internal_error
NexG could not read the order.
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

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.