> ## Documentation Index
> Fetch the complete documentation index at: https://docs.goshippo.com/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> Shippo is a multi-carrier shipping API. For agent integrations that execute shipping operations (rates, labels, tracking, address validation, customs), connect the hosted Shippo MCP server at https://mcp.shippo.com (per-user OAuth; setup at /guides/mcp-server). To search and read this documentation from an agent, a docs search MCP is available at https://docs.goshippo.com/mcp. Shipping workflow knowledge (agent skills and a knowledge pack) is published at https://github.com/goshippo/ai. For REST integrations start at /guides/api-quickstart; test mode uses shippo_test_ API keys.
# Choose your API workflow
> You've made your first API call. Find the workflow that matches how you ship, such as rate shopping, one-call labels, international, returns, batch labels, checkout rates, tracking, manifests, or voiding a label, then follow its endpoints in order.
Congratulations, you've made your first call to the Shippo API. This page helps you decide what to build next. Find the workflow that matches how you ship, then follow its endpoints in order.
Haven't made your first call yet? Start with the [API Quickstart](/guides/api-quickstart) guide to generate a token and install a client library.
## API quick reference
| Item |
Value |
| Base URL |
`https://api.goshippo.com` |
| Authentication |
`Authorization: ShippoToken YOUR_API_TOKEN` |
| Test vs. live |
Use a `shippo_test_` key to build for free. Swap to a `shippo_live_` key to go live. |
| Version pin |
`Shippo-API-Version: 2018-02-08` |
## Implementation plan
Most integrations follow the same four phases:
Get access and choose how you'll connect.
* Create an account and get your test and live API keys ([quickstart](/guides/api-quickstart))
* Connect or confirm carrier accounts
* Install an SDK or call the REST API directly
Wire up the workflow that matches how you ship.
* Pick the workflow(s) below that match how you ship
* Add address validation up front
* Store rate, transaction, and tracking IDs
Keep everyone informed once a label is bought.
* Register webhooks for tracking and labels
* Add refunds, returns, and end-of-day manifests as needed
Prove every path works, then switch to production.
* Run every path in test mode ([testing guide](/guides/testing))
* Handle errors and check `messages[]` on rates
* Swap to your live key
## Pick your workflow(s)
| If you... | Follow | Core endpoints |
| - | - | - |
| Ship domestic orders and want to compare carriers | [Rate shop and buy a label](#rate-shop-and-buy-a-label) | `/shipments` then `/transactions` |
| Always use the same carrier and service | [One-call label](#one-call-label-instalabel) | `/transactions` |
| Ship outside the US or to APO/FPO/territories | [International shipping](#international-shipping) | `/customs/items`, `/customs/declarations`, `/shipments` |
| Include or send return labels | [Returns](#returns) | `/shipments` with `is_return`, then `/transactions` |
| Print hundreds or thousands of labels at once | [Batch labels](#batch-labels) | `/batches` then `/batches/{id}/purchase` |
| Show shipping prices in your store's checkout | [Checkout rates](#checkout-rates) | `/live-rates`, `/service-groups` |
| Show delivery status to customers | [Tracking and webhooks](#tracking-and-webhooks) | `/tracks`, `/webhooks` |
| Hand off packages to the carrier at end of day | [Manifests and pickups](#manifests-and-pickups) | `/manifests`, `/pickups` |
| Cancel a label you didn't use | [Void a label](#void-a-label) | `/refunds` |
## Workflows
### Rate shop and buy a label
The standard flow for most merchants. Two calls.
1.
POST `/shipments` with `address_from`, `address_to`, and `parcels`. The response includes a `rates[]` array.
2. Pick a rate. Choose the cheapest, the fastest, or filter by rate `attributes`.
3.
POST `/transactions` with the rate's `object_id` and a `label_file_type`.
4. Save the `label_url` and `tracking_number`.
**Tip:** Validate the destination address before you request rates to avoid address-correction fees. Create it with
POST `/addresses` and use its `validate` option.
Learn more: [Generate your first label](/guides/generate-shipping-label), [Rate shopping](/shipments/rate-shopping-with-carriers), [Address validation](/addresses/address-validation)
### One-call label (Instalabel)
Use this when you already know the carrier and service level. It skips the rate step.
1.
POST `/transactions` with a nested `shipment`, plus `carrier_account` and `servicelevel_token` (for example, `usps_priority`).
2. The label and tracking number come back in the same response.
**Note:** Instalabel is only available for select carriers. Get the `carrier_account` ID from
GET `/carrier_accounts`.
Learn more: [Generate your first label](/guides/generate-shipping-label), [Carrier accounts](/carriers/carrier-accounts)
### International shipping
Use this for any shipment that clears customs.
1.
POST `/customs/items` for each product. Include description, quantity, value, weight, origin country, and HS code.
2.
POST `/customs/declarations` with the item IDs, `contents_type`, `non_delivery_option`, and `certify`.
3.
POST `/shipments` with the `customs_declaration` attached.
4.
POST `/transactions` to purchase the rate.
**Tip:** You can also nest items inside the declaration and create both in a single call.
Learn more: [International shipping](/international-shipping/international-shipping)
### Returns
Send a return label with the order, or create one on request.
1.
POST `/shipments` with `extra.is_return: true`. For USPS, FedEx, and UPS, keep the addresses in their original order: Shippo swaps them on the label. For other carriers, swap them yourself.
2.
POST `/transactions` to purchase the return rate.
**Tip:** USPS, FedEx, and UPS support scan-based returns, so you only pay when the label is used.
Learn more: [Returns](/shipments/returns)
### Batch labels
Use this for high-volume fulfillment, up to 10,000 labels per batch.
1.
POST `/batches` with `default_carrier_account`, `default_servicelevel_token`, and a `batch_shipments[]` array.
2.
GET `/batches/{id}` until `status` is `VALID`. Fix invalid rows, or remove them with
POST `/batches/{id}/remove_shipments`.
3.
POST `/batches/{id}/purchase`.
4. Listen for the `batch_purchased` webhook, then download the `label_url`.
Learn more: [Batch label creation](/shipments/batch-label-creation), [Webhooks](/tracking/webhooks)
### Checkout rates
Show shoppers real shipping prices in your cart.
1.
POST `/service-groups` to create options such as "Standard" and "Express" with flat, free, or live pricing.
2.
POST `/live-rates` with the cart's items and destination to get prices for each service group.
3. After checkout, follow [Rate shop and buy a label](#rate-shop-and-buy-a-label) for the service the shopper chose.
Learn more: [API reference](/api-reference/overview)
### Tracking and webhooks
Keep customers and your own system updated after you buy a label.
1.
POST `/webhooks` for `track_updated`. Add `transaction_created` if you want label events too.
2. Labels bought through Shippo are tracked automatically. For labels bought elsewhere,
POST `/tracks` with the carrier and tracking number.
3. To check status on demand,
GET `/tracks/{carrier}/{tracking_number}`.
**Tip:** In test mode, use the carrier `shippo` with tracking number `SHIPPO_TRANSIT` or `SHIPPO_DELIVERED` to simulate tracking events.
Learn more: [Tracking](/tracking/tracking), [Webhooks](/tracking/webhooks)
### Manifests and pickups
Hand packages off to the carrier at the end of the day.
1.
POST `/manifests` with `carrier_account`, `shipment_date`, and `address_from` to create a SCAN form (for example, for USPS).
2.
POST `/pickups` with the transaction IDs, location, and time window to schedule a pickup.
Learn more: [Manifests and SCAN forms](/manifests-and-pickups/manifest-and-scan-forms), [Pickups](/manifests-and-pickups/pickups)
### Void a label
Use this when an order is cancelled or a label was printed by mistake.
1.
POST `/refunds` with the `transaction` ID.
2.
GET `/refunds/{id}` to check status. It moves from `QUEUED` to `SUCCESS`, or to `ERROR` if the refund is rejected.
**Warning:** Refund windows vary by carrier. Don't ship a package on a refunded label.
Learn more: [Refunding labels](/billing-and-invoices/refunding-labels)