The Automations API is in beta. Request and response shapes may change without the notice period that applies to generally available Shippo endpoints, and they are not yet covered by the
SHIPPO-API-VERSION header. Breaking changes are announced to enrolled accounts before they ship — pin nothing in production you can’t redeploy.Buy the right label in one call
Shipping a parcel through the Shippo API takes four steps today: create a shipment, fetch rates, compare them against your own logic, then buy the label. The Automations API collapses that into one request. You send the shipment, Shippo applies your rule, selects the rate, and buys the label. One call toPOST https://api.goshippo.com/automations/labels does all four. Authenticate with Authorization: ShippoToken <API_TOKEN>. A missing or invalid token returns 401. If Automations isn’t enabled for your account, every endpoint returns 403; contact Shippo API Support.
The rule in beta
In this beta, every account is provisioned with exactly one rule, nameddefault, which selects the lowest-cost eligible rate for the shipment. The rule is created for you the first time you call the API — there’s nothing to configure, and there’s no endpoint for authoring or editing rules yet. Customer-defined rules are planned for a later release.
Service levels the rule never selects
The rule never selects the service levels below, even when one is the cheapest rate. Each is limited to certain contents, senders, or mail types that Automations can’t check. A label bought for a shipment that doesn’t qualify still goes through, and USPS can charge postage due or return the package later.
These rates are removed before the rule runs, so they don’t appear in the decision’s
rule_trace. If every rate returned for a shipment is excluded, the request ends in no_match with reason.code all_rates_excluded. To ship with one of these service levels, buy the label directly with Create a shipping label.
The request
The request body is the standard ShippoPOST /shipments create body, plus dry_run. Any field that endpoint accepts is passed through unchanged, so the shipment you send is the shipment Shippo rates and buys. Addresses and parcels can be sent inline or as existing Shippo object IDs.
Two things are required on every call:
Idempotency-Keyheader — a client-generated key, 1–255 characters, that makes retries safe. More on this below.address_from,address_to,parcels— the minimum a shippable shipment needs.
It’s asynchronous
The purchase doesn’t happen inside the request.POST /automations/labels responds 202 immediately with a request_id and a poll_url, then does the work — fetch rates → evaluate your rule → purchase — in the background.
- Polling — the source of truth. Call
GET /automations/labels/{request_id}(thepoll_url, a relative path) and readstatus. Use it to confirm an outcome, to reconcile a missed webhook, or on its own if you don’t run a webhook endpoint. Whilestatusisprocessing, the response carries a display-onlymessagetracking the stage (“Fetching rates.”, “Evaluating rules.”, “Purchasing label.”); don’t branch on it. Polling is read-only and safe to repeat. - Webhooks — an optional push. Subscribe to the
automations_label_resolvedevent to be notified when a request reaches a terminal state, so you don’t have to poll as often. Failed deliveries aren’t retried, so confirm outcomes by polling. See Webhooks.
Outcomes
A successful poll returns HTTP200 for every outcome. Branch on status:
A purchased response looks like this:
transaction_id. The label includes tracking_status and the carrier’s tracking link in tracking_url_provider.
selected_rate.carrier is the selected rate’s carrier name (its provider, such as USPS), and selected_rate.service_level is its service-level token, such as usps_priority.
When nothing is selected: no_match
no_match is a non-error outcome — your rule and fallback simply didn’t pick a rate. The reason.code tells you why. Branch on the code, not the message, and tolerate codes not listed here.
When it breaks: failed
Only failed responses include an error. Branch on error.code and tolerate additional codes — the catalog will grow.
Webhooks
Webhooks are a convenience on top of polling: they tell you when a request finishes so you don’t have to poll as often. Subscribe to theautomations_label_resolved event in the Shippo API Portal or with the Webhooks API — an all wildcard subscription receives it too. The SDK event enums don’t include it, so SDK users subscribe through the API.
One event, every outcome. Each request produces one automations_label_resolved event, when it reaches a terminal state — purchased, dry_run_completed, no_match, or failed. In-progress states never fire.
Delivery. Delivery is best effort. If a delivery fails, including a timeout or a 5XX from your endpoint, Shippo doesn’t retry it; the retries in Expected webhook behavior don’t apply to this event. Deliveries can arrive out of order, and the same event can occasionally be delivered more than once. Polling is the source of truth: if a webhook and a poll disagree, trust the poll.
The payload is the terminal result, field for field. The event’s data is exactly what GET /automations/labels/{request_id} returns for that outcome — same status, reason, error, and selected_rate. Read the outcome from data.status, and detect a dry run from data.dry_run (never from status). The rule trace, poll_url, and any event id are not included.
Accounts on API version 2017-03-29 or older receive the result itself, without the event, test, and data wrapper, so read status, dry_run, and request_id at the top level.
Shippo-Auth-Signature on every delivery before trusting it (see Webhook security). Treat data.request_id as the idempotency key, and reconcile anything you didn’t receive by polling GET /automations/labels for terminal requests with no matching delivery. The test field reflects whether the request used a test token and is unrelated to dry_run.
A successful purchase also fires transaction_created. Because Automations buys the label through the normal Transactions path, a purchased request triggers your existing transaction_created webhook in addition to automations_label_resolved. If you subscribe to both, you’ll receive two events for one successful purchase — dedupe on request_id.
Dry runs
Senddry_run: true to evaluate your rule and select a rate without purchasing or charging. The request runs through rate-fetching and rule evaluation, then stops — it ends in dry_run_completed (or no_match / failed if selection couldn’t complete). Automated callers should dry-run an unfamiliar shipment shape before running it live.
dry_run must be a genuine JSON boolean (no string coercion). Dry runs are never deduplicated — each one starts a fresh evaluation, even with a repeated Idempotency-Key.
Idempotency
TheIdempotency-Key header is required on every request. For a live request, repeating the same key returns a pointer to the original request instead of creating a duplicate purchase, which makes it safe to retry after a network blip. Keys don’t expire and the request body isn’t compared, so a repeated key always returns the original request, even if the body changed or the original request failed. To try again after a failed outcome, use a new key. Dry runs are never deduplicated.
The decision record — “why this carrier, why this price”
Every request keeps a decision record.GET /automations/labels/{request_id}/decision returns the rule that matched, the rate selected, the facts the engine evaluated, and the full rule trace — the audit answer to “why this carrier, why this price,” without building and instrumenting your own rate-comparison logic.
processing. If evaluation hasn’t written a decision yet, /decision returns 409; an unknown request_id returns 404.
Because beta runs a single always-matching rule, fallback_triggered is always false. The matched_priority and fallback_triggered fields describe ordering and fallback behavior that become meaningful once customer-defined rules ship.
Listing requests
GET /automations/labels lists your label-purchase requests, newest first — a management view for dashboards and reconciliation. It returns a page of flat summaries plus a next link (an opaque cursor; null on the last page).
Filter with shipment_id, tracking_number, status, and dry_run. Filters are AND-combined and preserved across pages by the next link. Page size is 1–100 (default 25).
Before you go live
- Subscribe to
automations_label_resolved, verify theShippo-Auth-Signature, and dedupe onrequest_id. Failed deliveries aren’t retried, so poll to reconcile anything you miss; polling is the source of truth. - Dry-run first. Validate an unfamiliar shipment shape with
dry_run: truebefore spending money on it. - Send a fresh
Idempotency-Keyper logical purchase. Reuse it verbatim when retrying the same request after a network error so a blip can’t double-charge you, and use a new key to try again after afailedoutcome. - Branch on
statusand thecodefields, and tolerate codes you don’t recognize — reason and error catalogs will grow. - Treat a
failedoutcome as possibly purchased whenerror.codeispipeline_dropped_during_purchaseorpipeline_dropped_purchase_unresolved; check your labels before retrying. - Expect change. Shapes may shift during beta and aren’t covered by
SHIPPO-API-VERSION.