Summary
Heartland customer records are transferred into iPaaS.com as Customer records, together with the customer's billing and shipping addresses. The transfer carries core identity values (customer number, first name, last name, email address), records the Heartland active status in the iPaaS.com Comment field through a dynamic formula, and stores several Heartland-specific values — phone number, loyalty points balance, and loyalty points total — on the iPaaS.com customer as custom fields.
This area uses four mapping collections: two parent customer collections and one address child collection under each parent.
Add Heartland Customer TO iPaaS.com, with the child collection Add Heartland Customer Address TO iPaaS.com.
Update Heartland Customer TO iPaaS.com, with the child collection Update Heartland Customer Address TO iPaaS.com.
This article covers all four together, because they share one flow and one set of mappings. The section Add and Update: What Differs explains the split and why it matters.
An opposite-direction area also exists (iPaaS.com → Heartland). It is documented separately and is not covered here.
Add and Update: What Differs
Out of the box, the Add and Update collections carry identical mappings — the same nine mappings on each parent, and the same thirteen mappings on each address child. Nothing about the field-by-field behavior changes between them. What differs is which collection fires:
Add Heartland Customer TO iPaaS.com (with its address child) runs when the Heartland customer is not yet linked to an iPaaS.com Customer record. It creates the iPaaS.com customer.
Update Heartland Customer TO iPaaS.com (with its address child) runs when the Heartland customer is already linked to an iPaaS.com Customer record. It updates that existing customer in place.
The decision is made by the integration before the mappings run, based on whether an external-id link exists (and, failing that, whether an iPaaS.com customer with the same email address can be found and linked). It is not based on which event triggered the transfer, and it is not a subscriber setting.
Why the split exists. Because the two paths are separate collections, you can configure them differently — and the reason that matters is DestinationValue preservation. On a create, there is no existing iPaaS.com data to protect. On an update, there is: a TO-iPaaS.com update replaces the full record, so any writable iPaaS.com field this collection does not map is cleared. Adding a preservation mapping to the Add collection would be pointless; adding one to the Update collection is exactly how you keep an unmapped value from being wiped.
Concretely: to keep the iPaaS.com Company value on a customer that Heartland does not supply, open Update Heartland Customer TO iPaaS.com, add a mapping of type Dynamic Formula with the source DestinationValue.Company and the destination Company. At transfer time that formula reads the current iPaaS.com Company value and writes it straight back, so the update does not blank it. Repeat for each field you need to keep, on the Update collection only. The same technique applies to Update Heartland Customer Address TO iPaaS.com for address fields. See Unmapped Field Overwrite Risk for the exact field list.
ID Format
Manual Sync ID Format
On the iPaaS.com Manual Sync page, enter the Heartland customer ID — for example, 101602. That transfers the single customer and its addresses.
The address child collections have no Manual Sync entry of their own. Addresses are transferred only as part of their parent customer.
External ID Format
After a successful transfer, the Heartland customer's unique identifier is saved as the external-id link between the two systems. Subsequent transfers of that customer update the same iPaaS.com Customer record rather than creating a duplicate, and the presence of that link is what routes a transfer to the Update collection instead of the Add collection.
The address child collections do not maintain an external-id link of their own. Each address is associated with the iPaaS.com customer that the parent collection created or updated.
Deleted Record Support
Deleting a customer is not supported in this direction, and neither is deleting a customer address. The integration creates and updates iPaaS.com Customer and address records only. Removing a customer or an address in Heartland does not delete or deactivate the linked iPaaS.com records — they remain in iPaaS.com until they are removed there directly.
Plan for this when Heartland is treated as the source of truth: a customer removed in Heartland simply stops being transferred, and its iPaaS.com record is left as it was at the last successful transfer.
Custom Field Support
Four Heartland values are stored on the iPaaS.com customer and its addresses as custom fields:
Heartland Phone Number: the Heartland customer's phone number.
Heartland Loyalty Points Balance: the customer's current Heartland loyalty points balance.
Heartland Loyalty Points Total: the customer's lifetime Heartland loyalty points total.
Heartland Default Address: on each address, whether it is the address marked as the default in Heartland.
Each requires a matching iPaaS.com subscription custom field of the same name — the first three on the Customer collection, and Heartland Default Address on the Customer Address collection. If the subscription custom field does not exist, the customer or address still transfers and its remaining fields are written; only that custom value is not retained. Create these custom fields during setup if you intend to use these values.
You can also read any Heartland customer custom field. Add a mapping of type Dynamic Formula whose source calls GetValueFromCustomField(Custom, "[Heartland custom field name]") and choose any iPaaS.com destination. At transfer time the integration returns the value of the named Heartland custom field.
A Heartland custom field must be created in Heartland before it becomes visible on the Heartland website and available to mappings.
Mapping Collection Status
Status: All four collections are Enabled.
Trigger Events: Customer create, customer update, and customer polling events, plus the matching create, update, and polling events for customer addresses. Automatic transfers run on a schedule through polling — Heartland's webhook format is not compatible with iPaaS.com instant webhooks, so customers arrive through polling rather than instant push notifications. Polling does not run until the subscription is configured and enabled. Individual customers can be transferred at any time from the Manual Sync page. A customer is also transferred automatically as a prerequisite when a Heartland transaction or a Heartland customer address that references an unlinked customer is transferred.
Duplicate or Conflicting Mappings
The following mapping collections also operate on Heartland customer and customer address data:
Add Heartland Customer TO iPaaS.com and Update Heartland Customer TO iPaaS.com: the same inbound direction, split by whether the customer is already linked. These are complementary rather than competing — exactly one of them handles any given transfer.
Add Heartland Customer Address TO iPaaS.com and Update Heartland Customer Address TO iPaaS.com: the address children of those two parents, and likewise complementary.
Add/Update Heartland Customer FROM iPaaS.com and its address child: the opposite direction, writing customers and addresses to Heartland from iPaaS.com data.
Important: Before running the inbound and outbound directions together, review your mapping collection filters and clearly define which system is the source of truth for customer data. If both directions are active with the default mappings, changes may propagate back and forth between the systems.
If you customize one inbound collection, customize the other to match. Because the Add and Update collections ship with identical mappings, a change applied to only one of them produces different results depending on whether the customer happened to be linked at the time of transfer. The one intended exception is DestinationValue preservation mappings, which belong on the Update collection only.
Collision Handling
This integration does not use iPaaS.com collision handling for customers or customer addresses. Whether an incoming customer is created or updated is determined by the external-id link, with an email-address search as the fallback that establishes that link. There is no collision recovery step to configure.
Supported Child Collections
Each parent collection has exactly one child:
Add Heartland Customer Address TO iPaaS.com: the child of Add Heartland Customer TO iPaaS.com. It attaches the customer's billing and shipping addresses to the iPaaS.com customer that the parent creates.
Update Heartland Customer Address TO iPaaS.com: the child of Update Heartland Customer TO iPaaS.com. It refreshes the addresses on the iPaaS.com customer that the parent updates.
Neither address collection transfers on its own. Neither has its own webhook, polling schedule, or Manual Sync entry. Each runs only as part of its parent customer's transfer, and each address is attached to the iPaaS.com customer that its parent handled.
System Caveats
Heartland Caveats
Heartland requires at least one of First Name or Last Name on a customer to form the customer Name. Supply one or both through the mappings.
A Heartland custom field must be created in Heartland before it is visible on the Heartland website and available to mappings.
Heartland's webhook format is not compatible with iPaaS.com instant webhooks, so customers are picked up by polling rather than pushed instantly. Expect a delay between a change in Heartland and its arrival in iPaaS.com, bounded by the polling schedule.
Addresses come from the Heartland customer record. An address transfers only when it is present on the customer being transferred.
When a Heartland address carries no phone number of its own, the address phone number falls back to the parent customer's phone number.
iPaaS.com Caveats
The EmailAddress field is required on every iPaaS.com Customer record and must be unique across iPaaS.com customers. Without it, the customer is not created and an update is not applied.
The CustomerNumber field is required on every iPaaS.com Customer record.
iPaaS.com requires at least one of FirstName, LastName, or Company on a customer. This collection maps FirstName and LastName; Company is not mapped.
iPaaS.com requires each address to belong to a valid customer. That association is supplied by the parent customer transfer and is not a subscriber mapping — addresses cannot be transferred independently of their parent customer.
No Customer or Customer Address field is flagged as non-updatable in iPaaS.com. Every writable field on both records, including CustomerNumber and EmailAddress, is accepted on update as well as on create. This differs from some other iPaaS.com records, where a field is honored on create and silently ignored on update. The practical consequence is that a change made to any of these values in Heartland does propagate to the linked iPaaS.com record — and equally, that a mapped field arriving empty does clear the iPaaS.com value.
Custom values are stored only when a matching subscription custom field exists — on the Customer collection for the customer custom fields, and on the Customer Address collection for Heartland Default Address.
Integration-Specific Caveats
Updates are a full replace. When iPaaS.com updates an existing Customer or address record, the full record is replaced. Any writable field not mapped in the collection is overwritten with an empty value. See Unmapped Field Overwrite Risk.
Transfers are additive at the record level: an incoming customer never deletes an existing iPaaS.com Customer record.
The email-address fallback that links an unlinked Heartland customer to an existing iPaaS.com customer only runs when the Heartland customer has an email address. A Heartland customer with no email address cannot be matched this way.
The Heartland Test Customer Field mapping ships as a template placeholder. It demonstrates the custom-field formula pattern and is not intended to be left as-is — see its row under Mappings.
Setup Requirements
Heartland Configuration
Ensure each customer has an email address. It is required in iPaaS.com and is also the fallback used to link an unlinked customer to an existing iPaaS.com record.
Ensure each customer has at least a First Name or a Last Name, which Heartland requires to form the Name.
Create any Heartland custom fields you intend to map before configuring the mappings, so they are available for selection.
iPaaS.com Configuration
Create the Heartland Phone Number, Heartland Loyalty Points Balance, and Heartland Loyalty Points Total subscription custom fields on the Customer collection if you want those Heartland values retained.
Create the Heartland Default Address subscription custom field on the Customer Address collection if you want that indicator retained.
Confirm the EmailAddress and CustomerNumber mappings resolve — both are required for the record to be written.
Replace the Heartland Test Customer Field placeholder mapping with a real Heartland custom field name and a real iPaaS.com destination, or remove it.
Add DestinationValue preservation mappings on the Update collections for any iPaaS.com Customer or address field you need to keep. Review Unmapped Field Overwrite Risk before enabling updates.
Enable the subscription so polling can run.
Authentication & Security
Heartland uses OAuth 2.0 to obtain an access token, which authorizes the Heartland API requests made during a transfer. Credentials are configured on the Heartland subscription — see the Heartland Installation Instructions.
Integration Flow
Scheduled polling:
On its polling schedule, the integration requests customer records that have changed in Heartland.
For each customer, the integration checks whether the Heartland customer is already linked to an iPaaS.com customer.
If no link is found and the Heartland customer has an email address, the integration searches iPaaS.com for a customer with that email address. When a match is found, the two records are linked so the transfer becomes an update rather than creating a duplicate. If the Heartland customer has no email address, no search is performed and no link is established.
If a link now exists, the customer is dispatched through Update Heartland Customer TO iPaaS.com and its addresses through Update Heartland Customer Address TO iPaaS.com. If no link exists, it is dispatched through Add Heartland Customer TO iPaaS.com and Add Heartland Customer Address TO iPaaS.com.
The customer's addresses are written as part of the same operation, attached to the iPaaS.com customer handled in the previous step.
Manual Sync:
A Heartland customer ID is entered on the iPaaS.com Manual Sync page.
The integration retrieves that single customer from Heartland and runs the same link check, email fallback, and add-or-update routing described above.
That customer's addresses are transferred with it.
Automatic customer transfer ahead of a transaction:
A Heartland transaction that references a customer is transferred to iPaaS.com.
Before the transaction is processed, the integration checks whether that customer is already linked to an iPaaS.com customer.
If it is not linked, the integration retrieves the full Heartland customer record and transfers it first, through the customer collections and their address children, so the transaction can be associated with a customer record.
Only after the customer transfer succeeds does the transaction transfer continue. If the customer transfer fails, the transaction transfer stops and is not written.
Automatic customer transfer ahead of a customer address:
A Heartland customer address is transferred to iPaaS.com and names a customer.
Before the address is processed, the integration checks whether that customer is already linked to an iPaaS.com customer.
If it is not linked, the integration retrieves the full Heartland customer record and transfers it first, so the address has a customer to attach to.
Only after the customer transfer succeeds does the address transfer continue. If the customer transfer fails, the address transfer stops.
All paths converge on the same mapping logic, so a customer's resulting iPaaS.com record is the same regardless of how the transfer was triggered.
Mappings
Add Heartland Customer TO iPaaS.com
Mapping Filter
This mapping collection does not have a mapping filter applied. All Heartland customer records routed to it are processed without additional filtering conditions.
Description: Creates the iPaaS.com Customer record from a Heartland customer that is not yet linked to iPaaS.com. The Heartland customer's unique identifier is saved as the record's external id and is the durable match key; it is not a configurable mapping row.
Mapping Type | Source Field (Heartland) | Destination Field (iPaaS.com) | Description |
Field | EmailAddress | Required. Stores the Heartland customer's email address in the iPaaS.com EmailAddress field. It must be unique across iPaaS.com customers; without an email address the customer is not created. The email address is also used to match and link an existing iPaaS.com customer when the Heartland record is not yet linked. | |
Field | FirstName | FirstName | Recommended. Stores the Heartland customer's first name in the iPaaS.com FirstName field. iPaaS.com requires at least one of FirstName, LastName, or Company on a customer, and Heartland requires at least one of First Name or Last Name to form the Name; this collection supplies both First and Last Name. |
Field | LastName | LastName | Recommended. Stores the Heartland customer's last name in the iPaaS.com LastName field. See the FirstName row for the name requirement in both systems. |
Field | Uuid | CustomerNumber | Required. Stores the Heartland customer's unique identifier in the iPaaS.com CustomerNumber field. iPaaS.com will not create a customer without a customer number. |
Dynamic Formula |
| Comment | Optional. Combines the text "Status is: " with the customer's Heartland active status and stores the result in the iPaaS.com Comment field, giving a quick, human-readable indicator of the customer's status in Heartland. |
Field | LoyaltyPointsBalance | Heartland Loyalty Points Balance (custom field) | Optional. Stores the customer's current Heartland loyalty points balance. Requires a subscription custom field of this name on the Customer collection before the value is stored. |
Field | PhoneNumber | Heartland Phone Number (custom field) | Optional. Stores the Heartland customer's phone number. Requires a subscription custom field of this name on the Customer collection before the value is stored. This value is also the fallback used by the address child collection when an address has no phone number of its own. |
Dynamic Formula |
| Heartland Test Customer Field (custom field) | Optional. Demonstrates the custom-field formula pattern: it reads a named value from the Heartland customer's custom fields and stores it in an iPaaS.com custom field. This is a placeholder to replace during implementation — substitute "Test Customer Field" with the name of the Heartland custom field you want to read, and point the mapping at the iPaaS.com custom field where the value should be stored. The named Heartland custom field must exist in Heartland, and the destination subscription custom field must exist on the Customer collection. |
Field | LoyaltyPointsTotal | Heartland Loyalty Points Total (custom field) | Optional. Stores the customer's lifetime Heartland loyalty points total. Requires a subscription custom field of this name on the Customer collection before the value is stored. |
Add Heartland Customer Address TO iPaaS.com
Mapping Filter
This mapping collection does not have a mapping filter applied. Every address delivered with the parent customer transfer is processed without additional filtering conditions.
Description: This is the child collection of Add Heartland Customer TO iPaaS.com. It attaches the Heartland customer's billing and shipping addresses to the iPaaS.com customer created by that parent. It does not transfer on its own and has no Manual Sync entry, polling schedule, or external-id link of its own. The association to the iPaaS.com customer is set automatically by the parent transfer and is not a subscriber mapping.
Mapping Type | Source Field (Heartland) | Destination Field (iPaaS.com) | Description |
Field | FirstName | FirstName | Optional. Stores the first name recorded on the Heartland address in the iPaaS.com address FirstName field. This is the name on the address itself, which can differ from the customer's name. |
Field | LastName | LastName | Optional. Stores the last name recorded on the Heartland address in the iPaaS.com address LastName field. This is the name on the address itself, which can differ from the customer's name. |
Field | Line1 | Address1 | Recommended. Stores the first street line of the Heartland address in the iPaaS.com Address1 field, so the address is complete and usable for shipping and billing. |
Field | Line2 | Address2 | Optional. Stores the second street line of the Heartland address (suite, unit, or similar) in the iPaaS.com Address2 field. |
Field | StreetAddress | Address3 | Optional. Stores the additional Heartland StreetAddress line in the iPaaS.com Address3 field. |
Field | City | City | Recommended. Stores the city of the Heartland address in the iPaaS.com City field, so the address is complete. |
Field | State | Region | Recommended. Stores the Heartland State in the iPaaS.com address Region field, so the address is complete. |
Field | Country | Country | Recommended. Stores the country of the Heartland address in the iPaaS.com Country field, so the address is complete. |
Field | PostalCode | PostalCode | Recommended. Stores the postal or ZIP code of the Heartland address in the iPaaS.com PostalCode field, so the address is complete. |
Field | IsPrimaryBilling | IsPrimaryBilling | Optional. Indicates whether this address is the Heartland customer's billing address, setting the IsPrimaryBilling indicator on the iPaaS.com address. |
Field | IsPrimaryShipping | IsPrimaryShipping | Optional. Indicates whether this address is the Heartland customer's shipping address, setting the IsPrimaryShipping indicator on the iPaaS.com address. |
Field | IsDefaultAddress | Heartland Default Address (custom field) | Optional. Records whether this is the address marked as the default in Heartland. Requires a subscription custom field of this name on the Customer Address collection before the value is stored. The default indicator is separate from the billing and shipping indicators. |
Dynamic Formula |
| PhoneNumber | Optional. Sets the iPaaS.com address phone number from the phone number on the Heartland address. When the address has no phone number of its own, the formula falls back to the parent customer's phone number, so the iPaaS.com address still records a contact number where one is available. |
Update Heartland Customer TO iPaaS.com
Mapping Filter
This mapping collection does not have a mapping filter applied. All Heartland customer records routed to it are processed without additional filtering conditions.
Description: Updates the iPaaS.com Customer record for a Heartland customer that is already linked to iPaaS.com. It ships with the same nine mappings as Add Heartland Customer TO iPaaS.com; the two collections differ only in when they fire and in the DestinationValue preservation mappings you may add here. This is the collection where unmapped-field overwrites matter, because it runs against customers that already hold data in iPaaS.com.
Mapping Type | Source Field (Heartland) | Destination Field (iPaaS.com) | Description |
Field | EmailAddress | Required. Stores the Heartland customer's email address in the iPaaS.com EmailAddress field. It must be unique across iPaaS.com customers; without an email address the update is not applied. The email address is also the value used to match and link an existing iPaaS.com customer when the Heartland record is not yet linked. | |
Field | FirstName | FirstName | Recommended. Stores the Heartland customer's first name in the iPaaS.com FirstName field. iPaaS.com requires at least one of FirstName, LastName, or Company on a customer, and Heartland requires at least one of First Name or Last Name to form the Name; this collection supplies both First and Last Name. |
Field | LastName | LastName | Recommended. Stores the Heartland customer's last name in the iPaaS.com LastName field. See the FirstName row for the name requirement in both systems. |
Field | Uuid | CustomerNumber | Required. Stores the Heartland customer's unique identifier in the iPaaS.com CustomerNumber field. iPaaS.com will not update a customer without a customer number. |
Dynamic Formula |
| Comment | Optional. Combines the text "Status is: " with the customer's Heartland active status and stores the result in the iPaaS.com Comment field. On every update the Comment is refreshed to reflect the current Heartland status, replacing whatever the field held before. |
Field | PhoneNumber | Heartland Phone Number (custom field) | Optional. Stores the Heartland customer's phone number. Requires a subscription custom field of this name on the Customer collection before the value is stored. This value is also the fallback used by the address child collection when an address has no phone number of its own. |
Field | LoyaltyPointsBalance | Heartland Loyalty Points Balance (custom field) | Optional. Stores the customer's current Heartland loyalty points balance. Requires a subscription custom field of this name on the Customer collection before the value is stored. Because loyalty balances change with activity, this is one of the values most likely to be refreshed on an update. |
Dynamic Formula |
| Heartland Test Customer Field (custom field) | Optional. Demonstrates the custom-field formula pattern: it reads a named value from the Heartland customer's custom fields and stores it in an iPaaS.com custom field. This is a placeholder to replace during implementation — substitute "Test Customer Field" with the name of the Heartland custom field you want to read, and point the mapping at the iPaaS.com custom field where the value should be stored. The named Heartland custom field must exist in Heartland, and the destination subscription custom field must exist on the Customer collection. |
Field | LoyaltyPointsTotal | Heartland Loyalty Points Total (custom field) | Optional. Stores the customer's lifetime Heartland loyalty points total. Requires a subscription custom field of this name on the Customer collection before the value is stored. |
Update Heartland Customer Address TO iPaaS.com
Mapping Filter
This mapping collection does not have a mapping filter applied. All addresses on a transferred Heartland customer are processed without additional filtering conditions.
Description: This is the child collection of Update Heartland Customer TO iPaaS.com. It refreshes the addresses on the iPaaS.com customer that its parent updates, so the customer's address records stay in step with Heartland. It does not transfer on its own and has no Manual Sync entry, polling schedule, or external-id link of its own. It ships with the same thirteen mappings as Add Heartland Customer Address TO iPaaS.com, and is the collection where address DestinationValue preservation mappings belong.
Mapping Type | Source Field (Heartland) | Destination Field (iPaaS.com) | Description |
Field | FirstName | FirstName | Optional. Stores the first name on the Heartland address in the iPaaS.com address FirstName field. Transfers only when the Heartland address carries a first name. |
Field | LastName | LastName | Optional. Stores the last name on the Heartland address in the iPaaS.com address LastName field. Transfers only when the Heartland address carries a last name. |
Field | Line1 | Address1 | Recommended. Stores the first line of the Heartland address in the iPaaS.com Address1 field. Address1 is a core postal component and should be mapped so the updated iPaaS.com address is complete. |
Field | Line2 | Address2 | Optional. Stores the second line of the Heartland address (suite, unit, or similar) in the iPaaS.com Address2 field. Transfers only when the Heartland address has a second line. |
Field | StreetAddress | Address3 | Optional. Stores the Heartland StreetAddress value in the iPaaS.com Address3 field. Transfers only when the Heartland address supplies this value. |
Field | City | City | Recommended. Stores the Heartland address city in the iPaaS.com City field. City is a core postal component and should be mapped so the updated iPaaS.com address is complete. |
Field | State | Region | Recommended. Stores the Heartland address state in the iPaaS.com Region field. Region is a core postal component and should be mapped so the updated iPaaS.com address is complete. |
Field | Country | Country | Recommended. Stores the Heartland address country in the iPaaS.com Country field. Country is a core postal component and should be mapped so the updated iPaaS.com address is complete. |
Field | PostalCode | PostalCode | Recommended. Stores the Heartland address postal code in the iPaaS.com PostalCode field. PostalCode is a core postal component and should be mapped so the updated iPaaS.com address is complete. |
Field | IsPrimaryBilling | IsPrimaryBilling | Optional. Marks the iPaaS.com address as the primary billing address when it corresponds to the Heartland customer's billing address. |
Field | IsPrimaryShipping | IsPrimaryShipping | Optional. Marks the iPaaS.com address as the primary shipping address when it corresponds to the Heartland customer's shipping address. |
Dynamic Formula |
| PhoneNumber | Optional. Sets the iPaaS.com address phone number to the phone number on the Heartland address when one is present, and otherwise falls back to the parent customer's phone number. This ensures the iPaaS.com address still carries a phone number when the address itself has none. |
Field | IsDefaultAddress | Heartland Default Address (custom field) | Optional. Records whether this is the address marked as the default in Heartland. Requires a subscription custom field of this name on the Customer Address collection before the value is stored. The default indicator is separate from the billing and shipping indicators. |
Unmapped Field Overwrite Risk
When iPaaS.com updates an existing Customer or customer address record, the full record is replaced. Every writable iPaaS.com field that the collection does not map is overwritten with an empty value on each transfer. This is not a partial update, and unmapped fields are not preserved automatically.
Customer. The writable iPaaS.com Customer values are CustomerNumber, FirstName, LastName, EmailAddress, Company, Categories, Comment, Addresses, Relationships, custom fields, and external ids. The customer collections map CustomerNumber, FirstName, LastName, EmailAddress, Comment, the four custom fields, and the addresses (through the address child). The writable Customer fields these collections do not map are:
Company
Categories
Relationships
Customer Address. The writable iPaaS.com address values are FirstName, LastName, Type, Company, PhoneNumber, Name, Address1, Address2, Address3, City, Region, Country, PostalCode, IsPrimaryBilling, IsPrimaryShipping, the customer association, custom fields, and external ids. The address collections map everything except the following, which are not mapped:
Company
Type
Name
If your integration stores values in any of these six fields on the iPaaS.com side — a company name on a customer, a customer category assignment, a customer relationship, or a company, type, or display name on an address — they are cleared every time an inbound update runs, unless you preserve them.
The remedy. On the Update collection (not the Add collection), add a mapping of type Dynamic Formula whose source is DestinationValue.[FieldName] and whose destination is the same field. That formula reads the current iPaaS.com value at transfer time and writes it back, so the update does not blank it. For example:
On Update Heartland Customer TO iPaaS.com, source
DestinationValue.Company→ destination Company.On Update Heartland Customer TO iPaaS.com, source
DestinationValue.Categories→ destination Categories.On Update Heartland Customer Address TO iPaaS.com, source
DestinationValue.Company→ destination Company.On Update Heartland Customer Address TO iPaaS.com, source
DestinationValue.Name→ destination Name.
Add one preservation mapping per field you need to keep. This is precisely why the template splits the customer transfer into separate Add and Update collections — the Add collection has nothing to preserve, so the preservation mappings live on the Update collection where they apply.
Note also that no Customer or Customer Address field is flagged as non-updatable in iPaaS.com. Every mapped field, including CustomerNumber and EmailAddress, is applied on update as well as on create. That means a mapped field that arrives empty from Heartland actively clears the iPaaS.com value — an empty mapped field is just as destructive as an unmapped one. Review the Customer and address fields your integration relies on and confirm each is either reliably populated in Heartland or preserved with a DestinationValue mapping before enabling updates.
Error Handling
Missing email address: the EmailAddress field is required in iPaaS.com. When Heartland does not supply an email address, or the mapping does not resolve, the iPaaS.com Customer record is not created and an update is not applied. Populate the email address in Heartland and confirm the mapping resolves before retrying. A customer with no email address also cannot be matched to an existing iPaaS.com customer, so this failure can lead to duplicates if the record is later given an email and re-transferred.
Duplicate email address: the EmailAddress must be unique across iPaaS.com customers. A Heartland customer whose email address is already held by a different, unlinked iPaaS.com customer will not create a second record. Reconcile the two records in iPaaS.com and re-transfer.
Missing name: iPaaS.com requires at least one of FirstName, LastName, or Company, and Heartland requires at least one of First Name or Last Name to form the Name. When neither name resolves, the record is not written. Ensure either the first name or the last name is populated before syncing.
Missing customer number: the CustomerNumber field is required on every iPaaS.com Customer record. When the Heartland unique identifier does not resolve through the mapping, the record is not written.
Unable to link by email address: when the integration finds an existing iPaaS.com customer with a matching email address but cannot establish the external-id link correctly, the transfer stops with an error reading "Unable to dynamically link to existing BC customer using email address. This may result in duplicate customer records." The wording refers to the iPaaS.com customer. Check for more than one iPaaS.com customer sharing that email address, resolve the duplication in iPaaS.com, and re-transfer.
Customer prerequisite failed during a transaction transfer: when a Heartland transaction references a customer that is not yet linked and that customer cannot be transferred first, the transaction transfer stops with an error stating that the customer could not be created and that this will prevent the transfer of the order. Resolve the underlying customer error — most often a missing email address or name — then re-transfer the transaction.
Customer prerequisite failed during an address transfer: when a Heartland customer address names a customer that is not yet linked and that customer cannot be transferred first, the address transfer stops with an error stating that the customer could not be created and that this will prevent the transfer of the customer address. Resolve the customer error, then re-transfer.
Customer not found: when a Manual Sync is run for a customer ID that does not exist in Heartland, or the record cannot be retrieved, the transfer fails and no iPaaS.com record is created or updated. Confirm the ID is correct and that the customer is still present in Heartland.
Custom value not stored: when a subscription custom field has not been created — on the Customer collection for the customer custom fields, or on the Customer Address collection for Heartland Default Address — the record still transfers and its other fields are written; only that custom value is not retained. Create the custom field and re-transfer to populate it.
Heartland unavailable: if the Heartland API is temporarily unavailable when a transfer is triggered, the transfer fails. The error appears in the iPaaS.com Dashboard error logs, and the record can be retried through a new polling cycle or Manual Sync.
Testing & Validation
Test Scenarios
New customer created — create a customer in Heartland with an email address and a name, transfer it, and confirm an iPaaS.com Customer record is created through Add Heartland Customer TO iPaaS.com and linked by the Heartland unique identifier.
Existing customer updated — change the last name on a linked Heartland customer, transfer it again, and confirm the same iPaaS.com record is updated through Update Heartland Customer TO iPaaS.com with no duplicate created.
Add versus Update routing — confirm that the first transfer of a customer runs through the Add collection and every subsequent transfer of that same customer runs through the Update collection.
Email match links an existing customer — create a customer in iPaaS.com manually, then create a Heartland customer with the same email address and transfer it. Confirm the two are linked and the existing iPaaS.com customer is updated rather than a duplicate being created.
No email, no match — transfer a Heartland customer with no email address and confirm the record is not written and the error is visible in the iPaaS.com Dashboard error logs.
CustomerNumber and EmailAddress update in place — change the Heartland unique identifier source value or the email address on a linked customer, transfer again, and confirm both propagate to the iPaaS.com record. Neither field is ignored on update.
Unmapped Customer field is cleared — set a Company value on a linked iPaaS.com customer, transfer the Heartland customer again, and confirm Company is blanked. This demonstrates the full-replace behavior.
Preservation mapping protects an unmapped field — add a Dynamic Formula mapping with source
DestinationValue.Companyand destination Company on Update Heartland Customer TO iPaaS.com, repeat the previous scenario, and confirm the Company value survives the update.Unmapped address field is cleared and preserved — set a Name value on a linked iPaaS.com address, transfer, and confirm it is blanked; then add source
DestinationValue.Name→ destination Name on Update Heartland Customer Address TO iPaaS.com and confirm it survives.Empty mapped field clears the value — clear the Heartland phone number on a linked customer, transfer again, and confirm the Heartland Phone Number custom field is emptied in iPaaS.com rather than retaining the previous value.
Addresses transfer with the parent — transfer a Heartland customer that has both a billing and a shipping address, and confirm both arrive on the iPaaS.com customer with the correct IsPrimaryBilling and IsPrimaryShipping indicators.
Address phone fallback — transfer a customer whose address has no phone number of its own and confirm the iPaaS.com address receives the parent customer's phone number.
Default address indicator — with the Heartland Default Address custom field created on the Customer Address collection, transfer a customer and confirm the address marked as the default in Heartland carries the indicator.
Child cannot run alone — confirm the address collections have no Manual Sync entry and no independent schedule, and that an address reaches iPaaS.com only when its parent customer transfers.
Customer prerequisite before a transaction — transfer a Heartland transaction that references a customer not yet linked to iPaaS.com, and confirm the customer is created first and the transaction is then associated with it.
Customer prerequisite failure blocks the transaction — transfer a transaction referencing a Heartland customer with no email address, and confirm the transaction does not transfer and the prerequisite error is logged.
Custom fields populated — with all four custom fields created, transfer a customer and confirm the phone number, loyalty balance, loyalty total, and default address indicator are stored.
Custom field absent — remove one custom field, transfer a customer, and confirm the record still transfers with the remaining fields written and no error raised for the missing custom value.
Comment formula — transfer a customer and confirm the iPaaS.com Comment field reads "Status is: " followed by the Heartland active status.
Manual Sync by ID — enter a known Heartland customer ID on the Manual Sync page and confirm that specific customer and its addresses transfer.
Polling — with the subscription enabled, change a customer in Heartland and confirm the change arrives in iPaaS.com on the next polling cycle without manual intervention.
Validation Checklist
Every transferred customer has an email address and at least one of first name or last name, and both resolve through the mappings.
Every transferred customer has a customer number resolving from the Heartland unique identifier.
Each transferred customer is linked by the Heartland unique identifier, and re-transfers update rather than duplicate.
A customer that already exists in iPaaS.com under the same email address is linked and updated, not duplicated.
Addresses arrive with their parent customer and carry the correct billing, shipping, and default indicators.
The address phone number resolves from the address where one is present and from the parent customer where it is not.
All four subscription custom fields exist and hold the expected Heartland values.
The Heartland Test Customer Field placeholder mapping has been replaced with a real Heartland custom field name and destination, or removed.
Every iPaaS.com Customer and address field your integration relies on is either mapped or protected by a DestinationValue preservation mapping on the Update collection — specifically Company, Categories, and Relationships on the customer, and Company, Type, and Name on the address.
The Add and Update collections carry matching mappings apart from the deliberate preservation mappings on the Update collections.
Polling and Manual Sync produce the same resulting record for the same customer.
Additional Notes
Heartland is the source of truth for the fields listed under Mappings. Editing those values directly in iPaaS.com will be overwritten on the next transfer of that customer.
Because customers arrive by polling rather than instant webhooks, allow for the polling interval when validating a change made in Heartland.
The Heartland Test Customer Field mapping is a template demonstration of the custom-field formula pattern. Leaving it as shipped attempts to read a Heartland custom field literally named "Test Customer Field", which most subscriptions will not have.
An earlier version of this documentation listed a Company mapping on the customer address collections. No such mapping exists in the current collections — Company is one of the unmapped writable address fields described under Unmapped Field Overwrite Risk, and it is cleared on update unless preserved.
Custom field values are stored only when the matching subscription custom field already exists. Creating the custom field after a transfer does not backfill the value; re-transfer the customer to populate it.
Related Documents
Setup & Reference
Mapping Documentation