Skip to main content
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 to POST 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.
This spends money. A successful live request charges your Shippo account for the selected rate, and it cannot be undone through this API — refunds go through the Refunds API. Send dry_run: true to see which rate your rule would select, with no purchase and no charge.

The rule in beta

In this beta, every account is provisioned with exactly one rule, named default, 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 Shippo POST /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-Key header — 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.
You receive the final outcome two ways:
  • Polling — the source of truth. Call GET /automations/labels/{request_id} (the poll_url, a relative path) and read status. Use it to confirm an outcome, to reconcile a missed webhook, or on its own if you don’t run a webhook endpoint. While status is processing, the response carries a display-only message tracking 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_resolved event 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.
Both channels return the same body shape — see Outcomes.

Outcomes

A successful poll returns HTTP 200 for every outcome. Branch on status:
Detect a real purchase with status == "purchased", not dry_run == false. The dry_run field echoes what you sent; it is not the purchase outcome. Always branch on status.
A purchased response looks like this:
To track the parcel, call Retrieve a shipping label with 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.
A failed automation may have an unconfirmed purchase. When error.code is pipeline_dropped_during_purchase or pipeline_dropped_purchase_unresolved, the purchase couldn’t be confirmed. Check the account or list your shipping labels before retrying, so you don’t buy a duplicate label. transaction_failed means the purchase failed, so no label was bought.

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 the automations_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.
Verify and dedupe. Check the 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

Send dry_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

The Idempotency-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.
The decision is written once and never changes. It’s available as soon as evaluation completes — including while a live purchase is still 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 the Shippo-Auth-Signature, and dedupe on request_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: true before spending money on it.
  • Send a fresh Idempotency-Key per 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 a failed outcome.
  • Branch on status and the code fields, and tolerate codes you don’t recognize — reason and error catalogs will grow.
  • Treat a failed outcome as possibly purchased when error.code is pipeline_dropped_during_purchase or pipeline_dropped_purchase_unresolved; check your labels before retrying.
  • Expect change. Shapes may shift during beta and aren’t covered by SHIPPO-API-VERSION.

What’s not here yet

No custom or multi-rule authoring and no rule-editing endpoints. These are planned for later releases.
Last modified on October 14, 2026