Summary
Heartland locations are transferred into iPaaS.com as Location records. A single Add/Update collection handles both creating new iPaaS.com locations and updating those already linked to Heartland, so the same flow covers a location's whole life cycle. Locations represent the stores or sites in Heartland, and transferring them keeps the iPaaS.com location catalog aligned with Heartland.
When a location is transferred, the integration appends the location's address information to the Heartland record so it is available to the mappings. The collection maps the location's name and a status description, and captures the location's contact name and full address as iPaaS.com custom fields drawn from that appended address.
A mapping filter is applied to this collection so that only active Heartland locations are transferred. This is an inbound-only area (Heartland to iPaaS.com). There is no opposite-direction collection that writes locations back to Heartland.
ID Format
Manual Sync ID Format
On the iPaaS.com Manual Sync page, enter the Heartland location ID — for example, 100012.
External ID Format
After a successful transfer, the Heartland location ID is saved as the external-id link between the two systems (for example, 100012). Subsequent transfers update the same iPaaS.com Location record rather than creating a duplicate. Whether an incoming location is created or updated in iPaaS.com is determined by whether it is already linked by an external id, not by which event triggered the transfer.
Deleted Record Support
Deleting a location is not supported in this direction. The integration creates and updates iPaaS.com Location records only — removing a location in Heartland does not delete or deactivate the linked iPaaS.com Location record. Note also that a location that has been made inactive in Heartland is excluded by the mapping filter, which means it simply stops being transferred; the previously created iPaaS.com Location record remains as it was at the last successful transfer. Locations that are no longer in use should be managed directly in iPaaS.com.
Custom Field Support
Two Heartland values are stored on the iPaaS.com Location as custom fields:
Heartland Location Contact Name: the contact name drawn from the location's Heartland address.
Heartland Location Full Address: the full, formatted address of the Heartland location.
Each requires a matching iPaaS.com subscription custom field on the Location collection before its value is stored. If the custom field does not exist, the location still transfers and the remaining fields are written; only the custom value is not retained. Create these custom fields during setup if you intend to use these values.
Beyond these two, this mapping collection can read Heartland location custom field values for use in the transfer. 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. Each iPaaS.com custom field used as a destination must first exist as a subscription custom field on the Location collection, or the value is not stored.
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: Enabled, with a mapping filter applied. See the Mapping Filter under Mappings for the condition that determines which locations transfer.
Trigger Events: Automatic transfers run on a schedule through polling. Heartland's webhook format is not compatible with iPaaS.com instant webhooks, so locations arrive through polling rather than instant push notifications. Polling does not run until the subscription is configured with a polling event and enabled. All eligible locations can also be transferred immediately from the Initialize Data section of the Heartland subscription in iPaaS.com, and individual locations can be transferred at any time from the Manual Sync page.
Duplicate or Conflicting Mappings
No other mapping collection operates on Heartland locations. This is the only Location collection in the integration, and there is no opposing iPaaS.com to Heartland Location collection, so there is no two-direction overwrite concern.
Because a single Add/Update collection serves both new and existing records, there is no separate Add collection that could compete with an Update collection for the same location.
Collision Handling
This integration does not use iPaaS.com collision handling for locations. Whether an incoming location is created or updated is determined solely by whether it is already linked by an external id; there is no collision recovery step to configure.
Supported Child Collections
None. This is a leaf collection with no dependent child collections. The location's address is appended to the Heartland location record and read directly through the mappings, rather than through a separate child address collection.
System Caveats
Heartland Caveats
Heartland requires a Name on every location. Supply it through the Name mapping.
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 locations 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.
A location that has no address in Heartland transfers normally, but the two address-derived custom fields are left empty.
iPaaS.com Caveats
The Name field is required on every iPaaS.com Location record. Without it the location is not created.
Custom values are stored only when a matching subscription custom field exists on the Location collection.
When iPaaS.com updates an existing Location record, the full record is replaced. Any Location field this collection does not map is cleared on each update unless it is preserved. See Unmapped Field Overwrite Risk under Mappings.
Integration-Specific Caveats
The mapping filter excludes inactive Heartland locations. A location that is deactivated in Heartland stops transferring, and its existing iPaaS.com Location record is left in place unchanged rather than being deactivated.
The iPaaS.com Description field is populated by a formula that reports the Heartland active status, so it is a status indicator rather than a free-text description. Text typed into that field in iPaaS.com is replaced on the next transfer.
Location is one of only three areas of this integration that support Initialize Data. Locations, payment methods, and shipping methods can each be transferred in bulk from the Initialize Data section of the Heartland subscription; no other Heartland record type offers a bulk initialization pass.
Setup Requirements
Heartland Configuration
Ensure each location has a Name, which Heartland requires to create the record.
Set the location's Active flag in Heartland for any location you want transferred; inactive locations are excluded by the mapping filter.
Populate the location's address in Heartland if you want the contact name and full address custom fields to hold values.
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 Location Contact Name and Heartland Location Full Address custom fields on the Location collection if you want those Heartland values retained.
Ensure the Name mapping resolves — it is required for the record to be created.
Review the iPaaS.com Location fields your integration relies on and confirm each is either mapped or preserved before running updates, because unmapped fields are cleared on update.
Enable the subscription and configure a polling event so polling can run, or use Initialize Data to transfer all existing locations on demand.
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 locations changed in Heartland since the previous poll.
For each location returned, it retrieves the full Heartland location record and, when the location has an address, appends that address to the record so the address-derived mappings can resolve.
Each record is evaluated against the mapping filter; only active locations continue.
Each remaining record is dispatched to iPaaS.com through the Location collection, where it is created if not yet linked, or updated if the Heartland location ID is already saved as the external id.
Initialize Data:
From the Initialize Data section of the Heartland subscription, the integration requests all locations from Heartland in one pass.
Each location is retrieved with its address and dispatched exactly as in the polling flow, so a subscription can be brought up to date without waiting for the next poll.
Manual Sync:
A Heartland location ID is entered on the iPaaS.com Manual Sync page.
The integration retrieves that single location with its address and dispatches it through the same filter and create-or-update path.
All three paths converge on the same mapping filter and mapping logic, so a location's resulting iPaaS.com record is identical regardless of how the transfer was triggered.
Mappings
Add/Update Heartland Location TO iPaaS.com
Mapping Filter
Active==true
The filter has a single branch. A Heartland location is transferred to iPaaS.com only when its Heartland Active flag is set — that is, when the location is currently active. Any location whose Active flag is not set is excluded and no iPaaS.com Location record is created or updated for it. The filter raises no message of its own; excluded records are simply not processed. This keeps the iPaaS.com location catalog limited to locations that are in use in Heartland.
Description: Creates or updates the iPaaS.com Location record from the Heartland location, matched durably by the Heartland location ID. That ID 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 |
Dynamic Formula |
| Name | Required. Maps the Heartland location's Name to the iPaaS.com Location Name field. iPaaS.com requires a name on every location record, and Heartland requires a name on every location, so this value must resolve for the location to transfer successfully. |
Dynamic Formula |
| Description | Optional. Combines the text "Status is: " with the Heartland location's active status and stores the result in the iPaaS.com Description field, giving a quick, human-readable indicator of whether the location is active in Heartland. |
Dynamic Formula |
| Heartland Location Contact Name (custom field) | Optional. Stores the contact name from the Heartland location's address. When the location has an associated address, the formula returns that address's contact name; when the location has no address, it returns nothing and the custom field is left empty. Requires a custom field of this name on the Location collection in iPaaS.com before the value is stored. |
Dynamic Formula |
| Heartland Location Full Address (custom field) | Optional. Stores the full, formatted address of the Heartland location. When the location has an associated address, the formula returns that address's complete formatted address; when the location has no address, it returns nothing and the custom field is left empty. Requires a custom field of this name on the Location collection in iPaaS.com before the value is stored. |
Unmapped Field Overwrite Risk
When iPaaS.com updates an existing Location record, the full record is replaced. Any iPaaS.com Location field that is not mapped in this collection is overwritten with an empty value each time an inbound transfer runs. The Location fields this collection does not map include Parent, Type, Location Groups, Address, and Relationships; if your integration stores values in these on the iPaaS.com side, they are cleared on update unless you preserve them.
To preserve a value, add a Dynamic Formula mapping whose source is DestinationValue.[FieldName] for each iPaaS.com Location field you need to keep. That reads the current iPaaS.com value and writes it back so it is not cleared. Review the Location fields your integration relies on and confirm each is either mapped or preserved before running updates.
Error Handling
Missing location name: the Name is required in both Heartland and iPaaS.com. When the Name mapping does not resolve, the iPaaS.com Location record is not created and an error is recorded in the iPaaS.com Dashboard error logs. Populate the Name in Heartland and confirm the mapping resolves before retrying.
Location excluded by the filter: a location whose Heartland Active flag is not set does not pass the mapping filter. No iPaaS.com Location record is created or updated and no error is raised — this is expected behavior. Activate the location in Heartland if it should transfer.
Location not found: when a Manual Sync is run for a location 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 location is still present in Heartland.
Custom value not stored: when the Heartland Location Contact Name or Heartland Location Full Address subscription custom field has not been created on the Location collection, the location 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.
Address-derived values empty: when a Heartland location has no address, both address-derived custom fields resolve to nothing and are left empty. The location itself still transfers and no error is raised. Add the address in Heartland and re-transfer to populate them.
Heartland API 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 active location created — create an active location in Heartland with a Name, transfer it, and confirm an iPaaS.com Location record is created with the matching name and linked by the Heartland location ID.
Existing location updated — change the name on a linked Heartland location, transfer it again, and confirm the same iPaaS.com record is updated with no duplicate created.
No duplicate on re-transfer — transfer the same location twice and confirm only one iPaaS.com Location record exists.
Inactive location excluded — set a Heartland location's Active flag off, attempt a transfer, and confirm no iPaaS.com Location record is created or updated for it.
Description reflects status — transfer an active location and confirm the iPaaS.com Description field shows the compiled status value.
Address custom fields populated — with both custom fields created on the Location collection, transfer a location that has a Heartland address and confirm the contact name and full address are stored.
Location without an address — transfer a location that has no Heartland address and confirm the record is still created with both address-derived custom fields left empty.
Custom field absent — remove or omit one of the custom fields, transfer a location, and confirm the record still transfers with the remaining fields written and no error raised for the missing custom value.
Unmapped field preservation — set a value in an unmapped iPaaS.com Location field, add a preservation mapping for it, re-transfer the location, and confirm the value survives the update.
Manual Sync by ID — enter a known Heartland location ID on the Manual Sync page and confirm that specific location transfers.
Initialize Data — run Initialize Data and confirm all eligible Heartland locations are transferred in one pass.
Polling — with the subscription enabled and a polling event configured, create a location in Heartland and confirm it arrives in iPaaS.com on the next polling cycle without manual intervention.
Validation Checklist
The Name is populated in Heartland and resolves through the mapping on every transferred record.
Each transferred location is linked by the Heartland location ID, and re-transfers update rather than duplicate.
Only locations with the Heartland Active flag set appear in iPaaS.com.
The Description field carries the compiled status value.
Both custom fields exist on the Location collection and hold the expected Heartland values when the location has an address, and are empty when it does not.
Every iPaaS.com Location field your integration relies on is either mapped in this collection or preserved by a Dynamic Formula mapping, and is unchanged after an update.
Polling, Initialize Data, and Manual Sync all produce the same resulting record for the same location.
Additional Notes
A single Add/Update collection covers both creation and updates. There is no separate Add or Update collection for locations, so no configuration choice is needed between them.
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 location.
Because locations arrive by polling rather than instant webhooks, allow for the polling interval when validating a change made in Heartland.
Location is one of only three areas of this integration that offer a bulk Initialize Data pass, alongside payment methods and shipping methods. Use it when first configuring a subscription so the iPaaS.com location catalog starts complete.
Related Documents
Setup & Reference