Create a Batch object via POST to https://api.goshippo.com/batches with an array of shipment objects (each containing from/to addresses, parcels, and carrier/service level); a single batch supports up to 10,000 shipments.
Poll the batch object's status field (VALIDATING → VALID or INVALID) before purchasing — Shippo asynchronously validates each shipment in the batch and marks individual entries as valid or invalid.
Review invalid shipments in the batch response and correct or remove them; you can add additional valid shipments to a VALID batch before purchasing.
Trigger label purchase by sending an empty POST to https://api.goshippo.com/batches/{BATCH_OBJECT_ID}/purchase; this is an asynchronous operation.
Listen for the batch_purchased webhook event (or poll the batch status) to confirm purchase completion; downloaded labels are returned as merged PDFs with up to 100 labels per file.
Reconcile the purchased batch against your order list; shipments that failed purchase (e.g., carrier rejection) appear with an error status and must be re-submitted as individual shipments or a new batch.
Known gotchas
Batch purchase is asynchronous — do not attempt to use label URLs immediately after the purchase POST; wait for the batch_purchased webhook or a PURCHASED status in a polling response before attempting downloads.
Shipments added to a batch after validation must go through another validation cycle; do not assume a previously VALID batch remains valid if new shipments are appended.
Carrier credentials must be pre-configured on the Shippo account for each carrier used in the batch; a missing or invalid carrier token causes all shipments for that carrier to fail silently in the batch.
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