Pickups

post/{connectorId}/pickupscreatePickupBooking

Book a pickup

Books a pickup — either derived from an existing consignment (`shipmentId`, address/items locked to that consignment) or standalone (`collection`, `items`, and `receiver` supplied directly, all three required together). A partial standalone submission (e.g. `collection` without `items`/`receiver`) is rejected with a 400.

Parameters

Name	In	Required	Description
connectorId	path	✓	Database ID of the carrier connector account (from `GET /connectors`)

Request body

PickupBookingRequest

Responses

201Pickup booked successfully (or recorded as failed — check `status`)

PickupBookingResponse

400Invalid request — validation failed or carrier rejected input

Error

401Missing or invalid API key

Error

403Freight access is not active for this tenant

Error

404Connector not found or not active for this tenant

Error

429Too many requests for this API key — see Retry-After header

Error

500The carrier accepted the pickup booking, but DataShift failed to record it locally — the pickup is real at the carrier and must not be retried (a retry would book a second real pickup). Reconcile manually using the returned `orderNumber` (the carrier's own pickup reference).

{
  message?: string
  orderNumber?: string
}

502Carrier API returned an error or is unavailable

Error

get/pickups/{id}getPickupBooking

Retrieve a pickup booking