This article lists the Heartland Retail API endpoints that the iPaaS.com Heartland integration calls, grouped by entity. Use it when whitelisting outbound traffic, assessing the impact of a Heartland API change, or troubleshooting a specific transfer.

All endpoint paths, parameters, authentication details, pagination behavior, and rate-limit statements below are taken from Heartland Retail's public API documentation at https://dev.retail.heartland.us/, accessed 20 July 2026. Where a path the integration calls does not appear in that published reference, this article says so rather than asserting behavior that Heartland has not documented.

Heartland Retail issues each account its own subdomain. The Heartland Retail web application and the Heartland Retail API are served from that same account address.

Heartland Retail does not publish separate regional hosts. There is one account address per Heartland Retail account.

The Heartland Retail API is a JSON REST API. Requests and responses use application/json, except for the token request described under Authentication, which is form-encoded.

Heartland Retail documents the API base path as an account-specific subdomain with /api/ appended (Heartland Retail API documentation, accessed 20 July 2026):

On the iPaaS.com Heartland subscription you supply the account address in the API URL setting. The integration appends the /api/... paths listed in this article to that value.

Throughout this article, [Base URL] stands for the account address you entered in API URL.

Heartland Retail does not publish a separate sandbox or test host. A non-production Heartland Retail account has its own subdomain and is reached through the same address pattern, so a test subscription differs only in the API URL value.

The Heartland Retail API is unversioned. There is no version segment in the path and Heartland Retail does not publish a version header.

Used for scheduled polling and for on-demand initialization. Query parameters used: page, per_page, and the change filter ~[updated_at][$gt] described under Pagination and Filtering.

Used to find an existing Heartland customer before creating a new one. Heartland Retail's published reference documents query, page, and per_page as the search parameters on this collection and does not document a bare email equality parameter, so this specific query form is not covered by the published reference.

Documented body fields include first_name, last_name, email, address_id, shipping_address_id, billing_address_id, and custom.

Documented body fields include line_1, city, state, postal_code, country, phone, and custom.

Heartland Retail models a product family as an item grid and each sellable variation as an item. The integration calls both.

Query parameters used: page, per_page, _filter, and the change filter ~[updated_at][$gt].

Sideloaded records are requested with _include[]. The integration requests combinations of _include[]=grid, _include[]=tags, and _include[]=custom_prices.

Heartland Retail documents public_id as an item field but does not document it as a bare query parameter on the item search, so this query form is not covered by the published reference.

Heartland Retail does not document grid_id as a bare query parameter on the item search. The equivalent documented approach is a filter expression, described under Pagination and Filtering.

Documented body fields include cost, price, financial_class_id, import_batch_id, and primary_vendor_id.

Query parameters used: page, per_page, and the change filter ~[updated_at][$gt].

Sideloaded with _include[]=tags and _include[]=custom_prices.

As with the item search, Heartland Retail does not document public_id as a bare query parameter on this collection.

Documented body fields include item_cost, item_price, item_original_price, item_financial_class_id, and item_primary_vendor_id.

This path does not appear in Heartland Retail's published API reference. Its behavior cannot be confirmed from the public documentation.

Query parameters used: item_id to scope the result to one item, location_id to scope it to one location, and group[] to group the returned quantities. The integration groups by location_id and item_id.

Used for scheduled polling with page, per_page, and the change filter ~[updated_at][$gt]. This path does not appear in Heartland Retail's published API reference.

Documented body fields: adjustment_reason_id and location_id.

Used to move an adjustment set to its completed state after its lines have been added.

Documented body fields: adjustment_set_id, item_id, qty, and unit_cost.

Used to resolve the adjustment reason required when creating an adjustment set. Heartland Retail's published reference documents an adjustment reason identifier on the adjustment set body but does not document an endpoint for listing inventory adjustment reasons, so neither this path nor the active parameter is covered by the published reference.

Query parameters used: page, per_page, and the change filter ~[updated_at][$gt].

Heartland Retail's published reference documents the location search but does not document retrieval of a single location by identifier.

This path does not appear in Heartland Retail's published API reference.

Heartland Retail calls these payment types.

Query parameters used: page, per_page, and the change filter ~[updated_at][$gt].

Documented fields include public_id, name, kind, description, payment_account_id, deposit_account_id, expiration_account_id, and max_refund_amount.

Query parameters used: page, per_page, and the change filter ~[updated_at][$gt].

Documented body fields: name, amount, and income_account_id.

Query parameters used: page, per_page, and the change filter ~[updated_at][$gt].

Heartland Retail documents this path as retrieval by gift card number, not by an internal identifier.

Documented body field: number.

Heartland Retail's published reference documents creation and retrieval of gift cards but does not document an update operation on this path.

The integration scopes this search to one gift card with the bracket filter ~[gift_card_id]. Heartland Retail notes that this search always returns HTTP 403 when gift cards are processed externally rather than in Heartland Retail.

Note the singular gift_card segment on adjustments against the plural gift_cards on gift cards themselves. Both are as Heartland Retail publishes them.

Documented body fields: gift_card_id, reason_id, and delta_balance.

Heartland Retail keeps three separate sales documents: orders, tickets, and invoices. The integration calls the same shapes against each, so the paths below are shown once with {SalesDocument} standing for orders, tickets, or invoices.

Query parameters used: page, per_page, and the change filter ~[updated_at][$gt].

Sideloaded records are requested with _include[]. The integration requests combinations of _include[]=payments, _include[]=taxes, _include[]=customer, _include[]=notes, _include[]=shipment, _include[]=shipping_address, _include[]=billing_address, and _include[]=order_shipping_method_name, depending on the document type.

Heartland Retail also uses this operation for changes that have no dedicated sub-resource, including setting the shipping method and shipping charge on an order, and voiding a sales document by setting its status to void. Heartland Retail does not document a DELETE operation on sales documents.

On orders the integration requests _include[]=discounts to return line-level discount detail alongside each line.

Heartland Retail documents line creation on orders and invoices at this path. On tickets, the published reference documents line creation at an item_lines sub-resource while lines are read from lines, so the ticket create path used here is not covered by the published reference.

Heartland Retail documents adding a payment but does not document updating or retrieving an individual payment at these paths.

Sales document notes are reachable as sideloaded data through _include[]=notes on the order retrieval above, but a notes sub-resource does not appear in Heartland Retail's published API reference.

Used to record tracking information against an invoice. Heartland Retail publishes a shipments sub-resource on inventory transfers but not on invoices, so this path is not covered by the published reference.

Used to resolve the tax detail applied to a transferred sales document. Documented tax rule fields include jurisdiction_id, liability_account_id, minimum_price, maximum_price, and the customer_filter and item_filter expressions, which use the same filter operator language described under Pagination and Filtering.

Heartland Retail documents the vendor search but does not document a bare name equality parameter on it.

Query parameters used: page and per_page.

Heartland Retail does not document a bare key equality parameter on this collection.

Documented body fields: group_id, name, validation_type (text or list), and validation_options.

Returns the account-specific host for the authorized account. iPaaS.com calls this endpoint on the shared Heartland Retail host to confirm that the stored credential is valid before treating the subscription as connected.

Heartland Retail authorizes API requests with a bearer token presented in the Authorization request header (Heartland Retail API documentation, accessed 20 July 2026):

Heartland Retail documents two ways to obtain that token.

Where an OAuth 2.0 access token has been obtained and stored on the subscription, the integration presents that token. Where none has been stored, it presents the value of the API Key setting. Either way the header format is identical.

Heartland Retail does not publish a token lifetime, an expiry field, or a refresh token grant for the API. Plan for a token to remain valid until it is revoked or regenerated in Heartland Retail, and update the API Key setting whenever you generate a new token.

Both OAuth 2.0 steps are served from the shared Heartland Retail host, not from your account subdomain.

Authorization request:

Documented parameters: client_id, scope, and redirect_uri (all required), plus an optional state value for cross-site request forgery protection.

Token request:

Documented parameters: client_id, client_secret, code, grant_type, and redirect_uri, all required. The only grant type Heartland Retail documents is authorization_code. The response carries access_token and token_type.

Heartland Retail paginates every search endpoint with two query parameters (Heartland Retail API documentation, accessed 20 July 2026):

The response envelope on a search endpoint carries three keys:

The integration walks the pages of a search until the last page is reached. For most polling and initialization searches it requests 100 records per page.

Heartland Retail does not publish a maximum or default value for per_page, and it does not document any pagination response headers. If you are validating a change against a large Heartland Retail catalog, confirm the page size behaves as you expect in a staging account before relying on it in production.

Heartland Retail supports two equivalent filter parameter names, _filter and the shorthand ~, in two forms.

Documented comparison operators are $eq, $neq, $in, $nin, $gt, $gte, $lt, $lte, and $like. Documented logical operators are $and and $or, which Heartland Retail states can be nested arbitrarily. The $like operator treats * as a wildcard, is case-insensitive, and behaves as $eq when no wildcard is supplied.

The integration uses the bracket form ~[updated_at][$gt] with the last successful poll timestamp to request only records changed since the previous run, and uses the JSON form for the compound filters on the item searches.

Heartland Retail also documents:

Heartland Retail does not document any sort or ordering parameter.

Heartland Retail does not publish any API rate limit. Its documentation states no request quota, no time window, no rate-limit response headers, and no documented HTTP 429 behavior, and it gives no general throughput guidance either (Heartland Retail API documentation, accessed 20 July 2026). No limit is asserted here because none is published.

Because no published ceiling exists, treat throughput as something to establish empirically against your own Heartland Retail account rather than something to read off a specification.

Throughput is governed on the iPaaS.com side by four settings on the Heartland subscription. The Heartland integration does not override the iPaaS.com platform defaults, so the platform-standard values apply until you change them.

For what each field does and where to set it, see Subscription Configuration – Edit.

Because Heartland Retail publishes no limits to design against, raise these values gradually and watch the Dashboard logs after each change rather than starting high. Stagger large transfers, and avoid running several bulk operations against the same Heartland Retail account at the same time.

Setup & Reference