Shippo

Shippo

This connector works with one Shippo account through the Shippo API (https://api.goshippo.com): addresses and validation, parcels, shipments with live rates from your carriers, buying labels, tracking, carrier accounts, customs declarations, label refunds and manifests (scan forms).

Setup (about 3 minutes)

1. Sign up at https://apps.goshippo.com/join (free) and open the API portal: https://portal.goshippo.com/api-config/api → API Configuration → Developer keys.
2. Click Create new test key (or Create new live key) and copy it at once; it is shown only once. Test keys start with shippo_test_, live keys with shippo_live_.
3. Paste it into SHIPPO_API_TOKEN and install. shippo_list_carrier_accounts should list Shippo's own carrier accounts (for example USPS), which are ready to use in the US.

Test or live: the key decides. With a test key labels are free, watermarked "SAMPLE - DO NOT MAIL", tracking numbers never update, refunds always succeed, and manifests and batches are not available. A test key sees only test data and a live key only live data. Carrier accounts you connect with your own carrier credentials work only in the mode in which they were added.

Buying a label costs money: confirm first. With a live key shippo_buy_label charges the label price (plus any insurance) to the Shippo account at once. Before calling it, state carrier, service, price and both addresses and wait for the user's yes. shippo_request_refund voids a label (it can no longer be used) and asks the carrier for the money back; only unused labels up to 90 days old qualify, and the refund itself takes days to weeks.

Typical flow

1. shippo_create_shipment with address_from, address_to and parcels (objects or saved object_ids) returns rates[]: each with object_id, amount, currency, provider, servicelevel.name, estimated_days.
2. Pick a rate with the user, then shippo_buy_label with its object_id. The answer has tracking_number, tracking_url_provider and label_url (a signed link to the PDF that expires; read the label again with shippo_get_label for a fresh one).
3. Follow the parcel with shippo_get_tracking (the carrier token as Shippo names it, such as usps, ups, fedex or dhl_express; shippo_list_carrier_accounts shows the tokens, plus the tracking number). In test mode use carrier shippo with tracking number SHIPPO_TRANSIT, SHIPPO_DELIVERED, SHIPPO_RETURNED or SHIPPO_FAILURE.

International shipments need a customs declaration: create items with shippo_create_customs_item (description, quantity, net weight, value, origin country, tariff number), then shippo_create_customs_declaration with those items, contents_type, non_delivery_option, certify: true and certify_signer, and pass its object_id as customs_declaration to shippo_create_shipment.

Units and formats: dimensions and weights are strings with their units ("length": "30", "distance_unit": "cm", "weight": "1.2", "mass_unit": "kg"). Countries are ISO 2 codes (DE, US). Dates are ISO 8601 (2026-10-12T09:00:00Z).

Waiting for results: the shipment, label, refund and manifest tools wait for the result by default (async: false). If Shippo answers with status QUEUED or WAITING, read the object again a few seconds later. A label with status ERROR explains why in messages[].

Address validation: shippo_create_address with validate: true (or shippo_validate_address on a saved address) returns validation_results.is_valid and messages. shippo_validate_address saves the checked, standardized address as a new object with its own object_id and leaves the original untouched, so ship to the new id. With a test key, addresses outside the US are echoed back without being checked; with a live key, validating them is charged.

API version: no SHIPPO-API-VERSION header is sent, so the account's default version applies. Sending one would also change the version for later calls of the whole account.

Rate limits per minute: 500 creates and 4,000 reads of single objects, but only 50 list calls (10 with a test key); prefer reading single objects by id over paging through lists.

Common errors

• 401 Token does not exist: wrong or deleted key; create a new one in the API portal.
• 400: a field is missing or invalid; the body names it (for example an address that the carrier rejects).
• 422 / status: ERROR with messages[]: the carrier refused, for example an unsupported service for that route or missing customs data.
• 429: over the rate limit; wait a minute.

Out of scope here: batches, orders, pickups, webhooks other than tracking registration, connecting carrier accounts and the v2 address API.