> 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/pickups.md).

# Pickups

The Pickups API allows you to schedule and manage all pickup types.

A **pickup** is the collection step of a shipment. **Priority Pickup** sends a dispatch immediately a shipment is booked to collect one shipment from the provided sender. **Scheduled Pickup** reserves a carrier collection for one or more shipments on a future day at your choice.

Follow the [pickup workflow](https://docs.terminal.africa/tship/guides/pickup-workflow.md) for the customer journey. The request reference for each operation is available on its own page below.

### The Pickup Object

This section describes the different attributes available for a pickup.

| Attribute                       | Type              | Description                                                                                                        |
| ------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------ |
| booking\_reason                 | *string*          | `initial_booking`, `manual_booking` or `automatic_reschedule` when a booking event is recorded.                    |
| carrier                         | *string / object* | Carrier ID when scheduling and in the pickup list. Expands to the carrier's ID, name, slug and logo on Get Pickup. |
| created\_at                     | *datetime*        | Time the pickup record was created.                                                                                |
| dropoff                         | *object / null*   | Hub dropoff\_id and customer-facing address for handover.                                                          |
| extras                          | *object*          | Additional information associated with the pickup.                                                                 |
| instructions                    | *string*          | Note for the courier. Defaults to an empty string.                                                                 |
| main\_shipment\_remains\_booked | *boolean / null*  | Whether the main shipment booking is preserved; null when not established by this event.                           |
| metadata                        | *object*          | Additional pickup information, including the collection address snapshot.                                          |
| next\_action                    | *enum*            | `none`, `wait`, `dropoff`, `schedule_pickup` or `contact_support`; the customer’s next collection action.          |
| personal\_account\_shipment     | *boolean*         | Whether collection uses the merchant's connected carrier account.                                                  |
| pickup\_address                 | *string*          | Saved collection address ID.                                                                                       |
| pickup\_id                      | *string*          | Unique identifier for the pickup, beginning with `PI-`.                                                            |
| pickup\_scheduled\_at           | *datetime*        | Time the carrier booking was confirmed; can be null before confirmation.                                           |
| reason\_code                    | *string / null*   | Machine-readable recovery or cancellation reason.                                                                  |
| reference                       | *string*          | Carrier's collection confirmation reference; can be null before booking.                                           |
| refund\_status                  | *enum*            | `pending`, `processed`, `failed`, `not_required` or `unknown`.                                                     |
| refund\_support\_required       | *boolean*         | Whether support needs to resolve a failed rider refund.                                                            |
| retry                           | *object / null*   | Priority Pickup retry attempt, max\_attempts and in\_progress flag.                                                |
| scheduled\_pickup\_date         | *datetime*        | Date and ready time for collection.                                                                                |
| shipments                       | *array*           | Shipment IDs in a scheduling response. Expands to shipment objects when listing or retrieving pickups.             |
| status                          | *enum*            | API status: `draft`, `confirmed`, `cancelled` or `completed`.                                                      |
| type                            | *enum*            | Pickup type: `priority_pickup`, `scheduled_pickup` or `pickup` (automatic carrier collection).                     |
| updated\_at                     | *datetime*        | Time the pickup record was last updated.                                                                           |
| version                         | *number*          | Increasing pickup event version. Use it to reconcile webhooks with the latest pickup state.                        |

{% hint style="info" %}
A `confirmed` pickup has been booked with the carrier; collection has not necessarily happened. A `draft` pickup is awaiting booking. App display labels may differ from the API status. Follow the shipment timeline for collection and onward delivery.
{% endhint %}

### Booking a pickup option

Fetch rates through [Get Rates for Shipment](https://docs.terminal.africa/tship/rate/get-rates-for-shipment-1.md). Each rate includes `pickup_options`; Priority Pickup includes its quoted additional amount and currency.

Pass the selected option when [arranging delivery](https://docs.terminal.africa/tship/shipment/arrange-pickup-and-delivery-for-shipment.md):

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

Priority Pickup is quoted and arranged automatically. Choose `scheduled_pickup` to defer collection, then fetch available dates and schedule the shipment for its carrier. Omit `pickup_option` to use the regular process.

### Pickup Requests

* [Get Pickups](https://docs.terminal.africa/tship/pickups/get-pickups.md)
* [Get Pickup](https://docs.terminal.africa/tship/pickups/get-pickup.md)
* [Cancel Pickup](https://docs.terminal.africa/tship/pickups/cancel-pickup.md)
* [Get Pickup Dates](https://docs.terminal.africa/tship/pickups/get-pickup-dates.md)
* [Schedule Pickup](https://docs.terminal.africa/tship/pickups/schedule-pickup.md)

{% hint style="warning" %}
If shipment booking succeeds but `metadata.priority_pickup_error` is returned, show the warning and hub drop-off instructions. This typically means the dispatch was not sent; the main shipment remains booked.
{% endhint %}

### Pickup Webhooks

Subscribe to `pickup.scheduled`, `pickup.booked`, `pickup.updated`, `pickup.completed`, `pickup.cancelled` and `pickup.failed`. Each event includes the pickup type, version and recovery instructions. Follow [Pickup Workflow](https://docs.terminal.africa/tship/guides/pickup-workflow.md#5-handle-pickup-webhooks-and-recovery) for automatic retry, drop-off, refunds and duplicate 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/pickups.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.
