This article walks you through installing the Shippo integration on iPaaS.com. You will get a Shippo API token, subscribe, fill in the settings, review the default templates, create the custom fields, load your carrier services, turn on the scopes and schedule the polls. Automatic label purchase is optional and comes last.
Before You Begin
You need a Shippo login that can open the Shippo API portal, where API tokens are created under API Configuration, then Developer keys (Shippo: Authentication).
What your Shippo account needs
Item | Needed for | Notes |
A Shippo API token | Everything | Shippo offers test keys (they begin shippo_test_) and live keys (they begin shippo_live_). Test labels cost nothing and never ship. Live labels cost real postage. |
Carrier accounts turned on in Shippo | Shipping methods and labels | Every service of every active carrier account becomes a Shipping Method in iPaaS.com. |
A sender address in Shippo | Labels bought by hand in Shippo | A label bought by hand in Shippo uses the sender address chosen there. Automatic label purchase takes the ship-from address from eight custom fields on each order (see Custom Fields). |
Start with the test token. Everything in this article works with it, and nothing it does costs money. Switch to the live token when you are ready to go live.
To get a Shippo API token
Log in to the Shippo API portal with your Shippo credentials.
Open API Configuration, then Developer keys.
Click Create new test key (or, when you go live, Create new live key) and copy the key. Shippo shows the full key only once.
Keep it somewhere safe, such as a password manager. You will paste it into the subscription's API Token setting.
Treat the token like a password: anyone with it can create orders and buy labels on your Shippo account.
Installation Instructions for Integration Setup
In iPaaS.com, go to Subscriptions and click Search Certified Integration Marketplace and Subscribe.
Click the Shippo integration tile.
Click Subscribe.
Enter a name for the subscription. It must be unique within the company.
Format: Shippo - [Environment/Purpose]
Example: Shippo - Production
Select Create Default Mappings (recommended). This applies the default templates listed under Default Mapping Collections below.
Enter the API Url.
Default value: https://api.goshippo.com
Leave it at the default. Blank also uses the default.
It must be an https address on Shippo's own host (goshippo.com). Any other address, such as a proxy, is refused with SHPO-VALD-1001 and the API Token is never sent to it.
Enter the API Token from Before You Begin.
Paste the token only here. A Shippo token pasted into API Url, Default Parcel or Label File Type stops the connection with SHPO-VALD-1010, which names the setting but never shows the value.
Spaces or line breaks copied around the token (or any other setting) don't matter: they are removed.
Leave Automatic Label Purchase at false for now. With it off, the integration sends orders to Shippo's Orders list, and your staff buy the labels in Shippo. See Turn On Automatic Label Purchase below.
Leave Allow Live Label Purchases at false. It matters only with a live token and Automatic Label Purchase on.
Leave Default Parcel blank for now. It is needed only for automatic label purchase.
Set Label File Type.
Default value: PDF_4x6
Other values: PNG, PNG_2.3x7.5, PDF, PDF_2.3x7.5, PDF_4x8, PDF_A4, PDF_A6, ZPLII. A value not in this list uses the default.
Set Days of Label History.
Default value: 7
This is how far back the scheduled label check looks for labels, and the age past which an update of an order already in Shippo never buys a label automatically (a first send is always bought). Allowed: 1 to 365.
Leave Label Page Size (default 100) and Carrier Account Page Size (default 25) at their defaults. They set how many records each Shippo call reads (1 to 100).
Leave the platform presets (API Throttle Limit, API Throttle Seconds, Concurrent Connections, Concurrent Batch Executions) at their defaults.
Click Apply to save the settings. Saving does not test the connection. The integration checks the token on its first transfer. A missing or wrong token or API Url makes that transfer fail with Unable to connect to subscription with id N. The reason, with its code (for example SHPO-AUTH-1001), is in the company's Logs at the same time.
See Shippo Connections and Settings for every setting in detail.
Default Mapping Collections
The default templates create these collections:
Collection | Type | Direction |
Add/Update Shippo Order FROM iPaaS.com | Transaction | FROM iPaaS.com |
Shippo Order Ship-To Address FROM iPaaS.com | Transaction Address (child) | FROM iPaaS.com |
Shippo Order Line Item FROM iPaaS.com | Transaction Line (child) | FROM iPaaS.com |
Add/Update Shippo Label TO iPaaS.com | Transaction Tracking Number | TO iPaaS.com |
Add/Update Shippo Carrier Service TO iPaaS.com | Shipping Method | TO iPaaS.com |
They also create the translation Shippo Label Service, used only by automatic label purchase.
Keep every collection's sync type at Add/Update. Shippo has no delete, so a delete is refused with SHPO-BIZL-1015. Don't add collections for other directions (for example Shipping Method or Transaction Tracking FROM iPaaS.com): they are refused with SHPO-BIZL-1014.
Set collision handling on the order collection
Templates don't carry collision handling, so set it yourself:
Open the Add/Update Shippo Order FROM iPaaS.com collection.
Set Collision Handling Method to Remap and Link, and save.
Why: before it creates a Shippo order, the integration looks for one Shippo already has with the same order number and placed-at time (for example, an order sent once whose answer was lost, or one entered in Shippo). It never creates a second one, and it never links one on its own: it hands the match back to iPaaS.com, and this setting decides.
Remap and Link: iPaaS.com links the order, its ship-to and its lines to the existing Shippo order, then runs its normal update. With Automatic Label Purchase on, a label is bought if that Shippo order has none.
Update and Link: links the order, but not its ship-to or lines. Use Remap and Link instead.
Update and No Link: creates no second Shippo order and links nothing.
Error: iPaaS.com shows "A data collision occurred. The data in the destination system has id ..." and nothing is created. Set Remap and Link and let iPaaS.com retry, or remove the order from Shippo.
If Shippo has two or more orders with the same number and placed-at time, nothing is sent and the order shows SHPO-BIZL-1001. Delete or renumber the extra orders in Shippo; iPaaS.com retries the transfer.
Review the filters before you go live
Order FROM iPaaS.com sends transactions whose type is Order, whose status is not Shipped, Complete or Draft, and that have a primary shipping address. Orders without one (in-store sales, pickups) are never sent. Shippo orders can't be changed or cancelled after they are sent, so narrow the filter to the status at which an order is ready to ship. For example:
return Type == "Order" && Status == "Processing" && Addresses != null && Addresses.Any(a => a.IsPrimaryShipping == true);. Leave out orders that already reach Shippo another way, such as through a store connected to Shippo directly.Cancelled, Refunded and Returned orders pass the default filter on purpose, so you hear about them. The order collection's TransactionStatus mapping (from the transaction's Status) is required: it lets the integration see the order's status, and an order without one is not sent (SHPO-VALD-1011). No label is ever bought for a cancelled, refunded or returned order:
An order cancelled, refunded or returned before it reaches Shippo is never sent and shows SHPO-BIZL-1005. Dismiss the error.
An order already in Shippo that is later cancelled, refunded or returned shows SHPO-BIZL-1004. Nothing is changed in Shippo: cancel the order in Shippo by hand and refund its label there if one was bought, then dismiss the error.
A narrowed filter (such as the Processing example above) leaves these orders out, so a cancellation after sending is not reported. To keep the reminder, replace the whole filter with this line instead:
return Type == "Order" && (Status == "Processing" || Status == "Cancelled" || Status == "Refunded" || Status == "Returned") && Addresses != null && Addresses.Any(a => a.IsPrimaryShipping == true);Label TO iPaaS.com brings in only labels for orders this integration sent. The tracking record lands on the iPaaS.com order; it reaches another system only through that system's own tracking flow FROM iPaaS.com.
Carrier Service TO iPaaS.com brings in every active carrier service. Keep it that way: a tracking record needs the shipping method of its label. The shipping methods are visible to every system in your company that receives shipping methods from iPaaS.com.
Order Line Item FROM iPaaS.com sends every line. Add a filter on it for items that don't ship, such as gift cards or service lines.
Weight: Shippo refuses an order with no weight, even when no label is bought, so every order's lines need a weight (the default template maps line weight). Keep the lines in one unit, and map WeightUnit on the order collection when that unit isn't pounds.
Load Your Carrier Services
Tracking records name a shipping method, and iPaaS.com refuses a tracking record whose shipping method it doesn't know. So load your carrier services before the first label:
On the Subscription Settings screen, find the Initialize Data section and click Shipping Method (see Subscription Configuration - Edit).
Each carrier service becomes a Shipping Method named by its carrier and service, for example USPS Priority Mail. Its description shows the value to use for it in the Shippo Label Service translation, for example Label Service: usps|usps_priority.
If a label later arrives for a carrier service that isn't in iPaaS.com yet, the integration transfers that shipping method first. A shipping method you deleted in iPaaS.com is not brought back this way (see the Shippo Integration Known Limitations).
Enable the Scopes
A scope is one kind of data the integration can bring TO iPaaS.com. A webhook scope is Shippo telling iPaaS.com as it happens; a poll scope asks Shippo on a schedule. Set the scopes Active under the subscription's Inbound Data Flows.
Scope | Turn on | What it does |
transaction_created | Yes (webhook) | A new label brings in its tracking record. Turning it on registers a webhook in your Shippo account. |
transaction_updated | Yes (webhook) | A label change, such as a refund, updates the tracking record. |
track_updated | Yes (webhook) | A carrier status change (in transit, delivered) updates the tracking record. |
label/poll | Yes | A scheduled check that brings in any label a webhook missed. |
shipping_method/poll | Optional | Keeps Shipping Methods current when you add carriers or services. |
shipping_method/initialize | Run once (above) | Loads every carrier service. |
shipping_method/updated | No | Transfers one carrier service on request (a Manual Sync with its carrier and service token); not needed for normal use. |
Setting a webhook scope inactive removes the integration's webhook for it from Shippo. The integration never touches webhooks you created in Shippo yourself.
Orders FROM iPaaS.com run on iPaaS.com's own transaction events. Under the subscription's Outbound Data Flows, set both of these scopes Active:
Scope | What it does |
transaction/created | Sends a new order to Shippo. |
transaction/updated | Sends an order that changed, for example one that now passes the filter, and reports a cancellation, refund or return. |
Without them, no order reaches Shippo. Orders already in iPaaS.com before you turn these on are not sent at setup: each is sent when it next changes in iPaaS.com, or when you resend it.
Schedule the Polls
A /poll scope runs only on a schedule. Turning it on doesn't start it. For each poll scope you turned on, create a Webhook Poll Request event in iPaaS.com's Events (see Events), naming this subscription and the scope.
Event | Subscription | Scope | Suggested schedule |
Shippo labels | your Shippo subscription | label/poll | every hour ( |
Shippo shipping methods | your Shippo subscription | shipping_method/poll | once a day ( |
The scheduled label check (label/poll) reads labels created within Days of Label History and passes on those changed since its last run.
Custom Fields
The default mappings use two sets of iPaaS.com custom fields. Confirm each exists in your iPaaS.com company, and create any that don't: click Data Management, then Custom Fields, then Add Custom Field, and enter the Name exactly as shown, the Module, a Description and the Data Type (see Custom Fields).
Ship-from address (module: Transaction)
The order collection reads each order's ship-from address from these eight Transaction custom fields, so different orders can ship from different places. Fill them on each order from the system that sends the order to iPaaS.com, or with a formula in that system's order mapping. Automatic label purchase needs a complete ship-from, and USPS also needs the phone and email (SHPO-VALD-1007 names a missing ship-from). Create them as text fields:
Custom field | What it holds | Example |
Shippo Ship From Name | Your warehouse, store or company name | Main Warehouse |
Shippo Ship From Street | The ship-from street address | 100 Example St |
Shippo Ship From City | The ship-from city | Springfield |
Shippo Ship From State | The state or province as its postal abbreviation | IL |
Shippo Ship From Postal Code | The ship-from postal code | 62701 |
Shippo Ship From Country | The country as a two-letter code | US |
Shippo Ship From Phone | A phone number | 5555550100 |
Shippo Ship From Email | An email address |
If every order ships from one place, you can instead change each ship-from mapping on Add/Update Shippo Order FROM iPaaS.com to return your own value.
Tracking (module: Transaction Tracking)
The default label mappings write to these custom fields on Transaction Tracking:
Custom field | What it holds |
Shippo Status | The label's status in Shippo: SUCCESS, QUEUED, WAITING, REFUNDPENDING, REFUNDED or REFUNDREJECTED. REFUNDED means the label was refunded and won't ship. |
Shippo Tracking Status | The carrier's status: UNKNOWN, PRE_TRANSIT, TRANSIT, DELIVERED, RETURNED or FAILURE. |
Shippo Tracking URL | The carrier's tracking page. |
Turn On Automatic Label Purchase (optional)
With automatic purchase on, the integration buys the label as soon as it sends the order, once per order. Before you turn it on:
Fill in the Shippo Label Service translation. It turns each iPaaS.com shipping method into the Shippo carrier service to buy. Edit the template's row, which reads REPLACE with your iPaaS.com shipping method name. Add one row per shipping method your orders use:
Source value: the iPaaS.com shipping method name on the order's shipping address, for example Ground.
Destination value: the Shippo carrier and service token joined by |, for example usps|usps_ground_advantage. Each loaded Shipping Method's description shows this value, for example Label Service: usps|usps_priority.
An order whose shipping method has no row is still sent to Shippo, but no label is bought. The error SHPO-VALD-1006 names the missing shipping method.
Fill the ship-from custom fields on your orders (see Custom Fields). The order collection's ship-from mappings (FromName, FromStreet1, FromCity, FromState, FromZip, FromCountry, FromPhone and FromEmail) read them.
Set Default Parcel to a Shippo carrier parcel template token, for example USPS_SmallFlatRateBox. The tokens are listed in Shippo's API documentation under carrier parcel templates. The order's weight comes from the line weights (pounds unless you map WeightUnit).
With a live token only: set Allow Live Label Purchases to true. Live labels cost real postage. With it off, a live token never buys a label (SHPO-BIZL-1006).
Check the orders already in Shippo. Once automatic purchase is on, an order already in Shippo without a label is bought on its next update if it was placed within Days of Label History, including orders your staff were holding back. Buy or clear those in Shippo first.
Set Automatic Label Purchase to true.
Orders that ship to another country are sent to Shippo but never bought automatically, because they need customs information (SHPO-BIZL-1008). Buy those in Shippo.
Authentication Configuration
Shippo uses a static API token, sent on every call. There is no OAuth and no token refresh. The token stays valid until you regenerate it in Shippo. To rotate it, generate a new token, update API Token on the subscription and save.
Switching from the test token to the live token moves the integration to your live Shippo data. Set each webhook scope inactive and active again under Inbound Data Flows so its webhook is registered for the live account.
Post-Installation Verification
Run the Shipping Method initialization and check that your carrier services appear under Shipping Methods.
Create a test order in iPaaS.com that passes the order filter. It appears in Shippo's Orders list shortly, and the iPaaS.com order shows the Shippo order as an external id.
Buy a label for it: in Shippo by hand, or turn on automatic purchase for a test order (a test label with the test token). Shortly after, the iPaaS.com order shows a tracking record with the tracking number, the shipping method and the Shippo custom fields.
Check Dashboard / Integration Monitoring / Error Logs, and the company's Logs, for any SHPO- code. The Shippo Error Messages article explains each one. iPaaS.com retries every transfer that shows an error, at growing intervals, until it succeeds or you dismiss the error. Fix what the error names, or dismiss it when it says to.






