Summary
Acumatica Sales Orders can be written from iPaaS.com using an Add/Update sync method. This mapping translates an iPaaS.com transaction into an Acumatica Sales Order — resolving the Acumatica customer account (from the order's Company, Customer, or email), assigning financial terms and the customer tax zone, and populating order-level totals and freight — and writes the order's addresses, line items, payments, taxes, and tracking as child records within the same order document. Orders are captured in the other direction, from Acumatica into iPaaS.com, by Add/Update Acumatica Sales Order TO iPaaS.com, which links an order to the same Transaction.
ID Format
Manual Sync ID Format
When manually transferring, supply the iPaaS.com Transaction ID of the order, for example 172595. The integration resolves the order to an Acumatica customer account from the order's iPaaS.com Company, then its Customer (a Customer that came from an Acumatica contact goes on that contact's business account), then its email address.
External ID Format
After a successful transfer, iPaaS.com saves the Acumatica order's record id, a GUID such as 9e730acb-f4ce-f111-ab30-000c29d9c730, as the transaction's external ID, and later transfers of that transaction update the same Acumatica order. The order's lines, taxes, and tracking packages are linked to their iPaaS.com records when the written order is read back. The order number (OrderNbr) is not the link; it is used only by Sales Order Duplicate Checking to find an existing order for a transaction that is not yet linked. Package contents are linked to the order line using a line-item identifier in the form TransactionId|TransactionLineId.
Deleted Record Support
Removing an order in iPaaS.com is not propagated as a delete in Acumatica, and delete mappings are not included in the default templates.
Mapping Collection Status
Status: Enabled
Trigger Events: the iPaaS.com transaction/created and transaction/updated triggers, subscribed in the subscription configuration's Outbound Data Flows section. No automatic transfers occur until these subscriptions are enabled. Whether a transfer adds or updates an Acumatica order depends on whether the transaction is already linked to one, not on which trigger fired. Orders can also be transferred on demand from the Manual Sync page with the iPaaS.com Transaction ID.
Duplicate or Conflicting Mappings
Add/Update Acumatica Sales Order TO iPaaS.com captures Acumatica sales orders into iPaaS.com. Both collections link an order to the same Transaction, so an order written by this collection is not sent straight back by the next order poll, and a change made in Acumatica after that poll updates its original Transaction; an Acumatica edit made before that poll is captured with the order's next change. Decide which system is the source of truth for each part of an order: a transfer of the Transaction into Acumatica writes the iPaaS.com values over the order. Repeated transfers of the same order are handled by the de-duplication behavior described under Integration Flow rather than by creating duplicate orders.
Collision handling is not supported for this collection; repeated transfers are de-duplicated by external-id linking and the Sales Order Duplicate Checking setting, not by collision resolution.
Supported Child Collections
The following child collections are written within the parent Sales Order transfer. None is invoked independently — to transfer any of them, transfer the parent order.
Add/Update Acumatica Sales Order Line FROM iPaaS.com: The order's product line items. At least one valid line is required for the order to post.
Add/Update Acumatica Sales Order Address FROM iPaaS.com: The order's billing and shipping addresses and contacts.
Add/Update Acumatica Sales Order Payment FROM iPaaS.com: The order's payment records.
Add/Update Acumatica Sales Order Tax FROM iPaaS.com: The order's tax details.
Add/Update Acumatica Sales Order Tracking Number FROM iPaaS.com: The order's shipment tracking numbers and package details.
System Caveats
Acumatica Caveats
Credit terms must be configured. The financial terms code mapped to the order must exist in the subscriber's Acumatica Credit Terms configuration (screen CS2065PL). Use a term defined with a single installment type — if a multiple-installment term is used, Acumatica rejects adding a payment to the order with the message "No applications can be created for documents with multiple installment credit terms specified."
Tax zone and tax codes must be configured. The customer tax zone and any tax codes applied to the order must exist in the subscriber's Acumatica Tax configuration. Configure Tax Categories and their eligible Tax IDs (screen TX2060PL) before transferring orders.
Every order needs a customer account. Acumatica places every sales order on a customer account, does not derive the account from a contact, and rejects a contact that belongs to a different account. An order that resolves to no account is rejected.
Manual order numbering must be enabled to honor the iPaaS.com order number. By default Acumatica assigns its own auto-incrementing sales order number and the order number supplied from iPaaS.com is not used. For Acumatica to accept the iPaaS.com order number, the sales order numbering sequence must be configured to use manual numbering in Acumatica (screen CS201010).
Open shipments only. For tracking, the Hold Shipments on Entry option must be deactivated in Acumatica Sales Order Preferences; otherwise the shipment cannot be created in the Open status the integration requires.
Only stock items are supported on order lines. Non-stock items are not written to the order.
iPaaS.com Caveats
Field references in dynamic formulas use the iPaaS.com field names exactly as written (for example, EmailAddress, TransactionNumber) and are case-sensitive.
An order transfer fails if the order's customer cannot be resolved.
The box and warehouse values used for tracking are supplied through custom fields on the iPaaS.com transaction; both must be populated for tracking to transfer.
Integration-Specific Caveats
Postal codes. The order address postal code is sent as given when present; a missing postal code is not sent, and the order address keeps the postal code Acumatica already holds for it (on a new order, the postal code of the customer's address). Acumatica checks the postal code against the address's country: a valid ZIP, ZIP+4 or international code is accepted, and a malformed one rejects the order with "The entered code doesn't match the required expression."
Country codes. The order address Country formula sends Acumatica's two-letter country ID: US for US, USA, U.S.A or United States, and any other two-letter code as given. Any other value is not sent, and the order address keeps the country Acumatica already holds for it; subscribers whose orders carry other country names should extend the formula to translate them to two-letter codes.
Payment method from the source payment. Each payment's method name on iPaaS.com is passed to Acumatica as the Payment Method ID, so it must exactly match a Payment Method configured in Acumatica. For example, an iPaaS.com payment with the method WEBCC is recorded against the Acumatica Payment Method WEBCC. When the source system uses other names, change the PaymentMethod mapping to a Lookup Translation (for example, Credit Card to WEBCC).
The iPaaS.com tax is kept on new orders. The shipped IsTaxValid mapping asserts Acumatica's tax override when an order is created, so Acumatica keeps the tax amounts from iPaaS.com instead of calculating its own; on updates, the existing tax details are updated with the iPaaS.com amounts. To have Acumatica calculate tax itself, change the IsTaxValid mapping to return null; a payment applied to the order must then stay within the order total Acumatica calculates.
Setup Requirements
Acumatica Configuration
The Acumatica Sales Order web services endpoint must be enabled.
Acumatica Credit Terms (screen CS2065PL), Tax Categories with eligible Tax IDs (screen TX2060PL), and the customer tax zone must be configured to match the values used by the order mappings.
Every payment method name used on iPaaS.com payments must be configured as a Payment Method in Acumatica (screen CA2040PL), with a Cash Account, or be translated to one by the PaymentMethod mapping.
Warehouses and boxes referenced by the tracking custom fields must exist.
Hold Shipments on Entry must be deactivated in Acumatica Sales Order Preferences for tracking.
Manual sales order numbering must be enabled to honor the iPaaS.com order number.
iPaaS.com Configuration
The iPaaS.com Product mapping collection must be active so order lines can resolve their SKUs to Acumatica Stock Items.
The transaction must carry the BoxId and WarehouseId custom fields for tracking to transfer.
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
This collection performs several dependency transfers and de-duplication steps automatically. Subscribers do not pre-synchronize these dependencies — the integration handles them as part of the order transfer, and a failed prerequisite blocks the order.
Automatic Customer transfer. If the order has no Company, and its Customer has no Acumatica link and its email matches no Acumatica account and no single Acumatica contact, the integration transfers the Customer into Acumatica first, then writes the order. A failed Customer transfer blocks the order. Nothing is created when the order resolves to an account another way. An order whose contact has no customer account stops with ACUM-BIZL-1010, and an order with a Company that is not linked to Acumatica, which nothing else resolves, stops with ACUM-BIZL-1011 (no Acumatica customer is created for an order with a Company).
Order and line de-duplication. When the Sales Order Duplicate Checking subscription setting is set to true and the transaction is not yet linked to an Acumatica order, the integration looks for an Acumatica order whose OrderNbr equals the iPaaS.com TransactionNumber and links to it instead of creating a duplicate. Lines that are not yet linked are then matched to that order's lines by SKU (and, when several lines share a SKU, by ordered quantity), and the external-id links are recorded so later transfers resolve to the same order and lines.
Tax de-duplication. On updates, each tax is found by its link (the Acumatica RecordID and row id of the tax row), so repeated transfers update the same tax records rather than duplicating them. A tax added to the iPaaS.com transaction after the order was created is not written to the order.
Tracking de-duplication. Tracking numbers written with the order are matched by tracking number so the same shipment is not duplicated on re-transfer.
Integration Flow
A transaction/created or transaction/updated trigger subscribed under Outbound Data Flows starts a transfer, or a subscriber runs a Manual Sync with the iPaaS.com Transaction ID.
A transaction already linked to an Acumatica order updates that order. For a transaction not yet linked, when Sales Order Duplicate Checking is set to true, the integration looks for an Acumatica order whose OrderNbr equals the iPaaS.com TransactionNumber, links it, and matches its lines by SKU (and, when several lines share a SKU, by ordered quantity).
The integration resolves the Acumatica customer account for the order from the order's iPaaS.com Company, then its Customer (a Customer that came from an Acumatica contact goes on that contact's business account), then its email address. Only when the order has no Company and nothing else resolves it is the order's Customer transferred to Acumatica first.
The order and its child records — addresses, lines, payments, taxes, and tracking — are written to Acumatica as one document. An order must contain at least one valid line item; an order with no lines is rejected.
The integration reads the created order back from Acumatica and links the Acumatica-assigned identifiers to the corresponding iPaaS.com records.
Mappings
Add/Update Acumatica Sales Order FROM iPaaS.com
Mapping Filter
Type == "Order"
Filter Description. This filter restricts the collection to iPaaS.com transactions whose Type is Order, so that only sales orders are processed. Transactions of any other type are skipped by this collection.
Description: Creates or updates the Acumatica Sales Order document — customer, financial terms, tax zone, totals, and freight.
Mapping Type | Source Field (iPaaS.com) | Destination Field (Acumatica) | Description |
Dynamic Formula |
| ActionType | Required. Passes the transaction type through to the document path. The order is only written when the action type resolves to Order; the mapping filter already restricts the collection to order-type transactions. |
Dynamic Formula | See the formula below the table. | CustomerId | Required. Resolves the Acumatica customer account: the order's Company, then its Customer (a Customer that came from an Acumatica contact goes on that contact's business account), then the account email, then the email of a single Acumatica contact. An order that cannot be resolved to an account is rejected. |
Dynamic Formula | See the formula below the table. | ContactID | Optional. The Acumatica contact who placed the order: the contact a Customer came from, or the contact found by the order's email. It must be a contact of the order's customer account; when empty, Acumatica uses the account's default contact. |
Static |
| FinancialTerms | Required. Assigns the Acumatica credit terms code. Use a term defined with a single installment type. See the placeholder note below the table. |
Field | TransactionNumber | OrderNbr | Recommended. The external order number. Acumatica honors this value only when manual sales order numbering is enabled; otherwise Acumatica auto-assigns the order number and this value is ignored. With Sales Order Duplicate Checking on, an existing Acumatica order whose number equals the iPaaS.com transaction number is linked instead of duplicated; remapping this field changes which orders are found. |
Field | Total | OrderTotal | Recommended for order reconciliation. The total order value. |
Static |
| Hold | Recommended. Written as a fixed |
Dynamic Formula | See the formula below the table. | CustomerTaxZone | Recommended for orders that carry tax. As shipped, returns the first tax zone listed in Acumatica, whatever the order. The tax zone returned must exist in the Acumatica Tax configuration. See the placeholder note below the table. |
Field | ShippingAmount | PremiumFreightValue | Recommended. Carries externally captured shipping onto the order total's Premium Freight Price. Add/Update Acumatica Sales Order TO iPaaS.com reads the shipping amount back as the freight plus the premium freight, so the amount survives a round trip only with this mapping. |
Dynamic Formula |
| Description | Optional. Builds a human-readable order description from the customer's email and the phrase "placed order". |
Dynamic Formula | See the formula below the table. | IsTaxValid | Recommended for orders that carry tax. Returns true for a new order, so Acumatica keeps the iPaaS.com tax amounts instead of calculating its own, and null for an order that already exists, so its tax details are updated. Keep the update branch null: when the override is sent on an update, Acumatica removes the order's tax details. |
Placeholder value — replace during implementation: 30D (FinancialTerms) is a template default representing 30 Days. Replace it with a credit terms code that exists in the target Acumatica installation and represents externally imported orders.
Placeholder value — replace during implementation: the CustomerTaxZone formula returns the first tax zone configured in Acumatica. Replace it with the tax zone for imported orders, for example await GetTaxZoneId("WEBTAX"); for a zone named WEBTAX. The shipped formula:
await GetTaxZoneId(); //return null;
The CustomerId dynamic formula tries the order's Company, then its Customer, then the account email, then the email of a single Acumatica contact. The steps can be reordered or removed, for example to prefer the Customer over the Company:
if (CompanyId != null && CompanyId > 0) {
var account = await GetExternalIdAsync(CompanyId, "Company", SpaceportSystemId);
if (!string.IsNullOrEmpty(account)) return account;
}
var customer = await GetExternalIdAsync(CustomerId, "Customer", SpaceportSystemId);
if (!string.IsNullOrEmpty(customer)) {
if (customer.EndsWith("|contact"))
return await GetContactBusinessAccountAsync(customer.Replace("|contact", ""));
return customer;
}
var byAccountEmail = await GetCustomerIdByEmail(EmailAddress);
if (!string.IsNullOrEmpty(byAccountEmail)) return byAccountEmail;
var contactId = await GetContactIdByEmailAsync(EmailAddress);
if (!string.IsNullOrEmpty(contactId)) return await GetContactBusinessAccountAsync(contactId);
return null;The ContactID dynamic formula sends the contact a Customer came from, or, for an order with only an email, the contact with that email:
var customer = await GetExternalIdAsync(CustomerId, "Customer", SpaceportSystemId);
if (!string.IsNullOrEmpty(customer) && customer.EndsWith("|contact"))
return customer.Replace("|contact", "");
if (string.IsNullOrEmpty(customer) && (CompanyId == null || CompanyId <= 0)
&& string.IsNullOrEmpty(await GetCustomerIdByEmail(EmailAddress)))
return await GetContactIdByEmailAsync(EmailAddress);
return null;The IsTaxValid dynamic formula sends the tax override only for an order that is not yet linked to an Acumatica order. To have Acumatica calculate tax itself, replace it with null:
var orderId = await GetExternalIdAsync(Id, "Transaction", SpaceportSystemId);
if (string.IsNullOrEmpty(orderId))
return true;
return null;Other Acumatica sales order fields. Every other top-level Acumatica sales order field can be added to this collection as a destination field. A field that is not mapped is not sent, so Acumatica keeps its default:
Writable: CustomerOrder (the customer's own order number, for example the web order number), Date, RequestedOn, ShipVia, PaymentMethod, CashAccount, PreferredWarehouseID, DestinationWarehouseID (transfer orders), Project, TaxCalcMode, DisableAutomaticDiscountUpdate, and DisableAutomaticTaxCalculation. ShipVia, PaymentMethod, and CashAccount must exist in Acumatica.
Writable only with an Acumatica feature or setting (otherwise Acumatica ignores the value): CurrencyID, CurrencyRateTypeID, CurrencyRate, ReciprocalRate, and EffectiveDate (multi-currency accounting), ControlTotal (validation of document totals on entry), and PaymentRef (order types that take a payment on the order).
Read-only (set or calculated by Acumatica; a mapping to them has no effect): Status, Approved, CreditHold, WillCall, TaxTotal, VATExemptTotal, VATTaxableTotal, CreatedDate, LastModified, and NoteID.
Add/Update Acumatica Sales Order Line FROM iPaaS.com
Mapping Filter
await CheckProductExistBySku(Sku);
Filter Description. This filter checks whether the line's Sku exists as a Stock Item in Acumatica. The integration looks the SKU up and, if a valid Stock Item is found, allows the line to be written; if the SKU is not found, the line is skipped so that only lines for valid products are added to the order. Keep the iPaaS.com Product mapping collection active so SKUs exist in Acumatica.
Description: Writes each order line item as a child of the order, mapping the iPaaS.com SKU to the Acumatica Stock Item and carrying quantity and prices. At least one valid line is required for the order to post.
Mapping Type | Source Field (iPaaS.com) | Destination Field (Acumatica) | Description |
Field | Sku | InventoryID | Required. The Acumatica Stock Item for the line. The SKU must exist as a Stock Item, and with Sales Order Duplicate Checking on it is the key used to match a line not yet linked against an existing Acumatica order. |
Field | Qty | OrderQty | Required. The ordered quantity. A line needs a positive quantity to be meaningful, and, when several lines of an existing order share a SKU, quantity decides which one a line not yet linked is matched to. |
Dynamic Formula |
| UnitPrice | Recommended. The price of a single unit before discounts. |
Dynamic Formula |
| DiscountedUnitPrice | Recommended. The discounted unit price; the template sources this from the unit price, so it matches the unit price unless the subscriber changes the mapping. |
Dynamic Formula |
| ExtendedPrice | Recommended. The line total (unit price multiplied by quantity). |
Dynamic Formula |
| Amount | Recommended. The line amount, sourced from the extended price. |
Static |
| ManualPrice | Recommended. Written as a fixed |
Add/Update Acumatica Sales Order Address FROM iPaaS.com
This child collection has no mapping filter; every address on the parent order is processed.
Description: Writes the order's billing and shipping addresses and contacts, using the iPaaS.com primary flags to mark the bill-to and ship-to designations.
Mapping Type | Source Field (iPaaS.com) | Destination Field (Acumatica) | Description |
Field | FirstName | FirstName | Recommended. The contact's first name. Acumatica order contacts have no first-name field; it forms the business name when the address has no company, and the Attention line when it has one. |
Field | LastName | LastName | Recommended. The contact's last name. Acumatica order contacts have no last-name field; it forms the business name when the address has no company, and the Attention line when it has one. |
Dynamic Formula | See the formula below the table. | Attention | Optional. The contact's first and last name on the Attention line, when the address has a company; without a company the name is the business name and no Attention is sent. |
Field | Company | BusinessName | Optional. The business name of the bill-to or ship-to contact. An address without a company sends the contact's first and last name instead. Keep it so that a company captured from Acumatica by Add/Update Acumatica Sales Order TO iPaaS.com survives a round trip. |
Field | Address1 | Address1 | Recommended. The primary address line. |
Field | Address2 | Address2 | Optional. The secondary address line. |
Field | City | City | Recommended. The city. |
Field | Region | Region | Recommended. The state, province, or region. |
Dynamic Formula | See the formula below the table. | Country | Optional. The two-letter country ID Acumatica expects: US for US, USA, U.S.A or United States, and any other two-letter code as given (for example CA). Any other value, or no country, is not sent, and the order address keeps the country Acumatica already holds for it. |
Field | IsPrimaryBilling | IsBillToAddress | Recommended. Selects which address fills the bill-to role on the order. |
Field | IsPrimaryShipping | IsShipToAddress | Recommended. Selects which address fills the ship-to role on the order. |
Field | IsPrimaryShipping | IsShipToContact | Optional. Treats the shipping address as the ship-to contact. |
Field | IsPrimaryBilling | IsBillToContact | Optional. Treats the primary billing address as the bill-to contact, as IsShipToContact does for the shipping address. Without it, a write from iPaaS.com turns the bill-to contact override off and an order edited in iPaaS.com loses the bill-to contact set in Acumatica. |
Dynamic Formula |
| Optional. Pulls the email from the parent order so the order address carries the customer's email. The value comes from the parent order, not the address record. | |
Dynamic Formula | See the formula below the table. | ZipCode | Optional. Sends the postal code, trimmed, when it is present; a missing code is not sent, and the order address keeps the postal code Acumatica already holds (on a new order, the postal code of the customer's address). Acumatica checks it against the address's country and rejects the order when it is malformed. |
The Attention dynamic formula sends the contact's first and last name only when the address has a company:
if (string.IsNullOrWhiteSpace(Company))
return null;
var first = FirstName == null ? "" : FirstName.Trim();
var last = LastName == null ? "" : LastName.Trim();
var name = (first + " " + last).Trim();
return name == "" ? null : name;The Country dynamic formula sends Acumatica's two-letter country ID; subscribers whose orders carry other country names should extend it to translate them to two-letter codes:
if (string.IsNullOrWhiteSpace(Country))
return null;
var c = Country.Trim().ToUpperInvariant().Replace(".", "");
if (c == "USA" || c == "UNITED STATES" || c == "UNITED STATES OF AMERICA")
return "US";
return c.Length == 2 ? c : null;The ZipCode dynamic formula sends the postal code, trimmed, when it is present:
var zip = PostalCode == null ? "" : PostalCode.Trim(); return zip == "" ? null : zip;
When the order carries a single address, that address is used for both bill-to and ship-to; with multiple addresses, the bill-to and ship-to flags select which address fills each role. If no address is flagged for a role, the integration uses the first address on the order. The selected address is written as an override of the order's address whenever it has a first address line, so it replaces the customer's default address on the order. The contact is overridden only when the address flagged as that contact carries contact data (a company, a first or last name, an email, an attention line, or a phone); otherwise Acumatica keeps the customer's contact rather than blanking it. The contact's business name is the address's company (the BusinessName mapping); an address without a company uses its first and last name instead, leaving out a blank one.
Add/Update Acumatica Sales Order Payment FROM iPaaS.com
This child collection has no mapping filter; every payment on the parent order is processed.
Description: Records externally captured payments against the order — amount, applied amount, payment method, and a generated reference.
Mapping Type | Source Field (iPaaS.com) | Destination Field (Acumatica) | Description |
Field | Amount | PaymentAmount | Recommended. The payment amount. |
Field | Amount | AppliedToOrder | Recommended. Records how much of the payment is applied against this order. |
Dynamic Formula |
| PaymentMethod | Required. The iPaaS.com payment's method name, passed to Acumatica as the Payment Method ID, with the example name Test Gateway translated to WEBCC. See the placeholder note below the table. It must exactly match a Payment Method configured in Acumatica (screen CA2040PL) that has a Cash Account, for example WEBCC. Use a Lookup Translation when source names differ. |
Dynamic Formula |
| PaymentRef | Recommended. Generates a unique payment reference from the iPaaS.com payment identifier so each payment is traceable to its source transaction. Many Acumatica payment methods require a reference. |
Placeholder value — replace during implementation: Test Gateway and WEBCC in the PaymentMethod formula are examples. Replace them with the subscriber's own names, for example Method == "Credit Card" ? "CREDITCARD" : Method for payments arriving as Credit Card and an Acumatica Payment Method CREDITCARD.
Payment method names: apart from the example translation, the payment method name on each iPaaS.com payment is written to Acumatica as-is. When the source system's names differ from the Acumatica Payment Method IDs (for example, Credit Card or PayPal), change the PaymentMethod mapping to a Lookup Translation that converts each name to its Acumatica ID. Transfer of Acumatica payment methods into iPaaS.com is not supported, so methods must be configured in Acumatica (screen CA2040PL).
Warning when payments exceed the order total: When the payments applied to the order add up to more than the order total sent to Acumatica (lines, tax, and premium freight), a warning that names both totals is written to the integration log before Acumatica rejects the order with "The applied amount cannot exceed the unbilled balance." A shipping amount missing from the iPaaS.com transaction's ShippingAmount is the usual cause.
Add/Update Acumatica Sales Order Tax FROM iPaaS.com
This child collection has no mapping filter; every tax detail on the parent order is processed.
Description: Records externally collected tax against an eligible Acumatica tax code — tax amount, tax rate, and the resolved tax code.
Mapping Type | Source Field (iPaaS.com) | Destination Field (Acumatica) | Description |
Dynamic Formula |
| TaxID | Required. Sets the Acumatica tax code; as shipped, it returns the first tax code listed in Acumatica, whatever the iPaaS.com tax. To record externally collected tax, a tax code must be provided, and it must be eligible for the tax category assigned to the order's products. Configure Tax Categories and their eligible Tax IDs in Acumatica (screen TX2060PL). See the placeholder note below the table. |
Field | Amount | TaxAmount | Recommended. The tax collected on the order. Acumatica keeps it as sent on a new order because of the parent order's IsTaxValid mapping. |
Field | TaxPercent | TaxRate | Recommended. The tax rate. |
Dynamic Formula |
| Spaceport_SystemId | Supplied automatically. The subscription identifier the integration uses internally to resolve and link the tax record. This is not a subscriber-tunable field; keep the mapping as shipped. |
Placeholder value — replace during implementation: the TaxID formula returns the first tax code configured in Acumatica. Replace it with the tax code for imported tax, for example await GetTaxId("WEBTAX"); for a tax code named WEBTAX. The code must belong to the order's tax zone and be eligible for the tax category of the order's products.
Add/Update Acumatica Sales Order Tracking Number FROM iPaaS.com
Mapping Filter
var boxId = GetCustomFieldValue(CustomFields, "BoxId");
var warehouseId = GetCustomFieldValue(CustomFields, "WarehouseId");
if(boxId!= null && boxId!="" && warehouseId!= null && warehouseId!=""){
return true;
}
return false;Filter Description. This filter checks whether both the BoxId and WarehouseId custom fields have values. The tracking flow is written only when both are present; if either is empty, the tracking number is skipped. Both values are needed because the warehouse identifies the shipment location and the box is required to create the package.
Description: Creates a Sales Order shipment in Acumatica for the order, recording the package's box, tracking number, carrier, declared value, and description, and linking package contents to the order line for partial shipments.
Mapping Type | Source Field (iPaaS.com) | Destination Field (Acumatica) | Description |
Field | WarehouseId (custom field) | WarehouseId | Required. The shipment location, supplied through a custom field. The filter blocks the tracking flow when it is empty. The warehouse value must exist as a configured Warehouse in Acumatica. |
Field | BoxId (custom field) | BoxID_Package | Required. The package box, supplied through a custom field. The filter blocks the tracking flow when it is empty, and the box is required to create the package. The box value must exist as a configured Box in Acumatica. |
Field | iPaaS_LineItemId (custom field) | iPaaS_LineItemId | Required for creating package contents. Links the package contents to the order line so partial shipments are recorded against the correct line. The value must be in the form TransactionId, then a separator, then TransactionLineId (see the note below the table). |
Dynamic Formula | See the formula below the table. | CustomerID | Required. Resolves the shipment's Acumatica customer account from the parent order, the same way as the order's CustomerId: the order's Company, then its Customer (a Customer that came from an Acumatica contact uses that contact's business account), then the account email, then the email of a single Acumatica contact. When it returns nothing, Acumatica uses the order's customer. |
Dynamic Formula |
| OrderNbr | Required. Carries the order number from the parent transaction so the shipment is created against the correct order. |
Static |
| OrderType | Required. Written as a fixed |
Static |
| Operation | Required. Written as a fixed |
Static |
| Status | Required. Written as a fixed |
Field | TrackingNumber | TrackingNbr_Package | Recommended. The carrier tracking number; also the key used to de-duplicate the shipment on re-transfer. |
Field | ShippingMethod | Type_Package | Recommended. The shipping method or carrier. |
Field | Cost | DeclaredValue_Package | Optional. The declared value of the package, used for shipping and insurance. |
Field | ShippingMethodDescription | Description_Package | Optional. The package or shipping-method description. |
Field | Picked (custom field) | Picked | Environment-specific. See the placeholder note below the table. |
Placeholder value — replace during implementation: the Picked mapping sources an environment-specific custom field carried from a prior client configuration; it does not apply generally. Review this mapping and replace or remove it to match the target environment before relying on it, and validate the shipment behavior in a staging environment with this mapping reviewed.
The iPaaS_LineItemId value joins the transaction identifier and the transaction line identifier with a single pipe character, in the form TransactionId then a pipe then TransactionLineId.
The CustomerID dynamic formula:
if (Parent.CompanyId != null && Parent.CompanyId > 0) {
var account = await GetExternalIdAsync(Parent.CompanyId, "Company", SpaceportSystemId);
if (!string.IsNullOrEmpty(account)) return account;
}
var customer = await GetExternalIdAsync(Parent.CustomerId, "Customer", SpaceportSystemId);
if (!string.IsNullOrEmpty(customer)) {
if (customer.EndsWith("|contact"))
return await GetContactBusinessAccountAsync(customer.Replace("|contact", ""));
return customer;
}
var byAccountEmail = await GetCustomerIdByEmail(Parent.EmailAddress);
if (!string.IsNullOrEmpty(byAccountEmail)) return byAccountEmail;
var contactId = await GetContactIdByEmailAsync(Parent.EmailAddress);
if (!string.IsNullOrEmpty(contactId)) return await GetContactBusinessAccountAsync(contactId);
return null;A separate standalone Tracking Number flow handles tracking numbers transferred on their own; this child collection handles tracking that moves with the order.
Error Handling
"No applications can be created for documents with multiple installment credit terms specified": Occurs when adding a payment to an order whose credit term is defined with multiple installments. Resolution: use a credit term defined with a single installment type.
Invalid Customer ID: The order cannot be resolved to an Acumatica customer account, so Acumatica reports "'CustomerID' cannot be empty". Resolution: link the order to a Company or Customer that is linked to Acumatica, or give it an email that belongs to one Acumatica account or contact.
ACUM-BIZL-1010: The order's contact has no business account that is an Acumatica customer. Resolution: assign the contact to a customer account in Acumatica, or link the order to a Company that is linked to one.
ACUM-BIZL-1011: The order is linked to a Company that is not linked to Acumatica, and neither its Customer nor its email resolves an account; no Acumatica customer is created for an order with a Company. Resolution: let the Company's Acumatica account transfer TO iPaaS.com, which links the Company, or link the order to a Customer or a matching email.
Unsupported financial terms: The mapped credit terms code is not configured in Acumatica. Resolution: configure the credit term, or map a code that already exists.
Invalid tax zone or tax code: The customer tax zone or applied tax code is not configured or not eligible for the products' tax category. Resolution: configure Tax Categories and their eligible Tax IDs (screen TX2060PL), and the customer tax zone.
Invalid SKU: A line's SKU is not found as an Acumatica Stock Item. Resolution: verify the product exists in Acumatica before the order transfer; the line is skipped, and if an order's only lines are skipped this way the order cannot post.
Payment method not found: The payment's method name is not a Payment Method ID configured in Acumatica, or that method has no Cash Account, so Acumatica reports "'Payment Method' cannot be empty" or "'Cash Account' cannot be empty". Resolution: add the method in Acumatica with a Cash Account, use a matching method name on iPaaS.com, or translate the name in the PaymentMethod mapping.
If the Acumatica web services endpoint is temporarily unavailable during a transfer, the order write fails and an error appears in Dashboard / Integration Monitoring / Error Logs.
Testing & Validation
Test Scenarios
Transfer a valid order with one or more lines, an address, a payment, and a tax detail, and verify the Acumatica Sales Order is created with all child records.
Transfer an order whose Customer has no Acumatica link and whose email matches nothing, with no Company, and verify the Customer is transferred automatically before the order.
Transfer an order linked only to a Company, an order from a Customer that came from an Acumatica contact, and an order with only a contact's email, and verify each is placed on the right account (with the contact as ContactID for the contact orders) and that no Acumatica customer is created.
Transfer an order with a SKU that does not exist in Acumatica and confirm the line is skipped; confirm an order with only invalid lines is not created.
Run a Manual Sync with the iPaaS.com Transaction ID and confirm the order writes.
With Sales Order Duplicate Checking set to true, transfer a transaction that is not yet linked but whose number matches an existing Acumatica order, and confirm the existing order and its lines are linked and updated rather than duplicated.
Transfer an order with the BoxId and WarehouseId custom fields populated and verify a shipment is created with the tracking package; transfer one with either field empty and confirm the tracking is skipped.
Validation Checklist
The order resolves to an Acumatica customer account through its Company, its Customer, or its email.
Financial terms and tax zone are assigned and valid in Acumatica.
At least one valid line item is present.
The payment method is valid and active.
Each SKU exists as an Acumatica Stock Item.
Manual sales order numbering is enabled if the iPaaS.com order number must be honored.
Additional Notes
Parent order validation must pass before any child collection is written; an error in a child collection may prevent the entire order from being created.
Writes into Acumatica are upserts. An update overwrites each mapped field that has a value. A mapped field with no value is generally not sent, and a field that is not mapped is left untouched, so Acumatica keeps its value; subscribers should validate in a staging environment before relying on a mapping to clear a field.
An Acumatica edit made before the next order poll that follows a write by this collection is not captured by that poll; it is captured into iPaaS.com with the order's next change in Acumatica.
Generating or transferring shipments and invoices for the sales order from iPaaS.com is not supported by this integration. Only the sales order itself, with its addresses, lines, payments, taxes, and tracking, is written.
Non-stock items on order lines are not supported and are not written to the order.
Related Documents
Related Mapping Documentation