Contents
Summary
ID Format
Deleted Record Support
Custom Field Support
Mapping Collection Status
Duplicate or Conflicting Mappings
Supported Child Collections
System Caveats
Setup Requirements
Integration Flow
Mappings
Error Handling
Validation Rules
Testing and Validation
Additional Notes
Summary
This documentation covers how the ShipStation integration sends iPaaS.com orders to ShipStation as shipments rather than ShipStation orders: one shipment for the order's shipping address or, when Enable Multi Address Shipment is on, one per destination address its line items name. Each shipment arrives with a matching sales order, a Pending status, and no label, so your team completes it in ShipStation. Re-sending the same order updates the shipments it created before rather than creating duplicates.
ID Format
Manual Sync ID Format: The identifier entered for a Manual Sync is the iPaaS.com Transaction ID (for example, 165977).
External ID Format: iPaaS.com records the ShipStation shipment ids created for the order as the transaction's external id. That is a single shipment id for an order that ships to one address (for example, se-324999718), or every destination's shipment id joined with "|" and ordered by address (for example, se-324999718|se-324999719).
The child collections record their own external ids during the same transfer:
Each destination address records the id of its own shipment (for example, se-324999718). This is how later transfers of the order find and update the same shipments.
Each line item with a SKU records its shipment id followed by "|" and the SKU (for example, se-324999718|ADM-TL2).
Inside ShipStation, each shipment's external shipment id is the iPaaS.com Transaction Address id, which combines the transaction and the address (for example, 165977|265025). The order's Transaction Number is sent as each shipment's number, for display only; it is not used to match records.
Deleted Record Support
Not implemented at the time this documentation was written. The integration creates and updates shipments in ShipStation but does not delete or cancel them. Deleting an order in iPaaS.com does not cancel its shipments. A destination removed from an order on a later update keeps its shipment in ShipStation, so cancel any shipment that should no longer ship directly in ShipStation. The child line item and address collections perform no standalone delete.
Custom Field Support
The order collection itself reads no custom fields. Its two child collections read seven custom fields that the order source populates on each order, so every order carries its own Ship From Location, store, currency, weights, and destinations. Create each custom field on the subscription that supplies the orders (the order source, not the ShipStation subscription), on the module shown, and map the order source's values into it. The ShipStation Installation Instructions walk through creating them.
Custom field | Module | Data type | Accepted values | When empty |
ShipStation Ship From Location | Transaction Address | String | Name of a ShipStation Ship From Location; letter case ignored | That address's shipment is not created and the transfer reports it |
Package Weight | Transaction Address | String | A number, such as 12.5 | 0 is sent |
Package Weight Unit | Transaction Address | String | pound, ounce, gram, or kilogram, singular or plural | ounce |
ShipStation Store | Transaction | String | Name of a ShipStation store; letter case ignored | ShipStation's default store |
Currency | Transaction | String | Three-letter currency code ShipStation supports, such as usd or cad | usd |
Weight Unit | Transaction Line | String | pound, ounce, gram, or kilogram, singular or plural | pound |
ShipToAddressExternalId | Transaction Line | String | The order source's external id for the destination address | The order's primary shipping address, else its first address that is not the billing address |
The field-level notes in the Mappings section below give examples, and describe what happens when a value is not recognized.
Mapping Collection Status
Enabled. No filter is applied to the order collection or to either child collection, so every order presented to the collection, with all of its addresses and line items, is processed.
Trigger Events: Outbound order transfers run automatically once subscribers or their MiSP enable the outbound order flow under the subscription's Outbound Data Flows (the iPaaS.com transaction/created and transaction/updated events). Manual Sync is available for a one-off or test transfer. The child collections have no trigger of their own; they transfer whenever the parent order transfers.
Duplicate or Conflicting Mappings
None. There is one order collection, one shipment address collection, and one line item collection for this direction. Subscriptions created from an earlier release may still carry the previous Add/Update ShipStation Order Address FROM iPaaS.com collection. It should be replaced by Add/Update ShipStation Shipment Address FROM iPaaS.com, because two address collections map every address twice. Collision handling is not supported.
Supported Child Collections
This order collection is the parent of two child collections that are dispatched as part of the same order transfer:
Add/Update ShipStation Shipment Address FROM iPaaS.com: maps every address on the order and supplies each shipment's ship-to address, Ship From Location, store, status, amounts and their currency, and package weight.
Add/Update ShipStation Order Line Item FROM iPaaS.com: maps each line item onto the shipment for its destination, including the item weight and its unit, the unit price, the tax amount, and the line's destination address for multi-address orders.
The child collections are not triggered independently; they transfer only as part of the parent order.
System Caveats
ShipStation Caveats
Package weight is recalculated. Shortly after creating a shipment, ShipStation recalculates its package weight through the sales order it creates. When the line items carry a weight, the package weight becomes their total weight (each item's weight multiplied by its quantity); otherwise the Package Weight sent is kept. ShipStation shows every package weight in ounces.
The store is fixed at creation. ShipStation does not allow a shipment's store to change, so a later update of the order leaves each shipment in the store it was created under.
The ship-to address is standardized. ShipStation stores the ship-to address in its own standardized form, for example an upper-case street and city and a nine-digit ZIP code. It may therefore differ cosmetically from the iPaaS.com address.
Shipment numbers are limited to 50 characters. A longer Transaction Number is shortened so the "(1 of N)" suffix of a split order stays whole.
iPaaS.com Caveats
No dependency transfers. The integration does not transfer any other record first; the addresses and line items present on the order at transfer time are the ones that are sent.
Failed transfers are retried. iPaaS.com requeues a failed order transfer and retries it automatically. Shipments already sent are updated on the retry, not created again.
Custom fields live on the order source. The custom fields listed above are created and populated on the order source subscription, not on the ShipStation subscription.
Setup Requirements
Credentials: The subscription must be configured with valid ShipStation V2 API credentials (V2 API Base URL and V2 API Access Key) for creating and updating shipments, and the V1 API Key and API Secret for the store lookup.
Custom fields: The order source must populate the ShipStation Ship From Location custom field on every address that can receive a shipment, and the other custom fields above where it can supply them.
Multi-address orders: To split orders by destination, turn on Enable Multi Address Shipment and populate ShipToAddressExternalId on the order source's line items.
Automatic transfers: Enable Outbound Data Flows so orders transfer automatically. Manual Sync is available for one-off or test transfers.
For the connection and subscription steps, refer to the ShipStation Installation Instructions and ShipStation Connections and Settings articles rather than duplicating those steps here.
Integration Flow
An order is created or updated in iPaaS.com, or a subscriber runs a Manual Sync using the iPaaS.com Transaction ID.
The integration maps the order through this collection, every address through the shipment address collection, and every line item through the line item collection. The formulas read the order source's custom fields, and each line item's destination is looked up from its ShipToAddressExternalId value.
The integration works out the destinations.
With Enable Multi Address Shipment off: the order's primary shipping address (or, when no address is flagged, its first address that is not the billing address) receives every line item.
With the setting on: each address named by a line item receives only its own line items. A line item that names no address joins the primary shipping address or, when no address is flagged, the first address that is not the billing address.
An order with no line items or no address creates no shipment, and the transfer finishes without reporting an error. The same happens with the setting on when the order's only address is its billing address and no line item names it.
For each destination, the integration checks that the address names a Ship From Location ShipStation recognizes. It then either updates the shipment it created for that address on an earlier transfer, or creates a new shipment and asks ShipStation to create the matching sales order. Shipments of a split order are numbered "[Transaction Number] (1 of N)", "(2 of N)", and so on.
iPaaS.com records the shipment ids: each address its own shipment, each line item its shipment and SKU, and the order all of its shipments.
If any destination could not be sent, the transfer fails with SHST-EXTN-1004, listing every failed address and its reason, while the other destinations stay sent. iPaaS.com requeues the transfer; the retry updates the shipments already sent and creates only the missing ones.
Mappings
Add/Update ShipStation Order FROM iPaaS.com
iPaaS.com data type: Transaction
This is the parent order collection. It maps the two order-level values every shipment of the order shares.
Mapping Type | Source Field (iPaaS.com) | Destination Field (ShipStation) | Description |
Field | TransactionNumber | orderNumber | Recommended. Sent as the shipment number of every shipment created for the order, with a "(1 of N)" suffix when the order is split. It is for display only and is not used to match shipments on later transfers. When empty, the shipments do not carry a number your team can relate to the order, so this mapping should not be left empty. |
Field | EmailAddress | customerEmail | Recommended whenever the order source carries an email. Sent as the ship-to email of every shipment created for the order. ShipStation does not require it, but it is the only contact detail for the recipient the shipped mappings send. |
Add/Update ShipStation Shipment Address FROM iPaaS.com
iPaaS.com data type: Transaction Address
This is a child of the Add/Update ShipStation Order FROM iPaaS.com collection. Every address on the order is mapped through it. The mappings without a Shipment_ prefix build the shipment's ship-to address; the Shipment_ mappings supply the store, Ship From Location, status, amounts, and package. The billing address is mapped like any other address. With Enable Multi Address Shipment off, it receives a shipment only when it is the order's only address; with the setting on, only when a line item names it.
Mapping Type | Source Field (iPaaS.com) | Destination Field (ShipStation) | Description |
Dynamic Formula | formula: | name | Required. The recipient name, built from the first and last name joined with a space. ShipStation requires a name on the ship-to address. |
Field | Id | id | Optional. Carries the iPaaS.com address identifier; shipments are keyed on the address identifier regardless of this mapping. |
Field | Company | company | Optional. The company or organization name, when the source supplies one. |
Field | Address1 | street1 | Required. The first address line. ShipStation requires it on every shipment. |
Field | Address2 | street2 | Optional. The second address line, such as a suite or unit number. |
Field | Address3 | street3 | Optional. The third address line. |
Field | City | city | Required. The city or town. ShipStation requires it on every shipment. |
Field | Region | state | Required. The state or province code, for example TX or ON. |
Field | PostalCode | postalCode | Required. The postal or ZIP code. ShipStation may store it in its standardized form, for example a nine-digit ZIP code. |
Dynamic Formula | formula: | country | Required. The two-letter country code, defaulting to US when the source country is blank. Subscribers or their MiSP with international orders should confirm the source country values. |
Field | IsPrimaryBilling | IsPrimaryBilling | Optional. Marks the billing address, so it is not mistaken for the destination: with Enable Multi Address Shipment off it ships only when it is the order's only address, and with the setting on a line item that names no address never falls back to it. |
Field | IsPrimaryShipping | IsPrimaryShipping | Recommended. With Enable Multi Address Shipment off, the address flagged primary shipping receives the order's single shipment; with the setting on, it receives every line item that names no address. Exactly one complete address per order should carry the flag. |
Dynamic Formula | formula (below) | Shipment_StoreId | Recommended. Files the shipment under the store named in the order's ShipStation Store custom field, for example Manual Orders (letter case ignored). When empty or not found, no store is sent and ShipStation uses the account's default store. The store is set only when the shipment is created. |
Dynamic Formula | formula (below) | Shipment_WarehouseId | Required. The Ship From Location named in the address's ShipStation Ship From Location custom field, for example Main Warehouse (letter case ignored). When empty or not found, that address's shipment is not created and the transfer reports it (SHST-EXTN-1004); the order's other destinations are still sent. |
Static | "no_validation" | Shipment_ValidateAddress | Optional. Allowed values: no_validation, validate_only, validate_and_clean. The shipped value creates the shipment as the address was entered, so your team can correct an unverifiable address in ShipStation. |
Static | "Pending" | Shipment_ShipmentStatus | Required. Creates each shipment as Pending so your team reviews it and purchases the label in ShipStation. Changing it is not recommended: a shipment created in another status can be picked up by ShipStation automation without review. |
Static | "false" | Shipment_IsGift | Optional. Treats every shipment as a standard shipment. Subscribers or their MiSP whose order source carries a gift indicator can map it here instead. |
Dynamic Formula | formula (below) | Shipment_AmountPaid_Currency | Optional. The currency of the amount paid, from the order's Currency custom field (a three-letter code such as usd, cad, or eur; any letter case). When empty, usd is sent. ShipStation rejects an unrecognized code such as dollars, and the order's shipments are not created. |
Dynamic Formula | formula: | Shipment_AmountPaid_Amount | Optional. The order Subtotal, recorded as the amount paid. Each shipment of a split order receives the full order value. Placeholder value — replace during implementation: the Subtotal may not equal what the customer paid; subscribers or their MiSP who track a true amount-paid value should point this formula at that field. |
Dynamic Formula | formula (below) | Shipment_ShippingPaid_Currency | Optional. The currency of the shipping charge, from the same Currency custom field; usd when empty. |
Dynamic Formula | formula: | Shipment_ShippingPaid_Amount | Optional. The order Shipping Amount. Each shipment of a split order receives the full order value. |
Dynamic Formula | formula (below) | Shipment_TaxPaid_Currency | Optional. The currency of the tax, from the same Currency custom field; usd when empty. |
Dynamic Formula | formula: | Shipment_TaxPaid_Amount | Optional. The order Tax Amount. Each shipment of a split order receives the full order value. |
Dynamic Formula | formula (below) | Shipment_Packages_Weight_Value | Required by ShipStation, so an empty value is sent as 0. The number in the address's Package Weight custom field, for example 12.5. A value that is not a number fails the order's transfer. When the line items carry weights, ShipStation replaces the package weight with their total. |
Dynamic Formula | formula (below) | Shipment_Packages_Weight_Unit | Required together with the weight, and always satisfied by the default. The unit from the address's Package Weight Unit custom field: pound, ounce, gram, or kilogram, singular or plural, in any letter case; ounce when empty. ShipStation rejects abbreviations such as lb or oz, and that address's shipment is not created. |
Dynamic Formula | formula: | Shipment_ExternalOrderId | Optional. Records the order's Transaction Number as ShipStation's external order reference on every shipment of the order. It does not affect how shipments are matched or how tracking returns to iPaaS.com. |
The multi-line formulas as shipped:
Shipment_StoreId
// Store: the name in the order custom field "ShipStation Store" (letter case ignored).
// Empty or unmatched sends no store, so ShipStation files the shipment under its default store.
var name = "";
if (Parent != null && Parent.CustomFields != null) { name = GetCustomFieldValue(Parent.CustomFields, "ShipStation Store"); }
if (string.IsNullOrWhiteSpace(name)) { return ""; }
var storeId = await GetStoreIdByNameAsync(name.Trim());
if (string.IsNullOrWhiteSpace(storeId)) { return ""; }
return storeId;Shipment_WarehouseId
// Ship From Location: the name in the address custom field "ShipStation Ship From Location" (letter case ignored).
// Empty or unmatched returns no warehouse, so the shipment is not sent with a guessed origin and the transfer reports the address.
var name = "";
if (CustomFields != null) { name = GetCustomFieldValue(CustomFields, "ShipStation Ship From Location"); }
if (string.IsNullOrWhiteSpace(name)) { return ""; }
var warehouseId = await GetWarehouseIdByNameAsync(name.Trim());
if (string.IsNullOrWhiteSpace(warehouseId)) { return ""; }
return warehouseId;Shipment_AmountPaid_Currency, Shipment_ShippingPaid_Currency, and Shipment_TaxPaid_Currency (the same formula on all three)
// Currency: the three-letter ISO 4217 code in the order custom field "Currency", lower-cased; usd when empty.
var currency = "";
if (Parent != null && Parent.CustomFields != null) { currency = GetCustomFieldValue(Parent.CustomFields, "Currency"); }
if (string.IsNullOrWhiteSpace(currency)) { return "usd"; }
return currency.Trim().ToLowerInvariant();Shipment_Packages_Weight_Value
// Package weight: the number in the address custom field "Package Weight", in the Package Weight Unit; 0 when empty,
// which lets ShipStation calculate the package weight from the line items.
var value = "";
if (CustomFields != null) { value = GetCustomFieldValue(CustomFields, "Package Weight"); }
if (string.IsNullOrWhiteSpace(value)) { return 0; }
return Convert.ToDouble(value.Trim());Shipment_Packages_Weight_Unit
// Package weight unit: the address custom field "Package Weight Unit" (pound, ounce, gram, kilogram), lower-cased; ounce when empty.
var unit = "";
if (CustomFields != null) { unit = GetCustomFieldValue(CustomFields, "Package Weight Unit"); }
if (string.IsNullOrWhiteSpace(unit)) { return "ounce"; }
return unit.Trim().ToLowerInvariant();
Add/Update ShipStation Order Line Item FROM iPaaS.com
iPaaS.com data type: Transaction Line
This is a child of the Add/Update ShipStation Order FROM iPaaS.com collection. Each line item is placed on the shipment for its destination. With Enable Multi Address Shipment off, every line item ships in the order's single shipment; with the setting on, each ships in the shipment for the address it names.
Mapping Type | Source Field (iPaaS.com) | Destination Field (ShipStation) | Description |
Field | Sku | sku | Recommended. The item's SKU on the shipment, passed through as supplied. |
Field | Sku | name | Recommended. The item's display name. By default it is the same SKU; subscribers or their MiSP who keep a separate product name can point this mapping at it. |
Field | Qty | quantity | Recommended. The ordered quantity. An empty quantity is sent as 1. When an order is split, each line item's full quantity ships with its own destination. |
Dynamic Formula | formula (below) | ShipToTransactionAddressId | Required for splitting an order by destination, and used only when Enable Multi Address Shipment is on. It holds the line item's ShipToAddressExternalId custom field value: the order source's own external id for the destination address. Examples are 450789469|SHIP for a Shopify shipping address, or 1234567 for a Counterpoint order's ship-to address, registered under the order document number. The formula resolves the value to the matching address on the order. When empty, the line item ships to the order's primary shipping address. When the value matches no address on the order, the line item is not shipped and the transfer reports it (SHST-EXTN-1004). |
Dynamic Formula | formula: | Shipment_Item_ExternalOrderItemId | Optional. Records the iPaaS.com line item identifier on the shipment item, for example 166215|402389. |
Field | Weight | Shipment_Item_Weight_Value | Optional. The weight of one unit of the item, in the unit set by Shipment_Item_Weight_Unit. ShipStation multiplies it by the quantity and uses the total of the items as the shipment's package weight. |
Dynamic Formula | formula (below) | Shipment_Item_Weight_Unit | Optional. The unit from the line item's Weight Unit custom field: pound, ounce, gram, or kilogram, singular or plural, in any letter case; pound when empty. It takes effect only when the item has a weight. ShipStation rejects abbreviations such as lb or kg. |
Field | UnitPrice | Shipment_Item_UnitPrice | Optional. The per-unit price of the item. It is informational in ShipStation. |
Field | EstimatedTaxAmount | Shipment_Item_TaxAmount | Optional. The line item's Estimated Tax Amount, an absolute currency amount. |
The multi-line formulas as shipped:
ShipToTransactionAddressId
// Destination address: the order source's own id for the address, from the line custom field "ShipToAddressExternalId",
// resolved to the iPaaS.com address. When empty: the order's primary shipping address, else its first non-billing address.
var value = "";
if (CustomFields != null) { value = GetCustomFieldValue(CustomFields, "ShipToAddressExternalId"); }
if (Parent == null) { return "null"; }
if (!string.IsNullOrWhiteSpace(value))
{
var resolved = await GetSpaceportId_StringAsync(value.Trim(), "Transaction Address", Parent.SystemId);
if (!string.IsNullOrWhiteSpace(resolved)) { return resolved; }
return value;
}
if (Parent.Addresses != null)
{
foreach (var address in Parent.Addresses) { if (address.IsPrimaryShipping) { return address.Id.ToString(); } }
foreach (var address in Parent.Addresses) { if (!address.IsPrimaryBilling) { return address.Id.ToString(); } }
}
return "null";Shipment_Item_Weight_Unit
// Line weight unit: the line custom field "Weight Unit" (pound, ounce, gram, kilogram), lower-cased; pound when empty.
var unit = "";
if (CustomFields != null) { unit = GetCustomFieldValue(CustomFields, "Weight Unit"); }
if (string.IsNullOrWhiteSpace(unit)) { return "pound"; }
return unit.Trim().ToLowerInvariant();
Error Handling
For the full list of error messages the integration can return, what each one means, and how to resolve it, refer to the ShipStation Error Messages article. Errors appear in the iPaaS.com Dashboard under Integration Monitoring and in the Error Logs. The ones an order transfer most often produces are:
SHST-EXTN-1004: one or more of the order's shipping addresses could not be sent as a shipment. The message lists each failed address with its reason, for example a missing Ship From Location, a line item destination that matches no address, or a value ShipStation rejected. The other addresses' shipments were sent.
SHST-EXTN-1001: ShipStation rejected a request. It usually appears inside SHST-EXTN-1004, with ShipStation's own message, for example "Requested value 'dollars' was not found" for a currency code or weight unit it does not accept.
SHST-EXTN-1003: reported for an address inside SHST-EXTN-1004 when ShipStation accepted its shipment but returned no shipment id, and the integration could not find the shipment by its external shipment id either (when it can, the id is recorded and no error is reported). Because that id was never recorded, the next attempt, including iPaaS.com's automatic retry, creates a second shipment for the address if the first one exists. Keep the most recently created one, which later updates of the order go to, and cancel the earlier one in ShipStation.
SHST-AUTH-1002: a V2 setting is missing, so the order could not be sent. Enter the V2 API Base URL and V2 API Access Key in the subscription settings.
A value that a formula cannot use, such as a Package Weight that is not a number, fails the transfer with a message naming the mapping, for example "applying mapping to Shipment_Packages_Weight_Value".
Validation Rules
No mapping filter is applied to the order collection or its child collections. A shipment is created for a destination only when these rules hold:
The address names a Ship From Location that exists in the ShipStation account, through its ShipStation Ship From Location custom field.
With Enable Multi Address Shipment on, a line item's ShipToAddressExternalId value, when present, matches an address on the order.
The Currency, Package Weight Unit, and Weight Unit custom fields, when populated, hold values ShipStation accepts, and Package Weight is a number.
The order has at least one line item and at least one address. Otherwise no shipment is created, and the transfer finishes without reporting an error; the same happens with Enable Multi Address Shipment on when the order's only address is its billing address and no line item names it.
Testing and Validation
Test Scenarios
Send an order with one shipping address and confirm one Pending shipment appears in ShipStation. It should be numbered with the Transaction Number and contain every line item, the Ship From Location named on the address, and no label.
Turn on Enable Multi Address Shipment. Send an order whose line items name two different addresses, and confirm two shipments appear, numbered "(1 of 2)" and "(2 of 2)", each with only its own line items.
With Enable Multi Address Shipment on, send an order with a line item that names no address, and confirm it ships with the primary shipping address.
Re-send the same order and confirm ShipStation shows the same shipments updated in place, with no duplicates.
Populate ShipStation Store, Currency, and the weight units on a test order, and confirm the shipment shows the store, currency, and units. Then send one with them empty and confirm the defaults: the default store, usd, ounce, and pound.
Send an order whose address has an empty or unknown Ship From Location. Confirm no shipment is created for that address and the transfer reports SHST-EXTN-1004.
Send an order with an unrecognized currency code or weight unit, and confirm the transfer reports ShipStation's rejection instead of creating the shipment.
Run a Manual Sync using the iPaaS.com Transaction ID and confirm the shipments are created or updated.
Validation Checklist
Each shipment arrives as Pending, with no label, carrier, or service selected.
The shipment number is the Transaction Number, with a "(1 of N)" suffix only when the order is split.
Re-sending an order updates its shipments rather than creating duplicates.
Every address that can receive a shipment carries a ShipStation Ship From Location value that matches a Ship From Location in ShipStation.
The store, currency, and weight units match the order source's custom fields, or the documented defaults when they are empty.
The ship-to address is complete and resolves to a two-letter country code.
The amount-paid source has been confirmed, or repointed to the field that holds the amount the customer paid.
The ShipStation credentials are valid, confirmed by a successful test transfer.
Additional Notes
At the time this documentation was written, the line item and address collections transfer only as part of their parent order and are not independently triggerable. Because orders are now created as shipments, the order key, order date, and order status translation from earlier releases are no longer sent. The shipment status, gift flag, and amounts paid are now mapped per shipment on the shipment address collection, and advanced options and customs contents are not mapped in the shipped template. For the full list of behaviors that fall outside this integration, refer to the ShipStation Integration Known Limitations article.
Related Documents
Related Mapping Documentation