Overview
An iPaaS Customer can be transferred to Heartland using an Add and Update sync method. This mapping supports the automated synchronization of Customer records from iPaaS into Heartland.
Integration Flow
Customer Creation: A new customer record is created in Heartland with the mapped details.
Customer Resolution: The system finds the corresponding customer in Heartland using their external ID or email address.
Child Collections Insertion: Related child collections (Address) are inserted to complete the customer record.
Integration Settings
Mapping Status: Enabled.
ID Format: When manually transferring customers from iPaaS.com, you need to enter the valid customer ID (internal ID) into the iPaaS.com input field on the iPaaS.com manual sync page. For example, use: 145146.
Conflicting Mappings: This mapping applies only to Customer. Ensure no other mappings target the same Heartland entity to prevent data from being overwritten.
Authentication & Security
Heartland uses Auth 2.0 authentication to generate an access token, which is then used to authorize all Heartland API requests in transfer operations.
Custom Field Support
When transferring customers from iPaaS.com, custom field data may be set using a mapping to a subscription custom field having the same name:
NOTE: The custom field must be created in Heartland manually, before it is visible on the Heartland website. |
The template mappings split customer transfers into separate Add and Update mapping collections. Alter these mappings as needed to preserve values you do not wish to overwrite.
Support Child Collection
The integration supports the synchronization of the parent Customer and its related child collections:
Customer Address: Maps billing and shipping addresses.
Mappings
Parent Collection: Heartland Customer Add from iPaaS
Mapping Type | Source (iPaaS.com) | Destination (Heartland) | Description |
Field | First Name | First Name | Maps the Customer First Name of IPaaS to Heartland Customer First Name |
Field | Last Name | Last Name | Maps the Customer Last Name of IPaaS to Heartland Customer Last Name |
Field | EmailAddress | Maps the Customer Last Name of IPaaS to Heartland Customer Last Name |
Child Collection: Heartland Customer Address From iPaaS
Mapping Type | Source (iPaaS.com) | Destination (Heartland) | Description |
Dynamic Formula |
| FirstName | Retrieves the FirstName; if it’s not available, it fetches the customer’s FirstName and assigns it to the Customer Address First Name field in Heartland. |
Dynamic Formula |
| LastName | Retrieves the lastName; if it’s not available, it fetches the customer’s last Name and assigns it to the Customer Address LastName field in Heartland. |
Field | Address1 | Line1 | Maps the Customer Address Address1 from iPaaS to the Customer Address Line1 field in Heartland. |
Field | Address2 | Line2 | Maps the Customer Address Address1 from iPaaS to the Customer Address Line1 field in Heartland. |
Field | City | City | Maps the Customer Address City from iPaaS to the Customer Address City field in Heartland. |
Field | Country | Country | Maps the Customer Address Country from iPaaS to the Customer Address Country field in Heartland. |
Field | IsPrimaryShipping | IsPrimaryShipping | Marks as the shipping address. |
Field | IsPrimaryBilling | IsPrimaryBilling | Marks as the billing address. |
Field | Region | State | Maps the Customer Address Region from iPaaS to the Customer Address State field in Heartland. |
Field | PostalCode | PostalCode | Maps the Customer Address PostalCode from iPaaS to the Customer Address PostalCode field in Heartland. |
Parent Collection: Heartland B2B Customer Update from iPaaS
Mapping Type | Source (iPaaS.com) | Destination (Heartland) | Description |
Field | First Name | First Name | Maps the Customer First Name of IPaaS to Heartland Customer First Name. |
Field | Last Name | Last Name | Maps the Customer Last Name of IPaaS to Heartland Customer Last Name. |
Field | EmailAddress | Maps Email to Heartland customer email address. | |
Static | Example values | Test Customer Field (Custom Field) | Static value will be mapped to the Customer Address Test Customer Field (Custom Field) field in Heartland. |
Child Collection: Heartland Customer Address Update From iPaaS
Mapping Type | Source (iPaaS.com) | Destination (Heartland) | Description |
Dynamic Formula |
| FirstName | Retrieves the FirstName; if it’s not available, it fetches the customer’s FirstName and assigns it to the Customer Address First Name field in Heartland. |
Dynamic Formula |
| LastName | Retrieves the lastName; if it’s not available, it fetches the customer’s last Name and assigns it to the Customer Address LastName field in Heartland. |
Field | Address1 | Line1 | Maps the Customer Address Address1 from iPaaS to the Customer Address Line1 field in Heartland. |
Field | Address2 | Line2 | Maps the Customer Address Address1 from iPaaS to the Customer Address Line1 field in Heartland. |
Field | City | City | Maps the Customer Address City from iPaaS to the Customer Address City field in Heartland. |
Field | Country | Country | Maps the Customer Address Country from iPaaS to the Customer Address Country field in Heartland. |
Field | IsPrimaryShipping | IsPrimaryShipping | Marks as the shipping address. |
Field | IsPrimaryBilling | IsPrimaryBilling | Marks as the billing address. |
Field | Region | State | Maps the Customer Address Region from iPaaS to the Customer Address State field in Heartland. |
Field | PostalCode | PostalCode | Maps the Customer Address PostalCode from iPaaS to the Customer Address PostalCode field in Heartland. |
Error Handling
Missing FirstName and LastName
Customer record could not be created in Heartland.
Description: Either firstname or lastname should be mapped to the Heartland fields.
Resolution: Ensure that either FirstName or LastName is available in iPaaS, and that the mapping is correct.
Invalid Email Format
EmailAddress is not valid.
Description: The EmailAddress provided does not meet Heartland format requirements.
Resolution: Validate the email format in the iPaaS before syncing.
Validation & Testing
Validation Rules
Customer ID must be resolvable in Heartland using either the external ID or the email address.
At least one of FirstName or LastName must be populated in iPaaS.
EmailAddress, if provided, must follow Heartland’s valid email format.
Billing and Shipping addresses must be correctly marked using IsPrimaryBilling and IsPrimaryShipping flags.
Validation Checklist
Customer ID is resolved (via external ID or email).
Mandatory Fields: Ensure either FirstName or LastName is populated in iPaaS.
Test Scenarios
New Customer Sync: Create a new customer in iPaaS with valid FirstName, LastName, and EmailAddress, run the workflow, and verify the customer appears in Heartland with accurate field values.
Missing Field Handling: Attempt to sync a customer with missing FirstName, LastName, or EmailAddress, and confirm the workflow logs the appropriate error and does not create a record.
Additional Notes
This workflow handles both customer and customer address records from iPaaS to Heartland.
Static, dynamic, and formula-based mappings are supported.