Skip to content
NexG ConciergeDevelopers
NexG Developers
Get an API key

Merchant integration guide

Connect your website or back office to NexG: issue a merchant key and keep your orders in step.

On this page

What you can integrate today

This guide is for NexG merchants and the developers who build their websites, point of sale, booking systems and back offices.

  • Read your own orders into your system, with a key bound to your merchant.
  • Show your NexG listing and catalogue on your own website.
  • Use NexG's delivery zones, published experiences and bookable services.
  • Keep your catalogue in your own system and import it to NexG as CSV.

Not through the API yet

Creating, changing or cancelling orders, accepting bookings, starting a payment and requesting a payout. Booking a service by API is designed and listed in the reference as coming soon. The service list is informational until then.

Set up an integration

  1. Sign in to the developer console

    Open the developer console with the NexG account that owns your merchant. Your merchants are listed by name.

  2. Issue a key for your merchant

    Choose your merchant and only the scopes you need: merchant_read for your orders, public_read for public data. Merchant keys need your merchant to be approved and operating.

  3. Store it as a secret on your server

    The key is shown once. Put it in your server's secret store, never in a website, an app or a repository. See Keeping keys safe.

  4. Call the API from your server

    Map NexG's ids and stages into your system. The order sync recipe shows one way.

Read your orders

Request GET /v1/orders with your merchant key. Orders come newest first, 25 to a page; follow next_cursor for more. The key decides the merchant: you never send a merchant id, and no request can read another merchant's orders.

curl "https://api.nexgapp.com/v1/orders" \
  -H "X-Api-Key: $NEXG_API_KEY"
One order in 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"
}

Amounts are integer cents: 161625 is KES 1,616.25. Keep both order_id and reference so you can match your record with NexG's. Every field is described in the reference.

Good practice

  • Call NexG from your server only, over HTTPS.
  • Handle errors by HTTP status and error.code: 401 means replace the key, 403 means the key lacks the scope, 429 means wait for Retry-After.
  • Page with next_cursor rather than assuming one response holds everything.
  • Poll your orders about once a minute. NexG does not push order changes yet; see Webhooks.
  • Do not call routes that are not in the reference. They are not part of the API.