Summary
Acumatica sales orders (order type SO) are captured into iPaaS.com as Transactions using an Add/Update sync method. The integration reads each order with its lines, bill-to and ship-to addresses and contacts, taxes, payments, and totals, and builds a Transaction with the order number, customer, Company, email, type, status, dates, and amounts. The lines, addresses, taxes, and payments are captured by child collections that run as part of the order transfer. Orders are written in the other direction by Add/Update Acumatica Sales Order FROM iPaaS.com, and both directions link an order to the same Transaction.
ID Format
Manual Sync ID Format
When manually transferring, enter the Acumatica order type and order number joined with "|", for example SO|000080. Order numbers are unique only within an order type, so both are needed.
External ID Format
iPaaS.com records the Acumatica record id (GUID) of the sales order as the external ID of the Transaction on a dedicated external-ID record, the primary match for every later transfer. Add/Update Acumatica Sales Order FROM iPaaS.com links orders by the same id, so an order created in Acumatica from an iPaaS.com Transaction updates that same Transaction instead of creating a second one. The template also maps the order number into TransactionNumber, which shows it on the Transaction and serves as a fallback match: an order that is not linked yet is linked to the one existing, unlinked Transaction with the same number (none is linked when several match). Remapping TransactionNumber to another value is supported, but it stops that fallback for orders already in iPaaS.com.
The children are linked as follows: each line and each payment by its Acumatica row id; each address by the Acumatica id of the bill-to or ship-to address together with its role, Billing or Shipping, since Acumatica can give both addresses the same id; and each tax by its Acumatica RecordID and row id, for example 282|fbde0cc3-2307-4c39-9bb0-db1ba4a9961a. Acumatica gives addresses and tax rows a new id in each session, so their links are refreshed on each transfer.
Deleted Record Support
Deleting or cancelling an order in Acumatica is not sent to iPaaS.com as a delete, and delete mappings are not included in the default templates. A cancelled order is captured with the status Cancelled.
Custom Field Support
No custom fields are mapped in the shipped template. The integration reads the standard fields of the sales order from the Acumatica Default web service endpoint; fields added to the sales order by an Acumatica customization are not read.
Mapping Collection Status
Status: Enabled
Trigger Events: Acumatica does not push order changes to the integration. An order reaches iPaaS.com in two ways:
Order poll: on each scheduled poll, the integration reads the Acumatica sales orders changed since the last poll (by their last-modified time, in UTC) and sends each one to this collection; the mapping filter decides which are captured. The first order poll on a subscription, when no earlier order poll time has been saved, only records its start time and does not pull existing orders. An order written to Acumatica by Add/Update Acumatica Sales Order FROM iPaaS.com is not sent straight back by the next poll; it is captured again once it changes in Acumatica after that poll. An edit made in Acumatica before that poll runs is skipped with it and reaches the Transaction with the order's next change.
Manual Sync: a subscriber can transfer a specific order on demand from the iPaaS.com Manual Sync page by entering its order type and number (see ID Format).
Duplicate or Conflicting Mappings
Add/Update Acumatica Sales Order FROM iPaaS.com writes iPaaS.com Transactions into Acumatica as sales orders. Both collections link an order to the same Transaction, so an order created from iPaaS.com and later changed in Acumatica updates its original Transaction. Decide which system is the source of truth for each part of an order: a change made in Acumatica is captured into the Transaction, and a later transfer of the Transaction into Acumatica writes the iPaaS.com values back over the order.
Collision handling: this collection does not use the Collision Handling Method setting. Duplicate handling is automatic: an order not linked yet is linked to the one existing, unlinked iPaaS.com Transaction with its number; when several match, none is linked and a new Transaction is created. On an existing Transaction, the order's lines, addresses, taxes, and payments are linked to the matching records already on it (lines by Sku, then quantity and line number; taxes by Authority; payments by Method, then amount); only a single match is linked, otherwise the record is added. Addresses are linked by their role: the bill-to to the Transaction's primary billing address and the ship-to to its primary shipping address, with the address fields compared only to choose between several, and the first linked when several still remain, so a capture never adds a second primary billing or shipping address.
Supported Child Collections
Add/Update Acumatica Sales Order Line TO iPaaS.com: The order's lines.
Add/Update Acumatica Sales Order Address TO iPaaS.com: The order's bill-to and ship-to addresses.
Add/Update Acumatica Sales Order Tax TO iPaaS.com: The order's taxes.
Add/Update Acumatica Sales Order Payment TO iPaaS.com: The payments applied to the order.
System Caveats
Acumatica Caveats
Status values: the Status formula compares Acumatica's own spelling of each order status, for example Canceled, Open, On Hold, and Back Order. A status the formula does not list is captured as Pending.
Shipping amount: the iPaaS.com ShippingAmount is the order's freight plus its premium freight. Add/Update Acumatica Sales Order FROM iPaaS.com writes the iPaaS.com shipping amount into the premium freight, so both are needed for the amount to survive a round trip.
Order types: the shipped filter captures order type SO only; an order type of the subscriber's own can be added to the filter.
iPaaS.com Caveats
Customer, Company, or email: iPaaS.com rejects a transaction with no customer, no Company, and no email (VALD-1002). Keep the EmailAddress mapping so that an order whose business account no filter captures is still captured.
Products: every line is captured with the type Product, and iPaaS.com requires each line's SKU to match an iPaaS.com product, so every SKU on the order's lines must exist as a product in iPaaS.com, or the order is not captured. This integration creates iPaaS.com products only for Acumatica stock items; a non-stock item line needs a product with that SKU in iPaaS.com, which this integration does not create.
Payment methods: every Acumatica payment method used on the orders must exist in iPaaS.com as a Payment Method, or be translated to one by the Method mapping. A new payment with a method iPaaS.com does not have is rejected with VALD-1036, and the whole order is not captured.
Setup Requirements
Acumatica Configuration
No Acumatica customization is needed. The integration reads sales orders through the standard Acumatica web service endpoint (Default) at the version set in the Version setting of your iPaaS.com Acumatica subscription.
iPaaS.com Configuration
Polling must be configured for the integration so that changed orders are captured on a recurring cadence; until it is, orders are captured only by a Manual Sync.
The stock items used on the orders must be in iPaaS.com as products, through Add/Update Acumatica Stock Item TO iPaaS.com (see Acumatica to iPaaS.com Stock Item Mapping Documentation).
Every Acumatica payment method used on the orders must exist in iPaaS.com as a Payment Method with the same name.
The collections Add/Update Acumatica Customer TO iPaaS.com and Add/Update Acumatica Company TO iPaaS.com must be active, so that an order's business account can be transferred first.
The child collections listed under Supported Child Collections must be active for lines, addresses, taxes, and payments to be captured.
Authentication & Security
The integration authenticates to the Acumatica instance with OAuth 2.0; the Acumatica company it works in is set by the Connected Application's Client Id. The full authentication walkthrough is covered in the Acumatica Connections and Settings and Acumatica Installation Instructions articles; this document does not repeat it.
Prerequisite Handling
Subscribers do not need to transfer an order's customer before the order: the integration handles it as part of the order transfer.
Business account first: when the order's business account (CustomerID) is not yet linked to an iPaaS.com Customer or Company, the account is transferred first through Add/Update Acumatica Customer TO iPaaS.com and then Add/Update Acumatica Company TO iPaaS.com. Their filters decide which one captures it, and their own duplicate handling links it to an existing record instead of creating a second one (see Acumatica to iPaaS.com Customer Mapping Documentation and Acumatica to iPaaS.com Company Mapping Documentation). An account that is already linked is not transferred again.
An account no filter captures: the order is captured without a customer or Company, with the email of its bill-to contact (or else of its ship-to contact), and a warning is written to the integration log.
A failed account transfer blocks the order: if the account transfer fails with an error, the order transfer fails with error ACUM-EXTN-1006; if the account cannot be read from Acumatica, the order transfer fails with that read error. Resolve the account error, shown with the order error in Dashboard / Integration Monitoring / Error Logs, then transfer the order again.
Existing Transaction: an order that is not linked yet is linked to the one existing, unlinked iPaaS.com Transaction with the same number. Whenever the order maps to an existing Transaction, already linked or linked now by number, its lines, addresses, taxes, and payments that are not linked yet are linked to the matching records on it (see Duplicate or Conflicting Mappings).
Integration Flow
The order poll finds the order changed in Acumatica, or a subscriber runs a Manual Sync with its order type and number. The mapping filter decides whether the order is captured.
The order is retrieved from Acumatica through the standard Default web service endpoint, with its lines, taxes, bill-to and ship-to addresses and contacts, payments, and totals.
When the business account is not yet in iPaaS.com, it is transferred first through the Customer and Company collections.
When the order is not yet linked, it is linked to the one existing, unlinked Transaction with the same number, if there is one. When the order maps to an existing Transaction, already linked or linked now, its children that are not linked yet are linked to the matching records on that Transaction.
The Transaction is created in iPaaS.com, or updated when it is already linked, with its lines, addresses, taxes, and payments, and each record is linked back to its Acumatica order or row.
Mappings
Add/Update Acumatica Sales Order TO iPaaS.com
iPaaS.com data type: Transaction
Mapping Filter
OrderType == "SO"
Filter Description. Only Acumatica sales orders (order type SO) are captured. Orders of every other order type, including invoices (IN), quotes (QT), and credit memos and returns (CM, RC, RM, CR), are skipped. Conditions can be added, for example on Status, but the OrderType condition must stay in place; the filter compares Acumatica's own spelling of each value, for example OrderType == "SO" && Status != "Canceled". Orders are best captured once their lines no longer change (see Additional Notes).
Description: Builds the iPaaS.com Transaction from the Acumatica sales order, its totals, and its bill-to and ship-to contacts.
Mapping Type | Source Field (Acumatica) | Destination Field (iPaaS.com) | Description |
Field | OrderNbr | TransactionNumber | Required. The Acumatica order number, for example 000080; the order type is not part of it. Also the fallback match that links an unlinked order to an existing iPaaS.com Transaction with the same number. |
Dynamic Formula | See the formula below the table. | CustomerId | Recommended. The order contact's iPaaS.com Customer when the business account is an iPaaS.com Company; otherwise the Customer linked to the business account. |
Dynamic Formula | See the formula below the table. | CompanyId | Optional. The iPaaS.com Company linked to the order's business account; empty when the account is a Customer. |
Dynamic Formula | See the formula below the table. | Type | Required. Order for SO orders; QT is a Quote, IN an Invoice, and CM, RC, RM, and CR are Returns when the filter is widened to those order types. |
Dynamic Formula | See the formula below the table. | Status | Required. Complete for Completed or Invoiced, Cancelled for Canceled or Rejected, Processing for Open, Back Order, or Shipping, and Pending for every other status. |
Field | DiscountTotal | DiscountAmount | Optional. The order's document-level discount total; line discounts are carried on each line's DiscountAmount, not here. |
Field | TaxTotal | TaxAmount | Recommended. The order's tax total. |
Dynamic Formula | See the formula below the table. | ShippingAmount | Recommended. The order's freight plus premium freight. |
Field | LineTotalAmount | Subtotal | Recommended. The order's line total, before tax and freight. |
Field | OrderTotal | Total | Recommended. The order total, including tax and freight. |
Field | OrderedQty | TotalQty | Optional. The order's total ordered quantity. |
Dynamic Formula | See the formula below the table. | TransactionCreatedDateTime | Recommended. The order date, in UTC. |
Dynamic Formula | See the formula below the table. | TransactionUpdatedDateTime | Optional. When the order was last changed in Acumatica, in UTC. |
Dynamic Formula |
| SystemId | Required. This subscription; iPaaS.com requires the system the transaction comes from. Keep as shipped. |
Dynamic Formula | See the formula below the table. | EmailAddress | Recommended. The email of the bill-to contact, or else of the ship-to contact, so that an order whose account no filter captures is not rejected (VALD-1002). |
The CustomerId dynamic formula:
var companyId = await GetSpaceportIdAsync(CustomerID, "Company", SpaceportSystemId);
if (companyId != null && ContactID != null)
{
var contactCustomerId = await GetSpaceportIdAsync(ContactID + "|contact", "Customer", SpaceportSystemId);
if (contactCustomerId != null)
return contactCustomerId;
}
var customerId = await GetSpaceportIdAsync(CustomerID, "Customer", SpaceportSystemId);
if (customerId != null)
return customerId;
return null;The CompanyId dynamic formula:
var companyId = await GetSpaceportIdAsync(CustomerID, "Company", SpaceportSystemId);
if(companyId != null)
return companyId;
return null;The Type dynamic formula:
if (OrderType == "QT")
return "Quote";
if (OrderType == "IN")
return "Invoice";
if (OrderType == "CM" || OrderType == "RC" || OrderType == "RM" || OrderType == "CR")
return "Return";
return "Order";The Status dynamic formula:
if (Status == "Completed" || Status == "Invoiced")
return "Complete";
if (Status == "Canceled" || Status == "Rejected")
return "Cancelled";
if (Status == "Open" || Status == "Back Order" || Status == "Shipping")
return "Processing";
return "Pending";The ShippingAmount dynamic formula:
return Convert.ToDecimal(Freight ?? 0) + Convert.ToDecimal(PremiumFreight ?? 0);
The TransactionCreatedDateTime dynamic formula:
if (Date == null)
return null;
return new DateTimeOffset(DateTime.SpecifyKind(Convert.ToDateTime(Date), DateTimeKind.Utc));The TransactionUpdatedDateTime dynamic formula:
if (LastModified == null)
return null;
return new DateTimeOffset(DateTime.SpecifyKind(Convert.ToDateTime(LastModified), DateTimeKind.Utc));The EmailAddress dynamic formula:
if (TransactionAddresses != null)
{
foreach (var address in TransactionAddresses)
if (address.IsPrimaryBilling && !string.IsNullOrEmpty(address.Email))
return address.Email;
foreach (var address in TransactionAddresses)
if (!string.IsNullOrEmpty(address.Email))
return address.Email;
}
return null;
Add/Update Acumatica Sales Order Line TO iPaaS.com
iPaaS.com data type: Transaction Line
This child collection has no mapping filter; every line of the order is processed.
Description: Captures each order line.
Mapping Type | Source Field (Acumatica) | Destination Field (iPaaS.com) | Description |
Field | InventoryID | Sku | Recommended. The line's Inventory ID. It must exist as a product in iPaaS.com, or the order is not captured; a non-stock item needs a product with that SKU in iPaaS.com, which this integration does not create. |
Field | LineDescription | Description | Optional. The line description. |
Field | OrderQty | Qty | Recommended. The ordered quantity. |
Field | UnitPrice | UnitPrice | Recommended. The unit price. |
Field | ExtendedPrice | ExtendedPrice | Recommended. Unit price times quantity, before discount. |
Field | DiscountAmount | DiscountAmount | Optional. The line discount amount. |
Field | DiscountPercent | DiscountPercent | Optional. The line discount percent. |
Field | LineNbr | SequenceNumber | Optional. The Acumatica line number. |
Dynamic Formula |
| Type | Required. Product; keep as shipped. |
Dynamic Formula | See the formula below the table. | Status | Required. Complete when the line is completed, otherwise Pending. |
The Status dynamic formula:
if (Completed == true)
return "Complete";
return "Pending";
Add/Update Acumatica Sales Order Address TO iPaaS.com
iPaaS.com data type: Transaction Address
This child collection has no mapping filter; the bill-to and ship-to addresses are processed.
Description: Captures the bill-to and ship-to addresses, with the business name of the matching contact.
Mapping Type | Source Field (Acumatica) | Destination Field (iPaaS.com) | Description |
Field | AddressLine1 | Address1 | Recommended. The first address line. |
Field | AddressLine2 | Address2 | Optional. The second address line. |
Field | City | City | Recommended. The city. |
Field | State | Region | Recommended. The Acumatica State. |
Field | Country | Country | Recommended. The country, for example US. |
Field | PostalCode | PostalCode | Recommended. The postal code. |
Field | BusinessName | Company | Optional. The business name of the bill-to or ship-to contact. |
Field | IsPrimaryBilling | IsPrimaryBilling | Recommended. True for the bill-to address. |
Field | IsPrimaryShipping | IsPrimaryShipping | Recommended. True for the ship-to address. |
Add/Update Acumatica Sales Order Tax TO iPaaS.com
iPaaS.com data type: Transaction Tax
This child collection has no mapping filter; every tax of the order is processed.
Description: Captures each tax detail.
Mapping Type | Source Field (Acumatica) | Destination Field (iPaaS.com) | Description |
Field | TaxID | Authority | Recommended. The Acumatica Tax ID; also links a tax to a tax already on an existing Transaction. |
Field | TaxAmount | Amount | Recommended. The tax amount. |
Field | TaxRate | TaxPercent | Optional. The rate Acumatica holds for the tax. |
Add/Update Acumatica Sales Order Payment TO iPaaS.com
iPaaS.com data type: Transaction Payment
This child collection has no mapping filter; every payment applied to the order is processed.
Description: Captures each payment applied to the order.
Mapping Type | Source Field (Acumatica) | Destination Field (iPaaS.com) | Description |
Field | AppliedToOrder | Amount | Recommended. The amount of the payment applied to the order. |
Field | PaymentMethod | Method | Required. The Acumatica payment method; it must exist in iPaaS.com as a Payment Method (VALD-1036). |
Field | Status | Status | Optional. The Acumatica payment status. |
Dynamic Formula |
| Description | Optional. The payment document type and reference number, for example Prepayment 000123. |
Error Handling
Errors appear in Dashboard / Integration Monitoring / Error Logs. For the full list of Acumatica error messages and codes, see Acumatica Error Messages.
Sales order could not be located (ACUM-NFND-1011): the order type and number entered for a Manual Sync do not exist in Acumatica, or the value entered is not an order type and number. Resolution: check the order on the Acumatica Sales Orders (SO301000) form and transfer it again with its order type and number, for example as SO|000080.
The order's business account could not be transferred first (ACUM-EXTN-1006): the transfer of the order's account to iPaaS.com failed. Resolution: correct the account error shown with it, then transfer the order again.
Existing transaction could not be linked (ACUM-BIZL-1012) and existing transaction line, address, tax, or payment could not be linked (ACUM-BIZL-1013 to 1016): a matching iPaaS.com record was found, but the link to it could not be saved. The transfer stops rather than create a duplicate. Resolution: reprocess the order; if the error repeats, ask your MiSP to check the record named in the message.
No customer, Company, or email (VALD-1002): the order has none of the three. Resolution: keep the EmailAddress mapping, or make sure the order's business account is captured by the Customer or Company collection.
Payment method not valid (VALD-1036): a payment's method does not exist in iPaaS.com. Resolution: create the Payment Method in iPaaS.com, or translate the method with the Method mapping, then transfer the order again.
A line's SKU is not an iPaaS.com product: the order is not captured. Resolution: transfer the stock item to iPaaS.com, then transfer the order again.
If Acumatica is temporarily unavailable during a transfer, the transfer fails and an error appears in Dashboard / Integration Monitoring / Error Logs; the next order poll or a Manual Sync transfers the order again.
Testing & Validation
Test Scenarios
Run a Manual Sync of an open SO order with two lines, a bill-to and ship-to address, a tax, and a payment, and verify the Transaction's number, type, status, customer, amounts, and dates, and its lines, addresses, tax, and payment in iPaaS.com.
Transfer the same order again and confirm the existing Transaction is updated rather than duplicated.
Change the premium freight of the order in Acumatica and confirm the Transaction's shipping amount and total are updated on the next order poll.
Cancel an order and confirm its Transaction status becomes Cancelled.
Send an order FROM iPaaS.com into Acumatica, run an order poll, and confirm the Transaction is not changed; then change a line quantity in Acumatica and confirm the poll updates the same Transaction.
Run a Manual Sync of a QT order and confirm nothing is captured.
Transfer an order whose payment method is not an iPaaS.com Payment Method and confirm VALD-1036 appears in Dashboard / Integration Monitoring / Error Logs.
Validation Checklist
Polling is configured for the integration.
The stock items used on the orders are in iPaaS.com as products.
Every Acumatica payment method used on the orders exists in iPaaS.com as a Payment Method.
The Customer and Company collections are active, with complementary filters.
Any condition added to the mapping filter uses Acumatica's own spelling of each value and keeps the OrderType condition.
Additional Notes
Bulk initialization is not available for this collection; orders are captured by the order poll as they change, or by Manual Sync.
The child collections run with the parent; lines, addresses, taxes, and payments cannot be transferred on their own.
Shipments and other Acumatica documents are not captured as Transactions.
At the time this documentation was written:
Transfer orders once their lines are final: changes to the quantity, price, or other fields of an existing line update the Transaction, but a change to the order's set of lines is not fully carried. A line removed from the Acumatica order after it has transferred stays on the iPaaS.com Transaction, and a line added later can be written onto the Transaction line of a removed line instead of being added as a new line. Orders are often passed on from iPaaS.com to systems that do not accept later edits, so capture an order when its lines no longer change, for example with a Status condition in the mapping filter.
First order poll: the first order poll on a subscription does not pull orders that already exist in Acumatica; send those with a Manual Sync if they are needed in iPaaS.com.
Related Documents
Related Mapping Documentation