Skip to main content
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 guide to generate a token and install a client library.

​
API quick reference

ItemValue
Base URLhttps://api.goshippo.com
AuthenticationAuthorization: ShippoToken YOUR_API_TOKEN
Test vs. liveUse a shippo_test_ key to build for free. Swap to a shippo_live_ key to go live.
Version pinShippo-API-Version: 2018-02-08

​
Implementation plan

Most integrations follow the same four phases:

Set up

Get access and choose how you’ll connect.
  • Create an account and get your test and live API keys (quickstart)
  • Connect or confirm carrier accounts
  • Install an SDK or call the REST API directly

Build your core flow

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

Handle post-purchase

Keep everyone informed once a label is bought.
  • Register webhooks for tracking and labels
  • Add refunds, returns, and end-of-day manifests as needed

Test and go live

Prove every path works, then switch to production.
  • Run every path in test mode (testing guide)
  • Handle errors and check messages[] on rates
  • Swap to your live key

​
Pick your workflow(s)

​
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, Rate shopping, 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, 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

​
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

​
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, 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 for the service the shopper chose.

Learn more: API reference

​
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, 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, 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

Last modified on October 13, 2026