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

# API reference overview

> Understand the UrbnBox integration API base URL, conventions, and endpoint groups.

The reference covers every route intended for external integrations in the
current UrbnBox server.

```text theme={null}
https://portal.urbnbox.io
```

## Endpoint groups

| Group | Authentication | Who uses it | Purpose |
| - | - | - | - |
| Delivery orders (Vendor API) | `X-API-Key` (`ubx_…`) | Vendors | Delivery orders, CSV validation, webhooks, earnings |
| Pickup-point shipments (Vendor API) | `X-API-Key` (`ubx_…`) | Vendors | Parcels between pickup points |
| Pickup-point shipments (Partner API) | `X-API-Key` (`ub_live_…`) | Partners | Quotes, shipments, pickup-point availability, and checkout sessions |
| Pickup-point bookings | Publishable key (`ubp_live_…`) | Browser widgets | Pickup-point selection and booking |
| Store discovery | None | Anyone | Active store and nearby-store lookup |
| Shopify callbacks | Shopify HMAC | Shopify (signed by Shopify) | Carrier rates and paid-order ingestion |

> [!NOTE]
>
> Not sure whether you need the Partner API or Vendor API? See [Partners and
> vendors](https://urbnbox.mintlify.site/concepts/partners-and-vendors.md).

## Request conventions

Send JSON bodies with `Content-Type: application/json`. Shipment dates use
`YYYY-MM-DD`; order times such as `scheduled_at` use RFC 3339. Money fields
ending in `_kes` (requests) or `KES` (order responses) contain whole KES
amounts.

The Partner API is versioned under `/api/partner/v1`. The Vendor API is
versioned under `/api/vendor/v1`. Public booking routes are not versioned.

## Errors

Some endpoints return JSON errors. Others return a plain-text error body.
Always branch on the HTTP status before decoding the response.

| Status | Meaning |
| - | - |
| `400` | Invalid JSON, date, query parameter, or required field |
| `401` | Missing, invalid, or inactive credential |
| `403` | Credential is not authorized for the operation |
| `404` | The resource does not exist for this account |
| `422` | No pickup-point lockers are available for the requested shipment |
| `500` | UrbnBox could not complete the request |

> [!TIP]
>
> Use a stable `external_reference` for each order. Store the UrbnBox resource
> ID with the order so you can reconcile and retrieve it later.


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