Integrate iPaaS.com with Heartland to enable seamless data synchronization for customers and customer addresses, locations, payment methods, shipping methods, products and product variants with their options and inventory, gift cards and gift card activity, sales orders, tickets, and invoices with their lines, payments, taxes, and tracking numbers.

How to Connect

Prerequisites

Before setting up the Heartland subscription in iPaaS.com, prepare the following in Heartland Retail:

A Heartland Retail account with administrative access: the person completing the connection must be able to review and approve an authorization request on behalf of the account.
The account subdomain: Heartland Retail hosts each account on its own subdomain, and every API request is made against that address. Confirm the correct subdomain for the account you intend to connect with your Heartland administrator before you begin.
A user or role with sufficient permissions: Heartland Retail uses granular role-based permissions, and the integration can only read or write the data its authorized role permits. The authorization screen presented during setup lists the permissions this integration requests, including managing webhooks, managing roles, and reading expired gift card reporting metrics. All requested permissions must be approved for the integration to operate fully.

Heartland Retail's authentication model and permission scopes are documented by the partner at Heartland Retail Developer Documentation.

Configuration Details

Collect these values before opening the subscription in iPaaS.com:

API URL: the base address of your Heartland Retail account, built from your account's own subdomain. Example: https://ipaasdev.retail.heartland.us/
API Key: a Heartland Retail access token, generated from the Heartland Retail dashboard under Account → My Account → API. This is only needed when you are not completing the interactive authorization described under Authentication Methods. Example: a long opaque token string issued by Heartland Retail.

Configure Subscription Settings

Navigate to the Heartland subscription in iPaaS.com and complete the fields below.

Field	Description	Required	Example
Name	A unique name for the Heartland subscription. Used to identify the subscription throughout iPaaS.com.	Yes	Heartland Production
Versions	The iPaaS.com integration version this subscription runs.	Yes	v1.0
Create Default Mappings	When selected, the shipped Heartland mapping collections and their mappings are created with the subscription. Leave selected unless you are deliberately building the mapping set by hand.	No	Selected
Adjust Empty Gift Card For Payment	Controls what happens when a gift card used to pay for an order or ticket has a zero balance at the time of transfer. Enter `true` to have the integration set the gift card's balance to the payment amount before the gift card is transferred, so the payment can be applied. Any other value, or an empty field, leaves zero-balance gift cards untouched. The value is not case sensitive.	No	true
Add On Item Limit	Caps how many add-on (related) products are retrieved for each product and product variant that defines an add-on filter. Enter a positive whole number to retrieve at most that many add-on products per record. Enter `0` to skip add-on product retrieval entirely. Leaving the field unset retrieves all matching add-on products, which can be slow for products with broad add-on filters. Enter only whole numbers — a non-numeric entry prevents add-on retrieval from completing.	No	100
Transaction Poll Search Days	How many days back the scheduled transaction poll looks when it runs for the first time, before a last-poll timestamp has been recorded. If left empty, or set to a value that is not a whole number, the first poll starts from the current date and no history is picked up. Set this if you want existing sales orders, tickets, or invoices brought across on the first run.	No	30
Inventory Poll Search Days	How many days back the scheduled inventory poll looks when it runs for the first time, before a last-poll timestamp has been recorded. If left empty, the integration uses 5 days. A value that is not a whole number results in no history being picked up.	No	15
API Key	A Heartland Retail access token used to authorize API calls. Conditional: leave this empty when you complete the interactive authorization described under Authentication Methods, because the access token obtained there is used in preference to this field. Supply a token here only if you are authorizing with a Heartland-issued API token instead.	Conditional	A Heartland Retail access token
API URL	The base address of your Heartland Retail account.	Yes	https://ipaasdev.retail.heartland.us

If the subscription cannot reach Heartland — for example because the address is wrong or the token has been revoked — the connection attempt fails and the reason Heartland returned is recorded. Review it under Dashboard → Integration Monitoring → Error Logs.

Authentication Methods

Heartland Retail authorizes API access with OAuth 2.0. iPaaS.com sends every request with the access token obtained through that authorization; where no access token has been stored, it falls back to the value in the API Key field. Each connection attempt is verified against Heartland before the subscription is treated as connected.

Follow these steps to authenticate the Heartland subscription:

Enter the Name and API URL in the subscription, then save it and reopen it.
Open the Heartland subscription in iPaaS.com and click the Authenticate icon.
You are redirected to a Heartland Retail permissions page. Review the permissions the integration requests — managing webhooks, managing roles, and reading expired gift card reporting metrics — and click Allow at the bottom of the screen.
Heartland confirms in the browser that authorization is complete.
Refresh the subscription in iPaaS.com. A valid access token is now shown on the subscription.

If the stored access token is later revoked or expires in Heartland Retail, repeat these steps to reauthorize the subscription. Heartland Retail's authorization flow and permission model are documented by the partner at Heartland Retail Developer Documentation.

Initialization Support

Three types of data support initialization and can be transferred in bulk from the Initialize Data section of the Heartland subscription:

Location TO iPaaS.com
Payment Method TO iPaaS.com
Shipping Method TO iPaaS.com

No other Heartland data type supports Initialize Data. Products, product variants, inventory, customers, gift cards, sales orders, tickets, and invoices are not bulk-initialized; they arrive through scheduled polling once the subscription is configured and enabled, or individually from the Manual Sync page.

Throttling

Throttling ensures that Heartland's API is not overwhelmed by excessive API calls, preserving system performance during heavy data transfers.

While the throttling fields are required, the values are pre-populated by the integration settings. For more details, refer to Subscription Configuration – Edit.

Heartland Retail does not publish request rate limits. Stagger large transfers and avoid running multiple bulk operations at the same time, and adjust the throttling values only if you observe Heartland rejecting requests.

Heartland Connections and Settings