Quickstart

Create your first UrbnBox delivery order and follow it to the customer’s door.

A delivery order sends an UrbnBox rider from your UrbnBox outlet to your customer’s address. This quickstart creates one delivery order with the Vendor API and reads its status back.

Prerequisites

Before you begin, you need:

• An active UrbnBox vendor account.
• A vendor API key. Create one under Integrations in the vendor dashboard. Vendor keys begin with ubx_.
• At least one active product in your UrbnBox catalogue with stock available.
• The customer’s name, WhatsApp number and delivery address.

Keep API keys on your server. Never add a key to browser code, a mobile app, or a public repository.

Create a delivery order

1. Find the product IDs

   Every order lists the items it carries. Each item references a product in your UrbnBox catalogue.

   curl \
     --url https://portal.urbnbox.io/api/vendor/v1/products \
     --header "X-API-Key: $URBNBOX_API_KEY"
   

   Note the ID of each product you want to send.

2. Create the order

   Send the customer and delivery details from your backend.

   curl --request POST \
     --url https://portal.urbnbox.io/api/vendor/v1/orders \
     --header "Content-Type: application/json" \
     --header "X-API-Key: $URBNBOX_API_KEY" \
     --data '{
       "external_reference": "ORDER-1001",
       "client_name": "Jane Mwangi",
       "client_phone": "[phone]",
       "fulfillment_type": "delivery",
       "address": "Kenyatta Avenue, Nairobi",
       "items": [
         { "product_id": "PRODUCT_ID", "quantity": 2 }
       ]
     }'
   

   UrbnBox geocodes the address when you do not send client_lat and client_lng, and calculates the delivery fee. Save the returned ID.

3. Read the order status

   Use the order ID to follow the order from draft to delivered.

   curl \
     --url https://portal.urbnbox.io/api/vendor/v1/orders/ORDER_ID \
     --header "X-API-Key: $URBNBOX_API_KEY"
   

Your integration works when the order comes back with the same ID, your items, and a DeliveryFeeKES value.

What happens next

New orders start as draft. The customer confirms the order on its public page, UrbnBox assigns a rider, and the order moves through assigned, packing and dispatched to delivered. See Orders for every field, fulfilment type and status.

All money fields ending in KES are whole Kenya shilling amounts. For example, 850 represents KES 850.

Next steps

Orders reference

Fulfilment types, statuses, bulk creation and CSV upload.

Authentication

Choose and secure the correct API key.