Mapping filter validations: these are written as Dynamic Formula expressions on a mapping collection's filter in the iPaaS.com UI. A subscriber with access to the subscription's mapping collections can edit or remove the validation, change its wording, or relax the condition that triggers it. Each of these entries is marked Subscriber-editable below.

Integration code validations and platform responses: every other message in this article is emitted by the integration itself or returned by the Heartland API. These cannot be changed from the iPaaS.com UI. If one of them is wrong, misleading, or blocking a legitimate record, the change has to come from iPaaS.com. Contact iPaaS.com Support at support@ipaas.com.

Customer

Customer Address

Product and Product Variant

Product Inventory

Gift Card

Sales Order and Ticket

Invoice

Location, Payment Method, and Shipping Method

Heartland API Responses

Connection Authorization

Integration-Internal Validation

Cause: Before a customer is transferred, the integration checks whether the customer already exists on the other side by looking it up on email address. When a match is found, the integration writes the external-id link that ties the two records together. This error is raised when that link is written but does not come back holding the expected identifier, so the two customer records are left unlinked. It applies in both directions and is raised from Add Heartland Customer TO iPaaS.com, Update Heartland Customer TO iPaaS.com, Add Heartland Customer FROM iPaaS.com, and Update Heartland Customer FROM iPaaS.com.

Resolution: Check both systems for two customer records sharing the same email address. If duplicates were created, merge or remove the unwanted record and re-run the transfer so the link is written against the surviving record. If the message repeats for customers that clearly match, contact iPaaS.com Support at support@ipaas.com.

Note: "BC" in this message is a leftover from the template this integration was built from. It refers to the Heartland customer record; there is no separate system involved.

Cause: A customer address cannot exist on its own. When an address arrives for a customer that is not yet linked, the integration transfers the parent customer first. This error is raised when that parent customer transfer fails, which stops the address transfer as well. It is raised from Add Heartland Customer Address TO iPaaS.com and Update Heartland Customer Address TO iPaaS.com.

Resolution: Look for the customer transfer error logged immediately before this one and resolve that first, then re-run the address transfer. Most commonly the customer is missing a value the receiving system requires. Transferring the customer successfully on its own is enough to clear this error.

Note: The logged text includes an internal processing-step name where the ellipsis appears above.

Cause: When a product is sent to Heartland and is not yet linked, the integration first searches Heartland for an item with the same SKU so an existing item is reused rather than duplicated. This error is raised when a matching item is found but the external-id link written back does not hold the expected Heartland item identifier. It is raised from Add/Update Heartland Product FROM iPaaS.com.

Resolution: Search Heartland for the SKU and confirm there is exactly one item using it. Duplicate or reused SKUs in Heartland are the usual cause. Correct the SKU in Heartland, then re-run the product transfer. If the SKU is unique and the message persists, contact iPaaS.com Support at support@ipaas.com.

Note: "Heart Land" is a spelling error in the message text itself; it refers to Heartland.

Cause: The same SKU-matching step runs for each variant of a grid item. This error is raised when a Heartland grid item variant is matched on SKU but the external-id link written back does not hold the expected variant identifier. It is raised from Add/Update Heartland Product FROM iPaaS.com while processing the product's variants.

Resolution: Confirm each variant SKU is unique within Heartland and that the variants belong to the expected grid item. Correct any duplicated variant SKU and re-run the parent product transfer, which reprocesses all of its variants. If the message persists, contact iPaaS.com Support at support@ipaas.com.

Cause: A product was requested from Heartland without an identifier, or with an empty one. In practice this happens when a Manual Sync is submitted with a blank ID. It is raised from Add/Update Heartland Product TO iPaaS.com.

Resolution: Re-run the Manual Sync with the Heartland product ID filled in. If the transfer was automatic rather than manual, contact iPaaS.com Support at support@ipaas.com.

Note: The message says "transaction" even though the record is a product. This is a wording error in the message, not a sign that the wrong record was processed.

Cause: The inventory record being sent to Heartland carries an iPaaS.com location that has no matching Heartland inventory location. The validation stops the transfer rather than writing a quantity against the wrong location. It is raised from Add/Update Heartland Product Inventory FROM iPaaS.com.

Resolution: Confirm the iPaaS.com location has been transferred to Heartland and is linked. Transferring locations through Add/Update Heartland Location TO iPaaS.com establishes the link. Once the location is linked, re-run the inventory transfer.

Subscriber-editable: Yes. This validation lives in the mapping filter on Add/Update Heartland Product Inventory FROM iPaaS.com and can be edited or removed in the iPaaS.com UI.

Cause: Writing gift cards into Heartland is not a supported flow. The two collections that would carry it, (DISABLED) Add Heartland Gift Card FROM iPaaS.com and (DISABLED) Update Heartland Gift Card FROM iPaaS.com, are shipped disabled and their filters raise this error if a transfer reaches them anyway. Seeing this message means gift card events are still being sent in that direction.

Resolution: Turn off the gift card webhook or scope that is pushing gift cards from iPaaS.com toward Heartland. Gift cards flow in the opposite direction only, through Add Heartland Gift Card TO iPaaS.com and Update Heartland Gift Card TO iPaaS.com, and those remain unaffected.

Subscriber-editable: Yes. The validation lives in the mapping filter on both disabled collections. Removing it does not make the flow work; the direction is unsupported regardless.

Cause: An order or ticket arriving from Heartland references a customer that is not yet linked in iPaaS.com. The integration transfers that customer first, and this error is raised when that customer transfer fails, which stops the order transfer. It is raised from Add Heartland Sales Order TO iPaaS.com, Add Heartland Ticket TO iPaaS.com, and Add Heartland Invoice TO iPaaS.com.

Resolution: Resolve the customer transfer error logged just before this one, then re-run the order transfer. Transferring the customer on its own first is a reliable way to confirm the problem is cleared.

Note: The logged text includes an internal processing-step name where the ellipsis appears above.

Cause: The same prerequisite runs in the opposite direction. An order being written to Heartland references an iPaaS.com customer that has no linked Heartland customer, so the integration transfers the customer first. This error is raised when that customer transfer fails. It is raised from Add/Update Heartland Sales Order FROM iPaaS.com, Add Heartland Ticket FROM iPaaS.com, and the Invoice collections in the same direction.

Resolution: Resolve the customer transfer error logged just before this one, most often a value Heartland requires on a customer that the iPaaS.com record does not supply. Then re-run the order transfer.

Cause: An order or ticket being written to Heartland includes a gift card payment, and the gift card it draws on is not yet linked in Heartland. The integration transfers the gift card first so the payment can be applied, and this error is raised when that gift card transfer fails. It is raised from Add/Update Heartland Sales Order FROM iPaaS.com and Add Heartland Ticket FROM iPaaS.com while handling gift card payments.

Resolution: Resolve the gift card transfer error logged just before this one, then re-run the order. If the gift card carries a zero balance, the Adjust Empty Gift Card For Payment subscription setting controls whether the integration raises the balance to cover the payment amount before transferring the card; review that setting if zero-balance cards are the pattern.

Cause: A Heartland transaction was requested without an identifier, or with an empty one. In practice this happens when a Manual Sync is submitted with a blank ID. It is raised from Add Heartland Sales Order TO iPaaS.com, Add Heartland Ticket TO iPaaS.com, Add Heartland Invoice TO iPaaS.com, and Update Heartland Transaction Status TO iPaaS.com.

Resolution: Re-run the Manual Sync with the transaction ID filled in, using the suffixed format described in the next entry.

Cause: Heartland orders, tickets, and invoices share one transaction record type, so the integration needs the identifier to state which kind it is. The identifier must end in _ORDER, _TICKET, or _INVOICE, for example 123456_ORDER. This error is raised when the identifier supplied has none of those suffixes. It is raised from Add Heartland Sales Order TO iPaaS.com, Add Heartland Ticket TO iPaaS.com, Add Heartland Invoice TO iPaaS.com, and Update Heartland Transaction Status TO iPaaS.com.

Resolution: Re-run the Manual Sync with the suffix appended to the Heartland transaction number: _ORDER for a sales order, _TICKET for a ticket, _INVOICE for an invoice.

Cause: A transaction reached Heartland carrying a type other than order, ticket, or invoice. The integration validates the type before attempting to create the record. It is raised from Add/Update Heartland Sales Order FROM iPaaS.com, Add Heartland Ticket FROM iPaaS.com, and Add Heartland Invoice FROM iPaaS.com (Invoice).

Resolution: Check the mapping that supplies the transaction type on the collection named in the error and confirm it resolves to one of the three supported values. If the mapping is correct and the error persists, contact iPaaS.com Support at support@ipaas.com.

Cause: The same type validation runs when an existing Heartland transaction is updated rather than created. It is raised from Update Heartland Invoice FROM iPaaS.com (Order Complete) and the update paths of the sales order and ticket flows.

Resolution: As above, confirm the transaction type mapping resolves to order, ticket, or invoice on the collection named in the error.

Cause: The invoice creation path was reached by a transaction whose type is not invoice. It is raised from Add Heartland Invoice FROM iPaaS.com (Invoice).

Resolution: Confirm the transaction type mapping on the invoice collection resolves to invoice. If the record should not have been routed to the invoice flow at all, review the mapping collection filter that selects records for it.

Cause: A Heartland invoice is always created against an existing Heartland sales order. This error is raised when the invoice reaching Heartland carries no usable order identifier. It is raised from Add Heartland Invoice FROM iPaaS.com (Invoice).

Resolution: Confirm the originating sales order transferred to Heartland successfully and is linked before the invoice is sent. An invoice for an order that never reached Heartland cannot be created. Transfer the order first, then re-run the invoice.

Cause: The invoice reaching Heartland does not carry the flag that authorizes the integration to create an invoice from it. It is raised from Add Heartland Invoice FROM iPaaS.com (Invoice).

Resolution: Review the mapping on the invoice collection that supplies the create-invoice flag and confirm it resolves to true for records that should be invoiced. If invoicing is not intended for this subscription, disable the invoice collections rather than leaving records to fail.

Cause: The invoice reaching Heartland has no invoice identifier to save against. It is raised from Add Heartland Invoice FROM iPaaS.com (Invoice) and Update Heartland Invoice FROM iPaaS.com (Order Complete).

Resolution: Review the mapping supplying the invoice identifier on the collection named in the error and confirm the source field is populated on the iPaaS.com record. Records that genuinely have no invoice number should be excluded by the collection's mapping filter rather than allowed to fail.

Cause: The order being invoiced at completion has no external-id link to a Heartland transaction, so the integration cannot tell which Heartland record to invoice. It is raised from Update Heartland Invoice FROM iPaaS.com (Order Complete).

Resolution: Confirm the sales order transferred to Heartland and is linked before the completion event runs. Re-run the sales order transfer, then re-run the invoice update.

Cause: The invoice validations require a status on the transaction, and none was supplied. It is raised from Add Heartland Invoice FROM iPaaS.com (Invoice) and Update Heartland Invoice FROM iPaaS.com (Order Complete).

Resolution: Review the status mapping on the collection named in the error and confirm the iPaaS.com source field is populated.

Cause: Only completed transactions can be invoiced. This error is raised when the transaction's status is present but is something other than complete. It is raised from Add Heartland Invoice FROM iPaaS.com (Invoice) and Update Heartland Invoice FROM iPaaS.com (Order Complete).

Resolution: This is usually correct behavior rather than a fault. Wait until the order is marked complete, then let the completion event re-trigger the invoice. If orders that are complete in iPaaS.com are still reporting this, check that the status mapping is translating the iPaaS.com status to the value Heartland expects.

Cause: Every line on a Heartland invoice must point at a line on the originating Heartland sales order. This validation stops the invoice when one of its lines has no such link. {Parent.TransactionNumber} resolves to the transaction number of the invoice being processed, and {Sku} resolves to the SKU of the line item that is not linked. It is raised from Add Heartland Invoice Line Item FROM iPaaS.com (Invoice).

Resolution: Confirm the originating sales order and all of its lines transferred to Heartland successfully. A line added to the order after it reached Heartland, or a line whose product never linked, will produce this. Transfer the missing line or correct the product link, then re-run the invoice.

Subscriber-editable: Yes. This validation lives in the mapping filter on Add Heartland Invoice Line Item FROM iPaaS.com (Invoice), and the message itself says so. Relaxing it allows the invoice through with an unlinked line, which Heartland may then reject on its own terms.

Cause: The identifier supplied for a record could not be interpreted as a valid key for that record type. {record type} resolves to the kind of record being processed, and {value} resolves to the identifier that was rejected. The message also names the specific field when the failure is on one part of a compound key. It applies to customer, customer address, location, payment method, and shipping method records, and so can be raised from Add Heartland Customer TO iPaaS.com, Update Heartland Customer TO iPaaS.com, Add Heartland Customer Address TO iPaaS.com, Update Heartland Customer Address TO iPaaS.com, Add/Update Heartland Location TO iPaaS.com, Add/Update Heartland Payment Method TO iPaaS.com, and Add/Update Heartland Shipping Method TO iPaaS.com.

Resolution: If the transfer was started from Manual Sync, check the identifier entered against the ID Format section of that collection's mapping documentation and re-run with a correctly formed value. If the transfer was automatic, contact iPaaS.com Support at support@ipaas.com with the value shown in the message.

Cause: Heartland rejected the request the integration sent. Everything after the colon is Heartland's own response, so the wording changes with each failure and is not controlled by the integration. Any collection that writes to Heartland can produce this, in either direction, because every call to Heartland is subject to it.

Resolution: Read the Heartland text in the message. It usually names the field or condition Heartland objected to, and correcting that value on the source record and re-running the transfer resolves it. Common causes are a required Heartland field left empty by a mapping, a value outside the range or list Heartland accepts, and a record that no longer exists in Heartland. If the Heartland text does not make the cause clear, contact iPaaS.com Support at support@ipaas.com and include the full message.

Note: This message is not always readable prose. When Heartland returns a structured response, the integration may surface the raw response body rather than a single sentence, so expect to read past punctuation and field names to find the meaningful part.

Cause: The authorization flow returned to iPaaS.com without the temporary code needed to complete the connection.

Resolution: Start the authorization again from the Heartland subscription and complete it without navigating away or letting the browser session expire. If it fails a second time, contact iPaaS.com Support at support@ipaas.com.

Cause: The integration version being connected is missing the client identifier that the authorization flow requires. This is a configuration value held by iPaaS.com, not by the subscriber.

Resolution: Contact iPaaS.com Support at support@ipaas.com.

Cause: The integration version being connected is missing the client secret that the authorization flow requires. This is a configuration value held by iPaaS.com.

Resolution: Contact iPaaS.com Support at support@ipaas.com.

Cause: The integration version being connected is missing the return address the authorization flow sends the subscriber back to. This is a configuration value held by iPaaS.com.

Resolution: Contact iPaaS.com Support at support@ipaas.com.

Cause: The temporary code returned by the authorization flow was rejected when the integration tried to exchange it for a lasting credential. Expired codes and revoked application access both produce this.

Resolution: Start the authorization again from the Heartland subscription and complete it promptly. Confirm the Heartland user completing it still has access to the Heartland account. If it fails again, contact iPaaS.com Support at support@ipaas.com.

Cause: A record or request reached a processing step that has no branch for it. This is a fault in the integration or in how the subscription is configured, not a problem with the data on the record. Any flow can produce one.

Resolution: Contact iPaaS.com Support at support@ipaas.com. Include the full message text and the name of the mapping collection that was running. There is no subscriber-side correction for these.

Heartland Connections and Settings

Heartland Installation Instructions

Heartland API Endpoints

Heartland Integration Known Limitations