# List pickups

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

Every pickup booked for the order, newest first, including cancelled ones.

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

## Returns

Returns the result.

- `scheduled_pickups` (array of objects, required): The order's pickups, newest first.
  - `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.
  - `order_status` (enum, required): Where the order is. List order statuses has every value. Possible enum values: `incomplete`, `order_received`, `awaiting_additional_documentation`, `awaiting_prepayment`, `awaiting_waybill_generation`, `awaiting_schedule_pickup`, `awaiting_pickup`, `awaiting_swap_out`, `pickup_missed`, `in_transit`, `partially_delivered`, `delivered`, `invoice_to_be_paid`, `invoice_paid`, `cancelled`, `lost_in_transit`, `awaiting_consolidation`, `consolidated`.
  - `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`.
- `meta` (object, required): How many pages and records the list has.
  - `page_count` (integer, required): How many pages the list has. Ask for another with `?page=`.
  - `record_count` (integer, required): How many records the list has across all pages.

## Errors

- `401 Unauthorized`: The token is missing, expired or invalid. Sign in again.

## Example request (curl)

```bash
curl -X GET "https://sandbox-api.vatit-stream.com/client_api/v2/orders/5/schedule_pickups" \
  -H "Authorization: Bearer $API_TOKEN"
```

## Example response (200)

```json
{
  "scheduled_pickups": [
    {
      "id": 2,
      "cancellable": true,
      "confirmation_number": "FDX-PU-4417823",
      "error_message": "",
      "freight_confirmation_number": null,
      "order_status": "awaiting_pickup",
      "scheduled_date": "2026/10/26 00:00:00 UTC",
      "status": "scheduled",
      "time_from": "10:00:00",
      "time_to": "16:00:00"
    }
  ],
  "meta": {
    "page_count": 1,
    "record_count": 1
  }
}
```