App guides
The Shippo app shows your customers live Shippo carrier rates at checkout, and sends paid orders to Shippo's Orders page, where you buy labels. When a label is bought, the app fulfills the order in Swell with the carrier and tracking number.
Rates come from the carrier accounts in your Shippo account, your own or Shippo's built-in ones.
| When | What the app does |
| A customer enters a shipping address at checkout | Asks Shippo for rates for one parcel and shows each service as a shipping option. |
| An order is paid, or submitted if you choose | Creates the order on Shippo's Orders page, with the address, items, weights and the service the customer chose. |
| Every 15 minutes | Checks up to 10 orders waiting for a label, and fulfills each one that has a label with the carrier and tracking number. |
| You choose Send to Shippo on an order | Sends that order to Shippo, for example a recent order placed before the app was installed. |
- A Shippo account with at least one active carrier account, your own or one of Shippo's.
- Shipping weights on your products, so rates and orders have the right weight.
Install Shippo from the Swell App Store, and set it up in your test environment before the live one.
Copy an API token
In Shippo, go to Settings > Advanced > API and copy a token. Use the test token, which starts with shippo_test_, in your Swell test environment, and the live token, which starts with shippo_live_, in live.
Add it to the app
In Swell, go to Apps > Shippo > Settings and enter the API token. On the Ship-from address tab, enter the address your parcels ship from: at least the street, city, postal code and country code, and the state code where carriers need it, such as in the US and Canada. On the Default parcel tab, check the box size and default weight. Click Save settings.
Test the connection
Choose Actions > Test connection. The message says whether Shippo accepted the token, lists your active carriers, and flags a missing ship-from address. Ignore its note about a webhook secret: the webhook isn't supported yet.
Turn on checkout rates
Go to Settings > Shipping, turn on Shippo and click Save changes. Rates appear at checkout only after this step.
Place a test order
Add an item to a cart and enter a shipping address. Shippo rates appear among the shipping options. Place and pay the order: it appears on Shippo's Orders page, and its Shippo tab in Swell says Awaiting label. Buy a label for it in Shippo. Within 15 minutes, or right away with Actions > Check for labels now in the app settings, the order gets a shipment with the tracking number.
Go live
Settings are saved separately for each environment. In the live environment, repeat steps 2 to 4 with your live token.
When a cart's shipping address or items change, the app asks Shippo for rates from your ship-from address to the customer's, for one parcel with the default dimensions. The weight is the sum of the items' shipping weights, or the default weight when no item has one. Each Shippo service becomes a shipping option, named like USPS Priority Mail, with the estimated delivery days.
- Limit the rates with Carrier accounts and Service levels, and add a Markup (%) and a Handling fee to each rate.
- A rate is shown only when Shippo quotes it in the cart's currency.
- Your other shipping services, Swell's own or other apps', stay at checkout alongside Shippo's.
When an order is paid, or submitted if Send orders when is set to that, the app creates it on Shippo's Orders page with the shipping and ship-from addresses, the items with their SKUs, prices and weights, the totals and the service the customer chose. Each order is sent once. Canceled orders and orders with nothing to ship aren't sent. If Shippo has an error or doesn't answer, Swell sends the order again; other errors are shown in Error on the order's Shippo tab. To send an order placed before the app was installed, or one that failed to send, open it and choose Actions > Send to Shippo.
Buy the label on Shippo's Orders page. Every 15 minutes the app checks up to 10 orders waiting for a label, those checked longest ago first, so with many orders waiting it can take a few checks. When it finds a purchased label, it creates a Swell shipment for everything still to ship, with the carrier, service and tracking number, and the order shows Label created. To check right away, choose Actions > Check for labels now in the app settings. With Create Swell shipment when a label is bought off, the label and tracking are saved on the order's Shippo tab but the order isn't fulfilled.
| Where | What it's for |
| Apps > Shippo > Settings | The API token, ship-from address, checkout rates, default parcel, and orders and labels settings, with Test connection and Check for labels now. |
| Settings > Shipping | Turns Shippo rates at checkout on or off. |
| The order list | A Shippo column with each order's status: Awaiting label, Label created or Error. |
| An order's Shippo tab | The status, Shippo order ID, carrier, service, tracking number, tracking page, label link, when it was last checked for a label, and the last error. |
| An order's Actions menu | Send to Shippo. |
Settings are in Apps > Shippo > Settings and are saved separately for each environment.
| Setting | Description | Default |
| API token | From Shippo > Settings > Advanced > API. Use a shippo_test_ token in test and a shippo_live_ token in live. Masked on the settings page. Required. | None |
| Enabled | Turns off checkout rates, automatic order sending and the automatic label check without uninstalling the app. Send to Shippo and Check for labels now still work. | On |
| Ship-from address | Name, company, street, city, state or province code, postal code, 2-letter country code, phone and email. Street, city, postal code and country are needed for rates. Some carriers need a phone number to buy a label. | None |
| Show Shippo rates at checkout | Turns checkout rates off while orders are still sent. | On |
| Carrier accounts | Optional. Shippo carrier account object IDs to quote, separated by commas. | All active accounts |
| Service levels | Optional. Shippo service level tokens to offer, such as usps_priority, separated by commas. | All services |
| Markup (%) | Added to each rate. | 0 |
| Handling fee | A flat amount added to each rate after the markup, in the checkout currency. | 0 |
| Show estimated delivery days | Shows the estimated delivery under each option. | On |
| Default parcel | The box size used for every rate, and the weight used when no item has a shipping weight. | 10 × 8 × 4 in, 1 lb |
| Send orders to Shippo | Creates Shippo orders and checks them for labels. | On |
| Send orders when | Order is paid or Order is submitted. | Order is paid |
| Create Swell shipment when a label is bought | Fulfills the Swell order with the carrier and tracking number. | On |
- The app doesn't buy labels, and the rate the customer chose isn't reserved. Buy labels on Shippo's Orders page.
- Shippo orders can't be changed or canceled through Shippo's API. A canceled Swell order stays on Shippo's Orders page, and changes made in Swell after the order was sent aren't sent.
- Rates use one parcel with the default dimensions, and an order is fulfilled with its first purchased label only.
- Orders older than 60 days aren't checked for labels, including older orders sent with Send to Shippo.
- A label reaches Swell with the next check, within 15 minutes when few orders are waiting. Refunded labels and carrier tracking updates don't reach Swell, so cancel the Swell shipment yourself when you refund a label.
- The Webhook tab in the app settings isn't supported yet. Leave it empty.
- International rate requests don't include customs details, so some international rates may be missing. Fill in customs forms in Shippo when you buy the label.
- Shippo has 8 seconds to return rates. If it fails or takes longer, checkout shows only your other shipping services.
- Items without a shipping weight add nothing to the parcel weight.
Errors from Shippo are shown in Error on the order's Shippo tab. The app also logs them. In the Swell dashboard, the logs are under Developer > Console > Logs.
Check that Shippo is turned on in Settings > Shipping and saved, that Show Shippo rates at checkout and Enabled are on, and that the ship-from address has a street, city, postal code and country code. Rates in another currency than the cart's aren't shown. Run Test connection to check the token and see your active carriers.
Check that Send orders to Shippo and Enabled are on, and that the order is paid, or submitted, as Send orders when requires. Canceled orders and orders with nothing to ship aren't sent. If sending failed, the reason is in Error on the order's Shippo tab. To send it again, choose Actions > Send to Shippo.
Wait for the next check, or choose Actions > Check for labels now in the app settings. Check that Create Swell shipment when a label is bought is on, and that the label was bought with the same Shippo account, test or live, as the token in this environment.
Uninstalling the app removes Shippo rates from checkout and from Settings > Shipping, stops sending orders and checking for labels, and removes the Shippo tab and column from your orders. Uninstalling applies to the environment you are in, so remove the app from the test and live environments separately.
Orders and labels already in Shippo stay there, and Swell shipments the app created stay on your orders.
| Function | Runs on | What it does |
| shipping-rates | after:order.shipping, for the shippo shipping extension | Gets Shippo rates and adds them to the shipping options. |
| order-events | order.paid and order.submitted | Sends the order to Shippo on the event chosen in the settings. |
| sync-labels | Every 15 minutes | Checks up to 10 orders waiting for a label and fulfills those that have one. |
| test-connection | The Test connection action | Checks the token and lists the active carriers. |
| check-labels | The Check for labels now action | Runs the label check now. |
| send-to-shippo | The Send to Shippo order action | Sends one order to Shippo. |
The app stores its fields on orders under $app.shippo: shippo_order_id, shippo_status, shippo_transaction_id, shippo_tracking_number, shippo_tracking_url, shippo_label_url, shippo_carrier, shippo_service, shippo_shipment_id, shippo_tracking_status, shippo_tracking_details, shippo_tracking_date, shippo_eta, shippo_checked_at and shippo_error. Rate IDs are shippo_ plus the Shippo service level token, such as shippo_usps_priority.
Swell builds and maintains the Shippo app. For help with the app, email support@swell.is. For questions about your Shippo account, carriers or labels, contact Shippo.