This article walks you through installing the ShipStation API v2 integration on iPaaS.com. You will prepare your ShipStation account, create an API v2 key, subscribe, fill in the settings, apply the default templates, turn on the scopes and fill in the custom fields your order source uses.

Before You Begin

You need a ShipStation login that can open Settings → Account → API Settings and create an API key. LTL freight also needs the freight provider account and the freight custom fields on your order source.

What your ShipStation account needs

Item	Needed for	Notes
A ShipStation plan that includes API v2	Everything	The integration uses the ShipStation API v2 only. It does not need v1 API access.
At least one warehouse (ship-from location)	Orders FROM iPaaS.com	The default template looks the warehouse up by its name. An order with neither a warehouse nor a ship-from address uses your ShipStation default warehouse, or your only warehouse. If you have several warehouses and none is the default, ShipStation refuses such an order, so set a default warehouse in ShipStation.
Carriers connected in ShipStation	Shipping methods and labels	Every service of every connected carrier becomes a Shipping Method in iPaaS.com.
A store id (optional)	Orders FROM iPaaS.com	Orders are filed under ShipStation's default store unless you give a store id. The id is shown in ShipStation's store settings. The API v2 has no way to look a store up by name.
An LTL freight provider account (optional)	LTL freight only	A commercial account with Unishippers or Worldwide Express, connected in ShipStation. You need its id, which starts with `se-`, for the Freight Provider Account setting. Skip LTL entirely if you don't have one.

ShipStation has no test mode for this kind of account. Every order the integration sends is a real, pending ShipStation order. The integration never buys a label. An LTL booking (Freight Mode = Book) dispatches a real carrier and is billed. Test with a filter that only lets test orders through, and cancel the test orders afterwards.

To create a ShipStation API v2 key

Log in to ShipStation.
Go to Settings → Account → API Settings.
Under Select API Version, choose V2 API, and create the key if none is shown. Do not use the v1 API Key and API Secret pair. The integration cannot use it.
Copy the key and keep it somewhere safe, such as a password manager. You will paste it into the subscription's API Key setting.

Treat the key like a password. Anyone with it can read and change your ShipStation data.

To find the freight provider account id (LTL only)

Skip this if you do not ship LTL freight.

Connect your Unishippers or Worldwide Express account in ShipStation's freight settings.
If ShipStation shows the account's id (it starts with se-), note it for the Freight Provider Account setting.

ShipStation may not show the id. Then leave Freight Provider Account blank and add one mapping instead (your MiSP can do this): on the Add/Update ShipStation Order FROM iPaaS.com collection, map the FreightProviderAccount field with this formula, putting your account's nickname or provider code between the quotes:

return await GetFreightProviderAccountIdAsync("UNISHIPPERS");

The function looks the account up in ShipStation and returns its id. See the Mapping Functions article for details.

Installation Instructions for Integration Setup

In iPaaS.com, go to Subscriptions and click Search Certified Integration Marketplace and Subscribe.
Click the ShipStation API v2 integration tile. This is a separate integration from the older ShipStation integration.
Click Subscribe.
Enter a name for the subscription. It must be unique within the company.
- Format: ShipStation API v2 - [Environment/Purpose]
- Example: ShipStation API v2 - Production
Leave Create Default Mappings selected (it is selected by default; recommended). This applies the default templates listed under Default Mapping Collections below.
Enter the API Url.
- Enter https://api.shipstation.com/v2.
- The field starts blank on a new subscription and is required.
Enter the API Key you created in Before You Begin.
Set Enable Multi Address Shipment.
- False (default): one ShipStation order per iPaaS.com order, shipped to the primary shipping address.
- True: one ShipStation order per destination address. Each line needs the ShipToAddressExternalId custom field (see below).
- Left at --select--, it is False.
Enter the Freight Provider Account (LTL only). This is the se- id from Before You Begin. Leave it blank if you do not ship LTL freight.
Set Freight Offer Selection (LTL only).
- Default value: Cheapest
- The other value is Fastest.
- With Freight Mode = Book, a value the integration can't read stops the booking with SSV2-FRGT-1005. Blank uses the default.
Set Freight Pickup Window (LTL bookings only).
- Default value: 09:00-17:00
- Format: HH:mm-HH:mm.
- With Freight Mode = Book, a value the integration can't read stops the booking with SSV2-FRGT-1005. Blank uses the default.
Set Days of Label History.
- Default value: 7
- The field starts blank; blank uses 7.
- This is how far back the first label poll looks. Raise it before the first poll if you want older labels brought TO iPaaS.com.
Leave the platform presets (API Throttle Limit 500, API Throttle Limit (To iPaaS) 500, API Throttle Seconds 60, API Throttle Seconds (To iPaaS) 60, Concurrent Batch Executions 10, Concurrent Connections 2) at their pre-filled values. All except Concurrent Batch Executions are required, so do not clear them. ShipStation allows 200 requests a minute, but the integration follows the rate limit ShipStation reports, so these values don't need to match it. If you see SSV2-RATE-1001 often, lower Concurrent Batch Executions.
Click Apply to save the settings. Saving does not test the connection. The integration checks the key on its first transfer; a wrong key or API Url makes that transfer fail with Unable to connect to subscription with id N. The reason, with its code (for example SSV2-AUTH-1002), is in the company's Logs at the same time, with the same reference id as the failed transfer.

See ShipStation API v2 Connections and Settings for every setting in detail.

Default Mapping Collections

The default templates create these collections:

Collection	Type	Direction
Add/Update ShipStation Order FROM iPaaS.com	Transaction	FROM iPaaS.com
ShipStation Order Address FROM iPaaS.com	Transaction Address (child)	FROM iPaaS.com
ShipStation Order Line FROM iPaaS.com	Transaction Line (child)	FROM iPaaS.com
Add/Update ShipStation Shipment Tracking TO iPaaS.com	Transaction Tracking Number	TO iPaaS.com
Add/Update ShipStation Shipping Method TO iPaaS.com	Shipping Method	TO iPaaS.com

Review the filters before you go live:

Order FROM iPaaS.com sends transactions whose type is Order and whose status is not Draft, Complete, Shipped, Refunded or Returned. Add your own conditions so only orders that ShipStation should ship are sent. For example, exclude orders a storefront already sends to ShipStation through ShipStation's own store connection.
Shipment Tracking TO iPaaS.com only brings in labels and freight shipments that belong to an order this integration sent (TransactionId != null).

The Order collection maps the iPaaS.com status Cancelled to Cancel Shipments. A cancelled order cancels its ShipStation orders.

Enable the Scopes

A scope is one kind of data the integration can bring TO iPaaS.com. A poll scope asks ShipStation for changes on a schedule; a webhook scope is ShipStation telling iPaaS.com as it happens. Turn the scopes on in the subscription's inbound (TO iPaaS.com) data flow section.

shipping_method/initialize is different: it isn't turned on, it is run. On the Subscription Settings screen, find the Initialize Data section and click Shipping Method (see Subscription Configuration - Edit). If it isn't listed there, contact your MiSP or iPaaS.com support.

Scope	Turn on	What it does
`shipping_method/initialize`	Run once after setup, before the first label	Loads every carrier service, plus LTL Freight (ShipStation), as a Shipping Method. Tracking records need them: iPaaS.com refuses a tracking record whose shipping method it doesn't know (its error VALD-1036).
`shipping_method/poll`	Optional	Keeps Shipping Methods current when you add carriers or services.
`label/poll`	Yes	Brings in new labels and voided labels as tracking records.
`track_event_v2`	Yes (webhook)	Brings in delivery status changes when ShipStation sends a tracking event. `label/poll` does not pick up later status changes. Turning it on registers a webhook in ShipStation.
`freight_shipment/poll`	LTL only	Refreshes LTL freight status, BOL and PRO numbers.

Orders FROM iPaaS.com run on iPaaS.com's own transaction events. Turn on the outbound order flow under the subscription's Outbound Data Flows: the transaction/created and transaction/updated events. Without them, no order reaches ShipStation.

Schedule the Polls

A /poll scope runs only on a schedule. Turning a poll scope on doesn't start it, and subscribing doesn't create the schedule. Until a poll event exists, no labels come TO iPaaS.com.

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. Production schedules run in UTC.

Event	Subscription	Scope	Suggested schedule
ShipStation labels	your ShipStation API v2 subscription	`label/poll`	every 15 minutes (`0 0/15 * * * ?`)
ShipStation freight	your ShipStation API v2 subscription	`freight_shipment/poll`	every hour (`0 0 * * * ?`), LTL only
ShipStation shipping methods	your ShipStation API v2 subscription	`shipping_method/poll`	once a day (`0 0 3 * * ?`), optional

Each poll reads ShipStation once (the labels poll reads labels created or voided since the last poll). Reads are free and count toward ShipStation's 200 requests a minute. The first label/poll looks back Days of Label History; after that, each poll starts where the last one ended.

Custom Fields

On your order source

These are iPaaS.com custom fields on the Transaction, Transaction Address and Transaction Line. The default templates read them by these exact names but don't create them: create any you use in iPaaS.com, then map them in the integration that sends your orders TO iPaaS.com. All are optional; fields marked LTL are only needed for freight orders.

Transaction

Custom field	Needed	What to put in it
ShipStation Ship From Location	Optional	The name of the ShipStation warehouse to ship from. The template turns it into the warehouse id. Blank uses your ShipStation default warehouse, or your only warehouse.
ShipStation Store	Optional	The ShipStation store id to file the order under. Blank uses the default store.
Currency	Optional	Three-letter currency code for every amount. Blank sends `usd`.
ShipStation Freight Mode	LTL	Blank for parcel, `Quote` to get an LTL quote, or `Book` to quote and book. Book dispatches a carrier and is billed.
ShipStation Freight Accessorials	LTL, optional	Comma-separated, for example `liftgate_delivery, appointment_delivery`.
ShipStation Freight Pickup Date	LTL, optional	`yyyy-MM-dd`. Blank uses the next weekday.

Transaction Address

Custom field	Needed	What to put in it
ShipStation Ship From Location	Optional	A warehouse name for this destination. It overrides the order's.
Package Weight	Optional	Package weight. Blank sends 0, and ShipStation then uses the items' weights.
Package Weight Unit	Optional	`pound`, `ounce`, `gram` or `kilogram`. Blank sends `ounce`.

Transaction Line

Custom field	Needed	What to put in it
Weight Unit	Optional	Unit of the line's weight: `pound`, `ounce`, `gram` or `kilogram`. Blank sends `pound`.
ShipToAddressExternalId	Multi-address	The source system's id of the address this line ships to. Blank sends the line to the primary shipping address.
Freight Class	LTL	One of 50, 55, 60, 65, 70, 77.5, 85, 92.5, 100, 110, 125, 150, 175, 200, 250, 300, 400, 500.
NMFC Code	LTL, optional	The NMFC code.
Handling Unit Key	LTL, optional	Lines with the same key share one handling unit (pallet). Blank gives the line its own.
Handling Unit Type	LTL, optional	For example `pallet`, `crate`, `drum`. Blank sends `pallet`.
Handling Unit Length	LTL	Inches.
Handling Unit Width	LTL	Inches.
Handling Unit Height	LTL	Inches.

Each LTL line also needs a weight: the line's Weight (with Weight Unit) and Quantity. If anything is missing, the transfer fails with SSV2-VALD-1004 and lists what is missing.

On the ShipStation API v2 subscription

The default Shipment Tracking and Shipping Method mappings write to these custom fields. Confirm they exist in your iPaaS.com company.

Transaction Tracking Number: ShipStation Shipment Id, ShipStation Order Number, ShipStation Label Id, ShipStation Status, ShipStation Tracking Status, ShipStation Tracking URL, ShipStation Estimated Delivery, ShipStation Actual Delivery, ShipStation Voided, ShipStation Freight Shipment Id, ShipStation BOL Number, ShipStation PRO Number, ShipStation Confirmation Number.
Transaction Tracking Number, LTL quotes and bookings: ShipStation Carrier SCAC, ShipStation Freight Offer Id, ShipStation Freight Quote Expires, ShipStation Freight Quote Inputs, ShipStation Transit Days. The integration writes these itself when it quotes or books freight. Do not edit ShipStation Freight Quote Inputs.
Shipping Method: ShipStation Carrier Code, ShipStation Service Code, ShipStation Carrier Id.

Authentication Configuration

ShipStation API v2 uses a static API key, sent as the API-Key header on every call. There is no OAuth and no token refresh. The key stays valid until you regenerate or delete it in ShipStation. To rotate it, create a new key, update API Key on the subscription, save, then remove the old key in ShipStation.

Post-Installation Verification

Connection check. There is no connection test on save. Run step 2: it is the first call to ShipStation. If it fails with Unable to connect to subscription with id N, open the company's Logs at that time and read the code (SSV2-AUTH-1001 to 1004), then fix the API Key or API Url.
Shipping methods. Run shipping_method/initialize (Subscription Settings → Initialize Data → Shipping Method). Check that iPaaS.com has one Shipping Method for each carrier service connected in ShipStation, and one named LTL Freight (ShipStation). Do this before any label comes in: the Shipment Tracking mapping looks up each label's shipping method by name, and iPaaS.com refuses a tracking record without one. Run it again after connecting a new carrier in ShipStation.
Order test. Send a test order that your filter lets through. Check that a pending order with no label appears in ShipStation with the same order number. Cancel it in iPaaS.com (status Cancelled) and check that it is cancelled in ShipStation.
Tracking test. Buy a label in ShipStation for an order the integration sent. After the next label/poll, check that a tracking record with the tracking number, the shipping method (for example, FedEx Ground®) and the cost appears on the iPaaS.com order.

Every error the integration records carries a code such as SSV2-AUTH-1002. Look the code up in ShipStation API v2 Error Messages.

Support and Troubleshooting

Click the Help button on any iPaaS.com page to contact Support or to search our documentation.

iPaaS.com Support Portal: https://support.ipaas.com/en/
iPaaS.com Contact Information: https://ipaas.com/contact-us/
ShipStation status: https://status.shipstation.com

ShipStation API v2 Installation Instructions