Pickups

Schedule carrier pickups at your warehouse or shipping location. Pickups are tied to a carrier account and specify a time window for the carrier driver to collect packages.

List Pickups

GET/api/pickups

List all scheduled pickups for the organization.

Requiredpickups:read

Returns a paginated list of pickups with their status and scheduling details.

Query Parameters

Parameter	Type	Description
`page`	number	Page number (default: 1)
`limit`	number	Items per page (default: 20, max: 100)
`status`	string	Filter by status: `scheduled`, `completed`, `cancelled`
`carrier_account_id`	string	Filter by carrier account


curl -X GET "https://api.orderly.dev/api/pickups?status=scheduled" \
  -H "Authorization: Bearer ord_sk_..."

Response


{
  "data": [
    {
      "id": "uuid",
      "carrier_account_id": "uuid",
      "carrier": "fedex",
      "status": "scheduled",
      "pickup_date": "2026-01-16",
      "ready_time": "09:00",
      "close_time": "17:00",
      "package_count": 15,
      "confirmation_number": "FDXP123456",
      "address": {
        "street1": "123 Warehouse St",
        "city": "Newark",
        "state": "NJ",
        "zip": "07102",
        "country": "US"
      },
      "created_at": "2026-01-15T10:00:00Z"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 2, "totalPages": 1, "hasMore": false }
}

Create Pickup

POST/api/pickups

Schedule a new carrier pickup.

Requiredpickups:write

Schedules a pickup with the specified carrier. The carrier account must be verified and support pickups.

Request Body

Field	Type	Required	Description
`carrier_account_id`	string	Yes	Carrier account to use
`pickup_date`	string	Yes	Pickup date (YYYY-MM-DD)
`ready_time`	string	Yes	Earliest pickup time (HH:MM, local time)
`close_time`	string	Yes	Latest pickup time (HH:MM, local time)
`package_count`	number	Yes	Number of packages
`total_weight`	number	No	Combined weight of all packages
`address`	object	No	Pickup address (defaults to org address)
`instructions`	string	No	Special instructions for the driver


curl -X POST "https://api.orderly.dev/api/pickups" \
  -H "Authorization: Bearer ord_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "carrier_account_id": "550e8400-e29b-41d4-a716-446655440000",
    "pickup_date": "2026-01-16",
    "ready_time": "09:00",
    "close_time": "17:00",
    "package_count": 15,
    "total_weight": 120,
    "instructions": "Ring doorbell at loading dock"
  }'

Response


{
  "data": {
    "id": "uuid",
    "status": "scheduled",
    "confirmation_number": "FDXP123456",
    "pickup_date": "2026-01-16"
  }
}

Cancel Pickup

DELETE/api/pickups/:id

Cancel a scheduled pickup.

Requiredpickups:write

Cancels a scheduled pickup. Only pickups in scheduled status can be cancelled. Some carriers may have cancellation deadlines.


curl -X DELETE "https://api.orderly.dev/api/pickups/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer ord_sk_..."