Book a service

POSThttps://api.nexgapp.com/v1/ordersComing soon

Not served yet

This endpoint is designed but not live. Nothing here works against api.nexgapp.com today; the request and response below are the planned shape and may change. It will appear in the changelog when it ships.

Designed for a business that books NexG services for its own guests: a hotel or tour company booking an airport transfer, for example. The database function behind it exists; the HTTP route is not served yet, so a POST to /v1/orders returns 405 today.

You say what and how many; NexG works out the price from its fee settings, the same way checkout does. A request can never state a price. The total is frozen on the order when it is placed.

Every booking needs an Idempotency-Key header. A retry with the same key returns the first answer instead of booking twice.

Authentication: API key with merchant_write, bound to your merchant
Rate limit cost: 5 tokens
Caching: Never cached
Status: Coming soon

curl -X POST "https://api.nexgapp.com/v1/orders" \
  -H "X-Api-Key: $NEXG_API_KEY" \
  -H "Idempotency-Key: booking-2026-11-14-jkia-0001" \
  -H "Content-Type: application/json" \
  --data '{"service":"airport_transfer","quantity":2,"pickup_label":"JKIA Terminal 1A","pickup_lat":-1.3192,"pickup_lng":36.9278,"dropoff_label":"Woodvale Grove, Westlands, Nairobi","dropoff_lat":-1.2648,"dropoff_lng":36.8027,"scheduled_for":"2026-11-14T06:30:00+03:00","passengers":[{"name":"Amina Wekesa","phone":"+254700000101","flight":"KQ 101"}],"payment_method":"on_account","note":"Two large suitcases."}'

Response · 201 Created

{
  "ok": true,
  "order_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "reference": "NX-261114-0012",
  "service": "airport_transfer",
  "quantity": 2,
  "total_cents": 450000,
  "currency": "KES",
  "payment_method": "on_account",
  "scheduled_for": "2026-11-14T03:30:00+00:00"
}

Headers

X-Api-Keyheader · stringRequired
A key bound to your merchant, with merchant_write.
Idempotency-Keyheader · stringRequired
16 to 128 characters, unique per booking. Reuse it only to retry the same booking.
Content-Typeheader · stringRequired
application/json

Request body

Booking request, sent as JSON.

servicestring
A service code from GET /v1/services.
quantityinteger
How many units, 1 to 60. Defaults to 1. For a transfer, passengers.
pickup_labelstring
Where to collect from. Needed for a ride or a courier.
pickup_latnumber
Pickup latitude.
pickup_lngnumber
Pickup longitude.
dropoff_labelstring
Where to go. Needed for a ride or a courier.
dropoff_latnumber
Drop-off latitude.
dropoff_lngnumber
Drop-off longitude.
scheduled_fortimestamp
When, with a UTC offset. Leave it out for as soon as possible.
passengersarray
Up to 60 of { name, phone, flight } for the people travelling.
payment_methodstring
on_account (the default), mpesa_stk or card.
notestring
Anything the driver should know. Up to 1,000 characters.

Response

Receipt body

okboolean
Always true on a receipt.
order_iduuid
NexG’s id for the new order.
referencestring
The reference people read.
servicestring
The service code you booked.
quantityinteger
How many units.
total_centsinteger
What it cost, in cents, priced by NexG from its fee settings. A caller never sets a price.
currencystring
Always KES.
payment_methodstring
How it will be paid.
scheduled_fortimestamp or null
When it is booked for, if scheduled.

Good to know

The planned request and receipt are shown, taken from ServiceBooking and BookingReceipt in @nexg/contracts/api. They may change before the route ships. The amount is illustrative.