See what the Heartland Retail integration can do →
This article walks through installing and configuring the Heartland integration in iPaaS.com. For a field-by-field reference of every credential and subscription setting, see Heartland Connections and Settings.
Before You Begin
Before installing the Heartland subscription, obtain an API token from Heartland. The token is issued in the Heartland Retail web application and cannot be viewed again after it is generated, so save it before leaving the page.
Log in to your Heartland account.
Click your Name in the upper-right corner and select My Account.
Select the API Tokens tab.
Type a descriptive name for the token.
Click Generate New Token.
Click Copy and save the token in a secure file. You will need the token to complete the integration setup.
You will also need the base URL of your Heartland account. Heartland issues each account its own subdomain, and the same address is used by the integration for both testing and production work; the environment is determined by which Heartland account the subdomain belongs to, not by a separate Heartland host.
With the API token saved and the account address confirmed, you can begin installing the integration.
Installation Instructions for Integration Setup
Go to Subscriptions Management > Subscriptions and click Search Certified Integration Marketplace and Subscribe.
Click the Heartland integration title.
On the Subscription Detail page, click the Subscribe button.
Enter the name of the subscription and select a version. It can be set to any relevant and unique subscription name within the company where this subscription is created.
Format: [Product Name] - [Environment/Purpose]
Example: Heartland - Production
Select Create Default Mappings (recommended).
NOTE: If you do not want to create default mappings and prefer to build all mappings from scratch yourself, clear this checkbox.
Enter the API Key. This is the API token you retrieved and saved from Heartland.
Provide the API URL endpoint for your Heartland account. Heartland issues an account-specific subdomain, and the base address always follows the same pattern.
Example: https://ipaasdev.retail.heartland.us
Environment URLs
Test/Sandbox: the address of your non-production Heartland account, in the same format (for example, https://ipaasdev.retail.heartland.us). Heartland does not publish a separate shared sandbox host.
Production: the address of your live Heartland account, in the same format.
Enter the Transaction Poll Search Days. See Operational Configuration below.
Enter the Inventory Poll Search Days. See Operational Configuration below.
Enter the Add On Item Limit. See Additional Configuration Options below.
Under Adjust Empty Gift Card For Payment, select True or False. See Additional Configuration Options below.
Enter the API Throttle Limit. This setting prevents any single integration or user from overwhelming the system with too many requests. It protects system performance by controlling how many API requests are allowed within the throttle window, ensuring fair usage.
Default Value: 500
Recommended Values
Initial Setup: 5, so that the first transfers can be watched closely
Ongoing Operations: 500
High Volume: 500
Enter the API Throttle Seconds. This defines the time window during which the API Throttle Limit is measured. If the integration makes too many requests within this time window, additional requests are held until the window resets.
Default Value: 60 seconds
Enter the number of Concurrent Connections. This specifies the maximum number of simultaneous API connections the Heartland integration can hold open at one time. If this limit is exceeded, new requests are queued until an active connection finishes.
Default Value: 10
Enter the number of Concurrent Batch Executions. This specifies the maximum number of simultaneous batch executions that can be processed for the integration at one time. If this limit is exceeded, new batches are queued until a running batch finishes.
Default Value: 10
Click Apply to save the settings.
NOTE: The Heartland integration does not override the iPaaS.com throttle and concurrency defaults, so the platform-standard values above apply unless you change them. Raise them gradually and watch the Dashboard logs after each change; Heartland does not publish request-rate limits, so the safe approach is to increase throughput in steps rather than starting at a high value.
Authentication Configuration
The Heartland integration authenticates with a bearer access token. Two credentials are involved.
Credential Name | Location | Description | Required |
API Key | Heartland: your Name menu > My Account > API Tokens > Generate New Token | The Heartland API token obtained in Before You Begin. It is presented as the bearer token on every request when no OAuth 2.0 access token has been stored on the subscription. | Yes |
API URL | Heartland: the address of your Heartland account in the browser, in the form https://[your-account].retail.heartland.us | The base address the integration calls for your Heartland account. | Yes |
Important Notes
The API token is shown only once when it is generated. If it is lost, generate a new token in Heartland and update the API Key setting on the subscription.
If the token is revoked or regenerated in Heartland, the subscription cannot connect until the new value is saved. Connection failures raised at that point report the message Heartland returned.
OAuth 2.0 Flow Initialization
Heartland also supports OAuth 2.0. When an OAuth 2.0 access token has been generated on the subscription, the integration uses that token in preference to the API Key. This step is conditional: complete it if your Heartland account is set up to authorize applications through OAuth 2.0. Heartland's developer documentation notes that new OAuth application registrations are not currently being accepted, so accounts without an existing registered application should use the API Key alone.
To initiate the OAuth 2.0 flow and generate an access token:
Go to your Heartland subscription.
Click the Authentication icon found in the top toolbar.
A new browser window opens, requesting permissions for the application.
While logged into Heartland, click Authorize when prompted.
Click Close Page.
Refresh the subscription. The access token value should now be present if the authorization succeeded.
NOTE: The Heartland OAuth 2.0 access token is a permanent access token and does not expire.
Operational Configuration
These two settings control how far back the integration looks when it polls Heartland for changes. Both are entered as a whole number of days.
Transaction Poll Search Days
Description: The number of days of overlap applied when polling Heartland sales orders, tickets, and invoices. Each poll runs from the last recorded poll time minus this number of days, so a larger value re-examines a wider window and catches records whose modification time landed just before the previous run.
Purpose: Guards against transactions being missed at the boundary between polling runs.
Default Value: 0. When the field is blank, zero, or not a whole number, no overlap is applied and each poll starts from the last recorded poll time.
Example: Entering 7 makes each transaction poll reach back seven days further than the last poll time.
Recommended Values
Initial Setup: 7
Ongoing Operations: 1
High Volume: 1
Inventory Poll Search Days
Description: The number of days of look-back applied when polling Heartland product inventory and product variant inventory.
Purpose: Controls how much inventory history each poll re-reads, which matters most on the first poll, when there is no previous poll time recorded.
Default Value: 5. When the field is blank or not a whole number, the integration uses 5 days.
Example: Entering 2 limits each inventory poll to a two-day window; entering 30 re-reads a month of inventory changes on every poll.
Recommended Values
Initial Setup: 5
Ongoing Operations: 5
High Volume: 1, to keep each inventory poll small
NOTE: Both values widen the volume of every poll, not just the first one. Large values on a busy account increase the number of Heartland requests per polling run.
Additional Configuration Options
Add On Item Limit
Purpose: Caps how many related products, also called add-on items, are retrieved and attached to a product or product variant during Heartland-to-iPaaS.com product transfers.
Default Value: No limit. When the setting has never been configured, all matching related items are retrieved.
Range/Format: A whole number. A positive number such as 5 retrieves at most that many related items per product. 0 disables related-item retrieval entirely.
IMPORTANT: Enter a whole number or leave the setting unconfigured. If the field is present but holds an empty or non-numeric value, product and product variant transfers fail when they attempt to read it. If you want no limit, remove the setting rather than saving it with a blank value.
Adjust Empty Gift Card For Payment
Purpose: Determines whether a gift card that has a zero balance in iPaaS.com is adjusted to the payment amount before the payment is processed into Heartland. This applies to transaction flows where a payment references a gift card.
Default Value: False. Any value other than True, including a blank value, leaves the behavior off.
Range/Format: True or False.
Effect: When True, a gift card whose balance is zero has its balance set to the payment amount and is transferred with that amount. When False, the gift card is transferred with its zero balance unchanged.
Post-Installation Verification
After completing the installation, perform these tests to verify the installation.
Connection Test
On the Heartland subscription, confirm that API Key and API URL are saved and click Apply.
The integration validates the credentials against Heartland the first time it connects. If the credentials or the account address are wrong, the subscription reports the failure and the message Heartland returned; a successful validation produces no error.
If a validation error appears, re-check the API token and confirm the API URL matches your Heartland account subdomain exactly.
Data Sync Test
Open the Initialize Data section of the Heartland subscription and initialize Location. All Heartland locations are read and transferred into iPaaS.com as Location records.
Confirm the locations appear in iPaaS.com and that the transfers are logged without errors on the Dashboard.
Repeat for Payment Method and Shipping Method.
Open the Manual Sync page, select the Heartland Shipping Method collection, enter the ID of a known Heartland shipping method, and run the sync. Confirm the matching iPaaS.com Shipping Method record is created or updated.
NOTE: Initialize Data is supported for Location, Payment Method, and Shipping Method only. Selecting any other collection in Initialize Data completes without transferring records. Use Manual Sync or wait for the scheduled polling to move other entities.
Functionality Test
Run one end-to-end business process for an entity you intend to use in production, such as transferring a Heartland sales order into iPaaS.com or creating a Heartland transaction from an iPaaS.com order.
Validate the results against the field mappings, confirming that the expected values landed on the destination record.
Review the transfer logs on the iPaaS.com Dashboard for warnings and errors, and confirm that the external-id link between the two records was created.
Confirm that scheduled polling picks up a subsequent change in Heartland, which verifies the poll search day settings are working as intended.
Support and Troubleshooting
Click the Help button on any iPaaS.com page to contact Support or to search our documentation. Additional resources include:
Documentation: API Introduction and the rest of the iPaaS.com documentation, searchable at the top of this article
Support Portal: https://support.ipaas.com/en/
Contact Information: Contact iPaaS.com
Heartland integration reference: Heartland Connections and Settings
Heartland API reference: Heartland Retail developer documentation
Related Documents
Setup & Reference