Obtain your ShipEngine API key from the ShipEngine dashboard; sandbox keys begin with TEST_ and should be used for all development and testing to avoid purchasing real labels.
Add the API-Key header (not Authorization Bearer) to every request: the header name is API-Key and the value is your key; omitting this header or using a different header name returns a 401 Unauthorized.
Build a JSON request body specifying shipment details: shipper and recipient address objects, parcel weight and dimensions, and the carrier_id and service_code for the desired carrier service.
POST the JSON body to https://api.shipengine.com/v1/labels; a successful response returns a label_id, tracking_number, label_download object with PDF and PNG URLs, and the shipment_cost.
Download the label from the label_download.pdf URL and transmit it to the shipping operator or print it; the label is valid immediately upon creation.
To void a label (cancel and request a refund), call PUT https://api.shipengine.com/v1/labels/{label_id}/void and check that the approved boolean in the response is true.
Known gotchas
ShipEngine uses the API-Key request header for authentication, not the Authorization header — code written for Bearer token APIs will send the wrong header name and receive a 401 error.
Production API keys purchase real labels and incur real charges immediately; always develop and test against a sandbox TEST_ key, and validate label creation logic thoroughly before switching to a production key.
Label voiding is subject to carrier-specific rules and time windows; some carriers do not permit voiding after the label has been scanned into their system — void unused labels as soon as you know they are not needed.
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