Skip to main content

Shippo Installation Instructions

How to install the iPaaS.com Shippo integration: the Shippo API token, the subscription settings, the default templates, the ship-from custom fields, the scopes and poll events, and turning on automatic label purchase.

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

  1. Log in to the Shippo API portal with your Shippo credentials.

  2. Open API Configuration, then Developer keys.

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

  4. Keep it somewhere safe, such as a password manager. You will paste it into the subscription's API Token setting.

    Shippo API portal, Developer keys, with Create new test key highlighted

Treat the token like a password: anyone with it can create orders and buy labels on your Shippo account.

Installation Instructions for Integration Setup

  1. In iPaaS.com, go to Subscriptions and click Search Certified Integration Marketplace and Subscribe.

    iPaaS.com Subscriptions page with the marketplace button highlighted
  2. Click the Shippo integration tile.

    The Shippo tile in the iPaaS.com integration marketplace
  3. Click Subscribe.

    The Shippo integration details page with the Subscribe button highlighted
  4. Enter a name for the subscription. It must be unique within the company.

    • Format: Shippo - [Environment/Purpose]

    • Example: Shippo - Production

  5. Select Create Default Mappings (recommended). This applies the default templates listed under Default Mapping Collections below.

  6. Enter the API Url.

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

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

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

  9. Leave Allow Live Label Purchases at false. It matters only with a live token and Automatic Label Purchase on.

  10. Leave Default Parcel blank for now. It is needed only for automatic label purchase.

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

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

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

  14. Leave the platform presets (API Throttle Limit, API Throttle Seconds, Concurrent Connections, Concurrent Batch Executions) at their defaults.

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

    Shippo Subscription Settings in iPaaS.com (example values; the API Token is hidden)

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:

  1. Open the Add/Update Shippo Order FROM iPaaS.com collection.

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

  1. On the Subscription Settings screen, find the Initialize Data section and click Shipping Method (see Subscription Configuration - Edit).

  2. 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 (0 0 * * * ?)

Shippo shipping methods

your Shippo subscription

shipping_method/poll

once a day (0 0 3 * * ?), optional

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

iPaaS.com Custom Fields page with Add Custom Field highlighted

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:

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

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

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

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

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

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

  1. Run the Shipping Method initialization and check that your carrier services appear under Shipping Methods.

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

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

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

Did this answer your question?