Buy a label using your automation rules
Purchases a shipping label. This spends money. A successful request charges your Shippo account for the selected rate; it cannot be undone through this API (refunds go through the Refunds API).
Send dry_run: true to see which rate the rules would select, with no purchase and no charge. Automated callers should dry-run an unfamiliar shipment shape before running it live.
The request body is the standard Shippo POST /shipments create body, plus dry_run; any field that endpoint accepts is passed through unchanged.
Responds 202 with a request_id and a poll_url. Work continues asynchronously — poll GET /automations/labels/{request_id} until status reaches a terminal state (purchased, dry_run_completed, no_match, or failed).
The Idempotency-Key header is required. Repeating a live request with the same key returns a pointer to the original request instead of creating a duplicate; dry runs are never deduplicated (each dry_run request starts a new evaluation).
Authorizations
Shippo API token, sent as Authorization: ShippoToken <API_TOKEN>.
Headers
Required. A client-generated key that makes retries safe: repeating a request with the same key returns the original result instead of creating a duplicate.
1 - 255Body
The body for POST /automations/labels: the Shippo create-shipment body plus dry_run. Any field that endpoint accepts is passed through unchanged, so the shipment Shippo rates and buys is exactly the one you sent. Only the address and parcel fields are described here; for the full field list, see Create a new shipment.
An inline Shippo address. The fields every shippable address needs are required; state and zip are optional because only some countries require them. To reuse an address you already created, pass its object_id string instead. Any other valid Shippo address field (for example company, phone, email, validate) is accepted and passed through unchanged.
An inline Shippo address. The fields every shippable address needs are required; state and zip are optional because only some countries require them. To reuse an address you already created, pass its object_id string instead. Any other valid Shippo address field (for example company, phone, email, validate) is accepted and passed through unchanged.
An inline Shippo parcel. Give its dimensions one of two ways: length, width, height, and distance_unit, or a carrier package template that supplies them. weight and mass_unit are always required, because a template sets the box size but not the weight of its contents. To reuse a parcel you already created, pass its object_id string instead. Any other valid Shippo parcel field (for example metadata, extra) is accepted and passed through unchanged.
When true, evaluate rules and select a rate but do NOT purchase a label. Requires a genuine JSON boolean (no coercion).
Response
Successful Response
Returned by POST /automations/labels: a pointer to the accepted request. Repeating a live request with the same Idempotency-Key returns the original request's pointer, with status showing that request's current outcome.