Shippo shipping integration

Overview

Shippo is a shipping API that connects Stokkap to carriers all over the world through a single account. Once connected, you can fetch live rates, buy shipping labels, and create return labels directly from an order - no separate shipping tool, spreadsheet, or carrier portal required.

Term	Meaning
Rate	A carrier's quoted price for a shipment
Label	The printable shipping label purchased from a carrier via Shippo
Carrier account	A carrier connected to Shippo - either your own contract or one provided through Shippo
Test / Live API key	Test API keys are free and issued instantly, limited to Shippo's test carriers; Live API keys must be requested from Shippo and buy real postage

Requirements

• A Stokkap subscription with the Smart Shipping feature enabled.
• A free Shippo account (sign up here).
• A payment card on file with Shippo and an issued Live key if you want to buy real labels (see below).

Why connect Shippo

• Huge global carrier support. Connect your own account with UPS, FedEx, DHL Express, DHL eCommerce, DHL Germany, Royal Mail, Evri, Canada Post, Australia Post, CouriersPlease, DPD, Deutsche Post, Purolator, GLS, and dozens of other regional and local carriers - so you're not limited to whichever couriers you'd normally have the time to integrate yourself.
• Labels from the order. Buy and print a shipping label straight from a WooCommerce order inside Stokkap - the workflow stays in one place.
• Return labels. Generate a return label addressed back to your dispatch address for handling customer returns, without a separate return portal.
• Built-in tracking webhooks. Stokkap has a built-in webhook for tracking updates - enable it in one click, with no copying URLs into Shippo. Tracking status updates flow back into the order automatically.
• Low, pay-as-you-go cost. The Shippo API itself costs very little to use, and label prices for carriers provided through Shippo are competitive, aggregated rates.
• Use your own carrier rates. Connect your own carrier account (UPS, DHL, Royal Mail, and dozens more) inside Shippo and Shippo won't add its markup to labels bought on that account - you pay your own negotiated carrier rate instead.
• Address validation. Shippo checks both the sender and delivery address before a label can be bought, catching incomplete or incorrect addresses before a parcel is sent to the wrong place.

Create a Shippo account & API keys

1. Sign up for a free account at apps.goshippo.com/join.
2. In the Shippo dashboard, go to API configuration > Developer keys and copy your Test API key. Test API keys are issued as soon as you open a Shippo account, with no card required, so you can start setting up straight away.
3. To buy real labels, request a Live API key from Shippo: add a payment card under Account > Billing first, then generate the Live API key from the same Developer keys page.

Connect Shippo to your store

1. Go to Settings > Stores and click the Settings (gear) button on the store you want to connect.
2. In the Edit Store dialog, switch to the Shipping tab.

3. Paste your Live API key and/or Test API key into the matching fields. A link to this documentation is shown at the top of the tab.
4. Click Save.
5. Reopen the Shipping tab and click Test connection next to each key to confirm Shippo answers successfully.
6. Click Enable tracking updates to register the tracking webhook for that environment. Stokkap has a built-in webhook for this - there's nothing to copy into Shippo yourself.

Further down the same tab, the Use for new labels dropdown chooses whether Test or Live is active for new labels. Changing it keeps both keys and any labels you've already bought - request fresh rates after switching. Disconnect test and live removes both keys from the store.

Carrier accounts

The Shipping tab also lists every carrier account connected inside your Shippo account, with a Refresh button to pull in any changes. Carriers are added, removed, and enabled or disabled entirely on the Shippo side - Stokkap just reflects what's connected there.

Rates and labels are available through carrier accounts provided by Shippo at Shippo's own rates, or through your own account with a carrier if you connect one in Shippo. Shippo's carrier list includes UPS, FedEx, DHL Express, DHL eCommerce, DHL Germany, Evri UK, Canada Post, CouriersPlease, Deutsche Post, DPD UK, OnTrac, Purolator, Veho, APC Postal, Australia Post, GLS, Royal Mail, and many more.

1. In the Shippo dashboard, go to Settings > Carrier Accounts.
2. Add the carrier and enter your own account credentials.
3. Click Refresh on the Shipping tab in Stokkap, or open it again, to pick up the newly connected carrier.

Dispatch addresses

Add at least one dispatch address before creating shipping labels - this is where labels say the parcel is shipped from. You can add several, for example if you dispatch from more than one location, and mark one as the default.

• Fill in the address carefully and make sure it validates correctly - carriers reject or delay labels built on an unverified address.
• Include a contact number and email address. Some carriers require both to generate a label.
• Add your business/company name where relevant, alongside the contact name.

Defaults & parcel presets

The Defaults section sets what prefills a new parcel. Each parcel can still be changed individually when creating a label.

Setting	What it does
Weight unit	kg or lb, used across the store's shipments
Dimension unit	cm or in, used for parcel dimensions
Label format	The print format for purchased labels, e.g. PDF 4x6
Default parcel size	Optional. Prefills length, width, and height on new parcels; leave blank to start every parcel empty
Default country of origin	A two-letter code (e.g. GB) prefilled into customs forms - important to set correctly for international shipments

Parcel presets are named box templates your team ships in regularly, for example a "standard" box at fixed dimensions. Choosing a preset when building a parcel fills in the dimensions; weight is still entered per parcel, since a preset's empty box weight is only a starting point and never becomes the shipping weight on its own.

Create shipping labels

Open an order and find the Shipping card. If no shipment exists yet, click Create shipment.

1. The delivery address is filled in from the order automatically. Click Update sender from saved address to set the sender from one of your dispatch addresses.
2. Each shipment starts with Parcel 1. Choose a Box (a saved preset, or Custom size), then enter the Weight and Dimensions - both are required before rates can be fetched.
3. Click Add parcel if the order is shipping in more than one box. Assign items is optional and mainly useful once there's more than one parcel, so you can split which order items go in which box; with a single parcel there's nothing to split, so it can be skipped.
4. Click Save parcel to keep the draft, or Get rates to fetch live rates for that parcel. Discard draft shipment cancels the whole shipment before a label is bought.

Rates are listed cheapest first, with the carrier shown under each service name. Next to each rate, Stokkap shows how that label's price compares with what the customer was actually charged for shipping on the order - shown as "short" when postage costs more than was collected at checkout. The Label format defaults to the store setting but can be overridden for that label only - note that once a label is bought, it can't be reprinted in a different format; a new label has to be created instead. Click Buy label on the rate you want.

If a carrier's service isn't offered for a parcel, a Why services were not offered panel explains why - for example a weight or size limit the parcel exceeds. A Show Shippo account notes link can reveal further account-specific notes from Shippo for that rate request.

Once bought, the parcel shows the carrier, service, and price paid, plus the tracking number and status. A Test tag appears on labels bought with a Test key. From here you can Print label, mark it Confirm printed, or Void label if it was bought in error - voiding puts the label's cost into a refund pending state rather than refunding it instantly.

Tracking isn't sent to the customer automatically. Click Send tracking to customer to manually notify them - it prefills an order note in the store's own language for that customer, including the tracking number and a link to track the shipment.

Create return labels

Once an order has a purchased label, Refund and Return label buttons appear on the order. Select Return label to generate a label addressed back to your dispatch address using the same carrier, so customer returns can be handled without a separate return portal.

Activity log

Every shipping action is logged. Go to Activity and filter by Shipments to see a feed of everything that's happened, including getting rates, buying and downloading labels, discarding draft shipments, voiding labels, and dispatch address changes. Each entry shows the order, the user who did it, how long ago, and their IP address, and can be filtered by user and date range.

Tracking webhooks

Stokkap has a built-in webhook for tracking updates - there's nothing to copy or paste into Shippo yourself. Click Enable tracking updates on the Shipping tab once per environment (Test and Live are registered separately), and Stokkap handles the registration with Shippo for you. As the carrier updates a shipment's status, Shippo notifies Stokkap and the order's tracking status updates on its own.

Switching between test and live

Stokkap can hold both a Test and a Live key for the same store. Use the Use for new labels dropdown to switch which one is active for new labels - existing labels and both saved keys are unaffected. Test mode is useful for checking a new setup, a newly connected carrier account, or a new dispatch address before spending on real labels.

Troubleshooting

• Connection failed / "Connection needs testing": double check the key was copied in full into the matching Test or Live field, then click Test connection again after saving.
• No live rates, only USPS test rates: a Live API key hasn't been issued yet - add a payment card in Shippo under Account > Billing and request one.
• No rates returned: confirm the order has a parcel weight/dimensions, a valid dispatch address, a valid ship-to address, and at least one carrier account connected in Shippo for the active mode.
• Label purchase failed in Live mode: check that a payment card is on file in Shippo, and that the chosen carrier account has accepted any pending terms.
• "Shippo could not verify this address": can apply to either the ship-from or ship-to address. If it's the ship-from address, check your dispatch address in Settings > Stores > Shipping saves and validates properly - a business/location name alone often isn't enough, Shippo may still need the full street address. If it's the ship-to address, the customer's address on the order may be wrong; verify it with the customer or correct it yourself by editing the customer's shipping details directly on the order page, then get rates again. Catching bad addresses like this before a label is bought is one of the benefits of using Shippo.
• Tracking updates not enabled: click Enable tracking updates on the Shipping tab for that environment (Test/Live are separate).
• A carrier won't connect: some carriers, such as Royal Mail (MBO), require Shippo support to enable them manually. Contact Shippo support from the email address you registered with.