Pickup-point shipments

Send a parcel between UrbnBox pickup points with the Partner API: quote, create and track it.

A pickup-point shipment moves a parcel from an UrbnBox pickup point in one town to a pickup point in another. The sender deposits the parcel in a locker at the origin and the recipient collects it at the destination with a PIN. Use the Partner API when your backend controls checkout or fulfilment. This guide creates one shipment.

Delivering to the customer’s door instead? Start with delivery orders.

Prerequisites

Before you begin, you need:

• An active UrbnBox partner account.
• A secret test or live API key.
• The origin and destination city.
• The recipient’s name and phone number.

Keep secret keys on your server. Never add a key beginning with ub_live_ or ub_test_ to browser code, a mobile app, or a public repository.

Create a shipment

1. Request a quote

   Confirm that lockers are available and retrieve the fee in whole KES.

   curl --request POST \
     --url https://portal.urbnbox.io/api/partner/v1/shipment-quote \
     --header "Content-Type: application/json" \
     --header "X-API-Key: $URBNBOX_API_KEY" \
     --data '{
       "destination_city": "Mombasa",
       "weight_tier": "light",
       "starts_at": "2026-07-05",
       "ends_at": "2026-07-08"
     }'
   

   Continue only when the response contains "available": true.

2. Create the shipment

   Send the order and recipient details from your backend.

   curl --request POST \
     --url https://portal.urbnbox.io/api/partner/v1/shipments \
     --header "Content-Type: application/json" \
     --header "X-API-Key: $URBNBOX_API_KEY" \
     --data '{
       "external_reference": "ORDER-1001",
       "recipient_name": "Jane Mwangi",
       "recipient_phone": "[phone]",
       "origin_city": "Nairobi",
       "destination_city": "Mombasa",
       "weight_tier": "light",
       "starts_at": "2026-07-05",
       "ends_at": "2026-07-08"
     }'
   

   Save the returned id, tracking_url, and deposit_pin.

3. Retrieve the shipment

   Use the shipment ID to read its current status.

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

Your integration works when the API returns the same shipment ID and a tracking URL.

Handle the creation response

The deposit_pin appears in the creation response. Store it securely at that time. It is not returned by the retrieve endpoint.

You can send deposit_whatsapp_link to the person who deposits the parcel. Send collection_whatsapp_link to the recipient when your fulfillment flow requires it.

All fee values ending in _kes are whole KES amounts. For example, 850 represents KES 850.

Next steps

Authentication

Choose and secure the correct API key.

Endpoint reference

Review every integration-facing endpoint.