Summary
The Add/Update ShipStation Shipment Tracking TO iPaaS.com collection brings ShipStation shipping labels (parcels) and LTL freight shipments into iPaaS.com as Transaction Tracking Number records on the order this integration sent to ShipStation. Each tracking record carries the tracking number, shipping method, cost, ShipStation status, the carrier's delivery status and dates and, for freight, the BOL, PRO and pickup confirmation numbers.
New and voided labels arrive through a scheduled label poll, delivery status changes arrive through ShipStation's track_event_v2 webhook, and LTL freight shipments are refreshed by a freight poll. The sync type is Add/Update, so a label or freight shipment that is brought in again updates its existing tracking record rather than creating a duplicate. Labels for orders that reached ShipStation another way are skipped.
ID Format
Manual Sync ID Format
A parcel label: the ShipStation label id, for example se-512345678.
An LTL freight shipment: freight| followed by the ShipStation freight shipment id.
External ID Format (saved after sync)
iPaaS.com saves the same value as the tracking record's external id, and a later poll, webhook or Manual Sync uses it to find the existing record to update. The label id is also written to the ShipStation Label Id field and the freight shipment id to the ShipStation Freight Shipment Id field.
A freight quote record written by the Add/Update ShipStation Order FROM iPaaS.com collection is keyed to its ShipStation shipment until the freight is booked. When it's booked, the same record takes the freight| external id, so the freight poll updates it from then on.
Deleted Record Support
Deletes aren't supported. A label voided in ShipStation keeps its iPaaS.com tracking record: the next label poll brings the voided label in again, and it updates the same record with ShipStation Voided set to true and ShipStation Status set to voided. Filter out or handle voided records in downstream collections.
Custom Field Support
There are no custom fields to configure. The collection writes its own Transaction Tracking Number custom fields (the ShipStation fields in the mapping table below) as routine mappings.
Five LTL freight fields, ShipStation Carrier SCAC, ShipStation Freight Offer Id, ShipStation Freight Quote Expires, ShipStation Freight Quote Inputs and ShipStation Transit Days, are written by the Add/Update ShipStation Order FROM iPaaS.com collection when it quotes or books freight. This collection only keeps them: their formulas return the value already on the tracking record and never take a value from ShipStation.
Mapping Collection Status
Status: Enabled.
Trigger Events: transfers are automatic once the scopes below are turned on in the subscription's inbound (TO iPaaS.com) data flow section. A poll scope also needs a schedule: create a Webhook Poll Request event in iPaaS.com Events for each poll scope. There are no automatic transfers until the scopes are turned on and the polls are scheduled.
label/poll: a scheduled poll for labels created and labels voided since the last poll. The first poll looks back the number of days set in the Days of Label History setting (7 when blank); older labels are never brought in automatically. The poll doesn't pick up later delivery status changes.
track_event_v2: a ShipStation webhook for delivery status changes on a label, for example In Transit or Delivered. Turn it on to receive delivery statuses. Turning the scope on registers the webhook in ShipStation for this subscription; no setup is needed in ShipStation. Without it, only new and voided labels arrive, through the label poll.
freight_shipment/poll: a scheduled poll for LTL freight shipments from the last 30 days that aren't yet delivered or cancelled. It fills in the PRO number and the latest freight status.
Manual Sync: subscribers or their MiSP can bring in a single label or freight shipment at any time by entering its id (see ID Format).
Duplicate or Conflicting Mappings
This is the only collection in the integration that writes tracking records from ShipStation labels and freight polls. The Add/Update ShipStation Order FROM iPaaS.com collection also writes the LTL freight quote and booking records directly when it quotes or books freight; this collection then updates those same records.
Collision handling: none is configurable. A transfer matches an existing tracking record by its external id and updates it; otherwise it creates one.
Overwrite behavior: iPaaS.com replaces the whole tracking record on update. Every standard tracking field (parent, shipping method, shipping method description, tracking number and cost) is mapped, so no unmapped field is cleared. Mapped fields are overwritten on every transfer, with these exceptions:
ParentId keeps the order the record is already linked to.
Cost, ShippingMethod and ShippingMethodDescription keep their existing values when ShipStation sends none. For an LTL freight record, ShippingMethodDescription always keeps the carrier and service written at quote or booking.
The five LTL freight fields listed under Custom Field Support always keep the values written at quote or booking.
Supported Child Collections
None. This is a standalone collection; each tracking record is linked to its iPaaS.com order through ParentId.
System Caveats
ShipStation Caveats
Labels are the record. Only labels are brought in as parcel tracking: a ShipStation shipment with no label has no tracking yet.
No webhook for voids or freight. ShipStation doesn't send a webhook for voided labels or for freight shipments, so those arrive only through the polls.
Freight cost after booking. ShipStation doesn't return the freight charge when a booked freight shipment is read again, so the cost written at booking (the booked offer's total charges) is kept.
PRO numbers arrive later. Carriers often assign the PRO number only after pickup. Until then the freight record's tracking number is the BOL number, and the freight poll replaces it with the PRO number when it appears.
iPaaS.com Caveats
Shipping Method must exist. iPaaS.com refuses a tracking record whose shipping method doesn't match the name of an existing Shipping Method. The name is the carrier's display name as ShipStation shows it, for example FedEx Ground®.
The webhook is a trigger only. The label is read again from ShipStation before anything is written to iPaaS.com.
Setup Requirements
For the full setup steps, see the ShipStation API v2 Installation Instructions and ShipStation API v2 Connections and Settings articles. In order:
Connect the ShipStation account with an API v2 key in the subscription's API Key setting.
Run shipping_method/initialize (on the Subscription Settings screen, Initialize Data section, Shipping Method) for the Add/Update ShipStation Shipping Method TO iPaaS.com collection before labels flow, so that every carrier service in use exists as an iPaaS.com Shipping Method. Run it again after connecting a new carrier in ShipStation.
Send orders to ShipStation through the Add/Update ShipStation Order FROM iPaaS.com collection. Only those orders receive tracking.
Set Days of Label History to cover the labels you want on the first label poll.
Turn on label/poll, track_event_v2 and, if LTL freight is used, freight_shipment/poll in the subscription's inbound (TO iPaaS.com) data flow section. A setting change can take a few minutes to apply to transfers.
Create a Webhook Poll Request event in Events for each poll scope, for example every 15 minutes for label/poll.
Integration Flow
Trigger. A label poll, a track_event_v2 webhook, a freight poll or a Manual Sync names a label or a freight shipment. The label poll lists labels created since the last poll and labels voided since the last poll. The first poll looks back Days of Label History days. The freight poll lists freight shipments created in the last 30 days and refreshes each one that isn't yet delivered or cancelled.
Read. The integration reads the label from ShipStation, with its carrier tracking status unless the label is voided, and the ShipStation order the label belongs to. For a freight shipment, it reads the shipment and, unless it's delivered or cancelled, its latest tracking.
Link. The iPaaS.com order id is taken from the ShipStation shipment, where the Add/Update ShipStation Order FROM iPaaS.com collection stored it when it sent the order. When an order was split into one ShipStation shipment per destination, every shipment carries the same order id, so all their labels land on the one iPaaS.com order. Labels with no iPaaS.com order id are skipped by the mapping filter.
Map and write. The record is mapped through this collection and written to iPaaS.com as an add or an update, matched by its external id. The shipping method is resolved to the name of the iPaaS.com Shipping Method for the label's carrier service.
LTL freight quote and booking records. When the Add/Update ShipStation Order FROM iPaaS.com collection quotes LTL freight, it writes a tracking record with the tracking number QUOTE, the Shipping Method LTL Freight (ShipStation) and the quote fields. Booking the freight updates that record with the booked cost, BOL and confirmation numbers and the freight| external id. From then on the freight poll updates it through this collection, filling in the PRO number and status without changing the cost or the order.
Mappings
Add/Update ShipStation Shipment Tracking TO iPaaS.com
iPaaS.com data type: Transaction Tracking Number
Description: ShipStation labels and LTL freight shipments become tracking records on the iPaaS.com order this integration sent to ShipStation.
Mapping Filter: the filter transfers a label or freight shipment only when it carries an iPaaS.com order id. Its purpose is to bring in tracking only for orders this integration sent to ShipStation: labels for orders that reached ShipStation another way (entered by hand, or from another sales channel) have no iPaaS.com order to attach to, so they are skipped rather than failing.
Mapping Type | Source Field (ShipStation) | Destination Field (iPaaS.com) | Description |
Dynamic Formula | Dynamic Formula | ParentId | Required. Links the tracking record to its iPaaS.com order. An existing record keeps the order it's already linked to; otherwise the formula uses the iPaaS.com order id stored on the ShipStation shipment. |
Field | TrackingNumber | TrackingNumber | Required. The label's tracking number. For LTL freight, the PRO number once the carrier assigns it and the BOL number until then; a freight quote record carries QUOTE until the freight is booked. |
Dynamic Formula | Dynamic Formula | ShippingMethod | Required. The name of the iPaaS.com Shipping Method brought in for the label's carrier service, which is the carrier's display name (for example, FedEx Ground®); LTL freight uses LTL Freight (ShipStation). When none is found, an existing record keeps its value and a new record fails. |
Dynamic Formula | Dynamic Formula | ShippingMethodDescription | Recommended. The label's ShipStation service code, for example fedex_ground. An existing record keeps its description when ShipStation sends no service code; an LTL freight record always keeps the carrier and service written at quote or booking. |
Dynamic Formula | Dynamic Formula | Cost | Recommended. The label's shipment cost plus its insurance cost. An existing record keeps its cost when ShipStation sends none, which keeps the booked freight charge on LTL freight records. |
Field | ShipmentId | ShipStation Shipment Id | Recommended. The ShipStation shipment id the label belongs to, for example se-123456789. LTL freight quote and booking records are matched by it, so keep it mapped if you use LTL freight. |
Field | ShipmentNumber | ShipStation Order Number | Optional. The ShipStation order number, including any "(1 of N)" suffix on a split order. |
Field | LabelId | ShipStation Label Id | Optional. The ShipStation label id; also the record's external id. Empty for LTL freight. |
Field | Status | ShipStation Status | Optional. The label's status (for example, completed or voided) or the freight shipment's status (quoted, booked, in_transit, delivered, cancelled or exception). |
Field | TrackingStatus | ShipStation Tracking Status | Optional. The carrier's tracking status, for example In Transit or Delivered. For a label, updated by the track_event_v2 webhook; for LTL freight, the latest tracking event. |
Field | TrackingUrl | ShipStation Tracking URL | Optional. The link to the carrier's tracking page. |
Field | EstimatedDeliveryDate | ShipStation Estimated Delivery | Optional. The estimated delivery date and time, in ISO 8601 format; for LTL freight, the quoted estimate. |
Field | ActualDeliveryDate | ShipStation Actual Delivery | Optional. The delivery date and time, in ISO 8601 format. Empty until delivered, and cleared when ShipStation sends no value. |
Field | Voided | ShipStation Voided | Recommended. True when the label was voided in ShipStation. This is how a voided label is identified downstream. |
Field | FreightShipmentId | ShipStation Freight Shipment Id | Optional. The ShipStation id of an LTL freight shipment. The integration checks it before booking so that an order is never booked twice, so keep it mapped if you book freight. |
Field | BolNumber | ShipStation BOL Number | Optional. The LTL freight Bill of Lading number, assigned at booking. |
Field | ProNumber | ShipStation PRO Number | Optional. The LTL freight PRO number, filled in by the freight poll when the carrier assigns it. |
Field | ConfirmationNumber | ShipStation Confirmation Number | Optional. The pickup confirmation number of a booked LTL freight shipment. |
Dynamic Formula | Dynamic Formula | ShipStation Carrier SCAC | Optional. The LTL freight carrier's SCAC code, written at quote or booking. The formula keeps the existing value and never takes one from ShipStation. |
Dynamic Formula | Dynamic Formula | ShipStation Freight Offer Id | Optional. The quoted or booked LTL freight offer id, written at quote or booking and kept by the formula. |
Dynamic Formula | Dynamic Formula | ShipStation Freight Quote Expires | Optional. When the LTL freight quote expires, in ISO 8601 format. Written at quote time and kept by the formula; the order collection reads it to decide whether an unchanged order needs a new quote. |
Dynamic Formula | Dynamic Formula | ShipStation Freight Quote Inputs | Optional. A fingerprint of what was quoted, so an unchanged order isn't quoted again while its quote is valid. Kept by the formula. Don't edit it by hand. |
Dynamic Formula | Dynamic Formula | ShipStation Transit Days | Optional. The quoted LTL freight transit days, written at quote or booking and kept by the formula. |
The LTL freight fields (Freight Shipment Id through Transit Days) are empty for parcel labels.
Error Handling
Errors from this collection appear in iPaaS.com Dashboard, Integration Monitoring or Error Logs. For the full list of error messages and how to resolve them, see the ShipStation API v2 Error Messages article.
The most common tracking failure is a shipping method that doesn't match an existing iPaaS.com Shipping Method. Run shipping_method/initialize on the Add/Update ShipStation Shipping Method TO iPaaS.com collection, then retry the transfer from Integration Monitoring.
Testing & Validation
Test Scenarios
Buy a label in ShipStation for an order this integration sent, and wait for the carrier to scan the package. Verify the next label poll, or a Manual Sync with the label id, creates a tracking record on that order with the tracking number, the Shipping Method name (for example, FedEx Ground®), the service code as description, the cost and the ShipStation Shipment Id, Order Number and Label Id.
With track_event_v2 turned on, verify a delivery status change updates ShipStation Tracking Status and ShipStation Estimated Delivery, and later ShipStation Actual Delivery.
Void the label in ShipStation. Verify the next label poll updates the same record with ShipStation Voided set to true and ShipStation Status set to voided, and that its order and cost are kept.
Buy a label for an order that reached ShipStation another way. Verify the poll skips it.
On an order split into one ShipStation shipment per destination, buy a label for each shipment. Verify each tracking record lands on the same iPaaS.com order.
If LTL freight is used, quote and then book freight for an order. Verify the booking record carries the cost, BOL and confirmation numbers and SCAC, and that the freight poll later fills in the PRO number and status without changing the cost or the order.
Validation Checklist
shipping_method/initialize has been run and every carrier service you ship with exists as an iPaaS.com Shipping Method, plus LTL Freight (ShipStation) if you use LTL freight.
label/poll, track_event_v2 and, for LTL freight, freight_shipment/poll are turned on, and each poll scope has a Webhook Poll Request event.
Days of Label History covers the labels you want on the first poll.
Downstream collections that read tracking records handle ShipStation Voided set to true.
Additional Notes
Known Limitations
New labels. At the time this documentation was written, a newly bought label fails its tracking transfer until the carrier recognizes the tracking number, which usually means until the carrier has scanned the package. No tracking record is created by that attempt, and the failure is shown in Dashboard, Integration Monitoring or Error Logs. Wait and retry the transfer from Integration Monitoring; with track_event_v2 turned on, the first carrier scan also triggers a new transfer.
Delivery statuses need the webhook. Without track_event_v2, the tracking status and delivery dates stay as they were when the label was first brought in.
One subscription per ShipStation account. Each subscription that turns on track_event_v2 receives tracking events for every label on the ShipStation account.
New or excluded carriers. A carrier connected after the last shipping_method/initialize, or a Shipping Method excluded by the Shipping Method collection's filter, makes tracking for that carrier's labels fail until the Shipping Method exists.
Related Documents
Related Mapping Documentation