> For the complete documentation index, see [llms.txt](https://docs.terminal.africa/tship/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.terminal.africa/tship/guides/pickup-workflow.md).

# Pickup Workflow

Book shipments with Priority Pickup or arrange a Scheduled Pickup in a few requests.

Fetch shipping rates, choose how the parcel will be collected, then arrange delivery. All requests use `Authorization: Bearer SECRET_KEY`.

### Pickup flow at a glance

```mermaid
flowchart TD
    Rates["1. Fetch shipping rates<br/>GET /v1/rates/shipment<br/>Options + Priority Pickup fare"]
    Book["2. Arrange delivery<br/>POST /v1/shipments/pickup<br/>rate_id + pickup_option"]
    Priority["Priority Pickup<br/>priority_pickup"]
    Auto["Shipment and rider booked<br/>Hub selected automatically"]
    Hub["Rider collects → hub<br/>Main carrier delivers"]
    Scheduled["Scheduled Pickup<br/>scheduled_pickup"]
    Dates["3. Get available dates<br/>GET /v1/pickups/dates"]
    Schedule["4. Schedule collection<br/>POST /v1/pickups/schedule"]
    Collect["Carrier collects<br/>selected shipments"]
    Regular["Regular Pickup<br/>pickup or option omitted"]
    RegularDone["Carrier's usual<br/>pickup process"]
    Dropoff["Drop-off<br/>dropoff + dropoff_id"]
    Location["Customer drops parcel<br/>at the chosen location"]

    Rates --> Book
    Book --> Priority --> Auto --> Hub
    Book --> Scheduled --> Dates --> Schedule --> Collect
    Book --> Regular --> RegularDone
    Book --> Dropoff --> Location

    classDef shared fill:#F1F5F9,stroke:#64748B,color:#0F172A
    classDef priority fill:#FFF4E5,stroke:#C77800,color:#663C00
    classDef scheduled fill:#EBF5FF,stroke:#2463A6,color:#123B64
    classDef standard fill:#F0FDF4,stroke:#36804B,color:#14532D
    class Rates,Book shared
    class Priority,Auto,Hub priority
    class Scheduled,Dates,Schedule,Collect scheduled
    class Regular,RegularDone,Dropoff,Location standard
```

### 1. Fetch shipping rates and available pickup options

Create the addresses and parcel using [Ship with Code](https://docs.terminal.africa/tship/ship-with-code.md). Fetch rates with `GET /v1/rates/shipment` using the shipment ID or address and parcel IDs.

Each rate includes its available `pickup_options`. Priority Pickup's `amount` is an additional fare, in the quoted currency:

```json
{
    "rate_id": "RT-EXAMPLE",
    "amount": 10000,
    "currency": "NGN",
    "priority_pickup_available": true,
    "priority_pickup_fee": 1275,
    "pickup_options": [
        {
            "type": "pickup"
        },
        {
            "type": "priority_pickup",
            "amount": 1275,
            "currency": "NGN"
        },
        {
            "type": "scheduled_pickup"
        },
        {
            "type": "dropoff"
        }
    ]
}
```

This is an abbreviated example; not every rate supports every option.&#x20;

### 2. Arrange delivery with the selected option

Call `POST /v1/shipments/pickup` with the main shipping rate and the chosen `pickup_option`:

```json
{
    "rate_id": "RT-EXAMPLE",
    "shipment_id": "SH-EXAMPLE",
    "pickup_option": "priority_pickup"
}
```

The draft `shipment_id` is optional; the existing booking endpoint can create a shipment from a rate. Use one of the option types returned with the rate:

| Option            | What happens                                                                      |
| ----------------- | --------------------------------------------------------------------------------- |
| priority\_pickup  | Terminal books the main shipment and arranges the collection automatically.       |
| scheduled\_pickup | Terminal books the shipment and defers collection. Continue with step 3.          |
| pickup            | The carrier's regular pickup process follows.                                     |
| dropoff           | The customer drops the parcel at an eligible location. Also send its dropoff\_id. |

If `pickup_option` is omitted, the regular booking process follows. Do not combine the selected option with other pickup instructions.

For Priority Pickup, inspect the shipment response's `pickup_id` and `metadata.priority_pickup_error`. A success with that warning means the shipment is booked but no rider was arranged, which means the package will have to be dropped off at the nearest hub. Display the warning and its hub drop-off instructions to your end user.

When the priority option is used, the assigned rider takes the parcel to the nearest Terminal hub, then the main carrier collects it onward. Hub arrival is not final delivery, and the shipment can stay Confirmed until that carrier collects from the hub. Follow its timeline; no separate priority-only detail endpoint is needed.

### 3. Choose a date for Scheduled Pickup \[DHL & FedEx ONLY]

After booking with `scheduled_pickup`, you already have the shipment ID, collection address and carrier. Only DHL and FedEx currently support scheduled pickups. For any other carrier, use the regular pickup option per shipment.

Fetch available dates:

```http
GET /v1/pickups/dates?address_id=AD-SENDER&carrier_id=CA-DHL&shipment_ids=SH-EXAMPLE
```

Use the returned dates, `ready_time` and `timezone`. Pickup dates typically start at the next business day and exclude weekends and public holidays; parcels must be packed and labelled by 10:00 in Africa/Lagos. Once the call is made, choose an available date and schedule the pickup by making the call below.

Schedule the collection:

```json
{
    "shipment_ids": [
        "SH-EXAMPLE"
    ],
    "address_id": "AD-SENDER",
    "carrier_id": "CA-DHL",
    "pickup_date": "2026-10-16",
    "instructions": "Ask at reception"
}
```

Send this to `POST /v1/pickups/schedule`. On success, keep `data.pickup_id` and the carrier's `data.reference`.

Several shipments can share one collection when they use the same carrier and billing account and are physically at the chosen address. Shipments on a personal carrier account follow the same flow: the API infers their connected account. Never mix Terminal and personal accounts, or different connected accounts.

NB: Use the returned availability from the shipment rates api; do not assume every shipment supports scheduling.

### 4. List, retrieve and cancel all pickups consistently

Use the same endpoints for Priority Pickup and Scheduled Pickup:

| Request                        | Purpose                                                         |
| ------------------------------ | --------------------------------------------------------------- |
| GET /v1/pickups                | List pickups in data.pickups. Optional type and status filters. |
| GET /v1/pickups/:pickup\_id    | Retrieve a pickup with its shipments and carrier.               |
| DELETE /v1/pickups/:pickup\_id | Cancel a pickup while cancellation is still allowed.            |

Each record has `type`: `priority_pickup`, `scheduled_pickup` or `pickup` for an automatic carrier collection. API statuses are `draft`, `confirmed`, `cancelled` and `completed`. Confirmed means the collection is booked, not necessarily completed.

Cancellation keeps the main shipment booked. After cancelling Priority Pickup, drop the parcel at the hub; check `refunded` and `refund_failed` and contact support for failed refunds. To move a scheduled collection, cancel it successfully, then choose a new date and schedule its shipments again.

After a timeout, inspect the shipment and pickup list before retrying. If an error says the carrier may have accepted the collection and it is held for support, contact support instead of creating a duplicate. For easy sync with events, subscribe to [Pickup Webhook Events](https://docs.terminal.africa/tship/miscallaneous/api-pricing.md).

See [Pickups](https://docs.terminal.africa/tship/pickups.md) for the object and individual request reference.

### 5. Handle pickup webhooks and recovery

Subscribe to the six pickup events using [Create Webhook](https://docs.terminal.africa/tship/webhooks/create-webhook.md). The same events serve Priority Pickup and Scheduled Pickup:

| Event              | Meaning                                                                                                                             |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| `pickup.scheduled` | A collection record was created and is awaiting carrier booking.                                                                    |
| `pickup.booked`    | The carrier or rider booking was confirmed. A replacement rider uses this event with `booking_reason: "automatic_reschedule"`.      |
| `pickup.updated`   | Pickup progress or the shipments on the collection changed.                                                                         |
| `pickup.completed` | Collection completed. For Priority Pickup, this means handover at the hub, with onward shipment delivery still to follow.           |
| `pickup.cancelled` | Collection has ended. Inspect `next_action` to determine what to do next.                                                           |
| `pickup.failed`    | A rider or carrier booking attempt failed or needs support. Inspect `next_action`; a failure can still be recovering automatically. |

Priority Pickup may be booked immediately, so its first event can be `pickup.booked`. Webhooks apply to pickup records that have been created. If the initial shipment response contains `metadata.priority_pickup_error`, handle that warning immediately; a failure before any pickup record exists does not guarantee a pickup webhook.

#### Priority Pickup recovery

```mermaid
flowchart TD
    Cancel["Carrier cancels the rider attempt"]
    Failure["pickup.failed<br/>next_action: wait"]
    Retry["Terminal retries automatically<br/>At most one replacement rider"]
    Result{"Replacement booked?"}
    Booked["pickup.booked<br/>booking_reason: automatic_reschedule<br/>next_action: none"]
    Handover["Rider collects → hub<br/>Main carrier continues delivery"]
    End["pickup.failed → pickup.cancelled<br/>next_action: dropoff"]
    Dropoff["Show hub address and drop-off instructions<br/>Main shipment remains booked"]
    Manual["Customer cancels Priority Pickup"]
    ManualEnd["pickup.cancelled<br/>next_action: dropoff"]
    Cancel --> Failure --> Retry --> Result
    Result -->|Yes| Booked --> Handover
    Result -->|No| End --> Dropoff
    Manual --> ManualEnd --> Dropoff

    classDef wait fill:#EBF5FF,stroke:#2463A6,color:#123B64
    classDef success fill:#F0FDF4,stroke:#36804B,color:#14532D
    classDef action fill:#FFF4E5,stroke:#C77800,color:#663C00
    class Failure,Retry wait
    class Booked,Handover success
    class End,Dropoff,ManualEnd action
```

If the automatic retry was already used, recovery goes directly to `pickup.failed` and `pickup.cancelled` with drop-off instructions. A carrier cancelling one rider attempt does not itself mean the entire pickup is permanently cancelled.

| Returned next\_action | What your application should do                                                                                                                                                             |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `wait`                | Show that Terminal is arranging a replacement or awaiting booking. Keep the shipment booked; do not create another pickup or ask the customer to drop off while retry.in\_progress is true. |
| `none`                | No collection action is required. Continue tracking; a booked pickup still has to be collected.                                                                                             |
| `dropoff`             | Show dropoff.address and ask the customer to take the parcel to that hub. No rider is coming.                                                                                               |
| `schedule_pickup`     | Fetch dates and schedule the eligible shipments again. This applies to an ended Scheduled Pickup; verify current shipment eligibility first.                                                |
| `contact_support`     | Contact support before booking again. The carrier's result may be uncertain, or the hub address may need clarification.                                                                     |

A replacement uses the **same pickup\_id** and a new `reference`. Check `retry.attempt`, `retry.max_attempts` and `retry.in_progress`. Terminal refunds the failed rider fare and, when the refund succeeds, charges for the replacement under the original fare cap. If the original refund fails, the replacement is not charged again.

Refund outcome is separate from collection outcome. `refund_status` is `pending`, `processed`, `failed`, `not_required` or `unknown`. Show a refund only after `processed`; `refund_support_required: true` means support must resolve a failed refund. A replacement can be successfully booked while its original refund still needs support. A failed refund does not remove the instruction to drop off.

A terminal failure or customer cancellation keeps the main shipment booked and sets `main_shipment_remains_booked: true`. Cancellation of the whole shipment instead uses `reason_code: "shipment_cancelled"`, `main_shipment_remains_booked: false` and `next_action: "none"`; do not ask for drop-off in that case.

#### Example: retry has ended and drop-off is required

```json
{
    "event_id": "WE-EXAMPLE",
    "event": "pickup.cancelled",
    "occurred_at": "2026-10-14T09:00:00.000Z",
    "data": {
        "pickup_id": "PI-EXAMPLE",
        "type": "priority_pickup",
        "version": 4,
        "status": "cancelled",
        "reference": "RIDER-REFERENCE",
        "shipment_ids": ["SH-EXAMPLE"],
        "next_action": "dropoff",
        "reason_code": "automatic_retry_exhausted",
        "main_shipment_remains_booked": true,
        "retry": {
            "attempt": 1,
            "max_attempts": 1,
            "in_progress": false
        },
        "dropoff": {
            "dropoff_id": "DO-HUB",
            "address": {
                "line1": "Example hub address",
                "city": "Lagos",
                "state": "Lagos",
                "country": "NG"
            }
        },
        "refund_status": "processed",
        "refund_support_required": false
    }
}
```

#### Process duplicates, delays and replays safely

Verify `X-Terminal-Signature` using the raw request body and your secret key before accepting the event. Store the event durably, then return a successful response and process it asynchronously.

Deduplicate on `event_id`. For each `pickup_id`, apply only events with a `data.version` greater than the version you have already applied. Perform that check and state update atomically so two webhook workers cannot apply an older event after a newer one. Replays keep the original ID, version and snapshot; delivery order is not guaranteed.

Use `GET /v1/pickups/:pickup_id` to reconcile uncertain or missing notifications. It returns `version` and the same recovery fields. Fetch `GET /v1/webhooks/deliveries?pickup_id=PI-EXAMPLE` to inspect your delivery history. Replay a stored delivery through `POST /v1/webhooks/replay` with its `delivery_id`; a replay does not arrange a rider or schedule a collection.

See [Pickup Event Payloads](https://docs.terminal.africa/tship/miscallaneous/sample-webhook-event-payloads/pickup.md) for all six examples. See the [Webhook Events](https://docs.terminal.africa/tship/miscallaneous/webhook-events.md) and [Handling Webhook Events](https://docs.terminal.africa/tship/miscallaneous/webhook-events/handling-webhook-events.md) references for subscriptions and signature handling.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.terminal.africa/tship/guides/pickup-workflow.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
