Batches & manifests

Buy labels in bulk asynchronously, with partial-success results and per-carrier manifests.

A batch buys labels for up to 100 shipments in a single call. Processing is asynchronous: the request returns immediately with a batchId and you poll for progress.

Buy in bulk

Body parameters

PropType

shipmentIdsstring[]

Up to 100 shipment IDs from your organization. Duplicates are deduplicated; shipments that already have a label are skipped.

Typestring[]

curl -X POST https://api.sendit.mx/v1/batches \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "shipmentIds": ["clxship_aaa", "clxship_bbb", "clxship_ccc"] }'

Response 202 Accepted:

{
  "success": true,
  "data": {
    "id": "bat_xyz",
    "status": "PENDING",
    "totalShipments": 3,
    "purchasedCount": 0,
    "failedCount": 0,
    "createdAt": "2026-07-17T12:00:00.000Z"
  }
}

Batch rules:

Up to 100 shipments per batch; all from your organization.
Duplicate IDs are deduplicated automatically.
Shipments that already have a valid label are skipped (counted as succeeded).

Track the progress

PENDING → PROCESSING → COMPLETED | PARTIAL | FAILED

Status	Meaning
`PENDING`	Queued, not started
`PROCESSING`	Buying labels
`COMPLETED`	All labels purchased
`PARTIAL`	Some purchased, some failed
`FAILED`	No labels purchased

Poll with GET /v1/batches/:id:

{
  "success": true,
  "data": {
    "id": "bat_xyz",
    "status": "PARTIAL",
    "totalShipments": 3,
    "purchasedCount": 2,
    "failedCount": 1,
    "purchasedShipmentIds": ["clxship_aaa", "clxship_bbb"],
    "failedItems": [
      {
        "shipmentId": "clxship_ccc",
        "errorCode": "INSUFFICIENT_BALANCE",
        "errorMessage": "Wallet balance too low for this shipment"
      }
    ]
  }
}

A manifest groups several labels from the same carrier into one document the courier scans once at pickup. It is generated automatically when the batch completes and all purchased labels belong to the same carrier.

The manifest comes in the batch response when available:

{
  "scanForm": {
    "id": "scf_abc",
    "carrierCode": "DHL",
    "formUrl": "https://labels.sendit.mx/scan-forms/scf_abc.pdf",
    "formNumber": "MAN-DHL-20260717",
    "status": "GENERATED"
  }
}

Print formUrl and hand it to the courier along with the packages.

Bulk endpoints

For high-volume read and validation operations, and not purchases, use the bulk endpoints. They have the same partial-success semantics, accept up to 100 items, and return one result per item in the same order:

Method	Path	Description
`POST`	`/v1/bulk/addresses/validate`	Validate up to 100 addresses
`POST`	`/v1/bulk/tracking/lookup`	Look up events for up to 100 tracking numbers
`POST`	`/v1/bulk/shipments/fetch`	Fetch up to 100 shipments by ID
`POST`	`/v1/bulk/orders/fetch`	Fetch up to 100 orders by ID

curl -X POST https://api.sendit.mx/v1/bulk/shipments/fetch \
  -H "X-API-Key: sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "ids": ["clxship_aaa", "clxship_bbb", "clxship_zzz"] }'

{
  "success": true,
  "data": [
    { "id": "clxship_aaa", "found": true, "data": { "...": "..." } },
    { "id": "clxship_bbb", "found": true, "data": { "...": "..." } },
    { "id": "clxship_zzz", "found": false, "data": null }
  ]
}

A missing ID, or one from another organization, returns found: false and never fails the whole batch. Deleted resources count as not found.