What we do
Tools
Industries
Department
How we workLet's talk →
Home/Shippo/Shippo API
Shippo

The Shippo API: Test Token, Live Token, and the Objects In Between

Shippo's API does what its dashboard does: rates across carriers, labels, tracking and address checks, called from your own code. The docs are good and a test label takes minutes. This page covers the parts people learn the slow way: what test mode won't show you, which object holds what, and how to know a webhook really came from Shippo.

shippo_test_ and shippo_live_ are two separate worlds

Every call sends Authorization: ShippoToken <your token>. Which token you send decides which data you see, and the two never mix.

shippo_test_

Test token

  • Labels are free and watermarked "SAMPLE - DO NOT MAIL".
  • Tracking numbers are generated but never update, so you can't watch a parcel move.
  • Batch labels and manifests don't work.
  • Refunds always succeed, and rates may not match what you'll pay live.
shippo_live_

Live token

  • Every label you buy is charged to the account.
  • Real tracking updates and real webhook traffic start here.
  • Carrier accounts you connected with the test token don't carry over. Shippo's own carrier accounts work in both.
  • Object IDs from test mode mean nothing here, so nothing stored from testing can be reused.

Responses carry a test flag, so log it. It's the quickest way to spot a live token in a staging server, or a test one left in production.

Which Shippo object does which job

You want to In the API Check before you rely on it
Catch a bad address before the label Create the address with validation on and read the result. Store the corrected address, not the one the shopper typed, or the next label repeats the mistake.
See prices across carriers Create a shipment with to, from and parcel. It comes back with a list of rates. Test-mode prices. Run a few of your real parcel sizes on the live token before you set shipping charges.
Buy the label POST to /transactions with the chosen rate's object_id. The transaction holds the label_url and tracking number. The transaction's status and messages. A call that returns isn't the same as a label that exists.
Skip the rate step when you already know the service Instalabel: one transaction call with the shipment, the carrier account and a service level token such as usps_priority. Only some carriers support it. Check Shippo's carrier capabilities list first.
Ship many orders at once A batch. It is built in the background, and batch_created then batch_purchased tell you when each stage is done. Batches don't run in test mode, so the first real run is in production. Start small.

Shippo webhooks: what to sort before going live

Events are transaction_created, transaction_updated, track_updated, batch_created and batch_purchased, or all of them. Shippo also creates a tracking webhook for each label you buy.

Anyone who finds the URL can post to it

How you'll know: Your endpoint accepts any JSON that looks like a Shippo payload, with no check on who sent it.

Fix: Shippo offers three options: allowlist its published IP ranges, add your own secret token to the webhook URL and compare it on arrival, or ask Shippo's account team for HMAC signing, which can take up to ten business days to set up. Use at least one from day one.

Slow handlers look like failures

How you'll know: Some events turn up twice, others never, and your logs show long request times.

Fix: Shippo expects a 2XX within three seconds and retries twice on a slow answer or a 408, 429 or 5XX. Store the event, reply, and do the order update afterwards. Skip any event you've already processed.

A 4XX quietly drops the event

How you'll know: A validation bug in your handler returns 400, and that shipment's update is simply gone.

Fix: Shippo doesn't retry other 4XX codes. Return 2XX for anything you received intact, even if you then park it for a person to look at.

Tracking tests that can't pass

How you'll know: You're waiting for track_updated in test mode and it never arrives.

Fix: Test tracking numbers don't update. Use the sample payload in the Shippo API portal to exercise your handler, then confirm on one real live label.

AI assistants, MCP, and where n-frames comes in

Shippo now hosts its own MCP server at mcp.shippo.com. You sign in with your Shippo account, and an assistant such as Claude or ChatGPT can compare rates, validate addresses and buy labels, asking you to confirm before anything is bought. It has no test mode, so every label it buys is real. That's handy for one-off shipments by a person. It isn't a replacement for your order system calling the API on its own.

That second part is the work n-frames does: the label bought when an order is ready, the carrier picked by your own rule (declared value, delivery promise, a preferred account), customs data filled from your catalog, and each track_updated event written back to the order and the customer email. Running WooCommerce? See Shippo and WooCommerce. Comparing label APIs? EasyPost's API is the nearest alternative, and if staff buy labels by hand today, Shippo vs Pirate Ship covers when an API is worth it at all.

Questions people ask

Where are Shippo's API docs?

At docs.goshippo.com. They cover authentication, addresses, shipments, rates, transactions, batches, tracking, webhooks, carrier accounts and per-endpoint rate limits, plus guides for individual carriers.

How much does Shippo's API cost?

The API uses your Shippo account, so you pay what that account pays: the plan you're on and the postage for each label bought on the live token. Shippo's pricing page has the current numbers. Test labels cost nothing.

Does Shippo have a status page?

Yes, at status.goshippo.com. It reports the REST API, the dashboard and the platform API separately, and lists each carrier connection, so you can tell a UPS outage from a bug in your own code.

Does Shippo support webhooks?

Yes. You can set them up in the Shippo API portal or through its Webhooks API, which Shippo marks as beta. Events cover transactions, tracking and batches, and a tracking webhook is created for each label you buy.

Does Shippo have an MCP server for connecting AI agents?

Yes, a hosted one at mcp.shippo.com. You connect an MCP client, sign in with your Shippo account, and it can rate, validate and buy labels with a confirmation step. It only works on live data. For testing, call the API with a shippo_test_ token instead.

What's the difference between Shippo's test and live API tokens?

Test tokens start with shippo_test_ and live ones with shippo_live_. Test labels are free and can't be shipped, test tracking doesn't update, and batches don't run. Data created with one token can't be seen with the other.

Who builds a Shippo API integration for us?

If your developers are tied up, n-frames takes it on: from the first live label through carrier rules, customs data, webhook security and tracking written back to the order, and the monitoring that flags when a carrier stops returning rates.

Let's talk

Tell us the one thing your team does manually that eats up time. We read every message and reply within a day.