Quickstart

Five steps

1. Make a request without a key

   Public data needs no key. Ask for the zones NexG delivers to:

   curl https://api.nexgapp.com/v1/zones

   {
     "ok": true,
     "data": {
       "items": [
         {
           "id": "7f1e2d3c-4b5a-4968-8776-655443322110",
           "name": "Kilimani",
           "tier": "core",
           "eta_min": 20,
           "eta_max": 30,
           "cod_allowed": true,
           "…": "and the zone's bounding box"
         }
       ],
       "next_cursor": null
     },
     "meta": { "api_version": "v1", "limit": 100 }
   }

   Every response has ok, then either data or error, then meta. Lists sit in data.items, with next_cursor for the next page.

2. Get a key

   Sign in to the developer console with the NexG account you use on nexgapp.com, and issue a key. Choose what it may do:

   • Read the public catalog (public_read): merchants, zones, experiences and services. Any account can have this.
   • Read your merchant orders (merchant_read): needs a merchant you own, which the console lists by name.

   The key is shown once and NexG keeps only a hash of it, so copy it before you leave the page. Store it where your server reads secrets:

   # On your server, in its secret store or environment. Never in a browser
   # bundle, a mobile app or a repository.
   NEXG_API_KEY=<the key from the developer console>

3. Call the API with your key

   Send the key in X-Api-Key. With a key, your requests spend from your own rate limit instead of the shared anonymous one.

   curlJavaScriptPython

   Copy

   curl "https://api.nexgapp.com/v1/catalog/merchants?city=nairobi&category=restaurant" \
     -H "X-Api-Key: $NEXG_API_KEY"

4. Read your orders

   With a merchant_read key, list your merchant's orders, newest first. You never name the merchant: the key does.

   curlJavaScriptPython

   Copy

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

5. Handle errors and limits

   Check ok on every response. When it is false, branch on error.code and the HTTP status, and on a 429 wait for the seconds in Retry-After. The Errors and Rate limits pages list every case.

Before you go live

• The key lives on your server only, and you can replace it without a code change.
• Your client handles 401 (replace the key), 403 (wrong scope), 429 (wait, then retry) and 5xx (retry with backoff).
• You follow next_cursor until it is null.
• You read amounts as integers: shillings in catalogues, cents on orders.
• You watch the changelog for changes to the endpoints you use.