POST to the batches endpoint with a payload containing 'default_carrier_account' and 'default_servicelevel_token' for batch-wide defaults, plus a 'batch_shipments' array where each element includes 'shipment' (address and parcel data) and optionally overrides for carrier account or service level.
The batch is created in 'VALIDATING' status; poll the batch endpoint (GET by batch ID) or rely on the 'batch.updated' webhook event until status transitions to 'VALID' (or 'INVALID' if some shipments failed validation).
Once 'VALID', POST to the batch's purchase sub-resource (verify exact path in current docs) to trigger label purchase; status transitions to 'PURCHASING' then 'PURCHASED'.
Poll or use webhooks to detect 'PURCHASED' status; retrieve the 'batch_shipments' page results to get individual 'transaction' IDs and download label URLs.
Handle partially failed batches: some shipments may have 'status: INVALID' in the batch_shipments list; extract these and retry them individually or fix address/parcel data and resubmit.
Known gotchas
Shippo batches have per-request limits on the number of shipments (verify current maximum in docs); split very large orders across multiple batch requests.
All shipments in a batch must use the same carrier account and service level by default; if you need per-shipment carrier selection, you must supply per-element overrides, which increases complexity.
Batch label creation is asynchronous; polling intervals should use exponential backoff to avoid excessive API calls during the PURCHASING phase.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp