Summary
This documentation covers how the Shippo integration sends iPaaS.com orders FROM iPaaS.com to Shippo as Shippo orders, with each order's ship-to address and line items, so they are ready for a shipping label. When the Automatic Label Purchase setting is on, the integration also buys the label right after creating the order, and the label's tracking comes back to the iPaaS.com order (see the Shippo to iPaaS.com Label Mapping Documentation).
Shippo's API can create, list and read orders but not change or cancel them, so each order is sent once. A later update of the iPaaS.com order changes nothing in Shippo, except that, with Automatic Label Purchase on, an update buys the label for an order that has none yet.
ID Format
Manual Sync ID Format
The iPaaS.com transaction id of the order, for example 178657.
External ID Format
After a successful transfer, iPaaS.com saves external-ID records that link the iPaaS.com order to Shippo. Later transfers use them to find the same Shippo order instead of creating another.
Order: the Shippo order id, 32 characters, for example c4cd9dcb2de849fcb76de2af83588ad6.
Ship-to address: the Shippo order id followed by |SHIP.
Line item: the Shippo order id and the Shippo line item id joined by |.
Deleted Record Support
Not supported at the time this documentation was written. Shippo's API can't cancel or delete an order, so deleting an order in iPaaS.com changes nothing in Shippo. Cancel the order in Shippo if needed, and refund its label if one was bought. A cancelled, refunded or returned iPaaS.com order is handled through its status (see Mapping Filter below).
Custom Field Support
Not supported. A Shippo order has no custom field area, so these collections don't write custom fields to Shippo. Values from iPaaS.com custom fields can still be sent to a Shippo field with a Dynamic Formula mapping.
Mapping Collection Status
Status: Enabled. Review the filter before turning on the outbound events.
Trigger Events: the iPaaS.com transaction/created and transaction/updated events, which subscribers or their MiSP enable under Outbound Data Flows. No automatic transfers occur until they are enabled. Whether a transfer creates or updates is decided by whether the order is already linked to a Shippo order, not by the event. Manual Sync sends one order by its iPaaS.com transaction id.
Duplicate or Conflicting Mappings
None. These are the only collections that send orders to Shippo.
Collision Handling
Before creating an order, the integration looks for a Shippo order with the same order number placed at the same time (Shippo allows several orders with one number, so the placed-at time is part of the match). When it finds one, the Collision Handling Method on the Add/Update Shippo Order FROM iPaaS.com collection's settings page decides what happens:
Collision Handling Method | Result |
Error | The transfer is refused with iPaaS.com's collision error; nothing is created in Shippo and nothing is linked. |
Remap and Link | The iPaaS.com order is linked to the existing Shippo order, with its ship-to and line items. The installation instructions recommend this method. |
Update and Link | The order is linked to the existing Shippo order, but its ship-to and line items stay unlinked. |
Update and No Link | No second Shippo order is created and nothing is linked. |
Line items are matched to the existing order's line items in the order they appear. If the Shippo order lists the same items in a different order, the links can point to the wrong line items; validate collision behavior in a staging subscription before relying on it in production. When Shippo has two orders with the same number and placed-at time, the integration can't tell which is this one, sends nothing and reports SHPO-BIZL-1001.
Supported Child Collections
Shippo Order Ship-To Address FROM iPaaS.com: the order's primary shipping address, sent as the Shippo ship-to.
Shippo Order Line Item FROM iPaaS.com: the order's lines, sent as Shippo line items.
Both run only as part of the order transfer; they have no trigger or Manual Sync of their own.
System Caveats
Shippo Caveats
Orders can't be changed through the API. Shippo's API can create, list and read orders but has no update or cancel; changes to an order already in Shippo are made in Shippo.
A weight is required on every order. Shippo refuses an order with no weight, even when no label is bought. Map Weight on the line items or on the order.
Keep one weight unit. Line weights in different units are added as plain numbers, and an unrecognized unit is sent as pounds. Use lb, oz, g or kg throughout.
International labels need customs. International orders are created in Shippo, but their labels are not bought automatically (SHPO-BIZL-1008); add the customs declaration in Shippo and buy the label there.
Sender phone and email. Carriers such as USPS can require the sender's phone and email to buy a label.
Rate limiting. When Shippo limits the rate of calls, the transfer is held and resumes automatically; no action is needed from subscribers or their MiSP.
iPaaS.com Caveats
The primary shipping address is the ship-to. Billing and other addresses are never sent.
Country codes. Shippo needs two-letter country codes; the ship-to Country formula converts names and three-letter codes, and sends US when the address has none.
Setup Requirements
For full setup steps see the Installation Instructions and Connections and Settings articles. For these collections specifically:
Set Collision Handling Method on the order collection to Remap and Link.
Create the eight Shippo Ship From Transaction custom fields in iPaaS.com and fill them with your warehouse's address, phone and email, or point the ship-from mappings at another source.
Narrow the order collection's filter to the status your orders have when they are ready to ship.
To buy labels automatically: turn on Automatic Label Purchase, set Default Parcel, bring in Shippo's carrier services with the Shippo Carrier Service collection, and fill the Shippo Label Service translation with one row per shipping method your orders use.
Enable transaction/created and transaction/updated under Outbound Data Flows.
Integration Flow
An enabled outbound event or a Manual Sync starts the transfer, and the order passes the order collection's filter.
The integration checks the status first: an order without one is not sent (SHPO-VALD-1011); a cancelled, refunded or returned order is not sent (SHPO-BIZL-1005), or, when it is already in Shippo, left unchanged (SHPO-BIZL-1004).
It then checks for an order number (SHPO-VALD-1002), a placed-at date (SHPO-VALD-1005), no mapped value still starting with REPLACE (SHPO-VALD-1003), and a primary shipping address with a name, street, city and country (SHPO-VALD-1004). An order that fails a check is not sent.
The integration looks in Shippo for the same order number and placed-at time. If Shippo has it, the Collision Handling Method decides what happens. If not, it creates the Shippo order with its ship-to and line items, and iPaaS.com saves the external-ID records.
If the order is already linked to a Shippo order, nothing is changed in Shippo; SHPO-BIZL-1003 is logged as information, not an error.
With Automatic Label Purchase on, the integration buys the label for the ship-to's LabelService, using the ship-from, the order weight and Default Parcel. An order that already has a label is skipped (SHPO-BIZL-1010); an update doesn't buy labels for orders older than Days of Label History (SHPO-BIZL-1009).
When a label was bought, the integration queues its tracking TO iPaaS.com straight away.
Mappings
Add/Update Shippo Order FROM iPaaS.com
iPaaS.com data type: Transaction
Description: Sends each iPaaS.com order to Shippo as a Shippo order and, with Automatic Label Purchase on, buys its label.
Mapping Filter
// Orders with a primary shipping address that aren't already shipped, complete or drafts. Cancelled, refunded and returned orders // pass on purpose: one already in Shippo gets SHPO-BIZL-1004 (cancel it and refund its label there), one never sent gets SHPO-BIZL-1005. // Narrow it to your ready-to-ship status: Shippo orders can't be changed after they are sent. return Type == "Order" && Status != "Shipped" && Status != "Complete" && Status != "Draft" && Addresses != null && Addresses.Any(a => a.IsPrimaryShipping == true);
Filter Description. Only transactions whose Type is Order, whose Status is not Shipped, Complete or Draft, and that have at least one address with IsPrimaryShipping set are processed. Other transactions are skipped with no error. Cancelled, refunded and returned orders pass on purpose, so you see what happened to them: one never sent is not sent and reports SHPO-BIZL-1005 (dismiss it); one already in Shippo is left unchanged and reports SHPO-BIZL-1004 (cancel it, and void its label, in Shippo). Because orders are sent once, narrow the filter to your ready-to-ship status, for example by adding && Status == "Processing".
Mapping Type | Source Field (iPaaS.com) | Destination Field (Shippo) | Description |
Field | TransactionNumber | OrderNumber | Required. Becomes the Shippo order number; with PlacedAt it is how an existing Shippo order is recognized. Missing: SHPO-VALD-1002. |
Field | TransactionCreatedDateTime | PlacedAt | Required. Shippo's placed-at date. Missing: SHPO-VALD-1005. |
Field | Status | TransactionStatus | Required. Read, not sent: recognizes cancelled, refunded and returned orders. Missing: SHPO-VALD-1011. |
Field | EmailAddress | Recommended. Sent as the ship-to email when the address has none, so Shippo can send tracking emails. | |
Dynamic Formula |
| FromName | Required for automatic label purchase. Reads the Shippo Ship From Name custom field, for example Main Warehouse. |
Dynamic Formula |
| FromStreet1 | Required for automatic label purchase. Reads the Shippo Ship From Street custom field, for example 100 Example St. |
Dynamic Formula |
| FromCity | Required for automatic label purchase. Reads the Shippo Ship From City custom field, for example Springfield. |
Dynamic Formula |
| FromState | Required for automatic label purchase. Reads the Shippo Ship From State custom field, for example IL. |
Dynamic Formula |
| FromZip | Required for automatic label purchase. Reads the Shippo Ship From Postal Code custom field, for example 62701. |
Dynamic Formula |
| FromCountry | Required for automatic label purchase. Reads the Shippo Ship From Country custom field, for example US. Map it whenever the street is mapped: Shippo refuses a ship-from with no country. |
Dynamic Formula |
| FromPhone | Required for automatic label purchase. Reads the Shippo Ship From Phone custom field, for example 5555550100. Carriers such as USPS can require it. |
Dynamic Formula |
| FromEmail | Required for automatic label purchase. Reads the Shippo Ship From Email custom field, for example shipping@example.com. Carriers such as USPS can require it. |
Field | ShippingAmount | ShippingCost | Optional. Shipping the customer paid, shown on the Shippo order. |
Field | Subtotal | SubtotalPrice | Optional. Shown on the Shippo order. |
Field | TaxAmount | TotalTax | Optional. Shown on the Shippo order. |
Field | Total | TotalPrice | Optional. Shown on the Shippo order. |
By default the ship-from comes from eight Transaction custom fields on the order, which subscribers or their MiSP create in iPaaS.com and fill with their warehouse's address; the mappings can be pointed at another source instead. Without a ship-from, the order is still created but no label is bought (SHPO-VALD-1007). A mapped ship-from value that still starts with REPLACE stops the order (SHPO-VALD-1003).
Shippo Order Ship-To Address FROM iPaaS.com (Child)
iPaaS.com data type: Transaction Address
Description: Sends the order's primary shipping address as the Shippo ship-to and chooses the carrier service to buy.
Mapping Type | Source Field (iPaaS.com) | Destination Field (Shippo) | Description |
Field | IsPrimaryShipping | IsPrimaryShipping | Required. The primary shipping address becomes the ship-to. |
Dynamic Formula |
| Name | Required. The recipient's first and last name. |
Field | Company | Company | Optional. |
Field | Address1 | Street1 | Required. |
Field | Address2 | Street2 | Optional. |
Field | Address3 | Street3 | Optional. |
Field | City | City | Required. |
Field | Region | State | Recommended. Postal abbreviation in the US and Canada, for example CA. |
Field | PostalCode | Zip | Recommended. |
Dynamic Formula |
| Country | Required. Converts names and three-letter codes to the two-letter code; blank sends US. |
Field | ShippingMethod | ShippingMethod | Optional. Shown on the Shippo order; read by the LabelService translation. |
Lookup Translation | ShippingMethod, through Shippo Label Service | LabelService | Required for automatic label purchase. The carrier service to buy (see below). |
A primary shipping address missing a name, street, city or country stops the order with SHPO-VALD-1004, naming what is missing.
Shippo Label Service translation. The translation turns the iPaaS.com shipping method name into Shippo's carrier and service token. Placeholder value — replace during implementation: it ships with one example row, REPLACE with your iPaaS.com shipping method name to usps|usps_priority. Replace it with one row per shipping method your orders use, for example:
Source value (iPaaS.com shipping method) | Destination value (Shippo carrier service) |
Standard Shipping | usps|usps_ground_advantage |
Express | usps|usps_priority_express |
Each Shippo carrier service's token is shown in the description of its iPaaS.com Shipping Method (for example Label Service: usps|usps_priority). An order whose shipping method has no row is created in Shippo without a label (SHPO-VALD-1006); a token no active carrier account offers reports SHPO-NFND-1002.
Shippo Order Line Item FROM iPaaS.com (Child)
iPaaS.com data type: Transaction Line
Description: Sends the order's lines as Shippo line items, with the weights that make the order weight.
Mapping Type | Source Field (iPaaS.com) | Destination Field (Shippo) | Description |
Field With Default | Description, default Item | Title | Required. The item title Shippo shows on the order and packing slip. |
Field | Sku | Sku | Recommended. Shippo allows the same SKU on several lines. |
Field | Qty | Quantity | Recommended. Blank or 0 sends 1. |
Field | Weight | Weight | Required unless the order maps a weight. Weight of one item. The order weight is the sum of weight times quantity; the unit is the order's, else the first weighted line's, else pounds. |
Field | ExtendedPrice | TotalPrice | Optional. Line total, shown on the Shippo order. |
The line collection has no filter by default. To keep lines that don't ship off the Shippo order, add one, for example return Sku != "SERVICE-FEE";.
Error Handling
Errors from these collections appear in iPaaS.com Dashboard / Integration Monitoring / Error Logs. Label purchase problems leave the order in Shippo and report why, so the label can be bought in Shippo or the order resent after the fix.
SHPO-VALD-1002, 1004, 1005, 1011: the order is missing its number, a usable primary shipping address, its placed-at date or its status, and is not sent.
SHPO-VALD-1003: a mapped value still starts with REPLACE.
SHPO-VALD-1006: no carrier service for the order's shipping method (no translation row).
SHPO-VALD-1007: no ship-from address.
SHPO-VALD-1008: Default Parcel isn't set.
SHPO-VALD-1009: the order has no weight.
SHPO-NFND-1002: no active carrier account offers the service.
SHPO-BIZL-1001: Shippo has two orders with the same number and placed-at time.
SHPO-BIZL-1004, 1005: a cancelled, refunded or returned order (see Mapping Filter).
SHPO-BIZL-1006: a live API token while Allow Live Label Purchases is off.
SHPO-BIZL-1008: an international order; add customs and buy the label in Shippo.
SHPO-EXTN-1001: Shippo refused the order; its reason is quoted.
SHPO-EXTN-1002: Shippo limited the rate of calls; the transfer is held and resumes automatically.
SHPO-EXTN-1004: Shippo refused the label; its reason is quoted.
For the full catalog of error messages see the Shippo Error Messages article.
Testing & Validation
Test Scenarios
Send an order ready to ship. Verify a Shippo order with the same order number, the ship-to and the line items, and the external-ID records on the iPaaS.com order, ship-to and lines.
Send the same order again. Verify no second Shippo order is created.
With Automatic Label Purchase on and a test API token, send a new order. Verify one test label in Shippo and a tracking record on the iPaaS.com order.
Send a cancelled order that was never sent. Verify it is not sent and SHPO-BIZL-1005 is reported.
Create a Shippo order with the same number and placed-at time first, then send the iPaaS.com order with Remap and Link. Verify it links to the existing Shippo order instead of creating another.
Validation Checklist
The eight Shippo Ship From custom fields exist and are filled on each order with your own address, phone and email.
Every line, or the order, carries a weight in one unit.
The Shippo Label Service translation has a row for every shipping method your orders use.
The order filter is narrowed to your ready-to-ship status.
Additional Notes
Labels bought separately. A label bought separately for an order this integration sent comes back to the iPaaS.com order through the Shippo Label collection. Validate labels bought by hand in the Shippo web app in a staging subscription before relying on them in production.
Test and live tokens. A Shippo test token buys test labels, which aren't charged and don't ship; with a live token, labels cost real postage and are bought only when Allow Live Label Purchases is on.
