New here? This page is a configuration reference for teams implementing the ShipStation API v2 integration in iPaaS.com. It documents scope, design decisions, and settings to confirm before go-live. These are not product defects, and most items are handled during implementation by iPaaS.com or your Managed Integration Service Provider (MiSP). See Understanding Integration Scope & Known Limitations for how we document this for every integration.
This document lists what subscribers should know before installing the ShipStation API v2 integration. Most of these items come from design decisions, from what the ShipStation API v2 can and cannot do, or from the scope of the 1.0.0 release. A few describe current behavior that is expected to change; those are marked "at the time this documentation was written".
For each limitation we explain what it is, why it exists, and what this means for you.
Platform Scope and Tested Versions
Item | Value |
Integration name | ShipStation API v2 |
Integration version | 1.0.0 |
Remote platform API | ShipStation API v2 |
Not covered | The ShipStation v1 API, which the earlier ShipStation integration covers. |
Not verified with a live provider | LTL freight quoting, booking and the freight poll (section 9), which need a Worldwide Express or Unishippers account connected in ShipStation. ShipStation API v2 offers no freight test mode. |
Not observed live | A |
1. Labels are never bought by the integration
What: Orders reach ShipStation as pending orders with no label. The integration never buys a label.
Why: A label costs money and commits a carrier. That decision stays with the shipper in ShipStation.
What this means for you:
Buy labels in ShipStation: by hand, with automation rules, or in batches.
Tracking comes TO iPaaS.com only after a label exists. An order with no label has no tracking record.
2. The store is set by id, not by name
What: The Store Id field takes a ShipStation store id. It cannot be a store name.
Why: The ShipStation API v2 has no way to list stores, so the integration cannot turn a name into an id.
What this means for you:
Put the store id in the order's ShipStation Store custom field. The id is shown in ShipStation's store settings.
Leave it blank to use ShipStation's default store.
The store is set when the order is created. It is not changed on update.
3. A new integration, not an upgrade
What: ShipStation API v2 is a separate integration from the earlier ShipStation integration. It has different settings and a different field layout.
Why: It uses the ShipStation API v2 only. The earlier integration also needs a v1 key and secret.
What this means for you:
There is no upgrade path. Moving from the earlier integration means a new subscription.
The settings are now API Url and API Key only. The earlier integration's API Secret, V2 API Access Key and V2 API Base URL are gone.
Order-wide fields (warehouse, store, notes, amounts, dates, customs, freight) are on the Order table. The earlier integration repeated them on the address. Mappings from the earlier integration's templates do not carry over.
Tracking now comes from ShipStation API v2 labels, by polling plus a tracking webhook. The earlier integration polled the v1 shipments list.
4. Order amounts are not divided across destinations
What: With Enable Multi Address Shipment on, each destination's ShipStation order carries the full Amount Paid, Shipping Paid and Tax Paid of the iPaaS.com order.
Why: There is no reliable rule for dividing an order's payment across shipments.
What this means for you: Do not add up the amounts of a split order's ShipStation orders. If you need per-destination amounts, map them yourself.
5. Labeled or cancelled ShipStation orders are not changed
What: Once a ShipStation order has a label, or is cancelled, the integration leaves it as it is. It does not update it, cancel it, or void its label.
Why: ShipStation can't change a labeled or cancelled order. A label may already be on a box in a truck.
What this means for you:
Changes to the iPaaS.com order after labeling do not reach ShipStation.
To cancel a labeled order, void the label in ShipStation, then cancel the order there. The integration's cancel reports this in
SSV2-EXTN-1004.
6. Tracking comes back only for orders this integration sent
What: A label or freight shipment is linked to its iPaaS.com order through the external shipment id the integration sets on the ShipStation order. Labels for orders that reached ShipStation another way have no link.
Why: Orders that ShipStation imports through its own store connections (for example, from a storefront) carry no iPaaS.com id.
What this means for you: The default tracking filter skips records with no TransactionId. Tracking for those orders is not brought TO iPaaS.com.
7. Webhooks only for tracking events
What: ShipStation sends iPaaS.com one webhook, track_event_v2, for tracking status changes. New labels, voided labels, LTL freight and carrier services are polled.
Why: ShipStation API v2 has no usable webhook for the rest. Its label-created event carries a list query instead of one label, and there is no webhook for voids, freight or carriers.
What this means for you:
New labels are picked up by the next
label/poll, not the moment they are bought. At the time this documentation was written, a newly bought label fails its tracking transfer until the carrier recognizes the tracking number, usually after the first carrier scan, and no tracking record is created by that attempt. Retry the transfer from Integration Monitoring. With track_event_v2 turned on, the first carrier scan also triggers a new transfer.Delivery status changes come only from the webhook.
label/pollpicks up new and voided labels, not later status changes, so a missed tracking event is not caught by a poll.A label's delivery status is also read each time the label is transferred.
Shipment Tracking has no initial load. Labels older than Days of Label History at the first
label/pollnever come in.iPaaS.com cannot check ShipStation's webhook signature. The integration treats the webhook as a trigger only, and re-reads the label from ShipStation.
Orders shipped without a ShipStation label (for example, marked shipped with a tracking number typed in by hand) produce no tracking record.
8. Voided labels arrive as records
What: A voided label comes TO iPaaS.com as a tracking record with ShipStation Voided set to true.
Why: So a template can flag or remove it.
What this means for you: Filter or remove voided records in the collections that send tracking on to other systems.
9. LTL freight
9.1 LTL freight uses US units and a freight provider account
What: Freight is quoted in pounds and inches. Insured value is in US dollars. Freight goes through a freight provider account (Unishippers or Worldwide Express) connected in ShipStation.
Why: This is how ShipStation API v2 LTL freight works.
What this means for you:
Line weights in other units are converted to pounds. Handling unit dimensions must be in inches.
Connect a freight provider in ShipStation and set Freight Provider Account before you send freight orders.
9.2 Booking dispatches a carrier
What: Freight Mode = Book books an LTL offer. Booking dispatches a real carrier and is billed.
Why: A ShipStation freight booking is a real dispatch. ShipStation has no test mode for this kind of account.
What this means for you:
The default template leaves Freight Mode blank.
Quotegets a quote and saves the freight setup on the ShipStation order, so you can book in ShipStation's own screen.The integration never books a shipment twice. Before booking, it checks the iPaaS.com order for an existing booking, and it marks the booking as started on the order before it books.
If a booking's result doesn't reach iPaaS.com (for example, iPaaS.com refuses the record, or ShipStation doesn't answer), a resend stops with
SSV2-FRGT-1004instead of booking again. Check ShipStation's freight shipments for the order, then follow that error's steps.Booking needs the order's iPaaS.com transaction. Without it the integration refuses with
SSV2-FRGT-1003.
9.3 Only integration-booked freight carries its cost
What: The freight charge appears TO iPaaS.com only for freight the integration quoted or booked.
Why: ShipStation returns the freight charge only in the quote and booking responses. Reading a freight shipment later returns its status, BOL and PRO, but not the cost. So the integration writes the quote or booking record TO iPaaS.com at the moment it quotes or books.
What this means for you: Freight booked in ShipStation's screen has no cost on its iPaaS.com tracking record.
9.4 Freight booked in ShipStation can't be linked to its order
What: Freight booked in ShipStation's own screen is not linked to its iPaaS.com order.
Why: ShipStation returns the ShipStation order reference only in the booking response, not when a freight shipment is read later.
What this means for you: Freight booked in ShipStation has no TransactionId, so the default tracking filter skips it. Book through the integration (Freight Mode = Book) if you need the freight on the iPaaS.com order.
9.5 Freight status is polled, for 30 days
What: freight_shipment/poll reads freight shipments created in the last 30 days. It refreshes new ones and any not yet delivered or cancelled.
Why: ShipStation has no freight webhook and no "changed since" filter for freight.
What this means for you:
The PRO number often arrives after pickup. Until then, the tracking number is the BOL number.
A freight shipment still open after 30 days is no longer refreshed.
Only freight the integration booked is refreshed onto its order: the poll finds the order through the integration's own booking record (item 9.4).
10. No test mode in ShipStation
What: ShipStation has no sandbox for ShipStation platform accounts. Every write the integration makes is real.
Why: ShipStation offers sandbox keys only to its separate developer product.
What this means for you:
Test orders create real, pending ShipStation orders. Use a filter that lets only test orders through, and cancel them afterwards.
Quotes are free. Labels and freight bookings are not.
11. Duplicate protection depends on the iPaaS.com id
What: ShipStation does not enforce unique external shipment ids and has no idempotency keys. Before creating a ShipStation order, the integration looks for one with the same iPaaS.com address id.
Why: This lookup is the only way to stop a retry from creating a duplicate.
What this means for you:
If you create an order by hand in ShipStation with the same external shipment id, the integration may update it instead of creating a new one.
If several ShipStation orders share the id, the newest one that isn't cancelled is used, and the others are logged.
12. One Shipping Method per carrier service
What: Each carrier service becomes one Shipping Method, keyed carrier_code|service_code. If two carrier accounts in ShipStation offer the same service, only one record is kept.
Why: The two accounts offer the same service, and the key is the same.
What this means for you: ShipStation Carrier Id on that Shipping Method is one of the two accounts. Lookups by service name return the same account.
Load shipping methods before labels: iPaaS.com requires a tracking record's Shipping Method to be the name of a configured shipping method and refuses anything else (VALD-1036). The Shipment Tracking mapping finds that name through the link the Shipping Method flow creates, so run shipping_method/initialize before the first label comes in, and again after connecting a new carrier.
Existing shipping methods with the same name: if iPaaS.com already has a shipping method with the same name (for example, one the earlier ShipStation integration created), check after shipping_method/initialize that tracking records name the one you expect. Validate this in a staging environment before relying on it in production.
Two services with the same name: iPaaS.com requires every Shipping Method name to be unique, and ShipStation can list two carrier services under the same display name (for example, FedEx lists two services as "FedEx International Economy®"). Only one of them can be created during shipping_method/initialize; the other is refused with BIZL-1007 and has no Shipping Method of its own. To bring both in, change the Shipping Method collection's Name mapping to a Dynamic Formula that adds a distinguishing key, such as the ShipStation service code (for example, return Name + " (" + ServiceCode + ")";), then run shipping_method/initialize again. Tracking records find their Shipping Method through its link, so they follow the new names.
LTL freight: freight carriers are not listed by ShipStation's carriers endpoint, so the Shipping Method flow also creates one shipping method named LTL Freight (ShipStation) (external id freight|ltl), and every freight tracking record uses it.
13. Placeholder defaults to review before going live
Order filter. Sends transactions of type
Orderthat have a Transaction Number and whose status is notDraft,Complete,Shipped,RefundedorReturned. A status the filter doesn't name is sent, so add any hold or review statuses your source uses. If your source marks ordersCompletebefore they ship, removeCompletefrom the filter. Add other conditions (for example a store or channel) so only orders ShipStation should ship are sent.Cancel Shipments. True when the iPaaS.com status is
Cancelled. Change it if your order source uses another status for cancelled orders.Deletes are opt-in. The shipped Order collection is Add/Update only, so deleting an iPaaS.com order does nothing in ShipStation. To have deletes cancel the order's ShipStation orders, subscribers or their MiSP add a second Order FROM iPaaS.com collection with the sync type Delete (a copy of the Order collection works; no child collections are needed), and allow a few minutes after saving before relying on it. A delete cancels only the ShipStation orders recorded on the iPaaS.com order. Otherwise, use the Cancelled status.
Country. Blank sends
US, so a foreign address with no country ships as a US address. Populate Country on every non-US address.Currency. Blank sends
usd.Quantity. Rounded up to a whole number, with no warning: 1.5 is sent as 2. ShipStation accepts only whole-number item quantities and rejects a decimal, so the quantity must be converted. To round fractions down instead of up, change the Order Line Quantity mapping to
return Convert.ToInt32(Math.Floor(Qty));(1.5 is then sent as 1). With rounding down, a quantity below 1 is sent as 0 and that item ships no units. Either way, sources that sell by weight or length should send whole quantities.Package weight. Blank sends
0with unitounce. ShipStation then uses the items' weights, if they have them.Line weight unit. Blank sends
poundwhen a weight is mapped.Amount Paid. The full order total, on every destination's ShipStation order (see item 4).
14. ShipStation shows the send date, not the order date
What: ShipStation dates each order by when the integration created it, not by the iPaaS.com order date.
Why: ShipStation API v2 has no order date on a new order, so the integration has no field to send it in.
What this means for you: Sorting or reporting by order date in ShipStation shows the date the order was sent. Use the order number to find an order, or report on order dates in iPaaS.com or your order source.
15. Order updates replace ShipStation-side edits, and other update rules
What: Each update rebuilds the ShipStation order from the Order collection's mappings and sends only what is mapped. At the time this documentation was written:
Package dimensions entered in ShipStation are reset to 0 by the next update unless they are mapped.
An order split in ShipStation is undone by the next update, so the moved items can ship twice.
An order cancelled through the integration and then reopened in the source is not re-created; the transfer reports success and the order has no live ShipStation order.
An address removed in the order source may stay on the iPaaS.com order, because an update from the source does not always remove it. The integration cancels the ShipStation order of a destination removed from the iPaaS.com order, but while the address stays, its ShipStation order stays live.
Why: The integration treats iPaaS.com as the source of the order and ShipStation as the place it ships from.
What this means for you:
Map package dimensions if packers enter them in ShipStation.
Don't split integration orders in ShipStation.
Re-create a reopened order by hand in ShipStation, and if a removed address is still on the iPaaS.com order, cancel its ShipStation order there.
If you add a second Order FROM iPaaS.com collection, keep the two filters from matching the same order, so each order is sent by one collection with one set of mappings. A new Order collection also needs its own Address and Line child collections; without them the order has nothing to ship and stops with
SSV2-VALD-1003.We recommend one iPaaS.com subscription per ShipStation account, so one subscription's updates, cancels and label polls can't reach another's orders.
16. Setting changes take a few minutes
What: A change to a subscription setting (for example Enable Multi Address Shipment) or to a mapping collection can take several minutes to apply.
Why: Changes to settings and mapping collections are not applied to transfers immediately.
What this means for you: Orders sent in the minutes after a change use the old configuration. Wait a few minutes after a change before sending orders that depend on it.
17. Gift card lines are sent as items
What: Every line on an order is sent to ShipStation as an item, including lines whose type is Gift Card. At the time this documentation was written, the integration did not check the line type, and the template's ShipStation Order Line FROM iPaaS.com collection has no filter.
Why: Some gift cards are physical and need to be packed and shipped; electronic gift cards are not shipped. The integration cannot tell which kind a line is.
What this means for you: If your orders carry electronic gift cards, add a filter to the ShipStation Order Line FROM iPaaS.com collection so those lines are not sent. For example, return Type != "Gift Card"; leaves out every gift card line and sends the rest of the order. If you also sell physical gift cards that must ship, filter on something in your data that tells the two apart, such as the SKU, instead of on the line type alone. Test any such filter in a staging environment before relying on it in production. Wait a few minutes after saving the filter before sending orders (see section 16).
18. More than one subscription on one ShipStation account
What: Each subscription's label poll reads every label on the ShipStation account, not only labels for its own orders. Before creating a ShipStation order, the integration also looks across the whole account for an existing order with the same iPaaS.com transaction and address id (see section 11). At the time this documentation was written, those ids did not identify the subscription or the iPaaS.com environment.
Why: A ShipStation API key gives access to the whole account. iPaaS.com ids are unique within one iPaaS.com environment, but each environment numbers its records separately.
What this means for you:
Subscriptions in the same iPaaS.com environment can share a ShipStation account. Filter each subscription's Add/Update ShipStation Shipment Tracking TO iPaaS.com collection so it takes only its own orders, for example by an order number prefix:
return TransactionId != null && ShipmentNumber != null && ShipmentNumber.StartsWith("WEB-");. With only the default filter, each subscription also tries to bring in tracking for the other subscription's orders. Test the filter in a staging environment before relying on it in production.Subscriptions in different iPaaS.com environments, such as staging and production, should use separate ShipStation accounts. Their ids can match, so an order sent from one environment can update or cancel the other environment's ShipStation order, and a filter cannot prevent it.
Reporting an issue
If you see behavior not covered above and suspect a bug:
Capture the iPaaS.com Subscription ID, the ShipStation order number or label id, and the iPaaS.com error log entry (it includes ShipStation's request id).
Open a support ticket at https://support.ipaas.com/en/. Name the integration and its version: ShipStation API v2 1.0.0.
For problems on the ShipStation side, contact ShipStation support with the request id.