Skip to main content

iPaaS.com to Shippo Order Mapping Documentation

How iPaaS.com orders transfer FROM iPaaS.com to Shippo as Shippo orders with their ship-to address, line items and ship-from custom fields, including automatic label purchase, duplicate handling and what each default mapping carries.

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

  1. An enabled outbound event or a Manual Sync starts the transfer, and the order passes the order collection's filter.

  2. 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).

  3. 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.

  4. 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.

  5. 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.

  6. 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).

  7. 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

Email

Recommended. Sent as the ship-to email when the address has none, so Shippo can send tracking emails.

Dynamic Formula

return GetCustomFieldValue(CustomFields, "Shippo Ship From Name");

FromName

Required for automatic label purchase. Reads the Shippo Ship From Name custom field, for example Main Warehouse.

Dynamic Formula

return GetCustomFieldValue(CustomFields, "Shippo Ship From Street");

FromStreet1

Required for automatic label purchase. Reads the Shippo Ship From Street custom field, for example 100 Example St.

Dynamic Formula

return GetCustomFieldValue(CustomFields, "Shippo Ship From City");

FromCity

Required for automatic label purchase. Reads the Shippo Ship From City custom field, for example Springfield.

Dynamic Formula

return GetCustomFieldValue(CustomFields, "Shippo Ship From State");

FromState

Required for automatic label purchase. Reads the Shippo Ship From State custom field, for example IL.

Dynamic Formula

return GetCustomFieldValue(CustomFields, "Shippo Ship From Postal Code");

FromZip

Required for automatic label purchase. Reads the Shippo Ship From Postal Code custom field, for example 62701.

Dynamic Formula

return GetCustomFieldValue(CustomFields, "Shippo Ship From Country");

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

return GetCustomFieldValue(CustomFields, "Shippo Ship From Phone");

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

return GetCustomFieldValue(CustomFields, "Shippo Ship From Email");

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

return (FirstName + " " + LastName).Trim();

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

return CountryCodeWithDefault(Country, "US");

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

  1. 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.

  2. Send the same order again. Verify no second Shippo order is created.

  3. 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.

  4. Send a cancelled order that was never sent. Verify it is not sent and SHPO-BIZL-1005 is reported.

  5. 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.

Related Documents

Did this answer your question?