Overview
Heartland customer records may be transferred to iPaaS.com customers through polling or manually entered webhooks. Heartland webhook formats are not compatible with iPaaS.com webhooks to send instant notifications.
Custom Field Support
When transferring customers to iPaaS.com, custom field data can be accessed using a mapping formula that specifies the custom field name. For example, to access the custom field Test Customer Field, use this formula:
await GetValueFromCustomField(Custom, "Test Customer Field");
NOTE: The custom field must be manually created in Heartland before it is visible on the Heartland website. |
Integration Flow
Customer Creation: A new customer record is created in iPaaS with the mapped details.
Customer Resolution: The system finds the corresponding customer in iPaaS 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 data to iPaaS.com for a Heartland customer, such as customer ID 01915630e5db7214ab1ab2dc71608955, it is essential to enter the correct customer ID (e.g., "01915630e5db7214ab1ab2dc71608955") into the iPaaS.com input field on the iPaaS.com manual sync page.
Conflicting Mappings: This mapping applies only to Customer. Ensure no other mappings target the same iPaaS 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.
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 To iPaaS
Mapping Type | Source (Heartland) | Destination (iPaaS.com) | Description |
Field | UUID | CustomerNumber | The Heartland UUID will be added to the iPaaS customer CustomerNumber field. |
Field | Last Name | Last Name | The Heartland last name will be added to the iPaaS customer Last Name field. |
Field | FirstName | FirstName | The Heartland FirstName will be added to the iPaaS customer FirstName field. |
Field | EmailAddress | The Heartland Email will be added to the iPaaS customer “EmailAddress” custom field. | |
Dynamic Formula | "Status is: " + Active | Comment | This dynamic formula will be added to Comment field in iPaaS. |
Field | PhoneNumber | Heartland Phone Number (Custom Field) | The Heartland PhoneNumber will be added to the iPaaS customer “Heartland Phone Number” custom field. |
Field | LoyaltyPointsBalance | Heartland Loyalty Points Balance (Custom Field) | The Heartland LoyaltyPointsBalance will be added to the iPaaS customer “Heartland Loyalty Points Balance” custom field. |
Dynamic Formula |
| Heartland Test Customer Field (Custom Field) | This logic retrieves the value of the "Test Customer Field" from the custom fields using the GetValueFromCustomField method and assigns it to the "Heartland Test Customer Field" custom field in iPaaS for customer. |
Field | LoyaltyPointsTotal | Heartland Loyalty Points Total (Custom Field) | The Heartland LoyaltyPointsTotal will be added to the iPaaS customer Heartland Loyalty Points Total (Custom Field) |
Child Collection: Heartland Customer Address Add To iPaaS
Mapping Type | Source (Heartland) | Destination (iPaaS.com) | Description |
Field | FirstName | FirstName | The Heartland FirstName is added to the “FirstName” field in the iPaaS customer address. |
Field | LastName | LastName | The Heartland LastName is added to the “LastName” field in the iPaaS customer address. |
Field | Company | Company | The Heartland Company is added to the “Company” field in the iPaaS customer address. |
Field | Line1 | Address1 | The Heartland Line1 is added to the “Address1” field in the iPaaS customer address. |
Field | Line2 | Address2 | The Heartland Line2 is added to the “Address2” field in the iPaaS customer address. |
Field | StreetAddress | Address3 | The Heartland StreetAddress is added to the “Address3” field in the iPaaS customer address. |
Field | City | City | The Heartland City is added to the “City” field in the iPaaS customer address. |
Field | State | Region | The Heartland State is added to the “Region” field in the iPaaS customer address. |
Field | Country | Country | The Heartland Country is added to the “ Country” field in the iPaaS customer address. |
Field | PostalCode | PostalCode | The Heartland PostalCode is added to the “PostalCode” field in the iPaaS customer address. |
Field | IsPrimaryBilling | IsPrimaryBilling | The Heartland IsPrimaryBilling is added to the “IsPrimaryBilling” field in the iPaaS customer address. |
Field | IsPrimaryShipping | IsPrimaryShipping | The Heartland IsPrimaryShipping is added to the “IsPrimaryShipping” field in the iPaaS customer address. |
Dynamic Formula |
| PhoneNumber | If the Heartland PhoneNumber exists, it will be used; otherwise, the customer’s phone number will be added to the “PhoneNumber” field in the iPaaS customer address. |
Field | IsDefaultAddress | Heartland Default Address(Custom Field) | The Heartland IsDefaultAddress is added to the “Heartland Default Address” Custom field in the iPaaS customer address. |
Parent Collection: Heartland Customer Update To iPaaS
Mapping Type | Source (Heartland) | Destination (iPaaS.com) | Description |
Field | UUID | CustomerNumber | The Heartland UUID will be added to the iPaaS customer CustomerNumber field. |
Field | Last Name | Last Name | The Heartland last name will be added to the iPaaS customer Last Name field. |
Field | FirstName | FirstName | The Heartland FirstName will be added to the iPaaS customer FirstName field. |
Field | EmailAddress | The Heartland Email will be added to the iPaaS customer “EmailAddress” custom field. | |
Dynamic Formula |
| Comment | This dynamic formula will be added to Comment field in iPaaS. |
Field | PhoneNumber | Heartland Phone Number (Custom Field) | The Heartland PhoneNumber will be added to the iPaaS customer “Heartland Phone Number” custom field. |
Field | LoyaltyPointsBalance | Heartland Loyalty Points Balance (Custom Field) | The Heartland LoyaltyPointsBalance will be added to the iPaaS customer “Heartland Loyalty Points Balance” custom field. |
Dynamic Formula |
| Heartland Test Customer Field (Custom Field) | This logic retrieves the value of the "Test Customer Field" from the custom fields using the GetValueFromCustomField method and assigns it to the "Heartland Test Customer Field" custom field in iPaaS for customer. |
Field | LoyaltyPointsTotal | Heartland Loyalty Points Total (Custom Field) | The Heartland LoyaltyPointsTotal will be added to the iPaaS customer Heartland Loyalty Points Total (Custom Field) |
Child Collection: Heartland Customer Address Update To iPaaS
Mapping Type | Source (Heartland) | Destination (iPaaS.com) | Description |
Field | FirstName | FirstName | The Heartland FirstName is added to the “FirstName” field in the iPaaS customer address. |
Field | LastName | LastName | The Heartland LastName is added to the “LastName” field in the iPaaS customer address. |
Field | Company | Company | The Heartland Company is added to the “Company” field in the iPaaS customer address. |
Field | Line1 | Address1 | The Heartland Line1 is added to the “Address1” field in the iPaaS customer address. |
Field | Line2 | Address2 | The Heartland Line2 is added to the “Address2” field in the iPaaS customer address. |
Field | StreetAddress | Address3 | The Heartland StreetAddress is added to the “Address3” field in the iPaaS customer address. |
Field | City | City | The Heartland City is added to the “City” field in the iPaaS customer address. |
Field | State | Region | The Heartland State is added to the “Region” field in the iPaaS customer address. |
Field | Country | Country | The Heartland Country is added to the “ Country” field in the iPaaS customer address. |
Field | PostalCode | PostalCode | The Heartland PostalCode is added to the “PostalCode” field in the iPaaS customer address. |
Field | IsPrimaryBilling | IsPrimaryBilling | The Heartland IsPrimaryBilling is added to the “IsPrimaryBilling” field in the iPaaS customer address. |
Field | IsPrimaryShipping | IsPrimaryShipping | The Heartland IsPrimaryShipping is added to the “IsPrimaryShipping” field in the iPaaS customer address. |
Field | Phone ?? Parent.PhoneNumber | PhoneNumber | If the Heartland PhoneNumber exists, it will be used; otherwise, the customer’s phone number will be added to the “PhoneNumber” field in the iPaaS customer address. |
Field | IsDefaultAddress | Heartland Default Address(Custom Field) | The Heartland IsDefaultAddress is added to the “Heartland Default Address” Custom field in the iPaaS customer address. |
Error Handling
Duplicate Email Address
Customer already exists in iPaaS.
Description: The workflow rejected the record because an existing customer already has the same email address.
Resolution: Confirm the uniqueness of the email address, or update the existing record rather than creating a new one.
Missing Email Address
Email address is required.
Description: The workflow rejected the record because the email address was missing.
Resolution: Confirm the existence of the email address.
Validation Rules & Testing
Validation Checklist
Customer ID is resolved (via external ID or email).
Field Mapping: Verify Heartland fields map correctly to iPaaS fields (e.g., Uuid → CustomerNumber, FirstName → FirstName, LastName → LastName).
Duplicate Prevention: Check that Uuid is used to prevent duplicate customer creation in iPaaS.
Test Scenarios
New Customer Sync: Create a new customer in Heartland with valid fields, run the workflow, and verify the customer appears in iPaaS with all field values mapped correctly.
Missing Mandatory Field: Sync a customer missing Uuid or Email and verify the workflow logs an error without creating a record.
Dynamic Formula Evaluation: Ensure that formula fields like Comment and Test Customer Field are calculated and populated correctly in iPaaS.
Duplicate Email Address: Sync a customer whose emailaddress already exists in iPaaS and confirm that no exception is thrown.
Additional Notes
This workflow handles both customer and customer address records from Heartland to iPaaS.
Dynamic formulas and parent fallback mechanisms ensure missing child data is supplemented where necessary.