Skip to main content

ShipStation API v2 Known Limitations

Known limitations of the iPaaS.com ShipStation API v2 integration: design decisions, ShipStation API v2 constraints, changes from the earlier ShipStation integration, and defaults to review before go-live.

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.

LTL freight verified

Quoting, booking and the freight poll (section 9) through a Worldwide Express account connected in ShipStation. Unishippers was not verified. ShipStation API v2 offers no freight test mode.

Not observed live

A track_event_v2 webhook sent for a real carrier scan (section 7). Delivery status updates depend on ShipStation sending this webhook for carrier scans.

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, the integration leaves it as it is. It does not update it, cancel it, or void its label. A cancelled ShipStation order is not changed either; if its iPaaS.com order is still open (for example, reopened after a cancel), the next transfer creates a new ShipStation order for it.

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. A label whose tracking number the carrier hasn't registered yet arrives without a delivery status; with track_event_v2 turned on, the first carrier scan fills it in.

  • Delivery status changes come only from the webhook. label/poll picks 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/poll never 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.

  • Booking needs a ship-to phone. ShipStation refuses a booking without one (SSV2-EXTN-1008, "The ship to contact phone number field is required"). The template sends the address's phone, or the address custom field ShipStation Phone when the address has none.

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. Quote gets 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-BIZL-1002 instead 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-BIZL-1001.

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's own screen

What: At the time this documentation was written, freight booked through the integration was linked to its iPaaS.com order, and reading that freight shipment from ShipStation returned its ShipStation order reference. Freight booked in ShipStation's own screen was not tested.

Why: The freight poll links a freight shipment to its order through that ShipStation order reference.

What this means for you: Book through the integration (Freight Mode = Book) when you need the freight on the iPaaS.com order. If you book in ShipStation's screen, check after the next freight_shipment/poll that the freight reached the iPaaS.com order before relying on it.

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.

  • The poll finds a freight shipment's order through the ShipStation order reference returned with it, or else through the integration's own booking record (item 9.4).

9.6 A freight quote appears as a tracking record named QUOTE

What: With Freight Mode = Quote, the integration records the quote on the iPaaS.com order as a tracking record whose tracking number is QUOTE and whose cost is the quoted charge. With Book, the same record is marked as a booking in progress until the booking record replaces it.

Why: The quote's price exists only in ShipStation's quote response, and the record is also the mark that stops a carrier being booked twice.

What this means for you: Any flow that sends an order's tracking FROM iPaaS.com to another system, such as a storefront that emails shoppers their tracking, should skip records whose tracking number is QUOTE, so a quote isn't sent as a shipment. Add that condition to the flow's filter when you set it up.

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 (for example after a split in ShipStation), the oldest 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 Order that have a Transaction Number and whose status is not Draft, Complete, Shipped, Refunded or Returned. A status the filter doesn't name is sent, so add any hold or review statuses your source uses. If your source marks orders Complete before they ship, remove Complete from 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 0 with unit ounce. ShipStation then uses the items' weights, if they have them.

  • Line weight unit. Blank sends pound when 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. At the time this documentation was written:

  • A value edited in ShipStation on a field the mappings send is replaced by the next update. Package values nothing maps (weight, dimensions, package type) keep what was entered in ShipStation.

  • An order split in ShipStation keeps its split: the update leaves the items as ShipStation split them, and cancelling the order cancels every part.

  • An update of a split order reaches only the original ShipStation order. The part split off in ShipStation keeps the order details it had at the split, such as the ship-to email.

  • An order cancelled through the integration and then reopened in the source gets a new ShipStation order on its next transfer.

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

  • After splitting an order in ShipStation, change its quantities there: an iPaaS.com quantity change doesn't reach a split order.

  • After a split, make any later change to the ship-to details (address, email, phone) on each part in ShipStation, because an update from iPaaS.com reaches only the original part.

  • To stop an order shipping, cancel it in the order source. An order cancelled only in ShipStation gets a new ShipStation order if its iPaaS.com order is updated while still open.

  • If a removed address is still on the iPaaS.com order, cancel its ShipStation order in ShipStation.

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

  • 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 Add/Update 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 Add/Update 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.


This article covers 20 known limitations of the ShipStation API v2 integration; limitation 9 has six parts. For the field-level detail behind each one, including which fields a collection maps, its mapping filter and its prerequisites, see the ShipStation API v2 mapping collection descriptions and mapping documentation articles.

19. The residential indicator is not kept by ShipStation

What: At the time this documentation was written, ShipStation stored the residential indicator of every order as unknown in testing, whatever the integration sent: yes, no, or nothing.

Why: The integration sends the value mapped to Residential unchanged, and ShipStation API v2 accepts unknown, yes or no for it, but ShipStation kept unknown.

What this means for you:

  • Don't rely on the mapped Residential value to decide residential delivery or its surcharge. Check the address type in ShipStation, or with the carrier, before buying the label.

  • Validate this in a staging environment before relying on it in production; ShipStation may change how it treats the field.

20. The label poll reads every label on the account

What: label/poll reads every label created or voided in ShipStation since the last poll, including labels for orders iPaaS.com never sent, such as orders from ShipStation's own store connections. Each of those labels costs two or three ShipStation requests before the default tracking filter skips it.

Why: ShipStation can list labels by date, but it can't list only the labels on orders this integration sent.

What this means for you:

  • On an account where many orders come from ShipStation's store connections, label polls use more of ShipStation's request limit.

  • If label polls run into ShipStation's rate limit (SSV2-EXTN-1006), poll less often, or keep the store-connected orders on a separate ShipStation account.

Reporting an issue

If you see behavior not covered above and suspect a bug:

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

  2. Open a support ticket at https://support.ipaas.com/en/. Name the integration and its version: ShipStation API v2 1.0.0.

  3. For problems on the ShipStation side, contact ShipStation support with the request id.

Related Documents

Did this answer your question?