Authenticate using your Shippo API key in the Authorization header (format: 'ShippoToken <key>') on requests to the Shippo API base URL.
POST to the shipments endpoint with 'address_from', 'address_to', and 'parcels' arrays; set 'async: false' if you want rates returned synchronously in the same response, otherwise poll the shipment until status is 'SUCCESS'.
Inspect the 'rates' array on the shipment; each rate object includes 'provider' (carrier name), 'servicelevel.token', 'amount', 'currency', 'estimated_days', and an 'object_id' used to purchase.
Select the desired rate by filtering on carrier, service level token, and estimated days; note the rate's 'object_id'.
POST to the transactions endpoint with 'rate' set to the selected rate 'object_id' and 'label_file_type' set to your preferred format (e.g., 'PDF', 'PNG', 'ZPLII'); set 'async: false' for synchronous label creation.
Retrieve 'label_url' from the transaction response for printing; store 'tracking_number' and 'tracking_url_provider' for shipment tracking.
Known gotchas
Shippo rate objects expire (verify TTL in current docs); purchase the label promptly after retrieving rates or re-create the shipment to get fresh rates.
When 'async: false' is used, response times can be several seconds depending on carrier API latency; set appropriate HTTP timeouts in your client.
Label file type availability varies by carrier and service; not all carriers support ZPL output, so verify before committing to a thermal printer workflow.
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