A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Shippo API is how an app or AI agent works with a Shippo account: validating an address, comparing carrier rates for a shipment, buying a shipping label, and tracking a parcel. Access is granted through an API token that carries the full access of the account it belongs to, with no granular per-endpoint scopes, so the only built-in boundary is live versus test mode. Shippo versions its API by date and can push tracking and label events to a registered endpoint.
How an app or AI agent connects to Shippo determines what it can reach. There is a route for making calls, a route for receiving tracking and label events, and a hosted server that exposes Shippo tools to agents, and each is governed by the API token behind it.
The REST API takes JSON request bodies and returns JSON, at https://api.goshippo.com. A call authenticates with an API token sent as Authorization: ShippoToken
Shippo publishes a first-party Model Context Protocol server. A hosted version at https://mcp.shippo.com authenticates with OAuth sign-in to a Shippo account, and a local version, the npm package @shippo/shippo-mcp, runs over stdio and authenticates with a ShippoToken API key. It exposes Shippo operations to AI agents, including address validation, rate comparison, label generation, tracking, returns, customs, batches, and manifests.
Shippo POSTs an event to an HTTPS URL registered through the Webhooks API or the dashboard. A track_updated event carries the Tracking object and a transaction_created event carries the Transaction object, so an integration learns about tracking changes and bought labels without polling. Batch events report when a batch is created or finished purchasing.
Shippo authenticates a call with an API token sent in the Authorization header as ShippoToken
The hosted MCP server at https://mcp.shippo.com uses OAuth sign-in to a Shippo account instead of a raw token, so an agent connects by authorizing rather than by holding a long-lived key. The resulting access still acts on the whole account the user signed in with.
The Shippo API is split into areas an agent can act on, like addresses, parcels, shipments, rates, labels, tracking, and refunds. Each area has its own methods, and writes in some areas buy a real label or move money.
Methods for creating, listing, retrieving, and validating addresses.
Methods for working with parcels, the size and weight of what is shipped.
Methods for creating, listing, and retrieving shipments.
Methods for retrieving carrier rates for a shipment.
Methods for buying and retrieving shipping labels.
Methods for getting tracking status and registering a tracking webhook.
Methods for refunding the cost of a purchased, unused label.
Methods for customs declarations and items used on international shipments.
Methods for connecting and configuring carrier accounts.
Methods for buying many labels at once in a batch.
Methods for working with orders synced from a store.
Methods for creating end-of-day manifests that close out shipments.
Methods for registering and managing webhook endpoints.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
AddressesMethods for creating, listing, retrieving, and validating addresses.4 | ||||||
| POST | /addresses | Create a new address object, optionally validating it on creation. | write | API token | Current | |
A Shippo token grants access to the whole account; it has no per-endpoint scopes. Acts onaddress Permission (capability) API tokenVersionAvailable since the API’s base version Webhook eventNone Rate limit500/min live, 50/min test SourceOfficial documentation ↗ | ||||||
| GET | /addresses | List all address objects on the account. | read | API token | Current | |
Read-only. Acts onaddress Permission (capability) API tokenVersionAvailable since the API’s base version Webhook eventNone Rate limit50/min live, 10/min test SourceOfficial documentation ↗ | ||||||
| GET | /addresses/{AddressId} | Retrieve an existing address by object ID. | read | API token | Current | |
Read-only. Acts onaddress Permission (capability) API tokenVersionAvailable since the API’s base version Webhook eventNone Rate limit4000/min live, 400/min test SourceOfficial documentation ↗ | ||||||
| GET | /addresses/{AddressId}/validate | Validate an existing address against carrier records. | read | API token | Current | |
Read-only; returns validation_results on the address. Acts onaddress Permission (capability) API tokenVersionAvailable since the API’s base version Webhook eventNone Rate limit4000/min live, 400/min test SourceOfficial documentation ↗ | ||||||
ParcelsMethods for working with parcels, the size and weight of what is shipped.2 | ||||||
| POST | /parcels | Create a new parcel object describing the size and weight of what is shipped. | write | API token | Current | |
A core write. Acts onparcel Permission (capability) API tokenVersionAvailable since the API’s base version Webhook eventNone Rate limit500/min live, 50/min test SourceOfficial documentation ↗ | ||||||
| GET | /parcels | List all parcel objects on the account. | read | API token | Current | |
Read-only. Acts onparcel Permission (capability) API tokenVersionAvailable since the API’s base version Webhook eventNone Rate limit50/min live, 10/min test SourceOfficial documentation ↗ | ||||||
ShipmentsMethods for creating, listing, and retrieving shipments.3 | ||||||
| POST | /shipments | Create a shipment from a sender, recipient, and parcel, which generates the available rates. | write | API token | Current | |
The central object; its returned rates array is the input to buying a label. Acts onshipment Permission (capability) API tokenVersionAvailable since the API’s base version Webhook eventNone Rate limit500/min live, 50/min test SourceOfficial documentation ↗ | ||||||
| GET | /shipments | List all shipment objects on the account. | read | API token | Current | |
Read-only. Acts onshipment Permission (capability) API tokenVersionAvailable since the API’s base version Webhook eventNone Rate limit50/min live, 10/min test SourceOfficial documentation ↗ | ||||||
| GET | /shipments/{ShipmentId} | Retrieve an existing shipment by object ID. | read | API token | Current | |
Read-only. Acts onshipment Permission (capability) API tokenVersionAvailable since the API’s base version Webhook eventNone Rate limit4000/min live, 400/min test SourceOfficial documentation ↗ | ||||||
RatesMethods for retrieving carrier rates for a shipment.2 | ||||||
| GET | /shipments/{ShipmentId}/rates | Retrieve the carrier rates generated for a shipment, the basis for rate shopping. | read | API token | Current | |
Read-only. Acts onrate Permission (capability) API tokenVersionAvailable since the API’s base version Webhook eventNone Rate limit4000/min live, 400/min test SourceOfficial documentation ↗ | ||||||
| GET | /rates/{RateId} | Retrieve a single rate by object ID. | read | API token | Current | |
Read-only. Acts onrate Permission (capability) API tokenVersionAvailable since the API’s base version Webhook eventNone Rate limit4000/min live, 400/min test SourceOfficial documentation ↗ | ||||||
Transactions (Labels)Methods for buying and retrieving shipping labels.3 | ||||||
| POST | /transactions | Buy a shipping label, by passing a rate object ID or instant shipment details. | write | API token | Current | |
Charges the account and returns a label_url; the spend-money write. Acts ontransaction Permission (capability) API tokenVersionAvailable since the API’s base version Webhook event transaction_createdRate limit500/min live, 50/min test SourceOfficial documentation ↗ | ||||||
| GET | /transactions | List all transactions (purchased labels) on the account. | read | API token | Current | |
Read-only. Acts ontransaction Permission (capability) API tokenVersionAvailable since the API’s base version Webhook eventNone Rate limit50/min live, 10/min test SourceOfficial documentation ↗ | ||||||
| GET | /transactions/{TransactionId} | Retrieve a transaction (label) by object ID, including its label and tracking URLs. | read | API token | Current | |
Read-only. Acts ontransaction Permission (capability) API tokenVersionAvailable since the API’s base version Webhook eventNone Rate limit4000/min live, 400/min test SourceOfficial documentation ↗ | ||||||
TrackingMethods for getting tracking status and registering a tracking webhook.2 | ||||||
| GET | /tracks/{Carrier}/{TrackingNumber} | Get the current tracking status of a shipment by carrier and tracking number. | read | API token | Current | |
Read-only. Acts ontrack Permission (capability) API tokenVersionAvailable since the API’s base version Webhook eventNone Rate limit500/min live, 50/min test SourceOfficial documentation ↗ | ||||||
| POST | /tracks | Register a carrier and tracking number for tracking updates, delivered by webhook. | write | API token | Current | |
Subscribes a tracking number, so future updates fire track_updated. Acts ontrack Permission (capability) API tokenVersionAvailable since the API’s base version Webhook event track_updatedRate limit750/min live, 50/min test SourceOfficial documentation ↗ | ||||||
RefundsMethods for refunding the cost of a purchased, unused label.2 | ||||||
| POST | /refunds | Request a refund for a purchased, unused shipping label. | write | API token | Current | |
Refundable only while the label is unused; carrier rules apply. Acts onrefund Permission (capability) API tokenVersionAvailable since the API’s base version Webhook eventNone Rate limit500/min live, 50/min test SourceOfficial documentation ↗ | ||||||
| GET | /refunds | List all refund objects on the account. | read | API token | Current | |
Read-only. Acts onrefund Permission (capability) API tokenVersionAvailable since the API’s base version Webhook eventNone Rate limit50/min live, 10/min test SourceOfficial documentation ↗ | ||||||
CustomsMethods for customs declarations and items used on international shipments.2 | ||||||
| POST | /customs/declarations | Create a customs declaration for an international shipment. | write | API token | Current | |
Requires certify, certify_signer, contents_type, non_delivery_option, and items. Acts oncustoms_declaration Permission (capability) API tokenVersionAvailable since the API’s base version Webhook eventNone Rate limit500/min live, 50/min test SourceOfficial documentation ↗ | ||||||
| POST | /customs/items | Create a customs item, a line in a customs declaration. | write | API token | Current | |
A core write; referenced by a customs declaration. Acts oncustoms_item Permission (capability) API tokenVersionAvailable since the API’s base version Webhook eventNone Rate limit500/min live, 50/min test SourceOfficial documentation ↗ | ||||||
Carrier AccountsMethods for connecting and configuring carrier accounts.2 | ||||||
| POST | /carrier_accounts | Connect a new carrier account so its rates and services become available. | write | API token | Current | |
Adds a carrier connection to the account. Acts oncarrier_account Permission (capability) API tokenVersionAvailable since the API’s base version Webhook eventNone Rate limit500/min live, 50/min test SourceOfficial documentation ↗ | ||||||
| PUT | /carrier_accounts/{CarrierAccountId} | Update an existing carrier account; the account_id and carrier cannot be changed. | write | API token | Current | |
Changes carrier configuration; identity fields are immutable. Acts oncarrier_account Permission (capability) API tokenVersionAvailable since the API’s base version Webhook eventNone Rate limit500/min live, 50/min test SourceOfficial documentation ↗ | ||||||
BatchesMethods for buying many labels at once in a batch.3 | ||||||
| POST | /batches | Create a batch grouping many shipments for a single bulk label purchase. | write | API token | Current | |
Creating the batch does not buy labels; purchasing it does. Acts onbatch Permission (capability) API tokenVersionAvailable since the API’s base version Webhook event batch_createdRate limit50/min live, 10/min test SourceOfficial documentation ↗ | ||||||
| POST | /batches/{BatchId}/add_shipments | Add shipments to an existing batch. | write | API token | Current | |
Only allowed while the batch has not been purchased. Acts onbatch Permission (capability) API tokenVersionAvailable since the API’s base version Webhook eventNone Rate limit50/min live, 10/min test SourceOfficial documentation ↗ | ||||||
| POST | /batches/{BatchId}/purchase | Purchase every label in a VALID batch, moving its status to PURCHASING. | write | API token | Current | |
Buys every label in the batch and charges the account. Acts onbatch Permission (capability) API tokenVersionAvailable since the API’s base version Webhook event batch_purchasedRate limit50/min live, 10/min test SourceOfficial documentation ↗ | ||||||
OrdersMethods for working with orders synced from a store.2 | ||||||
| POST | /orders | Create an order object representing a customer's purchase to be fulfilled. | write | API token | Current | |
A core write. Acts onorder Permission (capability) API tokenVersionAvailable since the API’s base version Webhook eventNone Rate limit500/min live, 50/min test SourceOfficial documentation ↗ | ||||||
| GET | /orders | List all order objects on the account. | read | API token | Current | |
Read-only. Acts onorder Permission (capability) API tokenVersionAvailable since the API’s base version Webhook eventNone Rate limit50/min live, 10/min test SourceOfficial documentation ↗ | ||||||
ManifestsMethods for creating end-of-day manifests that close out shipments.1 | ||||||
| POST | /manifests | Create an end-of-day manifest that closes out a set of shipments for a carrier account. | write | API token | Current | |
A core write tied to a carrier account. Acts onmanifest Permission (capability) API tokenVersionAvailable since the API’s base version Webhook eventNone Rate limit500/min live, 50/min test SourceOfficial documentation ↗ | ||||||
WebhooksMethods for registering and managing webhook endpoints.2 | ||||||
| POST | /webhooks | Register a webhook URL to receive event notifications. | write | API token | Current | |
Sets where Shippo POSTs events; choose event types or all. Acts onwebhook Permission (capability) API tokenVersionAvailable since the API’s base version Webhook eventNone Rate limit500/min live, 50/min test SourceOfficial documentation ↗ | ||||||
| GET | /webhooks | List all registered webhooks on the account. | read | API token | Current | |
Read-only. Acts onwebhook Permission (capability) API tokenVersionAvailable since the API’s base version Webhook eventNone Rate limit50/min live, 10/min test SourceOfficial documentation ↗ | ||||||
Shippo can notify an app when something happens to a shipment, like a tracking status changing or a label being bought. It sends the object that changed, so an integration learns about activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
track_updated | A tracking status changed for a subscribed shipment. The request body is the Tracking object with the new status. | /tracks |
transaction_created | A transaction was created, meaning a label was bought. The request body is the Transaction object. | /transactions |
batch_created | A batch finished being created and validated. The request body is the Batch object. | /batches |
batch_purchased | A batch finished purchasing its labels. The request body is the Batch object. | /batches/{BatchId}/purchase |
Shippo limits how fast an app can call, by a per-minute request rate that differs by endpoint and by whether the call runs against a live or test token.
Shippo meters requests per minute, and the limit depends on the endpoint and the kind of call. On a live token, creating most objects (address, parcel, shipment, transaction, customs, refund, manifest, carrier account) allows 500 requests per minute, retrieving a single object by ID allows 4000 per minute, and listing allows 50 per minute. Tracking allows 750 creates per minute, and batch operations are lower at 50 per minute. A test token gets roughly a tenth of each limit. Going over returns HTTP 429. The reference does not document any rate-limit response headers.
List endpoints are paginated with results parameters and next and previous links in the response, so an integration walks pages rather than pulling everything at once. List calls carry the lowest rate limit, 50 per minute on a live token, so they are meant to be paged deliberately, not polled in a tight loop.
The reference does not publish a maximum page size or request body size limit; the binding constraint in practice is the per-minute rate limit for each endpoint.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | Bad Request | The request was not accepted, usually because a parameter is missing or invalid. | Read the messages array in the response, fix the parameters, and resend. |
| 401 | Unauthorized | No token was provided or the token does not exist, for example detail: Token does not exist. | Send a valid live or test token in the Authorization: ShippoToken header. |
| 404 | Not Found | The requested resource does not exist. | Verify the object ID and that it belongs to the same account and mode. |
| 409 | Conflict | There was a conflict in the request. | Resolve the conflicting state and retry. |
| 422 | Unprocessable Entity | The request contained content that could not be processed by the Shippo API. | Inspect the returned messages and correct the request body. |
| 429 | Rate Limit Exceeded | Too many requests were made to the Shippo API within a minute. | Slow the request rate to the per-minute limit for that endpoint and retry with backoff. |
| 500 | Server Error | Something went wrong on the Shippo server. May appear as other 5xx codes. | Retry with backoff, and contact Shippo support if it persists. |
Shippo versions its API by date, and a request pins a version with a header so a change to the format never breaks an existing integration without warning.
Shippo versions its API by date. 2018-02-08 is the current default version this reference documents, pinned per request with the Shippo-API-Version header. Pinning a dated version means a later format change does not break an existing integration until it moves up. Older integrations can stay on a legacy version documented separately.
Shippo has shipped earlier dated API versions before 2018-02-08, documented in a separate legacy reference guide. An older integration can continue to send an earlier version date in the Shippo-API-Version header.
Pin a dated version and move up when ready.
Shippo API changelog ↗Bollard AI sits between a team's AI agents and Shippo. Grant each agent exactly the access it needs, read or write, action by action, and every call is checked and logged.