Summary
Acumatica Customer records can be written from iPaaS.com using an Add/Update sync method. This mapping transfers the customer profile — identifier, name, email, customer class, and statement settings — into the Acumatica Customer entity, and carries the customer's main, billing, and shipping addresses through a child collection. The transfer is one-directional into Acumatica; capturing customers out of Acumatica is handled by a separate article.
ID Format
Manual Sync ID Format
When manually transferring a customer, supply the iPaaS.com Customer Id. The integration maps it to the Acumatica CustomerID during the write. For example, a customer whose iPaaS.com Id is 10 is entered as 10 on the Manual Sync page.
External ID Format
After a customer is written, the integration reads the resulting Customer back from Acumatica and links each returned address to its iPaaS.com source. The stored external id lets later transfers update the existing Acumatica record and addresses rather than creating duplicates.
Deleted Record Support
Outbound delete is not supported. Removing a customer in iPaaS.com is not propagated as a delete into Acumatica through this collection, and delete mappings are not included in the default templates.
Mapping Collection Status
Status: Enabled
Trigger Events: A transfer is initiated by Outbound Data Flow trigger subscriptions on customer create and update, and can also be run on demand from the Manual Sync page.
Duplicate or Conflicting Mappings
This collection writes Customer records into Acumatica. The following collection operates on the same entity in the opposite direction:
Add/Update Acumatica Customer TO iPaaS.com: Captures Customer records from Acumatica into iPaaS.com.
Before enabling this outbound collection alongside the inbound "To iPaaS.com" customer collection, review and customize your mapping collection filters to prevent circular updates between the two systems, where a write into Acumatica triggers a capture back into iPaaS.com that re-triggers the write.
Collision handling is not supported for the Acumatica Customer entity. Customers are matched by CustomerID; ensure the iPaaS.com Id maps to a stable Acumatica CustomerID so repeated transfers resolve to the same customer.
Supported Child Collections
Parent Collection: Add/Update Acumatica Customer FROM iPaaS.com — creates or updates the Acumatica Customer record itself.
Child Collection: Add/Update Acumatica Customer Address FROM iPaaS.com — writes the customer's main, billing, and shipping addresses into Acumatica as part of the parent transfer. It runs automatically with the parent Customer write and is not invoked independently.
System Caveats
Acumatica Caveats
The CustomerClass and StatementCycleID values must already exist in the subscriber's Acumatica installation. Values that do not exist are rejected.
Acumatica requires an email address on the customer when any send-by-email option (statements, invoices, or dunning letters) is enabled. Configure a primary billing contact with an email when those options are in use.
The Acumatica customer name is limited to 50 characters by default. Longer names are truncated unless the field is extended in Acumatica.
Addresses are stored in three locations on a customer — main contact, billing contact, and shipping contact — and an address can be flagged for only one of these types.
The Country value on an address must be in Acumatica's country format (for example, US for United States of America). Acumatica registers a contact address only when its core fields (line 1, city, state, postal code, country) are present together.
iPaaS.com Caveats
A customer with no addresses is written without contact addresses; the billing, shipping, and main contact slots are populated only from addresses supplied through the child collection.
The iPaaS.com field is named Region but it maps to the Acumatica address State; both represent the state, province, or region of the address.
Dynamic formula field references use the iPaaS.com field names exactly as they appear on the Customer record, and these references are case-sensitive.
Integration-Specific Caveats
Address routing by primary flag. Each child address is placed into Acumatica's main, billing, or shipping contact slot based on whether it is flagged primary contact, primary billing, or primary shipping. Only one address may carry each flag; flagging more than one address for the same type produces unpredictable contact assignment.
Override flags drive address application. The billing and shipping address and contact override flags must be set for Acumatica to accept the supplied contact and address values instead of inheriting them from defaults. The template sets these to true.
Add and update in one collection. As shipped, the template mappings both create and update the Acumatica Customer, treating iPaaS.com as the source of truth for all mapped profile data. Each transfer overwrites the mapped fields with the iPaaS.com values. It is strongly recommended to split these mappings into a separate add-only collection and an update-only collection so that values a subscriber manages directly in Acumatica — such as billing terms or customer class — are not overwritten on each update from iPaaS.com.
Setup Requirements
Acumatica Configuration
The Acumatica Customer web services endpoint must be enabled for writes.
The CustomerClass and StatementCycleID values mapped here must exist in the installation.
Valid country codes must be configured for the country format used on addresses.
A primary billing contact with an email address must be configured when any send-by-email option is enabled on the customer.
iPaaS.com Configuration
The child collection Add/Update Acumatica Customer Address FROM iPaaS.com must be active for addresses to be written with the customer.
Decide before go-live whether to keep the combined add-and-update mappings or split them into separate add-only and update-only collections.
Authentication & Security
The integration authenticates to the Acumatica instance with OAuth 2.0, and every request carries the company header. The full authentication walkthrough is covered in the Acumatica Connections and Settings and Acumatica Installation Instructions articles; this document does not repeat it.
Integration Flow
A customer create or update in iPaaS.com triggers a transfer, or a subscriber runs a Manual Sync with the iPaaS.com Customer Id.
The integration assembles the Acumatica Customer record from the mapped fields — identifier, name, email, customer class, statement settings, and the override flags.
The write is an upsert: a Customer with the supplied CustomerID is created if it does not yet exist and updated if it does. There is no separate create-only path; a "Create" is itself an upsert.
The child addresses are sorted into Acumatica's contact slots by their primary flags — primary contact populates the main contact, primary billing populates the billing contact, and primary shipping populates the shipping contact. The override flags on the parent record tell Acumatica to accept the supplied values rather than inheriting defaults.
After the write, the integration reads the resulting Customer back from Acumatica and links each returned address to its iPaaS.com source so that later transfers update the existing record rather than creating duplicates.
Mappings
Add/Update Acumatica Customer FROM iPaaS.com
This collection has no mapping filter; every customer transfer initiated from iPaaS.com is processed. Subscribers who want to write only a subset of customers can add a mapping filter to restrict which customers are processed.
Description: Creates or updates the Acumatica Customer record itself — identifier, name, email, customer class, statement settings, and the billing/shipping/contact override flags.
Mapping Type | Source Field (iPaaS.com) | Destination Field (Acumatica) | Description |
Field | Id | CustomerID | Required. The key that identifies the Acumatica Customer for both create and update. Map this to a stable iPaaS.com identifier so repeated transfers update the same customer rather than creating duplicates. |
Dynamic Formula |
| CustomerName | Recommended. Builds the customer name by joining the iPaaS.com first and last name with a single space. A customer with no name is created but is hard to identify. Acumatica limits the name to 50 characters by default; longer combined names are truncated unless the field is extended. |
Field | EmailAddress | Recommended, and effectively required whenever any send-by-email option is enabled on the customer, since Acumatica rejects the write if those options are on without an email present. | |
Static |
| CustomerClass | Recommended. Assigns the Customer Class, which drives default GL accounts, terms, and statement behavior. The value must match a Customer Class that exists in the installation. See the placeholder note below the table. |
Static |
| StatementCycleID | Recommended. Assigns the Statement Cycle, which controls when statements are generated. The value must match a Statement Cycle that exists in the installation. See the placeholder note below the table. |
Static |
| SendStatementsbyEmail | Optional. The live mapping ships this as |
Static |
| BillingAddressOverride | Recommended. Applies the billing address supplied through the child collection rather than inheriting it from defaults. The override has no effect unless a billing address is supplied. |
Static |
| BillingContactOverride | Recommended. Applies the billing contact details supplied through the child collection rather than inheriting them. The override has no effect unless a billing contact is supplied. |
Static |
| ShippingAddressOverride | Recommended. Applies the shipping address supplied through the child collection rather than inheriting it from defaults. |
Static |
| ShippingContactOverride | Recommended. Applies the shipping contact details supplied through the child collection rather than inheriting them. |
Placeholder value — replace during implementation: DEFAULT (Customer Class) and EOM (Statement Cycle) are template defaults. Set each to a value that exists in the target Acumatica installation. A value that does not exist is rejected.
Add/Update Acumatica Customer Address FROM iPaaS.com
This child collection has no mapping filter; every address on the parent customer is processed. It runs as part of the parent Customer write and is never invoked standalone.
Description: Writes each iPaaS.com address into one of Acumatica's three contact slots — main, billing, or shipping — based on its primary flags.
Mapping Type | Source Field (iPaaS.com) | Destination Field (Acumatica) | Description |
Field | Address1 | AddressLine1 | Required. Acumatica registers a contact address only when its core fields are present together; without the first line the address is not stored as a complete contact address. |
Field | Address2 | AddressLine2 | Optional. Used for suite, unit, or additional street detail. |
Field | City | City | Required. Part of the minimum address set Acumatica needs to register a contact address. |
Field | Region | State | Required. Part of the minimum address set. The iPaaS.com field is named Region but it represents the state, province, or region, which Acumatica stores as State. |
Field | PostalCode | PostalCode | Required. Part of the minimum address set. |
Static |
| Country | Required. Must be in Acumatica's country format (for example, |
Field | FirstName | FirstName | Recommended. Contact identity on the address, important when the address fills the main or primary contact slot. |
Field | LastName | LastName | Recommended. Contact identity on the address. |
Field | Company | CompanyName | Recommended. The business name on the contact, most relevant for the main contact slot. |
Field | PhoneNumber | Phone1 | Optional. Provides a contact phone on the address slot. |
Field | IsPrimaryBilling | IsPrimaryBilling | Recommended. Set to true to write the address as the Acumatica billing contact. Only one address may be the primary billing address. When the parent customer enables statements by email, this address must carry the email used for statements. |
Field | IsPrimaryShipping | IsPrimaryShipping | Recommended. Set to true to write the address as the Acumatica shipping contact. Only one address may be the primary shipping address. |
Field | Acumatica Primary Contact | IsPrimaryContact | Recommended. Set to true to write the address as the Acumatica main contact. Only one address may be the primary contact. The source is a custom field that must be configured in iPaaS.com for the value to flow. |
Dynamic Formula |
| id | Recommended for update transfers. Resolves the Acumatica address identifier stored from a prior transfer so an update targets the existing address rather than creating a duplicate. Use this mapping only in an update mapping collection when separate add and update collections are used. |
Placeholder value — replace during implementation: US (Country) is a template default. Set it to the country code that matches the addresses being transferred, or convert it to a field mapping when the country varies per record.
Custom field mappings other than Acumatica Primary Contact are not supported on the Customer Address write path; address custom field mappings configured here would not write to Acumatica.
Error Handling
"Email address must be specified if any of the following options is activated: Send Statements by Email, Send Invoices by Email, Send Dunning Letters by Email": Occurs when a send-by-email option is enabled on the customer but no primary billing contact with an email is supplied. Resolution: configure a single address flagged as the primary billing contact and ensure it carries the email used for statements, or disable the send-by-email options.
Missing CustomerID: The write cannot resolve which Acumatica Customer to create or update. Resolution: ensure the iPaaS.com record has a populated Id mapped to CustomerID.
Invalid email format: iPaaS.com rejects a malformed email. Resolution: correct the email to a valid format before transferring.
Customer Class or Statement Cycle not found: A CustomerClass or StatementCycleID value does not exist in the installation. Resolution: configure the value in Acumatica (Customer Classes form AR201000, Statement Cycles screen AR2028PL) or map a value that already exists.
Country not in Acumatica's format: An address country is rejected. Resolution: supply the country code in Acumatica's format or map it from a source field.
If the Acumatica web services endpoint is temporarily unavailable during a transfer, the write fails and an error appears in Dashboard / Integration Monitoring / Error Logs; the customer is retried on the next transfer.
Testing & Validation
Test Scenarios
Transfer a new customer with a primary billing and a primary shipping address and verify the Acumatica Customer is created with the addresses routed to the correct contact slots.
Update an existing customer's name or email in iPaaS.com and verify the change propagates to the Acumatica Customer on the next transfer.
Attempt a transfer with no Id mapped and confirm the write is rejected.
Run a Manual Sync using the iPaaS.com Customer Id and confirm the customer writes successfully.
Transfer a customer with addresses flagged for billing, shipping, and main contact and verify each fills its slot.
Enable Send Statements by Email without a primary billing contact email and confirm the documented email-required error.
Validation Checklist
Id maps to a stable Acumatica CustomerID.
The CustomerName formula produces the expected combined name.
Each address is flagged for exactly one primary type.
The override flags are set so supplied addresses are applied.
CustomerClass and StatementCycleID values exist in Acumatica.
The country is in Acumatica's format.
Additional Notes
The child address collection runs with the parent; it cannot be transferred on its own.
Because all writes are upserts that preserve blank fields, a field left unmapped on an update is not cleared in Acumatica. To clear a value, write an explicit empty value rather than omitting the mapping.