Summary
Shipment package tracking can be synchronized between Acumatica and iPaaS.com as Transaction Tracking Number records. Tracking is bidirectional: the TO iPaaS.com collections capture the carrier, tracking number, shipping method description, and declared value from an Acumatica shipment package and record them against the matching iPaaS.com transaction, while the FROM iPaaS.com collections write a tracking number from iPaaS.com into an Acumatica shipment package. Each direction has an Add collection that handles the record the first time and an Update collection that refreshes it.
This article covers the four standalone tracking collections, each of which resolves and attaches its own parent transaction:
Add Acumatica Transaction Tracking Number TO iPaaS.com
Update Acumatica Transaction Tracking Number TO iPaaS.com
Add Acumatica Transaction Tracking Number FROM iPaaS.com
Update Acumatica Transaction Tracking Number FROM iPaaS.com
Tracking can also be transferred as a child of a Sales Order rather than standalone. That child flow is documented separately in the Acumatica Sales Orders from iPaaS article; this article covers only the standalone collections.
ID Format
For the TO iPaaS.com direction, when manually transferring a tracking number into iPaaS.com, enter the Acumatica transaction identifier that the tracking number belongs to into the iPaaS.com input field on the Manual Sync page. The integration uses that identifier to resolve the parent transaction and attach (or locate) the tracking record.
For the FROM iPaaS.com direction, the transfer is keyed on the iPaaS.com transaction and transaction line. The integration resolves the Acumatica order number and customer from the iPaaS.com transaction and uses a line-link reference to match the tracking record to the correct order line. Subscribers do not enter an Acumatica shipment number; the integration creates or locates the shipment itself.
Child ID Format
For the FROM direction, the line-link reference takes the form of the transaction identifier followed by the transaction line identifier. This reference is what matches each tracking record to the correct order line and is what allows partial shipments to be packed correctly.
External ID Format
In the TO direction, each captured tracking record is attached to the iPaaS.com transaction resolved from the Acumatica transaction reference, stored as the parent identifier. In the FROM direction, the integration locates the Acumatica shipment for the resolved order and matches the package by the line-link reference; subscribers do not supply an Acumatica shipment number.
Custom Field Support
The TO collections do not use subscriber-defined custom fields. The FROM collections depend on three iPaaS.com custom fields that supply Acumatica-specific values not present on a standard transaction:
BoxId: Identifies the Acumatica box used for the package. Required.
WarehouseId: Identifies the Acumatica warehouse the shipment ships from. Required.
iPaaS_LineItemId: The line-link reference used to match the tracking record to the correct order line for partial shipments.
Subscribers configure these custom fields on the iPaaS.com transaction so the integration can populate the package and locate the right shipment line.
Mapping Collection Status
Status: Enabled (all four collections)
Trigger Events (TO iPaaS.com): Manual Sync. There is no automatic tracking trigger.
Trigger Events (FROM iPaaS.com): Outbound data flow trigger subscriptions, and Manual Sync on demand.
Supported Child Collections
None for the standalone collections. Each standalone collection resolves and attaches its own parent transaction. Tracking Number can also be transferred as a child of a Sales Order; that child collection is documented in the Acumatica Sales Orders from iPaaS article.
Duplicate or Conflicting Mappings
Transaction Tracking Number is bidirectional, so the inbound (TO iPaaS.com) and outbound (FROM iPaaS.com) collections operate on the same tracking data in opposite directions. Within each direction, the Add and Update collections share the same mapping filter and largely the same field mappings; the difference is the sync type.
Before enabling the inbound collections alongside the outbound collections, review and customize the mapping collection filters to prevent circular updates between Acumatica and iPaaS.com. There is no automatic collision handling on these collections.
System Caveats
Acumatica Caveats
Declared value may be absent. Some shipments do not carry a declared cost on the package, so the captured or written cost may be empty.
Tracking must be exposed in the Acumatica API. The shipment and package detail must be retrievable through the Acumatica web services endpoint the integration uses.
Shipments must be in Open status to be created (FROM direction). Only shipments with the Open status can be created; a shipment in another status causes Acumatica to reject the write.
Hold Shipments on Entry must be turned off (FROM direction). The "Hold Shipments on Entry" option in the Acumatica Sales Order preferences must be deactivated; otherwise shipments are created on hold and the package write does not behave as expected.
Box and warehouse must be configured in Acumatica (FROM direction). The BoxId must match a configured box and the WarehouseId must match a configured warehouse, or Acumatica rejects the write.
Writes are an upsert (FROM direction). An update overwrites each mapped field with the iPaaS.com value, including clearing the existing Acumatica value when the mapped value is blank. A field that is not mapped is left untouched.
iPaaS.com Caveats
A valid parent transaction is required (TO direction). The tracking record must resolve to an existing iPaaS.com transaction. If the order has not yet been captured into iPaaS.com, resolve the transaction first, then re-run the tracking transfer.
Shipping method must exist first (TO direction). The shipping method referenced by the package must already be configured in iPaaS.com; otherwise the transfer is rejected by the mapping filter.
The line-link reference must be populated (FROM direction). The iPaaS_LineItemId custom field must follow the form transaction identifier followed by transaction line identifier; if it is missing, the integration cannot match the tracking record to the correct shipment line.
Setup Requirements
Acumatica Configuration
The Acumatica connection must be configured and authorized so the integration can read or create shipments and packages.
For the FROM direction, the "Hold Shipments on Entry" option must be deactivated in the Acumatica Sales Order preferences, and the box and warehouse referenced by the transfer must already be configured in Acumatica.
iPaaS.com Configuration
For the TO direction, the parent order must already be present as a transaction in iPaaS.com, and the shipping method referenced by the package must already exist in iPaaS.com.
For the FROM direction, the BoxId, WarehouseId, and iPaaS_LineItemId custom fields must be configured and populated on the iPaaS.com transaction.
Authentication & Security
The Acumatica connection is authorized through OAuth 2.0 against the Acumatica instance, and every request carries the company identifier so the integration reads from and writes to the correct Acumatica company.
Integration Flow
TO iPaaS.com (Add and Update)
A subscriber runs a Manual Sync, entering the Acumatica transaction identifier the tracking number belongs to.
The integration reads the package detail from the Acumatica shipment.
The mapping filter checks that the package resolves to an existing iPaaS.com transaction and that its shipping method already exists in iPaaS.com. If either condition fails, the transfer is rejected.
When both conditions pass, the package carrier, description, tracking number, and declared value are captured, and the resolved transaction is recorded as the parent. The Add collection captures the record the first time; the Update collection refreshes an existing record in place.
FROM iPaaS.com (Add and Update)
An outbound data flow trigger subscription signals that a tracking number is ready to transfer, or a subscriber runs a Manual Sync.
The integration resolves the Acumatica customer and order number from the iPaaS.com transaction. Prerequisite auto-transfer: if the parent transaction has not yet been transferred into Acumatica, the integration transfers it automatically first; subscribers do not pre-sync the parent. If the parent transfer fails for its own reasons, the tracking transfer is blocked and the failure appears in the Dashboard.
The mapping filter checks that the BoxId and WarehouseId custom fields are present; if either is empty, the transfer is rejected.
The integration looks for an existing Acumatica shipment for the order. The Add collection creates a shipment if none exists and adds the package; the Update collection locates the existing shipment and updates the package. If the Update collection finds the tracking record has already been fully shipped and recorded in Acumatica, it completes without writing.
The package carries the tracking number, carrier type, description, declared value, box, and warehouse, with the line-link reference tying it to the correct order line.
Mappings
Add Acumatica Transaction Tracking Number TO iPaaS.com
Mapping Filter:
var parentId = await GetSpaceportIdAsync(TransactionID_, "Transaction", SpaceportSystemId);
if(parentId == null)
throw new exception("Transaction Tracking Number is not linked to any Transaction");
var getShipment = await FindShippingMethodFromName(Type);
if(getShipment == null)
throw new exception($"Shipping Method ({Type}) needs to be created manually in iPaaS first");
return true;This filter enforces two conditions, both of which must pass before a tracking record is captured. First, the package's Acumatica transaction must resolve to an existing iPaaS.com transaction; if it does not, the transfer is rejected with the message that the transaction tracking number is not linked to any transaction. Second, the package's shipping method must already exist in iPaaS.com; if a matching shipping method is not found, the transfer is rejected with guidance that the shipping method needs to be created manually in iPaaS.com first. Packages that satisfy both conditions are processed.
Mapping Type | Source Field (Acumatica) | Destination Field (iPaaS.com) | Description |
Dynamic Formula |
| ParentId | Required. Resolves the iPaaS.com transaction the tracking number belongs to from the Acumatica transaction reference. The mapping filter rejects any package that does not resolve to a transaction, so a tracking record cannot be captured without a parent. If the order has not yet been captured, resolve the transaction first, then re-run. |
Field | Type | ShippingMethod | Recommended. Maps the Acumatica package type (the carrier or service). The mapping filter requires that a matching shipping method already exist in iPaaS.com. |
Field | TrackingNbr_Package | TrackingNumber | Recommended. Maps the package tracking number. This is the core value the collection exists to capture. |
Field | Description_Package | ShippingMethodDescription | Optional. Maps the package description; context only. |
Field | DeclaredValue_Package | Cost | Optional. Maps the package declared value. Not present on every shipment, so it may be empty. |
Update Acumatica Transaction Tracking Number TO iPaaS.com
Mapping Filter:
var parentId = await GetSpaceportIdAsync(TransactionID_, "Transaction", SpaceportSystemId);
if(parentId == null)
throw new exception("Transaction Tracking Number is not linked to any Transaction");
var getShipment = await FindShippingMethodFromName(Type);
if(getShipment == null)
throw new exception($"Shipping Method ({Type}) needs to be created manually in iPaaS first");
return true;This collection uses the same two-condition filter as the Add collection: the package must resolve to an existing iPaaS.com transaction, and its shipping method must already exist in iPaaS.com. The difference is the sync type — this collection refreshes a tracking record that already exists in iPaaS.com rather than capturing it the first time.
Mapping Type | Source Field (Acumatica) | Destination Field (iPaaS.com) | Description |
Dynamic Formula |
| ParentId | Required. Resolves the iPaaS.com transaction the tracking number belongs to so the record stays attached to the correct order. The mapping filter rejects any package that does not resolve to a transaction. |
Field | Type | ShippingMethod | Recommended. Maps the Acumatica package type (the carrier or service). A matching shipping method must already exist in iPaaS.com. |
Field | TrackingNbr_Package | TrackingNumber | Recommended. Maps the package tracking number. This is the core value the collection exists to keep current. |
Field | Description_Package | ShippingMethodDescription | Optional. Maps the package description; context only. |
Field | DeclaredValue_Package | Cost | Optional. Maps the package declared value. May be empty. |
Add Acumatica Transaction Tracking Number FROM iPaaS.com
Mapping Filter:
var boxId = GetCustomFieldValue(CustomFields, "BoxId");
var warehouseId = GetCustomFieldValue(CustomFields, "WarehouseId");
if(string.IsNullOrEmpty(boxId)){
throw new exception("Required: BoxId.");
}
if(string.IsNullOrEmpty(warehouseId)){
throw new exception("Required: WarehouseId.");
}
return true;This filter checks the two custom fields the package write depends on. If the BoxId custom field is empty, the transfer is rejected with "Required: BoxId."; if the WarehouseId custom field is empty, it is rejected with "Required: WarehouseId.". When both custom fields are present, the transfer is processed.
Mapping Type | Source Field (iPaaS.com) | Destination Field (Acumatica) | Description |
Field | Custom field: BoxId | BoxID_Package | Required. Maps the BoxId custom field to the Acumatica package box. The filter rejects the transfer with "Required: BoxId." if empty, and the value must match a box configured in Acumatica's Boxes setup. |
Field | Custom field: WarehouseId | WarehouseId | Required. Maps the WarehouseId custom field to the Acumatica shipment warehouse (the location the shipment ships from). The filter rejects the transfer with "Required: WarehouseId." if empty, and the value must match a warehouse configured in Acumatica. |
Dynamic Formula |
| CustomerID | Required. Resolves the Acumatica customer for the shipment from the iPaaS.com transaction. The integration derives this; subscribers do not configure it directly. |
Dynamic Formula |
| OrderNbr | Required. Resolves the Acumatica order number from the iPaaS.com transaction. The write is rejected if the order number cannot be resolved. The integration derives this; subscribers do not configure it directly. |
Field | Custom field: iPaaS_LineItemId | iPaaS_LineItemId | Required. The line-link reference (transaction identifier followed by transaction line identifier) that matches the tracking record to the correct order line and supports partial shipments. |
Field | TrackingNumber | TrackingNbr_Package | Required. Maps the iPaaS.com tracking number to the Acumatica package tracking number. The write is rejected if it is empty. |
Field | ShippingMethod | Type_Package | Recommended. Maps the iPaaS.com shipping method to the Acumatica package type (the carrier or service). |
Field | ShippingMethodDescription | Description_Package | Optional. Maps the iPaaS.com shipping method description to the package description. |
Field | Cost | DeclaredValue_Package | Optional. Maps the iPaaS.com cost to the package declared value. Because the field is mapped, an empty value overwrites (clears) any existing declared value on an update; leave the field unmapped to keep an Acumatica-maintained value. |
Static |
| Operation | Recommended. Sets the inventory operation to Issue for a sales-order shipment. Subscribers should leave this as Issue. |
Static |
| OrderType | Recommended. Sets the order type to SO (sales order). Subscribers should leave this as SO. |
Static |
| Status | Recommended. Sets the shipment status to Open. Only Open shipments can be created; the "Hold Shipments on Entry" preference must be deactivated so the shipment is not created on hold. |
Update Acumatica Transaction Tracking Number FROM iPaaS.com
Mapping Filter:
var boxId = GetCustomFieldValue(CustomFields, "BoxId");
var warehouseId = GetCustomFieldValue(CustomFields, "WarehouseId");
if(string.IsNullOrEmpty(boxId)){
throw new exception("Required: BoxId.");
}
if(string.IsNullOrEmpty(warehouseId)){
throw new exception("Required: WarehouseId.");
}
return true;This collection uses the same custom-field filter as the Add collection: the transfer is rejected with "Required: BoxId." or "Required: WarehouseId." when either custom field is empty. The difference is the sync type — this collection refreshes a shipment package that already exists rather than creating it. This Update collection does not carry a static Status mapping; the shipment status used to locate the existing shipment is derived from the order's current shipment in Acumatica rather than set from a mapping. Subscribers should validate this behavior in a staging environment before relying on it in production.
Mapping Type | Source Field (iPaaS.com) | Destination Field (Acumatica) | Description |
Field | Custom field: BoxId | BoxID_Package | Required. Maps the BoxId custom field to the Acumatica package box. Rejected with "Required: BoxId." if empty; must match a configured box. |
Field | Custom field: WarehouseId | WarehouseId | Required. Maps the WarehouseId custom field to the Acumatica shipment warehouse. Rejected with "Required: WarehouseId." if empty; must match a configured warehouse. |
Dynamic Formula |
| CustomerID | Required. Resolves the Acumatica customer from the iPaaS.com transaction. The integration derives this. |
Dynamic Formula |
| OrderNbr | Required. Resolves the Acumatica order number from the iPaaS.com transaction. The write is rejected if it cannot be resolved. |
Field | Custom field: iPaaS_LineItemId | iPaaS_LineItemId | Required. The line-link reference (transaction identifier followed by transaction line identifier) that matches the tracking record to the correct order line for partial shipments. |
Field | TrackingNumber | TrackingNbr_Package | Required. Maps the iPaaS.com tracking number to the Acumatica package tracking number. The write is rejected if it is empty. |
Field | ShippingMethod | Type_Package | Recommended. Maps the iPaaS.com shipping method to the Acumatica package type. |
Field | ShippingMethodDescription | Description_Package | Optional. Maps the iPaaS.com shipping method description to the package description. |
Field | Cost | DeclaredValue_Package | Optional. Maps the iPaaS.com cost to the package declared value. Because the field is mapped, an empty value overwrites (clears) any existing declared value on an update; leave the field unmapped to keep an Acumatica-maintained value. |
Static |
| Operation | Recommended. Sets the inventory operation to Issue for a sales-order shipment. |
Static |
| OrderType | Recommended. Sets the order type to SO (sales order). |
Error Handling
Errors raised during a tracking transfer appear in iPaaS.com under Dashboard / Integration Monitoring / Error Logs. The most common conditions are:
"Transaction Tracking Number is not linked to any Transaction": Raised by the TO-direction mapping filter when the Acumatica transaction does not resolve to an existing iPaaS.com transaction. Resolution: capture the parent order into iPaaS.com first, then re-run the tracking transfer.
"Shipping Method (X) needs to be created manually in iPaaS first": Raised by the TO-direction mapping filter when the package's shipping method does not yet exist in iPaaS.com. Resolution: create the matching shipping method in iPaaS.com, then re-run the transfer.
"Required: BoxId.": Raised by the FROM-direction mapping filter when the BoxId custom field is empty. Resolution: populate the BoxId custom field on the iPaaS.com transaction with a valid Acumatica box identifier.
"Required: WarehouseId.": Raised by the FROM-direction mapping filter when the WarehouseId custom field is empty. Resolution: populate the WarehouseId custom field on the iPaaS.com transaction with a valid Acumatica warehouse identifier.
Order number cannot be resolved (FROM direction): The write is rejected if the Acumatica order number cannot be resolved from the iPaaS.com transaction. Resolution: confirm the parent transaction exists or can be auto-transferred; check the Dashboard for the parent transfer failure.
Acumatica temporarily unavailable: If Acumatica is unavailable during a transfer, the capture or write fails and is retried on the next run. Resolution: confirm Acumatica is reachable, then allow the next outbound run or re-run the Manual Sync.
For shared error message wording and resolutions across the integration, see the Acumatica Error Messages article.
Testing & Validation
Test Scenarios
TO direction, valid transaction: Run a Manual Sync with an Acumatica transaction identifier whose order already exists in iPaaS.com and whose shipping method is configured, and verify the tracking record is captured against the correct transaction.
TO direction, unlinked transaction: Run a Manual Sync for a tracking number whose order is not yet in iPaaS.com and confirm the "not linked to any Transaction" error appears.
TO direction, missing shipping method: Transfer a package whose shipping method does not exist in iPaaS.com and confirm the "needs to be created manually in iPaaS first" error appears.
FROM direction, missing custom fields: Transfer a tracking number with an empty BoxId or WarehouseId and confirm the corresponding "Required:" error appears.
FROM direction, prerequisite auto-transfer: Transfer a tracking number whose parent transaction is not yet in Acumatica and confirm the parent is transferred automatically before the package is written.
FROM direction, partial shipment: Populate iPaaS_LineItemId per line and verify each tracking record is matched to the correct order line.
Validation Checklist
TO direction: the parent transaction resolves and the tracking record is attached to the correct order
TO direction: the shipping method exists in iPaaS.com before transfer
FROM direction: BoxId and WarehouseId custom fields are populated with valid Acumatica values
FROM direction: iPaaS_LineItemId follows the transaction-then-line format
FROM direction: the shipment is created or located in Open status with operation Issue and order type SO
Tracking number is retained on both sides
Additional Notes
Tracking is bidirectional. The TO and FROM collections move the same tracking data in opposite directions. When both directions are enabled, review and customize the mapping filters to prevent circular updates.
FROM-direction prerequisite. A tracking number written from iPaaS.com is attached to a parent transaction. If that parent transaction has not yet been transferred into Acumatica, the integration transfers it automatically first; subscribers do not pre-sync the parent.
Child flow cross-reference. Tracking can also move as a child of a Sales Order. That child collection is documented in the Acumatica Sales Orders from iPaaS article, not here.
Writes into Acumatica are an upsert: an update overwrites each mapped field with the iPaaS.com value, including clearing it when that value is blank, while a field that is not mapped is left untouched.