The limitations below are inherent to the current design of the iPaaS.com Heartland integration and to the Heartland Retail API it works with, and they apply to all subscribers at the time this documentation was written. They are deliberate scope and design decisions, or faithful reflections of how Heartland Retail itself behaves, rather than defects.

Heartland Retail's webhook format is not compatible with iPaaS.com instant webhooks. Every automatic inbound transfer therefore runs on a polling schedule rather than being pushed the moment a record changes in Heartland. Outbound transfers are triggered from iPaaS.com when the subscription is enabled. Polling does not run at all until the subscription is configured and enabled.

What this means for you: expect a delay between a change in one system and its appearance in the other, sized by your polling schedule rather than measured in seconds. When you need a specific record moved immediately, use the iPaaS.com Manual Sync page instead of waiting for the next cycle. If near-real-time transfer becomes a requirement for your business, raise it with iPaaS.com Support as a feature request so it can be weighed against Heartland's published webhook capability.

The Initialize Data section of the Heartland subscription can bulk-load exactly three types of data: Location TO iPaaS.com, Payment Method TO iPaaS.com, and 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, and neither are any of the child collections.

What this means for you: plan your go-live around this. Initialize your locations, payment methods, and shipping methods first, then bring the remaining data across either by letting polling run through its look-back window or by transferring individual records from Manual Sync. Historical data that predates your polling window will not appear on its own. For a large back-catalog, coordinate the load with iPaaS.com Support rather than assuming a single bulk action will populate it.

Locations, payment methods, and shipping methods act as lookups for the transactional flows. Inventory is skipped for any Heartland location that is not yet linked to an iPaaS.com location, and payments cannot be resolved when their payment method has not been linked. Inventory for a product or variant that is not yet linked in iPaaS.com is skipped rather than queued for later, and an add-on product is linked only when the product it points to already exists in iPaaS.com.

What this means for you: run the initialization of locations, payment methods, and shipping methods to completion, and transfer your product catalog, before you enable the transaction and inventory flows. Records skipped for a missing lookup are not automatically retried once the lookup arrives — transfer them again from Manual Sync after the reference data is in place. Details on the Initialize Data section are in Heartland Connections and Settings.

Deleting a record in either system does not delete, deactivate, or otherwise mark the linked record in the other. This applies across the whole integration — customers, addresses, products, variants, options, inventory, gift cards, locations, payment methods, shipping methods, sales orders, tickets, invoices, and every transaction child record. The integration creates and updates records only.

What this means for you: treat removal as a manual, per-system task. When a record is retired in one system, retire it in the other yourself, or use a status or flag field that both systems can see instead of relying on deletion. Build any archival or clean-up routine on the assumption that the two systems will drift apart on deletions unless someone reconciles them.

The two directions behave differently, and the inbound direction carries real risk.

What this means for you: before you enable any update flow, list the fields your business relies on and confirm each one is either mapped in the collection or explicitly preserved. To preserve a field, add a mapping of type Dynamic Formula whose source is DestinationValue.[FieldName] for that field — this reads the value currently held in the destination and writes it straight back, so the update does not clear it. The template deliberately separates Add and Update collections so that you can apply these preservation mappings on update without affecting record creation. Every mapping documentation article for the inbound families repeats the affected-field list for that family.

Child collections have no independent transfer path. They carry no schedule, no separate trigger, and no Manual Sync entry of their own; they move only when their parent record is transferred. This covers customer addresses, order and invoice addresses, order and invoice and ticket line items, line discounts, taxes, payments, notes, tracking numbers, product options and option values, product variants, variant options, variant inventory, product inventory, gift card activity, and add-on products.

What this means for you: to move a child record, transfer its parent. If a child record is missing or stale, re-transfer the parent rather than looking for a way to sync the child directly. It also means a child change made in isolation — an edited address, a corrected line quantity — does not travel until the next parent transfer. Where a child cannot be resolved, the parent transfer is the place to look for the error.

When a transfer needs a related record that cannot be found or matched, the whole transfer stops with an error rather than skipping the offending part. The most common causes are a line item SKU with no matching Heartland item, a payment method that cannot be matched, a gift card that does not exist in Heartland, a customer that cannot be created or linked, and an invoice line that is not linked to a Heartland order line. Where a SKU is at fault, the error identifies the transaction number and the SKU.

What this means for you: the errors appear under Dashboard → Integration Monitoring → Error Logs and name the record at fault. Resolve the underlying condition — add the missing item in Heartland, link the payment method, create the gift card — and then retry the record from Manual Sync. Because the failure is all-or-nothing, a single unmatched line will hold up an entire order or ticket, so it is worth confirming your catalog is fully linked before you enable the transaction flows.

If the Heartland Retail API is unavailable or rejects the request when a transfer runs, that transfer fails. Nothing is partially written and nothing is queued for automatic retry. Because child records ride with their parent, a parent transfer that fails for this reason takes its children with it.

What this means for you: the failure is recorded under Dashboard → Integration Monitoring → Error Logs with the reason Heartland returned. Inbound records are picked up again by a later polling cycle; outbound records need to be retried from Manual Sync once Heartland is reachable. Heartland Retail does not publish request rate limits, so stagger large transfers and avoid running several bulk operations at the same time. Adjust the throttling values on the subscription only if you observe Heartland rejecting requests.

Heartland allows only one invoice per order. Partial invoicing — invoicing part of an order, or raising more than one invoice against a single order — is not possible. Updating an existing Heartland invoice from iPaaS.com is also outside the current scope: the outbound flow creates an invoice, and corrections after creation are made in Heartland. Invoicing also requires the referenced Heartland order to be in an open state. In the inbound direction, only invoices whose Heartland status is complete are transferred; invoices that are not yet complete are skipped until they reach that status.

What this means for you: structure orders so that a single invoice is the right outcome, and split shipments into separate orders where partial invoicing would otherwise be needed. Make post-invoice corrections directly in Heartland. If an invoice does not appear in iPaaS.com, check its Heartland status before investigating the transfer itself.

Heartland Retail holds and displays one tracking number on an invoice. When a transfer supplies more than one tracking number, only the last one found is retained.

What this means for you: for shipments split across multiple parcels, decide which single tracking number belongs on the Heartland invoice and map that one, or record the full set somewhere the tracking is not constrained to a single value. Do not rely on Heartland as the source of a complete multi-parcel tracking history.

Gift cards and gift card activity are read from Heartland into iPaaS.com. Writing gift card information from iPaaS.com back to Heartland is outside the current scope, and the outbound gift card collection ships disabled. Separately, the way gift cards behave when used to pay for a Heartland order or ticket — including the balance behavior driven by the Status and Deposit values, and the Adjust Empty Gift Card For Payment subscription setting — is not documented or formally supported by Heartland and is subject to change. The gift card handling in the template mappings is provided as a demonstration. Where a gift card payment references a card that cannot be found in Heartland, or the balance is insufficient, the transfer is prevented.

What this means for you: manage gift card issuance and balance changes in Heartland and treat iPaaS.com as the reporting side. Before you rely on gift card payments in production, validate the exact behavior you need in a staging environment, and re-validate it after any Heartland Retail change, because the partner does not commit to it. If outbound gift card creation matters to your workflow, raise it with iPaaS.com Support as a feature request.

The integration determines an inbound payment's type from the Heartland payment method name, and it recognizes the standard Heartland starter payment method names. A payment method whose name is not one of those recognized names transfers to iPaaS.com as Cash. In the outbound direction, cash payments cannot be applied as order deposits in Heartland, and only payments whose Heartland Payment Type custom field is set to ExternalPayment are handled by the external payment flow.

What this means for you: if you have renamed Heartland's payment methods or added your own, extend the PaymentType mapping to cover them, otherwise they will all land in iPaaS.com as Cash and your payment reporting will be wrong. Where a deposit is required on an order, use a payment type other than cash. Set the Heartland Payment Type custom field deliberately on any payment you intend to route as an external payment.

Inventory polling picks up records changed since the last polling cycle. The first time inventory polling runs, before a last-poll timestamp exists, it searches only the most recent few days of inventory history — five days by default. Inventory that changed before that window is not backfilled by polling. Inventory quantities transferred into iPaaS.com are read-only levels: the inbound flow records what Heartland holds and does not adjust it. Inventory for the hidden "Heartland Retail Online" location, and for any Heartland location not yet linked to an iPaaS.com location, is skipped silently and does not appear as an error.

What this means for you: set the Inventory Poll Search Days subscription setting before you first enable the subscription if you need history brought across, and use it as a temporary widening when older changes need to be recaptured — not as a permanent setting, since a wide window makes every cycle slower. If inventory appears to be missing for a location, first confirm that the Heartland location is linked to an iPaaS.com location rather than assuming a transfer failure. The equivalent setting for transactions is Transaction Poll Search Days; both are described in Heartland Connections and Settings.

Outbound inventory adjustments are calculated as the difference between the iPaaS.com quantity and Heartland's current quantity. When the two already agree, no adjustment is created. Each adjustment created from iPaaS.com contains a single item, and only one variant is adjusted per Heartland inventory adjustment. Looking up the default adjustment reason costs one extra Heartland request per adjustment.

What this means for you: this reconciles iPaaS.com to Heartland rather than applying a delta on top of whatever Heartland holds, so expect no adjustment at all when the quantities already match — that is correct behavior, not a skipped transfer. Because each transferred record produces its own single-item adjustment, a large reconciliation produces a large number of Heartland adjustments; pace it. If adjustment volume is high, map a fixed reason code identifier instead of relying on the default reason lookup to remove the extra request per adjustment.

Heartland Retail derives ticket totals from the ticket's line items. Shipping and tax amounts supplied only as header-level totals are not applied to a ticket — they must be sent as line items to take effect. Heartland may also store order totals to more decimal places than its interface displays, and a payment cannot exceed the order balance.

What this means for you: map shipping and tax as line items on the outbound ticket flows rather than as header totals, which is what the shipped template does. Round tax amounts sent to Heartland to two decimal places so that a payment does not fail against a balance that carries hidden precision. If a payment is rejected for exceeding the balance on an order whose totals look correct on screen, suspect rounding first.

Heartland Retail saves product options and option values globally rather than scoping them to a single product. Option values added by earlier transfers remain in Heartland even after they no longer apply to the product that introduced them. Separately, the shipped product option child collection carries the option structure and its values but defines no field mappings of its own, so it does not populate the option name.

What this means for you: expect the Heartland option value list to accumulate over time and plan to tidy it in Heartland periodically; the integration will not prune it. If you need the Heartland option name carried into iPaaS.com, add an OptionName mapping to the option collection — the template deliberately leaves that choice to you.

Custom prices can be read from Heartland using advanced mapping formulas, but uploading custom prices or price lists from iPaaS.com to Heartland is outside the current scope.

What this means for you: maintain custom pricing and price lists in Heartland Retail and treat iPaaS.com as the consuming side for those values. If outbound price list management becomes a requirement, raise it with iPaaS.com Support as a feature request.

The number of related (add-on) products retrieved for each product and variant is capped by the Add On Item Limit subscription setting when a limit is configured. An add-on item is linked only when the product it points to already exists in iPaaS.com.

What this means for you: set Add On Item Limit to a value that covers your widest add-on filter, and be aware that leaving it unset retrieves every matching add-on product, which is slow for products with broad filters. Transfer the full product catalog before you rely on add-on relationships, since add-ons pointing at products that are not yet in iPaaS.com are not linked and are not retried automatically.

The Heartland sales order deposit collections produce records that are copies of the sales order. The deposit lines duplicate the order's product lines and the deposit line discounts duplicate the discounts on those lines. This is deliberate, and exists for compatibility with downstream integrations that expect a deposit document alongside the order. Deposit records follow their parent sales order and have no separate schedule or Manual Sync entry.

What this means for you: do not treat a deposit record as a second, independent sale. When you total sales or count line quantities across iPaaS.com, exclude the deposit records or you will double-count. If your downstream systems do not consume deposit documents, you can leave the deposit collections disabled.

Not every collection in the shipped template is meant to run. The outbound gift card collection ships disabled and non-functional: it will not transfer records and is not intended to be enabled. The product option child collection ships as a structural carrier with no field mappings of its own, as described above.

What this means for you: review the enabled state of each collection during setup rather than enabling everything. Leave the disabled collections as shipped unless iPaaS.com Support advises otherwise for your configuration.

Heartland Retail publishes API documentation but does not publish a field-level specification for several record types the integration writes — product variants, variant options, item custom fields and their allowed values, addresses, and transaction notes among them. For these, field requirements, the handling of an empty value, and update behavior are not formally documented by the partner. The sales order note flow uses an Add sync method, and its behavior on repeated transfer of the same order is similarly undocumented.

What this means for you: validate these behaviors in a staging environment before relying on them in production, and re-validate after a Heartland Retail platform change. Where a write against one of these record types fails, the reason Heartland returned in the iPaaS.com error log is the most reliable guide to the constraint. The partner's current documentation is at Heartland Retail Developer Documentation (accessed 20 July 2026).

The Update Heartland Transaction Status TO iPaaS.com collection updates settled, non-deposit transactions. Pending transactions and deposit records are excluded by the collection's filter and are not updated through it. Related identifiers also have specific sources: the station identifier is supplied only from the Heartland Station Id custom field on the parent record.

What this means for you: if a transaction's status is not updating in iPaaS.com, confirm it is settled and is not a deposit record before investigating further. Populate the Heartland Station Id custom field where station-level reporting matters, since there is no fallback source for it.

The shipped template includes several mappings whose values are demonstrations rather than working configuration. They exist to show the shape of a mapping and must be replaced or removed before you go live, or they will write example data into your systems. Review each one below.

This article covers 22 known limitations of the iPaaS.com Heartland integration. For the behavior of an individual data flow — including its field mappings, filters, and the caveats specific to that collection — see the mapping collection descriptions and mapping documentation articles for that flow. For setup, credentials, and subscription settings, see Heartland Connections and Settings and Heartland Installation Instructions.

Setup & Reference