Customer and Customer Address

Product and Product Variant

Product Inventory

Gift Card

Sales Order and Ticket

Invoice

Heartland API Responses

Record Identifiers

Internal Validation

Connection Authorization

Description: Before a customer is transferred, the integration looks for an existing match on email address and writes the external-id link that ties the two records together. This warning 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 is raised from Add Heartland Customer TO iPaaS.com and Update Heartland Customer TO iPaaS.com.

Resolution: Check both systems for two customer records that share the same email address. If duplicates exist, merge or remove the unwanted record and re-run the transfer so the link is written against the surviving record.

Description: The same email-match and link step runs when a customer is transferred from iPaaS.com toward Heartland. The warning is raised when the link is written but does not return the expected identifier, leaving the records unlinked. It is raised from Add Heartland Customer FROM iPaaS.com and Update Heartland Customer FROM iPaaS.com.

Resolution: Check both systems for duplicate customers sharing one email address, resolve the duplicate, and re-run the transfer.

Description: An update to a Heartland customer arrived without the Heartland customer id needed to identify the record, so the integration cannot tell which customer to update. It is raised from Add/Update Heartland Customer FROM iPaaS.com.

Resolution: Confirm the customer transferred to Heartland successfully and is linked before an update is sent — an update depends on that link supplying the id. Re-run the customer transfer to establish the link, then re-run the update. If the customer is linked and the error persists, ask your MiSP to review the customer id mapping on the collection.

Description: The integration sent a create request for a customer and Heartland did not return a created customer record. It is raised from Add Heartland Customer FROM iPaaS.com.

Description note: A Heartland API response error (see HRTL-EXTN-1001) is usually logged alongside this and names the specific reason.

Resolution: Review the Heartland API response logged with this error for the field or value Heartland rejected, correct it on the source record or its mapping (with your MiSP), and re-run the transfer.

Description: The integration sent an update request for a customer and Heartland did not return the updated record. It is raised from Update Heartland Customer FROM iPaaS.com.

Resolution: Review the Heartland API response logged with this error, correct the rejected value with your MiSP, and re-run the transfer.

Description: 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 customer transfer fails, which stops the address transfer. It is raised from Add Heartland Customer Address TO iPaaS.com and Update Heartland Customer Address TO iPaaS.com.

Resolution: Find the customer transfer error logged immediately before this one and resolve that first — most often the customer is missing a value the receiving system requires. Transferring the customer on its own is enough to clear this error, after which you can re-run the address.

Description: An update to a customer address arrived without the customer id or the address id needed to identify the record in Heartland. It is raised from Update Heartland Customer Address FROM iPaaS.com.

Resolution: Confirm the customer and the address both transferred to Heartland and are linked before an update is sent. Re-run the customer (and address) transfer to establish the links, then re-run the update.

Description: 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 warning is raised when a match 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 exactly one item uses it. Duplicate or reused SKUs in Heartland are the usual cause; correct the SKU in Heartland and re-run the product transfer.

Description: The same SKU-matching step runs for each variant of a grid item. This warning is raised when a Heartland grid 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.

Description: A grid (variant) product in Heartland is defined by its options, so the integration cannot create variants when no product option is supplied. It is raised from Add/Update Heartland Product FROM iPaaS.com.

Resolution: Ask your MiSP to confirm the product option mappings are populated for grid products so each variant carries at least one option and value. Re-run the product transfer once the options are supplied.

Description: 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.

Description: A product being written to Heartland has no Public Id, which Heartland requires to identify the item. It is raised from Add/Update Heartland Product FROM iPaaS.com.

Resolution: Ask your MiSP to confirm the Public Id mapping is populated from a source field that is always present, then re-run the transfer.

Description: The inventory record being sent to Heartland carries an iPaaS.com location that has no matching, linked Heartland inventory location, so the validation stops the transfer rather than writing a quantity against the wrong location. This validation lives in the mapping filter on 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. Because this check lives in the mapping filter, your MiSP can adjust or remove it in the iPaaS.com UI if the behavior needs to change.

Description: A gift card being written to Heartland has no card number supplied through the mappings, so it cannot be created. It is raised from Add Heartland Gift Card FROM iPaaS.com.

Resolution: Ask your MiSP to confirm the gift card number mapping is populated, then re-run the transfer.

Description: A gift card update reached Heartland without the card number needed to identify and update the card. It is raised from Update Heartland Gift Card FROM iPaaS.com.

Resolution: Ask your MiSP to confirm the gift card number mapping is populated on the update collection, then re-run the transfer.

Description: A gift card was requested from Heartland with a missing or malformed id. In practice this happens on a Manual Sync submitted with a blank or wrong ID. It is raised while retrieving a gift card from Heartland.

Resolution: Re-run the Manual Sync with the correct Heartland gift card id.

Description: A gift card activity record reached Heartland without the mandatory fields (such as the gift card it applies to and the reason) needed to record it. It is raised while processing gift card activity.

Resolution: Ask your MiSP to confirm the required gift card activity mappings are populated, then re-run the transfer.

Description: A gift card activity was requested from Heartland with a missing or malformed id. It is raised while retrieving gift card activity from Heartland.

Resolution: Re-run the Manual Sync with the correct gift card activity id.

Description: An order or ticket coming 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. It is raised from the Sales Order and Ticket collections that capture into iPaaS.com.

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

Description: The same prerequisite runs in the opposite direction: an order being written to Heartland references an iPaaS.com customer with 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 and the ticket and invoice collections in the same direction.

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

Description: An order or ticket being written to Heartland includes a gift card payment whose gift card 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 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, ask your MiSP whether the Adjust Empty Gift Card For Payment subscription setting should raise the balance to cover the payment before the card is transferred.

Description: 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 the Sales Order, Ticket, Invoice, and Transaction Status collections that capture into iPaaS.com.

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

Description: 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.

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.

Description: A transaction validation ran with no transaction to check, meaning the record did not reach the validator in a usable form. It is raised from the transaction create and invoice validators.

Resolution: Re-run the transfer. If it recurs for the same record, ask your MiSP to review the mapping collection that produces the transaction payload for the record named in the log.

Description: A transaction reached Heartland carrying a type other than order, ticket, or invoice. The integration validates the type before creating or updating the record. It is raised from the Sales Order, Ticket, and Invoice collections in both directions.

Resolution: Ask your MiSP to 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.

Description: The create path was reached by a transaction whose type Heartland does not create through this integration. {Type} resolves to the type that was supplied. It is raised while creating a transaction in Heartland.

Resolution: Ask your MiSP to confirm the transaction type mapping resolves to a type this integration creates (order, ticket, or invoice) for the collection named in the error.

Description: The update path was reached by a transaction whose type Heartland does not update through this integration. {Type} resolves to the type that was supplied. It is raised while updating a transaction in Heartland.

Resolution: Ask your MiSP to confirm the transaction type mapping resolves to a type this integration updates for the collection named in the error.

Description: An order, ticket, or invoice is written to Heartland as a parent record plus its components — lines, payments, addresses, tracking numbers, notes, and status. This error is raised when one of those components fails to save; the logged text carries the specific reason for the component that failed. It is raised from the Sales Order, Ticket, and Invoice collections written to Heartland.

Resolution: Read the component detail in the logged message to see which part failed and why. A Heartland API response error (see HRTL-EXTN-1001) is usually logged alongside it. Correct the value on the source record or its mapping (with your MiSP), then re-run the transfer.

Description: A transaction update reached the end of its processing without completing successfully and without a more specific error. It is raised from Update Heartland Invoice FROM iPaaS.com (Order Complete) and the update paths of the sales order and ticket flows.

Resolution: Re-run the transfer. If it recurs, share the full log — including any Heartland API response logged with it — with your MiSP, who can escalate to iPaaS.com Support at support@ipaas.com if the integration itself needs a change.

Description: 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. Transfer the order first, then re-run the invoice.

Description: 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: Ask your MiSP to review the mapping that supplies the invoice identifier on the collection named in the error and confirm the source field is populated. Records that genuinely have no invoice number should be excluded by the collection's mapping filter rather than left to fail.

Description: 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.

Description: 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: Ask your MiSP to review the mapping 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, the invoice collections should be disabled rather than left to fail.

Description: Only completed transactions can be invoiced. This error is raised when the transaction's status is missing, or is present but 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 — wait until the order is marked complete and let the completion event re-trigger the invoice. If orders that are complete in iPaaS.com still report this, ask your MiSP to check that the status mapping translates the iPaaS.com status to the value Heartland expects.

Description: An invoice can only be created from a source transaction that is still open. {External_Id} resolves to the transaction being invoiced and {Status} resolves to its current status. This error is raised when the source transaction is in a status that does not allow invoicing.

Resolution: Confirm the source transaction is in an open, invoiceable state in Heartland before the invoice is sent. If the transaction is already closed or fully invoiced, no further invoice is expected.

Description: 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, and {Sku} resolves to the SKU of the unlinked line. This validation lives in the mapping filter on 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. Because this check lives in the mapping filter, your MiSP can adjust it in the iPaaS.com UI; relaxing it allows the invoice through with an unlinked line, which Heartland may then reject on its own terms.

Description: Heartland rejected the request the integration sent. The logged message includes Heartland's own response, so the specific wording changes with each failure and is not controlled by the integration. {action} names the operation and {code} is the HTTP status returned. Any collection that reads from or writes to Heartland can produce this.

Resolution: Read the Heartland text in the message — it usually names the field or condition Heartland objected to. 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. Correct that value on the source record or its mapping (with your MiSP) and re-run the transfer. If the Heartland text does not make the cause clear, share the full message with your MiSP.

Description: The identifier supplied for a record could not be interpreted as a valid key for that record type. The logged message names the record type and the value that was rejected, and the specific field when the failure is on one part of a compound key. It can be raised from any collection while reading a record's identifier — customer, customer address, location, payment method, shipping method, and others.

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, share the rejected value from the message with your MiSP to review the mapping that supplies the identifier.

Description: A record type, endpoint, or request parameter reached a step in the integration that has no branch for it — for example an unsupported parameter type or a call made with parameters the step does not recognize. These indicate a fault in the integration or in how the subscription is configured, not a problem with the data on the record, and any flow can produce one. The logged text names the unhandled type in a short technical statement.

Resolution: These are not correctable from the record itself. Share the full message text and the name of the mapping collection that was running with your MiSP, who can escalate to iPaaS.com Support at support@ipaas.com if the integration or the subscription configuration needs a change.

Description: 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 again, contact your MiSP.

Description: 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 and complete it promptly. Confirm the Heartland user completing it still has access to the Heartland account. If it fails again, contact your MiSP.

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

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

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

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

Description: 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.

Description: When a subscription is established or tested, the integration validates the connection against Heartland. This error is raised when that validation does not succeed — most often because the credential is missing, expired, or revoked.

Resolution: Re-enter or re-authorize the Heartland credential on the subscription and test the connection again. If it continues to fail with a known-good credential, contact your MiSP.

Heartland Connections and Settings

Heartland Installation Instructions

Heartland API Endpoints

Heartland Integration Known Limitations