> ## Documentation Index
> Fetch the complete documentation index at: https://urbnbox.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

> [!WARNING]
>
> 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.

```bash theme={null}
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.

```bash theme={null}
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": "+254712345678",
    "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`.

```bash theme={null}
curl \
  --url https://portal.urbnbox.io/api/vendor/v1/orders/ORDER_ID \
  --header "X-API-Key: $URBNBOX_API_KEY"
```

> [!TIP]
>
> 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](https://urbnbox.mintlify.site/api-reference/vendor/orders.md)
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](https://urbnbox.mintlify.site/api-reference/vendor/orders.md)**
>
> Fulfilment types, statuses, bulk creation and CSV upload.

> **[Authentication](https://urbnbox.mintlify.site/concepts/authentication.md)**
>
> Choose and secure the correct API key.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.