Skip to main content

Shippo Connections and Settings

Every setting of the iPaaS.com Shippo integration: what it does, its default, where the value comes from, and what happens when it is empty or wrong.

Integrate iPaaS.com with Shippo to send orders, with their ship-to address and line items, to Shippo FROM iPaaS.com, optionally buy their labels, and bring labels back TO iPaaS.com as tracking records and Shippo carrier services TO iPaaS.com as shipping methods.

How to Connect

Prerequisites

  • A Shippo account. Shippo offers a test mode and a live mode, each with its own API keys: "In test mode, you can use all of the Shippo services like retrieving shipping rates and creating test labels without being charged", while in live mode "Your account will be charged for purchasing labels", and "Data is not shared between test account and live account" (Shippo: Authentication).

  • A Shippo API token for that account. In the Shippo API portal, open API Configuration, then Developer keys, and create a test key or a live key. Test keys begin with shippo_test_ and live keys with shippo_live_; Shippo shows the full key only once (Shippo: Authentication).

  • For automatic label purchase: a carrier account in Shippo for each carrier you ship with, and a Shippo carrier parcel template for your usual box (see Default Parcel, below).

Configuration Details

  • API Url: Shippo's API address. Example: https://api.goshippo.com.

  • API Token: the Shippo API token of the account this subscription connects to. Example: (your token, as Shippo shows it when you create it).

Configure Subscription Settings

Field

Description

Required

Example

API Url

Shippo's API address. Pre-populated; leave it as it is. A blank value uses https://api.goshippo.com, and a trailing slash is ignored. The value must be an https address on Shippo's own host with no user name in it; anything else, a proxy included, stops the connection (SHPO-VALD-1001) and the token is never sent there.

Yes

API Token

The Shippo API token that signs every call to Shippo. Stored as a password and never shown in logs or errors. A test token (shippo_test_) buys only free test labels that never ship; any other token is treated as live, and live labels cost real postage. A Shippo token pasted into another text setting stops the connection (SHPO-VALD-1010), which names the setting and never shows the value.

Yes

(your token)

Automatic Label Purchase

True buys each order's label when the order is sent to Shippo, once per order. False sends orders only, and they wait in Shippo's orders list for your staff to buy the label. Only True turns it on. Automatic purchase also needs a row in the Shippo Label Service translation for the order's shipping method, the ship-from custom fields filled on the order, a weight, and Default Parcel.

No

False

Allow Live Label Purchases

Must be True for automatic purchase with a live token. With it off, a live token never buys a label (SHPO-BIZL-1006) and the order still reaches Shippo. Only True turns it on.

No

False

Default Parcel

The parcel used for every automatic label: a Shippo carrier parcel template, with the weight taken from the order (or the sum of its lines). Blank refuses automatic purchase (SHPO-VALD-1008); orders are still sent. A template Shippo doesn't know is refused by Shippo when the label is bought (SHPO-EXTN-1004).

No

USPS_SmallFlatRateBox

Label File Type

The file type of bought labels: PNG, PNG_2.3x7.5, PDF, PDF_2.3x7.5, PDF_4x6, PDF_4x8, PDF_A4, PDF_A6 or ZPLII (not case sensitive). Anything else uses PDF_4x6.

No

PDF_4x6

Days of Label History

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 (SHPO-BIZL-1009). A first send is always bought. Allowed values 1 to 365.

No

7

Label Page Size

How many labels each call reads during the scheduled label check. Allowed values 1 to 100 (Shippo's largest page). Leave the default.

No

100

Carrier Account Page Size

How many carrier accounts each call reads when the integration loads carrier services. Allowed values 1 to 100. Leave the default.

No

25

API Throttle Limit

The number of calls to Shippo allowed per throttle period. Pre-populated.

Yes

500

API Throttle Seconds

The length of the throttle period, in seconds. Pre-populated.

Yes

60

API Throttle Limit (To iPaaS)

The number of calls back to iPaaS.com allowed per throttle period, for transfers TO iPaaS.com. Pre-populated.

Yes

500

API Throttle Seconds (To iPaaS)

The length of that throttle period, in seconds. Pre-populated.

Yes

60

Concurrent Connections

How many transfers run at the same time. Pre-populated.

Yes

2

Concurrent Batch Executions

Not used by this integration. Leave the default.

No

10

Number and Switch Settings

Every setting is trimmed, so spaces or line breaks copied around a value don't matter. A number the integration can't use as entered is adjusted rather than refused: a value outside the allowed range uses the nearest allowed value, and a value that isn't a whole number uses the default. Automatic Label Purchase and Allow Live Label Purchases are on only when they read True; blank or anything else is off.

Before you turn on Automatic Label Purchase: 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. With a live token that postage is real, so buy or clear held orders in Shippo first.

Values the Integration Stores

Once the subscription has exchanged data with Shippo, the settings page also lists values the integration saved for itself:

  • Last Date of Label Poll: where the scheduled label check last stopped. The next poll picks up from it. Don't edit it.

  • Shippo Webhook Id for transaction_created, transaction_updated and track_updated: the id of each webhook the integration registered in Shippo. The integration keeps them current itself; don't edit them.

Authentication Methods

  1. In Shippo, create an API token for the account this subscription connects to (see Prerequisites).

  2. In the iPaaS.com subscription settings, enter API Token (and leave API Url as it is), then click Apply. There is no separate Authorize step and no token refresh: the integration keeps using the saved token until you change it.

  3. The integration signs every call to Shippo with the token, as Shippo requires: "Shippo authenticates your API requests using your account's API keys" (Shippo: Authentication).

  4. Saving the subscription doesn't test the connection. At the start of a transfer the integration checks it with one read of your Shippo addresses. When the check fails, the transfer's error in Dashboard / Integration Monitoring / Error Logs reads only "Unable to connect to subscription with id N"; the reason is in the company's Logs at the error's time:

    • SHPO-AUTH-1002: the API Token setting is empty.

    • SHPO-AUTH-1001: Shippo refused the token, for example a deleted or mistyped token.

    • SHPO-AUTZ-1001: the token is valid, but its Shippo account isn't allowed the call; check the account's status in Shippo.

    • SHPO-VALD-1001: API Url isn't Shippo's https address.

    • SHPO-VALD-1010: a Shippo token was pasted into API Url, Default Parcel or Label File Type.

    • SHPO-EXTN-1003: Shippo couldn't be reached; iPaaS.com retries the transfer.

One Shippo account per subscription. A subscription holds one API token. Create a second subscription for a second Shippo account.

Changing the token: create the new token in Shippo, enter it in API Token and click Apply; the next transfer uses it. Delete the old token in Shippo only after the new one is saved. Moving between a test token and a live token moves the integration to the other set of Shippo data, so set each webhook scope inactive and active again to register its webhook for that mode.

Webhooks: setting a Shippo scope (transaction_created, transaction_updated or track_updated) Active under Inbound Data Flows registers one webhook for that event in your Shippo account, pointing at your subscription's iPaaS.com webhook address with its key. Setting the scope inactive removes that webhook. The integration never changes webhooks you created in Shippo yourself.

Initialization Support

Initialization is supported for shipping methods only: it loads every carrier service of the carrier accounts active in Shippo TO iPaaS.com as shipping methods. Orders are not initialized: an order already in iPaaS.com is sent to Shippo the next time it changes, or when you resend it with a Manual Sync. Existing labels arrive through the scheduled label check, which looks back Days of Label History: raise that setting before the first poll to bring in a longer history.

Throttling

The subscription's throttle fields are pre-populated with these defaults: API Throttle Limit 500 and API Throttle Seconds 60, API Throttle Limit (To iPaaS) 500 and API Throttle Seconds (To iPaaS) 60, Concurrent Connections 2 and Concurrent Batch Executions 10. Leave them at their defaults. Shippo limits calls per minute by endpoint and method, with lower limits for test tokens than for live ones, and "Exceeding the rate limit will give a 429 error" (Shippo: Rate limits). A transfer that reaches the limit is held and retried automatically (SHPO-EXTN-1002).

Related Documents

Did this answer your question?