Pickups

Schedule carrier pickups (recolecciones), check their status, and cancel them when needed.

A pickup (recolección) asks the carrier to collect your packages at an address, on a date, within a time window. Schedule, check, and cancel pickups with any carrier through the same API.

The lifecycle

PENDING → CONFIRMED → IN_PROGRESS → COMPLETED
                 ↘ CANCELLED
                 ↘ FAILED

Endpoints

Schedule a pickup

Body parameters

curl -X POST https://api.sendit.mx/v1/pickups \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "carrierCode": "DHL",
    "pickupAddressId": "clx_origin_address",
    "pickupDate": "2026-07-20",
    "readyTime": "09:00",
    "closingTime": "18:00",
    "packageCount": 5,
    "totalWeight": 12.5,
    "contactName": "Juan Pérez",
    "contactPhone": "+525512345678",
    "specialInstructions": "Ring the bell twice, ask for Juan.",
    "shipmentIds": ["clxship001", "clxship002"]
  }'

{
  "success": true,
  "data": {
    "id": "clxpickup_xyz",
    "carrierCode": "DHL",
    "pickupDate": "2026-07-20",
    "readyTime": "09:00",
    "closingTime": "18:00",
    "packageCount": 5,
    "totalWeight": "12.5",
    "status": "CONFIRMED",
    "confirmationNumber": "DHL-A1B2C3D4",
    "confirmedAt": "2026-07-17T10:30:00.000Z"
  }
}

Keep the confirmationNumber. It is the reference the carrier recognizes if you need to sort something out by phone.

Check which carriers pick up

GET /v1/pickups/carriers

{
  "success": true,
  "data": [
    { "carrierCode": "DHL", "carrierName": "DHL Express", "supportsPickups": true },
    { "carrierCode": "ESTAFETA", "carrierName": "Estafeta", "supportsPickups": true },
    { "carrierCode": "FEDEX", "carrierName": "FedEx", "supportsPickups": true }
  ]
}

List and filter

GET /v1/pickups?carrierCode=DHL&status=CONFIRMED&dateFrom=2026-07-01&dateTo=2026-07-31

Pagination follows the page model described in Pagination & filtering.

Cancel a pickup

curl -X PATCH https://api.sendit.mx/v1/pickups/clxpickup_xyz/cancel \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Packages will not be ready in time" }'

Pickups already CANCELLED or COMPLETED can’t be cancelled again (400).

Refresh the status

POST /v1/pickups/:id/refresh-status

Queries the carrier directly and updates the local record. Use it when you need a status fresher than the last sync.

Handle errors