# Book a pickup

`POST /client_api/v2/orders/{order_id}/schedule_pickups`

Books the carrier to collect the order, inside one of the slots from List pickup slots. Booking again cancels the earlier pickup.

## Parameters

- `order_id` (integer, required): The order's id. Get it from List orders (`GET /client_api/v2/orders`): send the `id` of the one you want. Ids differ between the sandbox and production.

## Body

- `scheduled_pickup` (object, required): The pickup to book.
  - `scheduled_date` (string, required): The day to collect, as `YYYY-MM-DD`. It has to be a day from List pickup slots.
  - `time_from` (string, required): When the goods are ready, as `HH:MM` in the collection address's local time. No earlier than the slot's `earliest_pickup_time` and no later than its `latest_pickup_start_time`.
  - `time_to` (string, required): When the collection point closes, as `HH:MM`. No later than the slot's `latest_pickup_end_time`, and at least `minimum_access_duration_minutes` after `time_from`.
  - `pickup_instructions` (string): Anything the driver needs to know, such as which door to use.

## Returns

Returns the scheduled pickup.

- `scheduled_pickup` (object, required): The pickup.
  - `id` (integer, required): The pickup's id.
  - `cancellable` (boolean, required): `true` while the booking can still be cancelled with the carrier.
  - `confirmation_number` (string, required): The carrier's confirmation number for the booking.
  - `error_message` (string, required): `Invalid postal code` when the carrier refused the booking over the postal code. Empty for every other outcome, including other refusals.
  - `freight_confirmation_number` (object, nullable, required): The carrier's second confirmation number, for freight collected separately. Usually empty.
  - `pickup_instructions` (string, required): What the driver was told.
  - `scheduled_date` (string, required): The collection day, as `YYYY/MM/DD HH:MM:SS UTC`. The time is always midnight, so read only the date.
  - `status` (enum, required): Where the booking stands. `system_to_schedule` means we are still booking it with the carrier. Possible enum values: `scheduled`, `cancelled`, `errored`, `system_to_schedule`, `missed`.
  - `time_from` (string, required): When the goods are ready, as `HH:MM:SS`.
  - `time_to` (string, required): When the collection point closes, as `HH:MM:SS`.

## Errors

- `400 Bad Request`: The request body isn't valid JSON, or something failed on our side.
- `401 Unauthorized`: The token is missing, expired or invalid. Sign in again.

## Example request (curl)

```bash
curl -X POST "https://sandbox-api.vatit-stream.com/client_api/v2/orders/4/schedule_pickups" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scheduled_pickup": {
      "scheduled_date": "2026-10-26",
      "time_from": "10:00",
      "time_to": "16:00",
      "pickup_instructions": "Collect from reception and ask for Thandi"
    }
  }'
```

## Example response (201)

```json
{
  "scheduled_pickup": {
    "id": 1,
    "cancellable": true,
    "confirmation_number": "FDX-PU-4417823",
    "error_message": "",
    "freight_confirmation_number": null,
    "pickup_instructions": "Collect from reception and ask for Thandi",
    "scheduled_date": "2026/10/26 00:00:00 UTC",
    "status": "scheduled",
    "time_from": "10:00:00",
    "time_to": "16:00:00"
  }
}
```