Pickups

Ask the carrier to collect parcels at an address. Available on carriers with canRequestPickup: true in /carriers.

Request a pickup

POST /pickups — rate limit 10 / min · requires an active subscription

Field	Type	Required	Description
`serviceType`	`string`	Yes	Contract code (from `/carriers` or `/rates`)
`pickupDate`	`date`	Yes	`YYYY-MM-DD`, today or later
`pickupTime`	`string`	No	Time window: `AM`, `PM` or `AMPM` (default)
`shipmentId`	`string`	No	LDV of the shipment the pickup is for
`instructions`	`string` (255)	No	Instructions for the driver
`paymentType`	`string` (30)	No	Carrier-specific payment type
`cod`	`Money`	No	Cash on delivery amount, where the carrier supports it on pickups
`shipper`	`Party`	Yes	Pickup address (`name`, `address.street`, `address.city`, `address.postalCode`, `address.countryCode` required)
`recipient`	`Party`	No	Destination. Default: the operational address of the account
`packages[]`	`Package[]`	Yes	Parcels to collect, each with `weight` and `dimensions`; `description` and `value` optional

Request


{
  "serviceType": "brt-standard",
  "pickupDate": "2026-09-04",
  "pickupTime": "AM",
  "shipmentId": "DEMO05407027",
  "instructions": "Ring at the warehouse door",
  "shipper": {
    "name": "Mario Rossi",
    "company": "ACME Srl",
    "address": { "street": "Via Roma 1", "city": "Milano", "province": "MI", "postalCode": "20100", "countryCode": "IT" },
    "phone": "+39 333 1234567",
    "email": "mario@acme.it"
  },
  "packages": [
    { "weight": { "value": 3, "units": "KG" }, "dimensions": { "length": 40, "width": 30, "height": 20, "units": "CM" } }
  ]
}

Field	Type	Description
`id`	`integer`	Internal pickup id (`GET /pickups/{id}`)
`pickupId`	`string`	Confirmation number assigned by the carrier
`shipmentId`	`string\|null`	LDV the pickup refers to
`pickupDate`, `pickupTime`	`date`, `string`	Requested date and window
`shipper`	`Party`	Pickup address
`parcels`, `weight`	`integer`, `Weight`	Totals
`cost`	`Money`	Pickup cost charged to the credit
`createdAt`	`datetime`

HTTP	`code`	When
`402`	`subscription_required` · `subscription_payment_failed` · `plan_limit_reached`	Subscription missing, unpaid or limit reached
`404`	`not_found`	Unknown contract code
`422`	`validation_failed`	Invalid payload (e.g. `pickupDate` in the past)
`422`	`shipment_rejected`	The carrier refused the pickup; the reason is in `message`

List pickups

GET /pickups?from=&to= — paginated

Pickups requested in the period (default: the last 30 days), most recent first.

Pickup detail

GET /pickups/{id}

Returns the pickup object shown above.

Pickups are handled by the carrier: to change or cancel one, contact the carrier with the pickupId.