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

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

> [!TIP]
>
> Delivering to the customer's door instead? Start with
> [delivery orders](https://urbnbox.mintlify.site/quickstart.md).

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

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

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

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

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

> [!TIP]
>
> 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](https://urbnbox.mintlify.site/concepts/authentication.md)**
>
> Choose and secure the correct API key.

> **[Endpoint reference](https://urbnbox.mintlify.site/reference-overview.md)**
>
> Review every integration-facing endpoint.


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