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.

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

Not sure whether you need the Partner API or Vendor API? See Partners and vendors.

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

Use a stable external_reference for each order. Store the UrbnBox resource ID with the order so you can reconcile and retrieve it later.