Summary
This integration transfers iPaaS.com transactions to ShipHawk as orders. When a transaction record with line items and addresses is created or updated in iPaaS.com, the corresponding line items and addresses (billing, shipping, and origin) are synchronized with ShipHawk.
ID Format
When manually transferring a transaction from iPaaS.com, enter the valid iPaaS.com transaction Id (internal ID) into the iPaaS.com input field on the manual sync page. For example, use: 145146.
External ID Format: Transaction (Parent)
The iPaaS.com Transaction External ID consists of the ShipHawk Order ID, for example, ord_y0qrZKSrN1dt.
Deleted Record Support
Outbound delete support is not implemented for the Order entity. The Delete method in the Order model throws a NotImplementedException. Delete mappings are not included in the default mapping templates. If an order is deleted in iPaaS.com, the deletion will not be propagated to ShipHawk.
Mapping Collection Status
Mapping Status: Enabled
Trigger Events: Create, Update
Duplicate or Conflicting Mappings
This mapping applies only to Transaction from iPaaS.com. Ensure no other mappings target the same ShipHawk Order entity to prevent data from being overwritten.
Supported Child Collections
This parent mapping collection supports the following child collections:
ShipHawk Add/Update Order Address FROM iPaaS.com
ShipHawk Add/Update Order LineItem FROM iPaaS.com
System Caveats
iPaaS.com Caveats
Prerequisite Handling For Line Items
External IDs are required for accurate linking of order line items.
SKU matching is used when external IDs are missing.
Missing or inconsistent SKUs can cause duplicate order line items.
Prerequisite handling only works if the ShipHawk order already exists.
Collision Handling For Order
Duplicate orders are detected when ShipHawk reports “order number has already been taken.”
Collision detection relies on matching the ShipHawk error message containing the text “order number has already been taken.”
When a collision is detected, the existing ShipHawk order ID is extracted and reused. Line items and addresses are then matched by external ID or SKU, but are not re-validated against the existing order.
If collision handling is not enabled in the mapping collection, duplicate orders may be created in ShipHawk.
ShipHawk Caveats
By default, shipments will be split into one package per unit pending ShipHawk configuration providing packing rules or package definitions.
Authentication and Security
ShipHawk uses API Key authentication to access its API. This key authorizes all ShipHawk API requests during transfer operations.
Integration Flow
The integration processes iPaaS.com Transactions as follows:
The integration is triggered when a transaction record is created or updated in iPaaS.com.
Sales order details are mapped and validated against ShipHawk requirements.
The Order, along with its addresses and line items, is created or updated in ShipHawk.
Upon successful transfer, the ShipHawk Order ID is saved as the External ID in iPaaS.com.
Mappings
Parent Collection: ShipHawk Add/Update Order FROM iPaaS.com
Mapping Type | Source Field (iPaaS.com) | Destination Field (ShipHawk) | Description |
Field | TransactionNumber | OrderNumber | (Required) Maps the transaction number from iPaaS.com to the ShipHawk order number. |
Field | SystemId | SourceSystem | (Optional) Retrieves the source system identifier from iPaaS.com. |
Field | Id | SourceSystemId | (Required) Maps the unique source system ID from iPaaS.com to ShipHawk. |
Field | Total | TotalPrice | (Optional) Maps the total amount from iPaaS.com to the ShipHawk order total. |
Field | ShippingAmount | ShippingPrice | (Optional) Maps the shipping amount from iPaaS.com to ShipHawk. |
Field | TaxAmount | TaxPrice | (Optional)) Maps the tax amount from iPaaS.com to ShipHawk. |
Field | Subtotal | ItemsPrice | (Optional) Maps the subtotal of items from iPaaS.com to ShipHawk. |
Lookup Translation | Transaction(Order) Status To iPaaS.com | Status | (Optional) Translates the order status from iPaaS.com to the corresponding ShipHawk status using the lookup table. |
Lookup Translation Table
Destination (ShipHawk) | Source (iPaaS.com) |
new | Pending |
Shipped | shipped |
Completed | Delivered |
cancelled | Cancelled |
on_hold | On Hold |
partially_shipped | Partially Shipped |
Child Collection: ShipHawk Add/Update Order Address FROM iPaaS.com
Description
This collection maps order address fields from iPaaS.com to ShipHawk, handling both shipping and billing addresses. A dynamic formula converts country names to ISO country codes, and the email address is pulled from the parent order record.
All fields are Optional.
Mapping Type | Source Field (iPaaS.com) | Destination (ShipHawk) | Description |
Field | FirstName + " " + LastName | Name | Maps the recipient's first name and last name to the ShipHawk name field. |
Field | Company | Company | Maps the company name. |
Field | Address1 | Street1 | Maps the primary street address. |
Field | Phone | PhoneNumber | Maps the phone number to the |
Field | Address2 | Street2 | Maps the secondary street address (suite, unit, etc.). |
Field | City | City | Maps the city name. |
Dynamic Formula | Parent.EmailAddress | Pulls the email address from the parent order record. | |
Field | Region | State | Maps the state or region. |
Field | PostalCode | Zip | Maps the postal/ZIP code. |
Dynamic Formula | return CountryCode(Country); | Country | Converts the country name to its ISO country code (e.g., United States to US). |
Field | IsPrimaryBilling | IsPrimaryBilling | Indicates whether this is the primary billing address. |
Field | IsPrimaryShipping | IsPrimaryShipping | Indicates whether this is the primary |
Field | ShippingMethod | RequestedShippingDetails | Maps the requested shipping method. |
Child Collection: ShipHawk Add/Update Order LineItem FROM iPaaS.com
Description
This collection maps order line item fields from iPaaS.com to ShipHawk, including product identification, quantity, pricing, dimensions, and weight. The item type is statically set to parcel for all line items.
Mapping Type | Source Field (iPaaS.com) | Destination Field (ShipHawk) | Description |
Dynamic Formula | Id | SourceSystemId | (Required) Retrieves the unique ID of the item from iPaaS.com and maps it to ShipHawk’s SourceSystemId. |
Field | Description | Name | (Required) Maps the item description from iPaaS.com to ShipHawk item name. |
Field | Sku | Sku | (Required) Maps the SKU from iPaaS.com to ShipHawk. |
Field | Qty | Quantity | (Optional) Maps the item quantity from iPaaS.com to ShipHawk. |
Field | UnitPrice | Value | (Optional) Maps the unit price of the item from iPaaS.com to ShipHawk. |
Field | currency | Currency | (Optional) Maps the currency of the item from iPaaS.com to ShipHawk. Default: USD |
Field | length | Length | (Optional) Maps the item length from iPaaS.com to ShipHawk.Value provided must be able to convert to a decimal |
Field | width | Width | (Optional) Maps the item width from iPaaS.com to ShipHawk.Value provided must be able to convert to a decimal |
Field | height | Height | (Optional) Maps the item height from iPaaS.com to ShipHawk.Value provided must be able to convert to a decimal |
Field | Weight | Weight | (Optional) Maps the item weight from iPaaS.com to ShipHawk. |
Static | parcel | ItemType | (Optional) Sets the item type as parcel in ShipHawk. Options:parcelhandling_unitunpacked |
Error Handling
Missing Required Field
Required field is missing.
Description: ShipHawk rejects order creation/update due to missing required fields.
Resolution: Ensure all required fields are populated (TransactionNumber, Id, Description, Sku).
Duplicate Order
Order number already exists.
Description: Collision handling detects duplicate orders.
Resolution: Use extracted ShipHawk order ID to link existing order; validate line items to avoid duplicates.
External ID Missing
External ID not found.
Description: Order or line item cannot be mapped to ShipHawk.
Resolution: Ensure valid External IDs exist in iPaaS.com.
Invalid SKU
SKU mismatch or not found.
Description: Line item cannot be linked.
Resolution: Verify SKUs are consistent across iPaaS.com and ShipHawk.
Validation and Testing
Validation Checklist
Parent Requirements
Transaction exists in iPaaS.com.
Transaction External ID is valid.
All line items have valid SKUs or external IDs.Child Requirements
Addresses exist and are mapped correctly.
Line item quantities, units, and values are valid.
Test Scenarios
Scenario 1: Create/Update Transaction
Create/update transaction in iPaaS.com.
Sync to ShipHawk.
Verify order, line items, and addresses are created/updated correctly.Scenario 2: Duplicate Order Detection
Attempt to create transaction with existing order number.
Expected: Existing ShipHawk order is reused; no duplicates created.Scenario 3: Missing External ID
Trigger transaction with line items missing external IDs.
Expected: Integration attempts to link using SKU if available; otherwise an error is logged.
Additional Notes
The SourceSystemId mapping on the line item collection uses a Dynamic Formula type with just Id as the formula body. This is implemented as a Dynamic Formula rather than a Field mapping to ensure the ID is retrieved at execution time. This is intentional: using a Dynamic Formula ensures the ID is evaluated at runtime, which is required for correct line item matching during collision handling (TranslationUtilities matches by SKU + SourceSystemId).
The Currency, length, width, and height fields on the line item collection are iPaaS.com custom fields that must be configured in your iPaaS.com subscription. The Phone field on the address collection is a standard field.
The Email field on the Address collection is pulled from Parent.EmailAddress, meaning it comes from the order header rather than the address record itself.