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 & Validation
Additional Notes
Related Documents
Summary
The ShipStation API v2 integration sends iPaaS.com orders (Transactions) to ShipStation so the warehouse can ship them. ShipStation API v2 has no separate orders resource: each order becomes a pending, unlabeled ShipStation shipment, which ShipStation shows as an order. With Enable Multi Address Shipment on, the order becomes one ShipStation order per destination address its lines name, numbered "(1 of N)"; with it off, it becomes a single ShipStation order.
Orders are sent automatically when they are created or updated in iPaaS.com, or on demand with Manual Sync. Re-sending an order updates the same ShipStation orders without creating duplicates. An iPaaS.com status of Cancelled cancels them, and the ShipStation Freight Mode custom field adds an LTL freight quote, or a quote and a booking. Labels are bought in ShipStation.
The parent collection transfers with two child collections: Add/Update ShipStation Order Address FROM iPaaS.com (each destination's ship-to address, package and optional warehouse) and Add/Update ShipStation Order Line FROM iPaaS.com (each item, with optional LTL freight details).
ID Format
Manual Sync ID Format
Enter the iPaaS.com Transaction ID (for example, 1680).
External ID Format
iPaaS.com saves the ShipStation shipment id of each ShipStation order created for the order as the external-id link on the iPaaS.com Transaction. An order that ships to one address records one shipment id (for example, se-324999718). An order split across destinations records every destination's shipment id joined with "|", in address order (for example, se-324999718|se-324999719). Later transfers use these links to update the same ShipStation orders.
The child collections save their own external-id links during the same transfer:
Each destination address records the shipment id of its own ShipStation order (for example, se-324999718). An address that receives no ShipStation order, such as a billing-only address, has no ShipStation order to link.
Each line records the shipment it went out on, then its iPaaS.com transaction and line ids (for example, se-324999718|1680|5021). Two lines with the same SKU on one ShipStation order therefore get distinct links.
Inside ShipStation, each ShipStation order carries the iPaaS.com Transaction Address it came from, which combines the transaction and the address (for example, 1680|2). When iPaaS.com has lost the link to a ShipStation order, the integration finds it again by this value before creating anything, so a lost link does not produce a duplicate. The same value lets the Shipment Tracking TO iPaaS.com collection attach labels to the originating order.
The Transaction Number is sent as the order number shown in ShipStation. It is for display only and is not used to match records.
Deleted Record Support
Opt-in. The shipped Order FROM iPaaS.com collection is Add/Update only, so by default deleting an order in iPaaS.com does nothing in ShipStation; iPaaS.com reports that there are no delete mappings and nothing to do. Deletes are left off by default so that no ShipStation order is cancelled unless subscribers choose it.
To have a deleted iPaaS.com order cancel its ShipStation orders, subscribers or their MiSP add a second Order FROM iPaaS.com mapping collection with the sync type Delete. A copy of the shipped Order collection works, and no Address or Line child collection is needed. Allow a few minutes after saving before relying on it. A delete cancels every ShipStation order recorded on the iPaaS.com order, following the same rules for labeled and already cancelled orders as the cancel path below. Unlike the cancel path, a delete does not look up ShipStation orders by destination, so a ShipStation order whose id was not recorded on the iPaaS.com order is not cancelled; use the Cancelled status for that case.
Without a Delete collection, give the iPaaS.com order the status Cancelled to stop its ShipStation orders. The cancel path works as follows:
The CancelShipments mapping cancels every ShipStation order recorded on the iPaaS.com order, plus any ShipStation order the integration finds for the order's destinations.
A destination removed from the iPaaS.com order has its ShipStation order cancelled on the next transfer.
ShipStation orders are cancelled, never deleted. One that is already cancelled, or no longer exists in ShipStation, counts as done.
Labels are never voided. A ShipStation order that already has a label is not cancelled, and the transfer fails with SSV2-EXTN-1004, naming that order. Void the label in ShipStation, then cancel the order there.
The child Address and Line collections perform no standalone delete.
Custom Field Support
The integration writes no custom fields to ShipStation. Its mappings read iPaaS.com custom fields on the order, its addresses and its lines with GetCustomFieldValue, so each order carries its own warehouse, store, currency, weights, destinations and freight details. The subscription that sends orders to iPaaS.com (the order source) should populate them. Currency already exists on most iPaaS.com companies; create any of the others as custom fields on the module shown if you use them.
Custom field | Module | Read by | Accepted values | When empty |
Currency | Transaction | Currency | A three-letter ISO currency code, such as USD or CAD | usd |
ShipStation Store | Transaction | StoreId | The id of a ShipStation store, as shown in ShipStation's store settings | ShipStation's default store |
ShipStation Ship From Location | Transaction | WarehouseId (order) | The name of a ShipStation warehouse, exactly as ShipStation shows it; letter case and surrounding spaces ignored | Your default ShipStation warehouse, or your only one |
ShipStation Freight Mode | Transaction | FreightMode | Blank, Quote or Book | Parcel shipping, no freight |
ShipStation Freight Accessorials | Transaction | FreightAccessorials | A comma-separated list of ShipStation accessorial names, such as liftgate_delivery | None |
ShipStation Freight Pickup Date | Transaction | FreightPickupDate | yyyy-MM-dd | The next weekday |
ShipStation Ship From Location | Transaction Address | WarehouseId (address) | The name of a ShipStation warehouse | The order's warehouse |
Package Weight | Transaction Address | Package_Weight | A number with a period as the decimal separator, such as 12.5 | A weight of 0 |
Package Weight Unit | Transaction Address | Package_WeightUnit | pound, ounce, gram or kilogram; plurals and lb, lbs, oz, g, kg, kgs accepted | ounce |
Weight Unit | Transaction Line | WeightUnit | pound, ounce, gram or kilogram; plurals and lb, lbs, oz, g, kg, kgs accepted | pound |
ShipToAddressExternalId | Transaction Line | ShipToTransactionAddressId | The order source's own id for the line's destination address | The primary shipping address |
Freight Class | Transaction Line | FreightClass | 50, 55, 60, 65, 70, 77.5, 85, 92.5, 100, 110, 125, 150, 175, 200, 250, 300, 400 or 500 | Required for freight |
NMFC Code | Transaction Line | NmfcCode | The NMFC item code | Not sent |
Handling Unit Key | Transaction Line | HandlingUnitKey | Any label, such as pallet-1 | The line gets its own handling unit |
Handling Unit Type | Transaction Line | HandlingUnitType | pallet, skid, crate, box, drum, tote and similar | pallet |
Handling Unit Length | Transaction Line | HandlingUnitLength | A number of inches | Required for freight |
Handling Unit Width | Transaction Line | HandlingUnitWidth | A number of inches | Required for freight |
Handling Unit Height | Transaction Line | HandlingUnitHeight | A number of inches | Required for freight |
Mapping Collection Status
Status: Enabled.
Trigger Events: the iPaaS.com transaction/created and transaction/updated events, once subscribers or their MiSP turn those scopes on for the subscription. Manual Sync is also available by Transaction ID. The child collections have no trigger of their own; they transfer with the parent order.
Duplicate or Conflicting Mappings
There is one order collection, one address collection and one line collection in this direction, and no collection in this integration sends orders the other way.
Other routes into ShipStation. Do not also send the same orders to ShipStation through another ShipStation integration, or import them into ShipStation directly from a sales channel. Each route creates its own ShipStation order.
One subscription per ShipStation account. The integration matches ShipStation orders by the iPaaS.com order and address they came from, so connect each ShipStation account to only one iPaaS.com subscription.
Collision Handling
Not supported. The integration offers no collision handling methods to choose from. Before creating a ShipStation order for a destination, it looks for one it created before: first by the external-id link iPaaS.com saved, then by the iPaaS.com Transaction Address recorded on the ShipStation order. When it finds one it updates it; otherwise it creates one.
Warning — Overwrite behavior on update: each update rebuilds the ShipStation order from these mappings and the child collections, 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 in the Order Address collection.
A value edited in ShipStation on a field these mappings send is replaced by the next transfer.
Splitting an order in ShipStation, for a partial shipment or a backorder, is undone by the next update: the original order gets its full quantity back while the split order keeps its units, so items can ship twice. Avoid splitting integration orders in ShipStation.
ShipStation orders that are labeled or cancelled are left as they are.
Supported Child Collections
Add/Update ShipStation Order Address FROM iPaaS.com (Child of Order): maps every address on the order. Each destination address becomes the ship-to of its own ShipStation order, with its package and, optionally, its own warehouse.
Add/Update ShipStation Order Line FROM iPaaS.com (Child of Order): maps each line onto the ShipStation order for its destination as an item. For LTL freight, the same lines also become the commodities and handling units of the freight quote.
The child collections are not triggered independently; they transfer only as part of the parent order.
System Caveats
ShipStation Caveats
The store and the starting status are fixed at creation. ShipStation does not allow them to change, so later updates leave them as they were.
The store is mapped by id. ShipStation API v2 has no list of stores to look a name up in, so the ShipStation Store custom field holds the store id.
A warehouse is needed for every order. A new ShipStation order with no warehouse and no ship-from address uses your default ShipStation warehouse, or your only one. If you have several warehouses and none is the default, ShipStation refuses that destination's order.
Addresses are standardized. ShipStation may store ship-to addresses in uppercase, correct a postal code to match the street or extend it to ZIP+4, add a unit prefix to a street number, and, at the time this documentation was written, replace accented letters in company and street lines (for example, "Café" is stored as "CAFI"). Names keep their accents. Downstream comparisons should not expect an exact match with iPaaS.com.
Package weight may be recalculated. When the items carry weights, ShipStation may replace the package weight with the items' total, in ounces. It does not always do so; check the weight before buying a label.
External ids are not unique in ShipStation. ShipStation accepts several orders for the same iPaaS.com address, so the integration always looks for an existing ShipStation order for each destination before creating one.
Amounts are not divided across destinations. Every ShipStation order of a split order carries the order's full amount paid, shipping paid and tax paid.
Order numbers are limited to 50 characters. A longer Transaction Number is shortened so the "(1 of N)" suffix of a split order stays whole.
Rate limits. The integration follows the request limits ShipStation reports. When a limit is reached, the transfer is held and retried after the wait ShipStation gives (SSV2-RATE-1001). See the ShipStation API v2 API Endpoints article.
iPaaS.com Caveats
Failed transfers are retried. iPaaS.com requeues a failed order transfer. ShipStation orders already created are saved first, so the retry updates them and creates only what is missing.
Setting changes take minutes to apply. A change to a setting such as Enable Multi Address Shipment can take several minutes to reach transfers. Orders sent in the meantime use the old setting.
Removed addresses may stay on the order. An update from the source system may leave an old address on the iPaaS.com order. Its ShipStation order then stays live; cancel the extra ShipStation order by hand.
No dependency transfers. The integration transfers no other record first. The addresses and lines on the order at transfer time are the ones sent.
Setup Requirements
Credentials: the subscription's API Key setting holds a ShipStation API v2 key.
Warehouse: set the ShipStation Ship From Location custom field on the order or on each destination address, or set a default warehouse in ShipStation if you have more than one.
Multi-address orders: turn on Enable Multi Address Shipment and have the order source populate ShipToAddressExternalId on each line.
LTL freight: connect a freight provider in ShipStation and set the Freight Provider Account setting. Review Freight Offer Selection and Freight Pickup Window. Freight Mode Book dispatches a carrier and is billed.
Automatic transfers: subscribers or their MiSP turn on the transaction/created and transaction/updated scopes under the subscription's Outbound Data Flows.
Filter and cancel status: review the collection filter and the CancelShipments formula against your source system's order statuses before enabling the collection.
The connection and subscription steps are in the ShipStation API v2 Installation Instructions and ShipStation API v2 Connections and Settings articles and are not repeated here.
Integration Flow
An order is created or updated in iPaaS.com and passes the collection filter, or a subscriber runs a Manual Sync with the Transaction ID.
The order is mapped through this collection, every address through the Order Address collection, and every line through the Order Line collection.
Cancel check. When CancelShipments is true, the integration cancels every ShipStation order of the order (those recorded on the iPaaS.com order and any it finds for the order's destinations) and stops. A labeled ShipStation order is reported, not cancelled.
Validation. An order with no Transaction Number fails with SSV2-VALD-1002. An order with no addresses, no lines, or no line with a usable destination fails with SSV2-VALD-1003.
Destinations.
With Enable Multi Address Shipment off: one ShipStation order for the primary shipping address (else the first address that is not billing-only, else the first address), carrying every line.
With it on: lines are grouped by their ship-to address. Each group becomes one ShipStation order numbered "(1 of N)", "(2 of N)", in address order. A line with no ship-to address joins the primary shipping address. A line naming an address that is not on the order is reported for that line and never sent to a different address.
Each destination, one at a time. The integration finds the destination's existing ShipStation order and updates it, or creates it with a matching sales order and the status pending. A ShipStation order that is labeled or cancelled is left as is. A failure on one destination does not stop the others.
Removed destinations. ShipStation orders recorded on the iPaaS.com order whose address is no longer a destination are cancelled.
LTL freight. When FreightMode is Quote or Book and every destination was sent successfully, the integration quotes (and, for Book, books) LTL freight for each ShipStation order. See Additional Notes.
iPaaS.com saves the external-id links: the order its shipment ids, each address its shipment id, each line its shipment, transaction and line ids.
If any destination failed, the transfer fails with SSV2-EXTN-1004, listing each failed destination and its reason, after saving the links already obtained.
Mappings
Add/Update ShipStation Order FROM iPaaS.com
iPaaS.com data type: Transaction
Description: iPaaS.com orders become pending, unlabeled ShipStation orders: one per destination address when Enable Multi Address Shipment is on, otherwise one per order. Re-sending updates the same ShipStation orders. Cancelled cancels them. ShipStation Freight Mode adds an LTL freight quote or booking.
Mapping Filter Description. The filter decides which iPaaS.com Transactions are sent to ShipStation. It should pass only Transactions of type Order that have a Transaction Number, and skip orders that should not reach the warehouse, such as drafts or orders already complete, shipped, refunded or returned. Cancelled orders must still pass, so that CancelShipments can cancel their ShipStation orders. A status the filter doesn't name is sent, so add any hold or review statuses your source uses (for example On Hold) to the filter. If your source marks orders Complete before they ship, remove Complete from the filter, or those orders are never sent. Subscribers or their MiSP should review the filter against their own order statuses before enabling the collection, along with the status in the CancelShipments formula.
Field Mapping Table
Mapping Type | Source Field (iPaaS.com) | Destination Field (ShipStation) | Description |
Field | TransactionNumber | OrderNumber | Required. The order number shown in ShipStation. A split order gets suffixes such as "(1 of 3)", in address order, and the number is shortened to 50 characters while keeping the suffix whole. For display only. An order without one fails with SSV2-VALD-1002. |
Field | EmailAddress | CustomerEmail | Recommended. The customer's email: the ship-to email on every ShipStation order whose address has no email of its own. A mapped address email wins. |
Dynamic Formula |
| CancelShipments | Recommended. When true, the transfer cancels the order's ShipStation orders instead of sending them, including any whose link iPaaS.com lost. A labeled ShipStation order is not cancelled and is reported in SSV2-EXTN-1004. Change the status text if your source system marks cancellations differently, and make sure the filter lets those orders through. |
Field | Total | AmountPaid | Recommended. The order total, sent as the amount the customer paid, in the order's currency. Every ShipStation order of a split order carries the full amount. |
Field | TransactionNumber | ExternalOrderId | Optional. The Transaction Number again, as ShipStation's external order reference. Map the source system's own order id here instead if your team searches ShipStation by it. Reference only; not used to match records. |
Field | ShippingAmount | ShippingPaid | Optional. The shipping the customer paid, in the order's currency. Not divided across destinations. |
Field | TaxAmount | TaxPaid | Optional. The tax the customer paid, in the order's currency. Not divided across destinations. |
Dynamic Formula | Dynamic Formula | Currency | Optional. Reads the order custom field Currency, trimmed and lower-cased; usd when empty. It applies to every amount on the ShipStation order. The value must be a three-letter ISO code; any other value makes ShipStation refuse that ShipStation order with SSV2-VALD-1001, naming the value. |
Dynamic Formula | Dynamic Formula | StoreId | Optional. Reads the order custom field ShipStation Store, trimmed: the id of the ShipStation store the order is filed under. Blank uses ShipStation's default store. Set when the ShipStation order is created; later updates do not change it. |
Dynamic Formula | Dynamic Formula | WarehouseId | Recommended. Reads the order custom field ShipStation Ship From Location and looks the name up with GetWarehouseIdByNameAsync, ignoring letter case and surrounding spaces. A warehouse set on a destination address overrides it. Blank uses your default ShipStation warehouse, or your only one. A name that matches no warehouse fails that destination with SSV2-VALD-1006, reported in SSV2-EXTN-1004. |
Dynamic Formula | Dynamic Formula | FreightMode | Optional, LTL. Reads the order custom field ShipStation Freight Mode, trimmed, ignoring case: blank (parcel, no freight), Quote, or Book. Booking dispatches a carrier and is billed. Without a freight provider account the transfer fails with SSV2-FRGT-1001. |
Dynamic Formula | Dynamic Formula | FreightAccessorials | Optional, LTL. Reads the order custom field ShipStation Freight Accessorials, trimmed: a comma-separated list of accessorial services requested with the freight quote. An unknown name stops the freight quote with SSV2-VALD-1004, naming it. |
Dynamic Formula | Dynamic Formula | FreightPickupDate | Optional, LTL. Reads the order custom field ShipStation Freight Pickup Date, trimmed, as yyyy-MM-dd (for example, 2026-11-03). Blank books the pickup for the next weekday. Used only when FreightMode is Book. |
Dynamic Formula Documentation
Currency, StoreId, FreightMode, FreightAccessorials, FreightPickupDate: each formula reads its order custom field with GetCustomFieldValue and returns the value with surrounding spaces removed. When the field is missing or blank, Currency returns usd and the others return nothing, so the default described in the table applies. Currency is also lower-cased.
WarehouseId: reads the order custom field ShipStation Ship From Location; when it has a value, the formula returns the id of the ShipStation warehouse with that name, found with GetWarehouseIdByNameAsync. Blank returns nothing, so a weight of 0 is sent.
Accepted FreightAccessorials values, ignoring letter case: liftgate_pickup, liftgate_delivery, inside_pickup, inside_delivery, appointment_delivery, notify_before_delivery, hold_at_terminal, carrier_terminal_pickup, sort_and_segregate, protection_from_cold, protection_from_heat, grocery_consolidation_pickup, grocery_consolidation_delivery. Accessorials are set when the freight is quoted; ShipStation does not accept them at booking.
Add/Update ShipStation Order Address FROM iPaaS.com (Child)
iPaaS.com data type: Transaction Address
Description: A child of the order collection. Every address of the order is mapped; each destination address becomes the ship-to of its own ShipStation order, with its package and optional warehouse. The destination rules in the Integration Flow decide which addresses receive a ShipStation order. It is not transferred independently.
Field Mapping Table
Mapping Type | Source Field (iPaaS.com) | Destination Field (ShipStation) | Description |
Dynamic Formula |
| Name | Required. The recipient name: first and last name joined with a space. ShipStation requires a ship-to name, so every destination address needs a first or last name. |
Field | Company | CompanyName | Optional. The company at the address. ShipStation may change its letter case and replace accented letters; enter company names without accents to keep labels readable. |
Field | Address1 | AddressLine1 | Required. The first street line. ShipStation may store it in uppercase, add a unit prefix to the street number and replace accented letters. |
Field | Address2 | AddressLine2 | Optional. The second street line, such as a suite or unit. Standardized the same way as AddressLine1. |
Field | Address3 | AddressLine3 | Optional. The third street line. Standardized the same way as AddressLine1. |
Field | City | City | Required. The city or locality. ShipStation may store it in uppercase. |
Field | Region | State | Required in the US and Canada. The state or province, as a two-letter code (for example, TX or ON) for US and Canadian addresses. |
Field | PostalCode | PostalCode | Required. The postal or ZIP code. ShipStation may correct it to match the street, or extend it to ZIP+4, even with address validation off. |
Dynamic Formula | Dynamic Formula | Country | Required. The two-letter country code (for example, US or CA), with surrounding spaces removed. A blank country is sent as US, so a foreign address with no country ships as a US address. Populate the country on every non-US address. |
Field | IsPrimaryShipping | IsPrimaryShipping | Required. Marks the primary shipping address. With Enable Multi Address Shipment off, the order ships to this address with every line; with it on, this address receives every line that names no ship-to address of its own. |
Field | IsPrimaryBilling | IsPrimaryBilling | Required. Marks the billing address so it is not mistaken for a destination. A billing-only address gets no ShipStation order, unless it is the order's only address or a line names it as its ship-to address. |
Dynamic Formula | Dynamic Formula | WarehouseId | Optional. Reads the address custom field ShipStation Ship From Location and looks the name up with GetWarehouseIdByNameAsync. Overrides the order's warehouse; blank uses the order's. A name that matches no warehouse fails that destination with SSV2-VALD-1006; the other destinations are still sent. |
Dynamic Formula | Dynamic Formula | Package_Weight | Optional. Reads the address custom field Package Weight as a number (for example, 12.5). Blank sends a weight of 0. A value that is not a number fails the mapping. When the items carry weights, ShipStation may replace the package weight with their total, in ounces. |
Dynamic Formula | Dynamic Formula | Package_WeightUnit | Optional. Reads the address custom field Package Weight Unit: pound, ounce, gram or kilogram; plurals and lb, lbs, oz, g, kg, kgs accepted. Blank uses ounce. Any other value makes ShipStation refuse the shipment with SSV2-VALD-1001. |
Dynamic Formula Documentation
Country: returns the address Country with surrounding spaces removed, or US when it is blank.
WarehouseId: reads the address custom field ShipStation Ship From Location with GetCustomFieldValue; when it has a value, returns the id of the ShipStation warehouse with that name, found with GetWarehouseIdByNameAsync. Blank returns nothing, so the order's warehouse applies.
Package_Weight: reads the address custom field Package Weight and converts it to a number, with a period as the decimal separator. Blank returns nothing, so a weight of 0 is sent.
Package_WeightUnit: reads the address custom field Package Weight Unit and returns it with surrounding spaces removed. Blank returns nothing, so ounce is used.
Package dimensions, phone, email, residential indicator and delivery instructions are available to map on this collection but are not mapped by default. Because each update sends only mapped fields, map the package dimensions if packers enter them in ShipStation.
Add/Update ShipStation Order Line FROM iPaaS.com (Child)
iPaaS.com data type: Transaction Line
Description: A child of the order collection. Each line becomes an item of the ShipStation order for its destination. For LTL freight, the same lines become the commodities and handling units of the freight quote. It is not transferred independently.
Field Mapping Table
Mapping Type | Source Field (iPaaS.com) | Destination Field (ShipStation) | Description |
Dynamic Formula | Dynamic Formula | ShipToTransactionAddressId | Optional; used only with Enable Multi Address Shipment on. The destination address the line ships to. Empty joins the primary shipping address. A value that matches no shipping address on the order is reported for that line; the line is never sent to a different address, and the other destinations are still sent. |
Field | Sku | Sku | Required. The item SKU. Lines are grouped by destination, never by SKU: two lines with the same SKU stay as two items. |
Dynamic Formula | Dynamic Formula | Name | Required. The item name shown on the ShipStation order and packing slip: the line Description, or the Sku when the Description is empty. |
Dynamic Formula |
| Quantity | Required. The quantity as a whole number. At the time this documentation was written, a fractional quantity is rounded up with no warning: 1.5 is sent as 2. Sources that sell by weight or length should send whole quantities. ShipStation rejects decimal quantities. To round fractions down instead, use |
Field | UnitPrice | UnitPrice | Optional. The price of one unit, in the order's currency. |
Field | EstimatedTaxAmount | TaxAmount | Optional. The tax on the line, as an amount. |
Field | Weight | Weight | Optional. The weight of one unit, in the unit given by WeightUnit. When items carry weights, ShipStation may use their total as the package weight. For LTL freight, Weight times Quantity, converted to pounds, is the line's commodity weight. |
Dynamic Formula | Dynamic Formula | WeightUnit | Optional. Reads the line custom field Weight Unit: pound, ounce, gram or kilogram; plurals and lb, lbs, oz, g, kg, kgs accepted in any letter case. Empty sends pound. Any other value makes ShipStation refuse the whole shipment with SSV2-VALD-1001. |
Dynamic Formula |
| ExternalOrderItemId | Recommended. The iPaaS.com line id, shown in ShipStation as the item's external order item id, so a ShipStation item can be traced back to its iPaaS.com line. |
Dynamic Formula | Dynamic Formula | FreightClass | Required for LTL freight. Reads the line custom field Freight Class. A missing or unlisted class stops the freight quote with SSV2-VALD-1004, naming the line. Not used for parcel orders. |
Dynamic Formula | Dynamic Formula | NmfcCode | Optional, LTL freight. Reads the line custom field NMFC Code: the NMFC item code sent with the line's commodity. |
Dynamic Formula | Dynamic Formula | HandlingUnitKey | Optional, LTL freight. Reads the line custom field Handling Unit Key. Lines with the same key (for example, pallet-1) travel on one handling unit; a line without a key gets its own. The type and dimensions of a shared unit come from the first line with that key. |
Dynamic Formula | Dynamic Formula | HandlingUnitType | Optional, LTL freight. Reads the line custom field Handling Unit Type, such as pallet, skid, crate, box, drum or tote. Empty sends pallet. |
Dynamic Formula | Dynamic Formula | HandlingUnitLength | Required for LTL freight. Reads the line custom field Handling Unit Length, in inches. Missing or zero stops the freight quote with SSV2-VALD-1004. A value that is not a number, such as 48in, fails the mapping for that line. |
Dynamic Formula | Dynamic Formula | HandlingUnitWidth | Required for LTL freight. Reads the line custom field Handling Unit Width, in inches. Missing or zero stops the freight quote with SSV2-VALD-1004. |
Dynamic Formula | Dynamic Formula | HandlingUnitHeight | Required for LTL freight. Reads the line custom field Handling Unit Height, in inches. Missing or zero stops the freight quote with SSV2-VALD-1004. |
Dynamic Formula Documentation
ShipToTransactionAddressId: reads the order source's own address id from the line custom field ShipToAddressExternalId, removes surrounding spaces, and looks up the matching iPaaS.com Transaction Address of the order. When the custom field is empty it returns nothing; when the lookup finds no address it returns the value as entered, which is then reported as unmatched.
Name: returns the line Description, or the Sku when the Description is empty.
WeightUnit, FreightClass, NmfcCode, HandlingUnitKey, HandlingUnitType: each reads its line custom field with GetCustomFieldValue and returns it with surrounding spaces removed, or nothing when it is blank.
HandlingUnitLength, HandlingUnitWidth, HandlingUnitHeight: each reads its line custom field and converts it to a number, with a period as the decimal separator, or returns nothing when it is blank.
Error Handling
Errors from these collections appear in iPaaS.com Dashboard / Integration Monitoring / Error Logs. Each message starts with its code, then a sentence in subscriber terms. ShipStation's own message, and the field it names, are included where ShipStation returns them. For the full catalog see the ShipStation API v2 Error Messages article.
SSV2-VALD-1002: the order has no Transaction Number. Map the Transaction Number to OrderNumber and populate it.
SSV2-VALD-1003: the order has no addresses, no lines, or no line with a usable destination. Check the transaction and the Address and Line collections.
SSV2-VALD-1006: a ShipStation Ship From Location name matches no ShipStation warehouse. Use the name exactly as ShipStation shows it, or leave it blank.
SSV2-VALD-1001: ShipStation refused the request, for example an invalid postal code, currency or weight unit, or no warehouse when the account has several and no default. Correct the value ShipStation names and resend.
SSV2-VALD-1004: freight details are incomplete, such as a missing freight class or handling unit dimension, or an unknown accessorial. Every problem is listed; fill them in and resend.
SSV2-EXTN-1004: some of the order's ShipStation orders failed or could not be cancelled. The message lists each destination and why; the others were sent and saved, and the retry creates only what is missing.
SSV2-EXTN-1003: ShipStation accepted an order but returned no id, and the integration could not find it. Check ShipStation for the order before resending.
SSV2-RATE-1001: ShipStation's rate limit was reached. No action needed: the transfer is held and retried.
SSV2-FRGT-1001 to SSV2-FRGT-1005: LTL freight could not be quoted or booked. See Additional Notes.
SSV2-EXTN-1005: iPaaS.com refused the freight tracking record. Fix the reason iPaaS.com gives, then resend.
SSV2-AUTH-1001 to SSV2-AUTH-1004, SSV2-EXTN-1001, SSV2-EXTN-1002, SSV2-NFND-1001: credential, permission, availability and not-found errors common to every flow.
Validation Rules
A Transaction Number is required.
At least one address and one line are required; with Enable Multi Address Shipment on, at least one line must have a usable destination.
ShipStation requires a recipient name, street address, city, postal code and country code; the state is required in the US and Canada.
A new ShipStation order needs a warehouse: from the order or address ShipStation Ship From Location, or your default (or only) ShipStation warehouse.
Currency must be a three-letter ISO code; weight units must be pound, ounce, gram or kilogram or an accepted abbreviation.
Freight lines need a Freight Class from the allowed list, a weight, and handling unit length, width and height in inches.
Testing & Validation
Test Scenarios
With Enable Multi Address Shipment off, send a single-address order with two lines. Verify one pending ShipStation order with both items, the order number, the ship-to email and the warehouse, and that the iPaaS.com order shows the ShipStation shipment id as its external id.
Re-send the same order after changing a line quantity. Verify the same ShipStation order is updated and no second one exists.
Turn on Enable Multi Address Shipment, wait a few minutes, and send an order whose lines name two addresses through ShipToAddressExternalId. Verify two ShipStation orders numbered "(1 of 2)" and "(2 of 2)", each with only its own lines.
Send a multi-address order where one destination has an invalid postal code. Verify the other destination is created, the transfer fails with SSV2-EXTN-1004 naming the bad address, and the retry after fixing it creates only the missing ShipStation order.
Set the order's status to Cancelled. Verify every ShipStation order of the order is cancelled; buy a label on one first and verify that one is reported, not voided.
Leave ShipStation Store and Package Weight empty. Verify ShipStation's default store is used and the package weight is 0 or the items' total.
Set ShipStation Freight Mode to Quote on an order with complete freight lines. Verify a freight quote and a QUOTE tracking record on the iPaaS.com order.
Validation Checklist
The API Key setting holds a current ShipStation API v2 key.
Every order supplies a warehouse through ShipStation Ship From Location, or your ShipStation account has a default warehouse.
ShipStation Store, where used, holds a store id, not a name.
The order source populates Currency for any order not in usd, and the country on every non-US address.
The collection filter and the CancelShipments formula match the statuses your source system uses.
If you use multi-address orders, the order source populates ShipToAddressExternalId on each line.
Package dimensions are mapped if packers enter them in ShipStation.
Freight Mode Book is set only on orders you intend to dispatch a carrier for.
Additional Notes
LTL Freight
Quote: after every destination's ShipStation order exists, the integration requests an LTL freight quote for each one. The quote also saves the freight setup on the ShipStation order, so the shipper can compare and book in ShipStation. The selected offer (by the Freight Offer Selection setting: Cheapest by total charges or Fastest by transit days; expired offers skipped) is recorded on the iPaaS.com order as a tracking record with tracking number QUOTE and the quoted charge as its cost. An unchanged order is not quoted again while its quote is still valid.
Book: quotes, selects the offer, then books it with the pickup date and the Freight Pickup Window setting (default 09:00-17:00). Booking dispatches a carrier and is billed. The quote record is replaced by the booking record, which carries the bill of lading and confirmation numbers and the booked charge. The integration never books the same ShipStation order twice.
Freight errors: SSV2-FRGT-1001 (no freight provider account: set the Freight Provider Account setting), SSV2-FRGT-1002 (no carrier quoted the lane), SSV2-FRGT-1003 (Book refused because the integration cannot make sure it books only once; book in ShipStation instead), SSV2-FRGT-1004 (an earlier booking started but its result never reached iPaaS.com; check ShipStation's freight shipments before anything else), SSV2-FRGT-1005 (with Book, a Freight Offer Selection or Freight Pickup Window value the integration can't read; nothing is booked).
Freight runs only when every destination's ShipStation order was sent successfully. The parcel ShipStation order is still created when freight fails, and the freight error is reported in SSV2-EXTN-1004.
Residential delivery follows the address's residential indicator on the ShipStation order.
Operational Notes
Labels are bought in ShipStation. The integration never buys or voids a label. Labels come back to iPaaS.com through the Shipment Tracking TO iPaaS.com collection.
Reopened orders. At the time this documentation was written, an order reopened after it was cancelled is not sent to ShipStation again: the transfer reports success while ShipStation keeps only the cancelled order. Re-create a reopened order by hand in ShipStation.
ShipStation unavailable. A server error or no response is reported as SSV2-EXTN-1002; resend the order once ShipStation answers again.
Related Documents
Related Mapping Documentation