Summary
This documentation covers how the Shippo integration brings Shippo labels TO iPaaS.com as tracking records on the orders they were bought for. A Shippo label (called a transaction in Shippo's API) becomes one tracking record on the iPaaS.com order: the tracking number, the Shipping Method, the postage cost, and the label's Shippo and carrier status. Other integrations in your company can then send the tracking on to your store or ERP.
A label links through its Shippo order, so only labels for orders this integration sent to Shippo land in iPaaS.com, whether the integration bought the label automatically or it was bought separately afterwards. A label delivered again updates the same tracking record. A refunded label keeps its record and shows REFUNDED in Shippo Status.
ID Format
Manual Sync ID Format
The Shippo label (transaction) id, 32 characters, for example 450a134e1ac149d1b42be9ece6150e41.
External ID Format
After a successful transfer, iPaaS.com saves the Shippo label id on a separate external-ID record. Later transfers of the same label use it to update the same tracking record instead of adding another.
Deleted Record Support
Not supported at the time this documentation was written. Tracking records are never deleted: a refunded label keeps its record, with Shippo Status showing REFUNDED. Refund a label in Shippo if needed.
Custom Field Support
The collection writes three iPaaS.com custom fields on the tracking record. Subscribers or their MiSP create them as Transaction Tracking custom fields before the first transfer:
Shippo Status: the label's status in Shippo: SUCCESS, QUEUED, WAITING, REFUNDED, REFUNDPENDING or REFUNDREJECTED. iPaaS.com tracking records have no active flag, so use this field in filters or reports to leave out refunded labels.
Shippo Tracking Status: the carrier's status: UNKNOWN, PRE_TRANSIT, TRANSIT, DELIVERED, RETURNED or FAILURE.
Shippo Tracking URL: the carrier's tracking page.
Custom fields this collection doesn't map keep their value when a label is transferred again.
Mapping Collection Status
Status: Enabled.
Trigger Events: subscribers or their MiSP turn on these scopes under Inbound Data Flows; no automatic transfers occur until they are turned on:
transaction_created: a new label.
transaction_updated: a label's status changes, for example a refund.
track_updated: the carrier's tracking status changes.
label/poll: the scheduled label check for labels the webhooks missed, run by a Webhook Poll Request event as the installation instructions describe.
Turning a webhook scope on registers the Shippo webhook for it; turning it off removes only that webhook. When the integration buys a label itself, it also queues the tracking straight away. Manual Sync transfers one label by its id.
Duplicate or Conflicting Mappings
None. This is the only collection that writes Shippo labels to iPaaS.com.
Collision handling is not offered: a label is matched only by its external-ID link, so each label makes one tracking record.
Unmapped field overwrite risk. On update, iPaaS.com replaces the tracking record's standard fields with what this collection sends. Removing the Cost or ShippingMethodDescription mapping clears that field the next time the label is transferred. To keep a value set in iPaaS.com, map the field to its current value with a Dynamic Formula, for example return DestinationValue.Cost;, and validate it in a staging subscription before relying on it in production. Custom fields this collection doesn't map keep their value.
Supported Child Collections
None. This is a standalone collection of the Transaction Tracking Number type; it isn't part of the order collection's hierarchy.
System Caveats
Shippo Caveats
Only labels for orders this integration sent. Labels for orders created in Shippo by other channels have no iPaaS.com order to land on and are skipped with no error.
Failed purchases. A label Shippo couldn't create (status ERROR) is not transferred.
Hourly check window. The label/poll check reads labels created within Days of Label History that changed since the previous check.
Tracking status changes. Carrier tracking status changes arrive through the track_updated webhook. The scheduled label check is not relied on to catch them.
Rate limiting. When Shippo limits the rate of calls, the transfer is held and resumes automatically; no action is needed.
iPaaS.com Caveats
A tracking record needs a Shipping Method. iPaaS.com requires the tracking's shipping method to name a configured Shipping Method (see Integration Flow).
Standard fields are replaced on update (see Unmapped field overwrite risk).
Setup Requirements
For full setup steps see the Installation Instructions and Connections and Settings articles. For this collection specifically:
Create the three custom fields Shippo Status, Shippo Tracking Status and Shippo Tracking URL as Transaction Tracking custom fields.
Run the Shippo Carrier Service initialization so the Shipping Methods exist.
Turn on transaction_created, transaction_updated and track_updated under Inbound Data Flows.
Schedule the label/poll event (hourly is suggested), as the installation instructions describe.
Integration Flow
A webhook, the scheduled label check, the integration's own purchase, or a Manual Sync starts the transfer for a label.
The integration reads the label and its rate from Shippo and finds the iPaaS.com order linked to the label's Shippo order. A label with no linked order is skipped by the filter, with no error; a label with status ERROR is not transferred.
If the label's carrier service has no iPaaS.com Shipping Method yet, the integration first brings it in through the Shippo Carrier Service collection. If it can't (the carrier service collection's filter leaves it out, or the carrier account is no longer active), the transfer reports SHPO-NFND-1003, naming the service and what to do.
The tracking record is added to the order, or updated when the label was transferred before.
A Shipping Method that was deleted in iPaaS.com is not brought back automatically: recreate it, or run the carrier service initialization, then resend the label.
Mappings
Add/Update Shippo Label TO iPaaS.com
iPaaS.com data type: Transaction Tracking Number
Description: Writes each Shippo label for an order this integration sent as a tracking record on that order.
Mapping Filter
// Labels for orders this integration sent (a tracking record needs its order); labels made in Shippo for other orders are skipped. return TransactionId != null;
Filter Description. Only labels whose TransactionId is set are processed: labels for Shippo orders this integration sent, which have an iPaaS.com order to land on. Labels for other Shippo orders are skipped with no error.
Mapping Type | Source Field (Shippo) | Destination Field (iPaaS.com) | Description |
Field | TransactionId | ParentId | Required. The iPaaS.com order the label belongs to. |
Dynamic Formula |
| ShippingMethod | Required. The name of the iPaaS.com Shipping Method linked to the label's carrier service. |
Field | TrackingNumber | TrackingNumber | Recommended. The carrier's tracking number. |
Dynamic Formula |
| ShippingMethodDescription | Optional. The carrier and service as text, for example USPS Priority Mail. |
Field | Cost | Cost | Optional. The label's postage cost. |
Field | Status | Shippo Status (Custom Field) | Recommended. The label's status in Shippo; REFUNDED after a refund. |
Field | TrackingStatus | Shippo Tracking Status (Custom Field) | Recommended. The carrier's tracking status. |
Field | TrackingUrl | Shippo Tracking URL (Custom Field) | Recommended. The carrier's tracking page. |
Error Handling
Errors from this collection appear in iPaaS.com Dashboard / Integration Monitoring / Error Logs.
SHPO-NFND-1003: the label's carrier service has no Shipping Method in iPaaS.com and couldn't be brought in; the message names the service and what to do.
SHPO-EXTN-1002: Shippo limited the rate of calls; the transfer is held and resumes automatically.
SHPO-BIZL-1011 and SHPO-BIZL-1012 are logged as information, not errors: a label for an order this integration didn't send, and a label Shippo couldn't create.
For the full catalog of error messages see the Shippo Error Messages article.
Testing & Validation
Test Scenarios
With a test API token and Automatic Label Purchase on, send an order. Verify one tracking record on the order with the tracking number, Shipping Method, cost and the three Shippo custom fields.
Deliver the same label again (Manual Sync with the label id). Verify there is still one tracking record.
Refund the label in Shippo. Verify the record shows REFUNDED in Shippo Status after the next transfer.
Buy a label in Shippo for an order created there by another channel. Verify no tracking record is created and no error is logged.
Validation Checklist
The three custom fields exist as Transaction Tracking custom fields.
The Shipping Methods for the carrier services you use exist in iPaaS.com.
The three webhook scopes are on, and the label/poll event is scheduled.
Additional Notes
Labels bought separately. A label bought separately for an order this integration sent arrives through the webhooks or the scheduled label check and lands on that order. Validate labels bought by hand in the Shippo web app in a staging subscription before relying on them in production.
