Summary
iPaaS.com transactions are written out to Heartland as Heartland invoices. iPaaS.com is the source in this direction and Heartland is the system being written to. Each transfer creates a Heartland invoice header, adds its line items, adds its payments, sets a shipment tracking number, and then completes the invoice — Heartland does not allow an invoice to be completed until a payment has been recorded, so the payment always precedes completion.
The template provides two separate parent collections for creating a Heartland invoice, and they are triggered by two different kinds of iPaaS.com record. Add Heartland Invoice FROM iPaaS.com (Invoice) fires on an iPaaS.com transaction whose type is Invoice. Update Heartland Invoice FROM iPaaS.com (Order Complete) fires on an iPaaS.com transaction whose type is Order and whose status has been set to Complete. Each parent carries its own three child collections for line items, payments, and tracking numbers.
This article covers all eight collections in this direction. The opposite direction — Heartland invoices brought into iPaaS.com — is handled by the Add Heartland Invoice TO iPaaS.com family and is documented separately.
The two invoice flows
The parenthetical qualifier in each collection name identifies the trigger, not a variation of the same transfer. The two flows are alternative ways of producing a Heartland invoice, and a given transaction should travel exactly one of them.
Flow A — invoice-triggered. Add Heartland Invoice FROM iPaaS.com (Invoice) runs when an iPaaS.com transaction of type Invoice, with a status of Complete, has not already been invoiced. This is the standalone, one-to-one workflow: the iPaaS.com transaction represents the invoice itself. Because Heartland builds an invoice from an existing sales order, this flow must be told which Heartland order and which Heartland order lines the invoice applies to, and it supplies those from custom fields on the iPaaS.com transaction and its lines. The resulting Heartland invoice identifier is saved as the external-id link on the iPaaS.com transaction.
Flow B — order-complete-triggered. Update Heartland Invoice FROM iPaaS.com (Order Complete) runs when an iPaaS.com transaction of type Order, already linked to a Heartland sales order, is updated to a status of Complete and that update is transferred. The order-line association is already established by the linked Heartland sales order, so this flow does not supply an order id or per-line order-line ids. The resulting Heartland invoice identifier is written to the Heartland Invoice Id custom field on the originating transaction rather than to the external id, because that transaction's external id already belongs to the sales order.
The two collection filters are otherwise identical and differ only in the transaction type they accept, so a single transaction cannot satisfy both. Both filters additionally require that the transaction's Heartland Invoice Id custom field be empty, which is what stops the same record from being invoiced twice.
Which one should a subscriber expect? If your source platform produces invoice documents in their own right and you transfer them to iPaaS.com as Invoice transactions, expect Flow A. If your source platform produces orders that you transfer to Heartland as sales orders and later mark complete, expect Flow B — invoicing happens as a side effect of the completion transfer, with no separate invoice record involved. Subscribers running both sales orders and standalone invoices should confirm which parent is enabled for each transaction type so one invoice is not attempted through both paths.
ID Format
Manual Sync ID Format
On the iPaaS.com Manual Sync page, enter the iPaaS.com transaction's internal ID — for example, 145146. This outbound direction uses the iPaaS.com identifier, not a Heartland identifier, and the same entry point serves both flows: the transaction's type and status determine which parent collection accepts it. Transferring a transaction this way also transfers its line items, payments, and tracking number through that parent's child collections.
External ID Format
The two flows record the resulting Heartland invoice identifier in different places, and this is one of the most important practical differences between them.
Flow A sets the SaveInvoiceId field to the value "ExternalId", so the Heartland invoice identifier returned after creation is saved as the external-id link on the iPaaS.com transaction. Heartland transaction external ids carry a suffix that keeps numeric ids unique across transaction types; invoice identifiers use the _INVOICE suffix — an invoice number followed by _INVOICE.
Flow B sets the SaveInvoiceId field to the custom field name "Heartland Invoice Id", so the Heartland invoice identifier is written to the Heartland Invoice Id custom field on the originating iPaaS.com order transaction. The transaction's external id is left alone, because it already links that transaction to its Heartland sales order. Writing the invoice identifier to this custom field is what makes the collection filter recognize an already-invoiced order on a later transfer.
Do not set Flow B to use "ExternalId". That value is appropriate only when the iPaaS.com transaction is linked solely to an invoice and not also to a sales order.
The Heartland invoice number shown to users is set separately through the PublicId mapping. Flow A writes the iPaaS.com transaction number as-is. Flow B writes the transaction number with an "-INV" suffix — for example, 100245-INV — so the invoice number stays distinct from the related order and ticket numbers derived from the same transaction.
Deleted Record Support
Deleting an invoice is not supported in this direction. The integration creates Heartland invoices only. Deleting or voiding a transaction in iPaaS.com does not delete the linked Heartland invoice, and there is no delete path for Heartland transactions in this integration at all. Invoices that must be removed or reversed in Heartland have to be handled in Heartland directly.
Updating an existing Heartland invoice from iPaaS.com is likewise not supported. Despite its name, Update Heartland Invoice FROM iPaaS.com (Order Complete) creates a new Heartland invoice — the "Update" in the name refers to the iPaaS.com order update that triggers it, not to updating an invoice. Corrections to an invoice after it has been created must be made in Heartland.
Custom Field Support
Both flows depend heavily on custom fields, in both directions.
iPaaS.com custom fields read by the mappings. These must exist under your Heartland subscription in iPaaS.com and be populated on the source record before transfer, or the mapped value is unavailable:
Heartland Station Id: read from the transaction and written to the Heartland invoice's station. Required by Heartland to create a transaction.
Heartland Source Location Id: read from the transaction and written to the Heartland invoice's inventory source location. Required by Heartland to create a transaction.
Heartland Invoice Order Id: read from the transaction by Flow A only, to identify the original Heartland sales order the invoice is created from.
Heartland Invoice Order Line Id: read from each transaction line by Flow A only, to identify the Heartland sales order line each invoiced line applies to.
Heartland Invoice Id: checked by both collection filters to decide whether a transaction has already been invoiced, and written back by Flow B after the invoice is created.
Heartland custom fields written by the mappings. Both parents write the static value "iPaaS.com" to a Heartland custom field named Transaction Source. This tag is what lets the opposite-direction Add Heartland Invoice TO iPaaS.com collection recognize and skip invoices that originated in iPaaS.com, preventing a feedback loop between the two systems. A Heartland custom field must be created in Heartland manually before it is visible on the Heartland website and available as a mapping destination, and a matching custom field of the same name must exist under your Heartland subscription in iPaaS.com. Until both exist, the value is not stored and the loop-prevention tag is not applied.
Mapping Collection Status
Status: Enabled. All eight collections — both parents and their six children — are enabled in the template. Disable Add Heartland Invoice FROM iPaaS.com (Invoice) if you will not be creating Heartland invoices from iPaaS.com Invoice transactions. Disable Update Heartland Invoice FROM iPaaS.com (Order Complete) to stop invoices from being created when iPaaS.com orders are completed.
Trigger Events: Outbound transfers are triggered from iPaaS.com. The integration recognizes transaction creation and transaction update events; a transaction reaching one of the two parent filters is invoiced in Heartland. No automatic transfers occur until the subscription is configured and enabled. A specific transaction can also be transferred on demand at any time from the iPaaS.com Manual Sync page.
The six child collections have no trigger of their own. Each runs only when its own parent transfers an invoice.
Duplicate or Conflicting Mappings
Eight mapping collections write invoice data to Heartland in this direction: the two parents described above and their six children. Because the two parent filters accept different transaction types, they never compete for the same record on the same transfer — but they represent two different invoicing workflows, and a subscriber should deliberately choose one per transaction rather than leaving the choice to chance.
Three further relationships matter:
Add Heartland Invoice TO iPaaS.com, with its own child collections, brings Heartland invoices into iPaaS.com. This is the opposite direction and has its own article. When both directions are active, an invoice created in Heartland by either flow described here could be transferred back into iPaaS.com. The Transaction Source tag written by both parents is the mechanism that prevents that loop: the inbound collection's filter rejects invoices whose Transaction Source is iPaaS.com. Confirm the Transaction Source custom field exists on both sides before running the two directions together.
Add/Update Heartland Sales Order FROM iPaaS.com creates the open Heartland sales order that Flow B later invoices. Order creation deliberately forces a non-complete status, because Heartland will not invoice an order that was created complete. If you create sales orders and invoices from iPaaS.com together, review both collections and confirm your order status handling.
The three child collections under one parent are not interchangeable with the similarly named children under the other. Add Heartland Invoice Line Item FROM iPaaS.com (Invoice) and Update Heartland Invoice Line Item FROM iPaaS.com (Order Complete) are different collections with different mappings, and the same is true of the payment and tracking-number pairs. Editing one does not affect the other.
Important: before running both directions together, review your mapping collection filters and clearly define which system is the source of truth for invoice data. If both directions are active with the default mappings, records may propagate back and forth between the systems.
Collision Handling
This integration does not use iPaaS.com collision handling for invoices. Whether an invoice is created is determined entirely by the two collection filters — the transaction type, its status, and whether the Heartland Invoice Id custom field is already populated. There is no collision recovery step to configure.
Supported Child Collections
Each parent has exactly three children, and each child runs only as part of its own parent's transfer. None has a webhook, polling schedule, or Manual Sync entry of its own.
Children of Add Heartland Invoice FROM iPaaS.com (Invoice):
Add Heartland Invoice Line Item FROM iPaaS.com (Invoice): transfers the invoice's line items. Each line must be linked to the Heartland sales order line it invoices; a line that is not linked prevents the transfer of the whole invoice.
Add Heartland Invoice Payment FROM iPaaS.com (Invoice): transfers the invoice's payments. At least one payment must be added before the invoice can be completed in Heartland.
Add Heartland Invoice Tracking Number FROM iPaaS.com (Invoice): adds shipment tracking information to the invoice before completion. Heartland displays only one tracking number, so if several are supplied only the last one processed is set.
Children of Update Heartland Invoice FROM iPaaS.com (Order Complete):
Update Heartland Invoice Line Item FROM iPaaS.com (Order Complete): adds the completed order's line items to the Heartland invoice. It does not supply an order-line reference, because the invoice is generated from the sales order the transaction is already linked to.
Update Heartland Invoice Payment FROM iPaaS.com (Order Complete): adds the payment to the Heartland invoice. At least one payment is required before the invoice can be completed.
Update Heartland Invoice Tracking Number FROM iPaaS.com (Order Complete): adds shipment tracking to the Heartland invoice before completion. Only the last tracking number found is set.
System Caveats
Heartland Caveats
One invoice per order: Heartland allows only one invoice per order and does not support partial invoicing. Invoice completed orders only.
Open orders only: an invoice may be created only for a Heartland order in an open state. Orders intended for invoicing must be created in a non-complete status first; once all line items are invoiced, Heartland moves the order to a closed status. If the order being invoiced is not open, Heartland rejects the request and the transfer fails with an error indicating the invoice could not be attempted for the current order state.
Payment before completion: an invoice cannot be completed until a payment is recorded, so the integration creates the invoice, adds payments, and only then completes it.
Payment cannot exceed the balance: Heartland rejects a payment whose amount is greater than the remaining invoice or order balance, returning an error such as "Payment cannot exceed balance of sales order." The Heartland order total is built from line item prices, line item taxes, and shipping amounts.
Hidden decimal precision: although the Heartland order interface shows only two decimal places, larger amounts can be stored in the following decimal places. This is often not apparent until a payment is added and Heartland returns a balance error. Round all payment and tax amounts sent to Heartland to two decimal places to prevent and troubleshoot this.
Line item taxes must be supplied per line: Heartland calculates the order total from per-line tax amounts. Source platforms that do not provide line-item tax individually require the tax to be allocated across lines before transfer. The template mappings demonstrate a formula that allocates a proportional share of line-item tax to the product total portion of the order subtotal; more advanced allocation logic should be arranged with your integration support provider.
Station and source location required: Heartland requires a station and an inventory source location to create a transaction. Location ids are visible in the Heartland retail website under Settings and then Locations; station ids are visible under the same location after selecting a location name and viewing its station list.
Single tracking number: Heartland displays only one tracking number per invoice. When several tracking records exist for a transaction, the integration keeps the last one processed; earlier values are not retained.
Custom field visibility: a Heartland custom field must be created in Heartland manually before it is visible on the Heartland website and available as a mapping destination.
iPaaS.com Caveats
Manual Sync uses the iPaaS.com ID: Manual Sync in this direction takes the iPaaS.com transaction's internal ID, not a Heartland identifier.
Unique transaction number: iPaaS.com requires a unique transaction number on every transaction. When invoices, orders, and tickets are transferred together, the external-id suffixes — _INVOICE, _ORDER, _TICKET — keep the numeric ids from overlapping.
Custom field prerequisites: every custom field listed under Custom Field Support must exist under your Heartland subscription in iPaaS.com and be populated before its value is available to the mappings. A transfer that reaches Heartland without a station or source location is rejected.
Skipped is not failed: transactions that do not satisfy a collection filter are skipped silently. They are not errors and do not appear in the error logs. A transaction that appears never to have been invoiced is most often one that did not match its filter.
Two fields control invoicing: CreateInvoice must return true for a transfer to be processed as an invoice, and SaveInvoiceId controls where the resulting Heartland invoice identifier is stored. Changing either changes the workflow, not just a value.
Integration-Specific Caveats
The parenthetical qualifier is the trigger: the (Invoice) and (Order Complete) suffixes in the collection names denote which iPaaS.com record type fires the transfer. They are not two versions of the same collection and their mappings differ.
"Update" in a collection name refers to the iPaaS.com event, not to Heartland: the Order Complete parent creates a new Heartland invoice. Invoice updates from iPaaS.com are not supported in either flow.
Automatic customer prerequisite: when a transaction is transferred to Heartland and the iPaaS.com customer it references is not yet linked to a Heartland customer, the integration retrieves that customer and transfers it to Heartland first, before the invoice. Subscribers do not need to pre-sync customers ahead of invoices. If the customer transfer fails, the invoice transfer is stopped with an error rather than being written against a missing customer. This step is not gated by a subscription setting.
Automatic gift card prerequisite: when a payment on the transaction references an iPaaS.com gift card that is not yet linked to Heartland, the integration retrieves that gift card and transfers it to Heartland before the invoice. If the gift card transfer fails, the invoice transfer is stopped with an error.
Zero-balance gift card handling is a subscription setting: Heartland requires a gift card to hold an available balance at least equal to the payment amount, which is a problem for cards already depleted on another platform. The optional subscription setting Adjust Empty Gift Card For Payment covers this case: when it is set to True and a gift card payment references a card with a zero balance, the Heartland card is adjusted to permit the full payment, and the zero balance is re-transferred afterward to restore it. When the setting is not enabled, a zero-balance card is not adjusted and Heartland may reject the payment.
Transfers are additive: an outbound transfer never removes a Heartland invoice, line, payment, or tracking number.
Setup Requirements
Heartland Configuration
Identify the Heartland location and station the invoices should be created against, and note their ids from Settings and then Locations in the Heartland retail website.
Create the Transaction Source custom field in Heartland before configuring the mappings, so it is available as a mapping destination and the loop-prevention tag can be stored.
For Flow B, confirm the Heartland sales orders you intend to invoice are created in an open, non-complete state.
iPaaS.com Configuration
Enable the subscription so outbound transfers can run.
Create the custom fields listed under Custom Field Support under your Heartland subscription, and populate Heartland Station Id and Heartland Source Location Id on every transaction to be invoiced.
For Flow A, additionally populate Heartland Invoice Order Id on the transaction and Heartland Invoice Order Line Id on every line.
Decide which flow applies to each transaction type, and disable the parent collection you do not intend to use.
Confirm line-item tax amounts are allocated per line and rounded to two decimal places before transfer.
Set the Adjust Empty Gift Card For Payment subscription setting to True if your source platform can present gift card payments against depleted cards.
Authentication & Security
Heartland uses OAuth 2.0 to obtain an access token, which authorizes the Heartland API requests made during a transfer. Credentials are configured on the Heartland subscription — see the Heartland Installation Instructions.
Integration Flow
Flow A — standalone invoice transaction:
An iPaaS.com transaction of type Invoice reaches a status of Complete and is transferred, either automatically or by Manual Sync.
The collection filter on Add Heartland Invoice FROM iPaaS.com (Invoice) is evaluated. Only invoice transactions that are complete and whose Heartland Invoice Id custom field is empty proceed; everything else is skipped without error.
Before anything is written, the integration checks whether the iPaaS.com customer on the transaction is already linked to a Heartland customer. If it is not, the customer is retrieved and transferred to Heartland first. If that customer transfer fails, the invoice transfer is stopped.
Still before the invoice is written, the integration inspects each payment on the transaction. Any payment referencing an iPaaS.com gift card that is not yet linked to Heartland causes that gift card to be transferred first, with the zero-balance adjustment applied when the Adjust Empty Gift Card For Payment setting is enabled. If a gift card transfer fails, the invoice transfer is stopped.
The integration resolves the Heartland customer and the original Heartland sales order to invoice, then creates the invoice header in Heartland from the mapped values.
Invoice line items are added through the child Add Heartland Invoice Line Item FROM iPaaS.com (Invoice) collection. Each line must reference the Heartland sales order line it invoices.
Payments are added through the child Add Heartland Invoice Payment FROM iPaaS.com (Invoice) collection, so the invoice can be completed.
Any shipment tracking number is set through the child Add Heartland Invoice Tracking Number FROM iPaaS.com (Invoice) collection.
The invoice is completed in Heartland.
The resulting Heartland invoice identifier is saved back to the iPaaS.com transaction as its external-id link, which also makes the transaction ineligible for a second invoice.
Flow B — completed order:
An iPaaS.com transaction of type Order, already linked to an open Heartland sales order, is updated to a status of Complete and that update is transferred.
The collection filter on Update Heartland Invoice FROM iPaaS.com (Order Complete) is evaluated. Only order transactions that are complete and whose Heartland Invoice Id custom field is empty proceed.
The same customer and gift card prerequisites described in Flow A are applied before anything is written, and a failure in either stops the invoice transfer.
The integration creates the invoice in Heartland from the completed order, applying the header values mapped in this collection — customer, station, inventory source location, type, and status.
Line items are added through the child Update Heartland Invoice Line Item FROM iPaaS.com (Order Complete) collection. No order-line reference is supplied, because the association comes from the linked sales order.
The payment is added through the child Update Heartland Invoice Payment FROM iPaaS.com (Order Complete) collection.
The shipment tracking number is set through the child Update Heartland Invoice Tracking Number FROM iPaaS.com (Order Complete) collection.
The invoice is completed in Heartland.
The Heartland invoice identifier is written to the Heartland Invoice Id custom field on the originating iPaaS.com transaction, which is what prevents the same completed order from being invoiced a second time.
Once all of the order's line items are invoiced, Heartland moves the sales order to a closed status.
Manual Sync:
An iPaaS.com transaction ID is entered on the Manual Sync page.
The transaction is evaluated against both parent filters. Its type and status determine which flow accepts it; a transaction that matches neither is skipped.
The accepting flow then proceeds exactly as described above, including the customer and gift card prerequisites.
Both flows converge on the same Heartland sequence — create the invoice, add lines, add payments, set tracking, complete — so the shape of the resulting Heartland invoice is the same regardless of which trigger produced it. What differs is where the order association comes from and where the invoice identifier is recorded.
Mappings
Add Heartland Invoice FROM iPaaS.com (Invoice)
Mapping Filter
var value = GetCustomFieldValue(CustomFields, "Heartland Invoice Id");
if (Type == "Invoice" && Status == "Complete" && string.IsNullOrEmpty(value)){
return true;//Only invoice completed
}
return false;The filter first reads the Heartland Invoice Id custom field from the transaction, then evaluates a single condition with three parts, all of which must be true for the transaction to be processed:
The transaction's type is Invoice. Orders and tickets are rejected here — an order that is complete is handled by the other flow instead.
The transaction's status is Complete. Invoices that are not yet complete are rejected, because Heartland creates a direct invoice in a complete state.
The Heartland Invoice Id custom field is empty. A transaction that already carries a value in that field has already been invoiced and is rejected, because Heartland allows only one invoice per order and does not support partial invoicing.
If any of the three is false, the filter returns false and the transaction is skipped. Skipped transactions are not errors and do not appear in the error logs.
Description: Creates a new Heartland invoice directly from an iPaaS.com transaction of type Invoice, saving the resulting Heartland invoice identifier as the transaction's external-id link. The parent of the Add Heartland Invoice Line Item FROM iPaaS.com (Invoice), Add Heartland Invoice Payment FROM iPaaS.com (Invoice), and Add Heartland Invoice Tracking Number FROM iPaaS.com (Invoice) child collections.
Mapping Type | Source Field (iPaaS.com) | Destination Field (Heartland) | Description |
Static | "Invoice" | Type | Required. Identifies the transaction as an invoice. The transfer is only processed as an invoice when this value is present; any other value causes Heartland to handle the record as a different transaction type. |
Dynamic Formula |
| CreateInvoice | Required. Signals Heartland to create an invoice from this transaction. The formula always returns true, so every transaction that passes the filter is processed as an invoice creation. The transfer is not handled as an invoice unless this field returns true. |
Static | "complete" | Status | Required. Sets the invoice status to complete. A direct invoice is created in a complete state in Heartland. |
Dynamic Formula |
| CustomerId | Required. Resolves the Heartland customer the invoice is created against. The formula first looks for the Heartland customer identifier already linked to the iPaaS.com customer on this transaction. If no linked Heartland customer is found, it falls back to searching Heartland for a customer whose email address matches the transaction's email address. The resolved value associates the invoice with the correct Heartland customer. If the customer cannot be resolved by either the linked identifier or a matching email, validate the behavior in a staging environment before relying on it in production. |
Dynamic Formula |
| OrderId | Required for this flow. Identifies the original Heartland sales order the invoice is created from. The formula reads the Heartland Invoice Order Id value from the transaction's custom fields; when a value is present it is used as the order to invoice, and when it is absent no order id is sent. A direct invoice requires the original Heartland order id, and that order must be in an open state in Heartland or the transfer is rejected with an error stating the invoice could not be created due to the order's current state. This mapping is unique to this flow — the order-complete flow derives the order association from the linked sales order instead. |
Static | "ExternalId" | SaveInvoiceId | Required. Controls how the resulting Heartland invoice identifier is recorded when CreateInvoice is true. The value ExternalId selects the standard one-to-one workflow: the iPaaS.com transaction is transferred as a new Heartland invoice, and the resulting Heartland invoice identifier is saved as the external-id link on the transaction. If any other value is entered, the invoice identifier is instead saved to an iPaaS.com custom field of that name. For this standalone invoice collection, use ExternalId. |
Field | Heartland Station Id | StationId | Required. Provides the Heartland station for the invoice, sourced from the Heartland Station Id custom field on the iPaaS.com transaction. Heartland requires a station to create a transaction, so populate this custom field with a valid Heartland station id; station ids are visible in the Heartland retail website under Settings and then Locations, after selecting a location name and viewing its station list. Validate this in a staging environment before relying on it in production. |
Field | Heartland Source Location Id | SourceLocationId | Required. Provides the Heartland inventory source location for the invoice, sourced from the Heartland Source Location Id custom field on the iPaaS.com transaction. Heartland requires a source location to create a transaction, so populate this custom field with a valid Heartland location id; location ids are visible in the Heartland retail website under Settings and then Locations. Validate this in a staging environment before relying on it in production. |
Dynamic Formula |
| PublicId | Optional. Sets the public-facing invoice number in Heartland. By default the formula assigns the iPaaS.com transaction number as the invoice's PublicId, overriding the number Heartland would otherwise auto-assign. The formula also carries a commented alternative that, when enabled, returns no value so Heartland keeps its own auto-assigned invoice number. Adjust it if you prefer Heartland's auto-assigned numbers. |
Static | "iPaaS.com" | Transaction Source (custom field) | Recommended when invoices are transferred in both directions. Stamps the created invoice with a Transaction Source of iPaaS.com. This tag lets the opposite-direction Add Heartland Invoice TO iPaaS.com collection recognize and skip invoices that originated in iPaaS.com, preventing a feedback loop between the two systems. Requires a Transaction Source custom field under your Heartland subscription in iPaaS.com and a matching custom field created in Heartland. |
Add Heartland Invoice Line Item FROM iPaaS.com (Invoice)
This is a child collection of Add Heartland Invoice FROM iPaaS.com (Invoice). It does not transfer on its own and has no Manual Sync ID, webhook, or polling schedule of its own.
Mapping Filter
var value = GetCustomFieldValue(CustomFields, "Heartland Invoice Order Line Id");
if(string.IsNullOrEmpty(value)){
throw new exception($"Transaction {Parent.TransactionNumber} can not be invoiced because line item {Sku} is not linked to a Heartland sales order line id. Adjust the mapping collection filter to change this validation.");
}
return true;The filter reads the Heartland Invoice Order Line Id custom field from the line and then takes one of two branches:
The custom field is empty. The filter raises an error rather than skipping the line, and the whole invoice transfer is prevented. The message names the parent transaction number and the SKU of the offending line: "Transaction {Parent.TransactionNumber} can not be invoiced because line item {Sku} is not linked to a Heartland sales order line id. Adjust the mapping collection filter to change this validation." The error surfaces in the iPaaS.com Dashboard error logs. This is a deliberate validation, not a fault — Heartland creates an invoice from an existing sales order, so an unlinked line cannot be invoiced. Subscribers who need a different validation rule can adjust the mapping collection filter, as the message itself indicates.
The custom field holds a value. The filter returns true and the line is processed.
Description: Writes the individual line items of the iPaaS.com invoice transaction to the Heartland invoice created by its parent, resolving the Heartland item from each line's SKU and linking each line back to the Heartland sales order line it invoices.
Mapping Type | Source Field (iPaaS.com) | Destination Field (Heartland) | Description |
Dynamic Formula |
| ItemId | Required. Resolves the Heartland item for the invoice line from the iPaaS.com line SKU. When a matching Heartland item is found, its identifier is used for the invoice line. When no matching item is found, the transfer is prevented and an error is raised stating that the SKU was not found in Heartland; the condition surfaces in the iPaaS.com Dashboard error logs. An invoice line cannot be written without a resolved Heartland item. |
Field | Heartland Invoice Order Line Id | OrderLineId | Required. Links this invoice line to the original Heartland sales order line by writing the Heartland Invoice Order Line Id value into the Heartland OrderLineId field. Heartland creates an invoice from an existing sales order, so each invoiced line must reference the sales order line it applies to. The mapping collection filter prevents the invoice when this value is missing on a line. The source value comes from the iPaaS.com transaction line custom field of the same name, which must be populated on each line before transfer. This mapping is unique to this flow. |
Field | Qty | Qty | Recommended. Carries the quantity from the iPaaS.com invoice line into the Heartland Qty field so the invoiced quantity matches the source line. Confirm the invoiced quantity in a staging environment before relying on it in production. |
Static | "ItemLine" | Type | Fixed. Sets the Heartland line Type to the value ItemLine, identifying the line as a product item line on the invoice and distinguishing it from other line types. Leave it as ItemLine for standard product lines. |
Add Heartland Invoice Payment FROM iPaaS.com (Invoice)
This is a child collection of Add Heartland Invoice FROM iPaaS.com (Invoice). It does not transfer on its own and has no Manual Sync ID, webhook, or polling schedule of its own.
Mapping Filter
1 == 1
This collection carries a filter expression, but it is a constant comparison that is always true. It applies no filtering condition: every payment delivered with the parent invoice transfer is processed and none are skipped. It behaves identically to a collection with no filter applied. Treat it as a starting point for a real condition if you need one — for example, restricting which iPaaS.com payment methods are written to Heartland — rather than as production filtering logic.
Description: Writes each payment on the iPaaS.com invoice transaction to the Heartland invoice created by its parent. A Heartland invoice cannot be completed until a payment has been entered, so the integration creates the invoice, adds the payment through this collection, and then completes the invoice.
Mapping Type | Source Field (iPaaS.com) | Destination Field (Heartland) | Description |
Field | Amount | Amount | Required. Writes the payment amount from the iPaaS.com transaction payment to the Heartland invoice payment. A payment must carry an amount. The amount cannot exceed the remaining balance of the Heartland invoice; if it does, Heartland rejects the payment with a balance error. Because Heartland can store more than two decimal places internally even though its interface shows only two, round payment and tax amounts to two decimal places to avoid balance-mismatch errors. |
Field | Description | Description | Recommended. Writes the payment description from the iPaaS.com transaction payment to the Heartland invoice payment. Heartland requires a description for external-style payments, which is the default payment type for this collection, so mapping a description avoids a rejected payment. Validate this behavior in a staging environment before relying on it in production. |
Static | "complete" | Status | Required. Sets the invoice payment Status to complete. A completed payment is required before the Heartland invoice itself can be completed, so this value is set for every payment. Subscribers do not normally change it. |
Dynamic Formula |
| PaymentTypeId | Optional. Sets the Heartland payment type identifier on the invoice payment. As delivered the formula returns no value, so no built-in Heartland payment type is assigned and the payment is recorded as an external-style payment. The commented block looks up a Heartland payment type identifier from the iPaaS.com payment method name; enable it only if you need this collection to record payments against a specific Heartland payment method. When that lookup is enabled, the transfer is prevented for any payment whose iPaaS.com payment method cannot be matched in Heartland, and that condition surfaces as an error in the iPaaS.com Dashboard error logs. |
Dynamic Formula |
| Type | Optional. Sets the Heartland payment type on the invoice payment. As delivered the formula returns no value, so the payment is recorded as an external-style payment rather than one of Heartland's built-in payment types. Heartland's built-in payment types are CashPayment, CheckPayment, and GiftCardPayment; a subscriber can set this field, together with the matching PaymentTypeId, to record the payment as one of those types instead. Note that this is the one mapping where the two flows differ: the order-complete flow sets this to a fixed external payment value rather than leaving it unset. |
Add Heartland Invoice Tracking Number FROM iPaaS.com (Invoice)
This is a child collection of Add Heartland Invoice FROM iPaaS.com (Invoice). It does not transfer on its own and has no Manual Sync ID, webhook, or polling schedule of its own.
Mapping Filter
This mapping collection does not have a mapping filter applied. All records routed to it are processed without additional filtering conditions.
Description: Adds shipment tracking information to the Heartland invoice created by its parent, before that invoice is completed.
Mapping Type | Source Field (iPaaS.com) | Destination Field (Heartland) | Description |
Field | TrackingNumber | TrackingNumber | Required. Writes the shipment tracking number from the iPaaS.com transaction to the Heartland invoice. This is the only value this collection writes, and it is added to the invoice before the invoice is completed in Heartland. Heartland displays only one tracking number per invoice, so when more than one tracking record is supplied for the same invoice only the last one processed is retained. When the iPaaS.com transaction carries no tracking number, no tracking information is set on the Heartland invoice. Validate this behavior in a staging environment before relying on it in production. |
Update Heartland Invoice FROM iPaaS.com (Order Complete)
Mapping Filter
var value = GetCustomFieldValue(CustomFields, "Heartland Invoice Id");
if (Type == "Order" && Status == "Complete" && string.IsNullOrEmpty(value)){
return true;//Only invoice completed orders once
}
return false;The filter reads the Heartland Invoice Id custom field from the transaction and then evaluates a single condition with three parts, all of which must be true for the transaction to be processed:
The transaction's type is Order. Standalone invoice transactions are rejected here — those are handled by the other flow.
The transaction's status is Complete. An order that has not reached a complete status is rejected, so invoicing happens only when the order is finished.
The Heartland Invoice Id custom field is empty. A completed order whose invoice identifier has already been written is rejected, so a given order is invoiced only once. This is the condition the SaveInvoiceId mapping in this collection exists to satisfy.
If any of the three is false, the filter returns false and the transaction is skipped. Skipped transactions are not errors and do not appear in the error logs.
Description: Creates a Heartland invoice from an iPaaS.com order that has been marked complete and is already linked to an open Heartland sales order. Despite the "Update" in its name, it creates a new invoice; the name refers to the iPaaS.com order update that triggers it. The parent of the Update Heartland Invoice Line Item FROM iPaaS.com (Order Complete), Update Heartland Invoice Payment FROM iPaaS.com (Order Complete), and Update Heartland Invoice Tracking Number FROM iPaaS.com (Order Complete) child collections.
Mapping Type | Source Field (iPaaS.com) | Destination Field (Heartland) | Description |
Static | "Invoice" | Type | Required. Sets the transaction type to Invoice so Heartland processes the record as an invoice rather than an order or ticket. |
Dynamic Formula |
| CreateInvoice | Required. Controls whether the transfer is processed as a Heartland invoice. It returns true so that every completed order passing the collection filter is invoiced in Heartland. If it returned false, the order update would be transferred without generating an invoice. |
Static | "complete" | Status | Required. Sets the invoice status to complete. Creating an invoice from a completed order requires the status to be complete. |
Dynamic Formula |
| CustomerId | Required. Determines the Heartland customer the invoice is billed to. The formula first looks up the Heartland customer already linked to the iPaaS.com order's customer; if the order's customer is not yet linked, it falls back to finding the Heartland customer by the order's email address. The invoice must be associated with a Heartland customer. If neither the linked customer nor the email lookup returns a customer, confirm the customer exists and is linked in a staging environment before relying on this in production. |
Field | Heartland Station Id | StationId | Required. Supplies the Heartland station for the invoice, read from the Heartland Station Id custom field on the iPaaS.com transaction. Heartland's transaction API requires a station when creating an invoice, so this value must be present on the order. Populate the custom field on the order, or adjust the mapping to determine the value through business logic. If the source can be empty, validate the behavior in a staging environment before relying on it in production. |
Field | Heartland Source Location Id | SourceLocationId | Required. Supplies the Heartland inventory source location for the invoice, read from the Heartland Source Location Id custom field on the iPaaS.com transaction. Heartland's transaction API requires an inventory source location when creating an invoice, so this value must be present on the order. Populate the custom field on the order, or adjust the mapping to determine the value through business logic; consult your integration support provider for the correct location value. |
Static | "Heartland Invoice Id" | SaveInvoiceId | Recommended. Controls where the resulting Heartland invoice identifier is stored after the invoice is created, and works together with CreateInvoice. Two kinds of value may be entered: the name of an iPaaS.com transaction custom field, in which case the new Heartland invoice identifier is written to that custom field on the originating transaction; or the value ExternalId, which stores the identifier as the transaction's external ID. The template uses the custom field name Heartland Invoice Id so the identifier is written back to the same custom field the collection filter checks — this is what prevents the completed order from being invoiced a second time. Do not use ExternalId here; that option applies only when creating an invoice from a transaction that is not linked to a sales order. |
Dynamic Formula |
| PublicId | Recommended. Sets the public-facing invoice number in Heartland, overriding Heartland's auto-assigned number. The formula uses the iPaaS.com transaction number with an "-INV" suffix — for example, 100245-INV — so the Heartland invoice number matches the originating transaction while staying distinct from the related order and ticket numbers. The commented alternative, if enabled, returns no value so Heartland assigns its own invoice number instead. |
Static | "iPaaS.com" | Transaction Source (custom field) | Optional. Stores the value iPaaS.com in the Transaction Source custom field on the Heartland invoice, marking the invoice as originating from iPaaS.com. This lets a later transfer of Heartland transactions to iPaaS.com filter out records that iPaaS.com itself created, preventing the same record from echoing back. Requires the Transaction Source custom field to exist for the value to be stored. |
Update Heartland Invoice Payment FROM iPaaS.com (Order Complete)
This is a child collection of Update Heartland Invoice FROM iPaaS.com (Order Complete). It does not transfer on its own and has no Manual Sync ID, webhook, or polling schedule of its own. It is a different collection from Add Heartland Invoice Payment FROM iPaaS.com (Invoice), which belongs to the other parent.
Mapping Filter
This mapping collection does not have a mapping filter applied. All records routed to it are processed without additional filtering conditions.
Description: Writes a payment onto the Heartland invoice created for a linked iPaaS.com order flagged complete, so the parent invoice can be completed. The payment is written as an external payment — one captured outside Heartland, such as a payment collected by the source ecommerce platform.
Mapping Type | Source Field (iPaaS.com) | Destination Field (Heartland) | Description |
Field | Amount | Amount | Required. Writes the iPaaS.com transaction payment amount to the Heartland invoice payment. A payment cannot be added without an amount. Heartland rejects a payment whose amount exceeds the invoice or order balance, returning an error such as "Payment cannot exceed balance of sales order," where the order total is the sum of line item prices, line item taxes, and shipping amounts. Because amounts can carry more than two decimal places internally even though Heartland displays two, round the amount to two decimal places to avoid an unexpected balance error. |
Field | Description | Description | Required. Writes the iPaaS.com transaction payment description to the Heartland invoice payment. Heartland expects a description on an external payment, which is the type this collection uses. If the iPaaS.com description is empty, the Heartland value is written empty, which can cause Heartland to reject the payment. Validate this behavior in a staging environment before relying on it in production. |
Static | "ExternalPayment" | Type | Fixed. Sets the Heartland payment type to ExternalPayment, designating the payment as one captured outside Heartland. Heartland's built-in payment types — CashPayment, CheckPayment, and GiftCardPayment — are identified by numeric payment type identifiers, whereas an external payment does not require one. Heartland allows only Gift Card, Custom, or External payment types to be applied as order deposits, and an External payment type is recommended to represent external order payments imported from iPaaS.com, which is why this collection uses it. Note that the invoice-triggered flow leaves this field unset instead. |
Static | "complete" | Status | Fixed. Sets the Heartland invoice payment status to complete, marking the payment as fully applied so the parent invoice can be completed. The value is a fixed part of this template's external payment flow. |
Dynamic Formula |
| PaymentTypeId | Optional. As delivered this formula returns no value, so no Heartland built-in payment type identifier is assigned. That is appropriate for the external payment type this collection uses, because Heartland does not require a built-in payment type identifier for external payments. The commented block would look up a Heartland payment type identifier from the iPaaS.com payment method name and stop the transfer with an error when no matching Heartland payment type is found. Leaving it commented preserves the default behavior; uncomment it only if you need this collection to resolve and enforce a Heartland built-in payment type from the payment method name. |
Update Heartland Invoice Line Item FROM iPaaS.com (Order Complete)
This is a child collection of Update Heartland Invoice FROM iPaaS.com (Order Complete). It does not transfer on its own and has no Manual Sync ID, webhook, or polling schedule of its own. It is a different collection from Add Heartland Invoice Line Item FROM iPaaS.com (Invoice), which belongs to the other parent and carries an additional order-line mapping and a filter.
Mapping Filter
This mapping collection does not have a mapping filter applied. All records routed to it are processed without additional filtering conditions. Unlike its counterpart under the invoice-triggered parent, this collection performs no order-line validation, because the invoice is generated from the Heartland sales order the transaction is already linked to.
Description: Adds the completed order's line items to the Heartland invoice created by its parent, resolving the Heartland item from each line's SKU and carrying the invoiced quantity.
Mapping Type | Source Field (iPaaS.com) | Destination Field (Heartland) | Description |
Dynamic Formula |
| ItemId | Required. Resolves the Heartland item for the invoice line from the iPaaS.com line SKU. When a matching Heartland item is found, its identifier is used for the invoice line. When no matching item is found, the transfer is prevented and an error is raised stating that the SKU was not found in Heartland and that the transaction cannot be transferred; the condition surfaces in the iPaaS.com Dashboard error logs. An invoice line cannot be written without a resolved Heartland item. |
Field | Qty | Qty | Recommended. Carries the quantity from the iPaaS.com order line into the Heartland Qty field so the invoiced quantity matches the source line. Confirm the invoiced quantity in a staging environment before relying on it in production. |
Static | "ItemLine" | Type | Fixed. Sets the Heartland line Type to the value ItemLine, identifying the line as a product item line on the invoice and distinguishing it from other line types. Leave it as ItemLine for standard product lines. |
Update Heartland Invoice Tracking Number FROM iPaaS.com (Order Complete)
This is a child collection of Update Heartland Invoice FROM iPaaS.com (Order Complete). It does not transfer on its own and has no Manual Sync ID, webhook, or polling schedule of its own. It is a different collection from Add Heartland Invoice Tracking Number FROM iPaaS.com (Invoice), which belongs to the other parent.
Mapping Filter
This mapping collection does not have a mapping filter applied. All records routed to it are processed without additional filtering conditions.
Description: Attaches the shipment tracking number carried on the iPaaS.com transaction to the Heartland invoice created by its parent, before that invoice is completed.
Mapping Type | Source Field (iPaaS.com) | Destination Field (Heartland) | Description |
Field | TrackingNumber | TrackingNumber | Recommended. Writes the iPaaS.com transaction tracking number to the Heartland invoice as shipment tracking information. The value is attached to the invoice before the invoice is completed by the parent transfer. Heartland displays only one tracking number per invoice, so when several tracking records exist for the transaction the integration keeps the last one processed; earlier tracking numbers are not retained. If the iPaaS.com TrackingNumber field is empty when the parent transfer runs, no tracking number is written. Because this collection runs each time the parent invoice transfers, a repeat transfer replaces the Heartland tracking number with the value present on the iPaaS.com transaction at that time. Validate the behavior in a staging environment before relying on it in production, especially where the source transaction may carry an empty tracking value. |
Unmapped Field Overwrite Risk
This direction writes to Heartland, and the transfer sends a partial payload built from the mapped values. Unmapped Heartland fields are generally not cleared — the behavior is not the full-replace behavior that applies when records are written into iPaaS.com. Four qualifications matter, and all four are subscriber-visible.
Invoice header fields fall back to Heartland's own handling. Because Heartland builds invoice and order totals from line items and payments, any Heartland invoice-header field not populated by these mappings takes Heartland's own value rather than being cleared. Both parents create a new invoice on each transfer, and both filters prevent a second invoice for the same transaction, so an existing Heartland invoice is not replaced by a repeat transfer.
Unmapped payment fields are sent empty. This is the one documented exception, and it applies to both payment child collections. Only the fields mapped in the payment collection are sent to Heartland; any Heartland invoice-payment field that is not mapped is sent without a value on the payment that is created. If your business process depends on a Heartland payment field that these collections do not map, do not assume it will be populated.
Payments are added, not updated. Neither payment collection updates or replaces an existing Heartland payment — each adds one. Transferring the same invoice more than once would therefore add a duplicate payment. The parent collection filters are what prevent that from happening, so review both filters and confirm which transactions are eligible before enabling these collections.
Tracking numbers are replaced on every transfer. Each tracking-number collection sets the tracking number on the Heartland invoice from the current iPaaS.com value. If the parent transfer runs again for the same record, the Heartland tracking number is replaced with whatever iPaaS.com holds at that time, and any earlier value is lost. Confirm iPaaS.com holds the intended tracking value before a repeat transfer.
Preservation remedy. For any Heartland field you need to keep, add a Dynamic Formula mapping whose source is DestinationValue.[FieldName] in the collection that writes to that field. That reads the current Heartland value and writes it back, so the field is not overwritten with an empty value.
Validate in staging. Partner-side clearing behavior should be confirmed rather than assumed. Before enabling either flow in production, run a transfer against a Heartland invoice in a staging environment that has values in the Heartland payment fields these collections do not map, and confirm afterward which values survived. Add preservation mappings for anything that did not. Do this separately for each flow — the two payment collections do not carry identical mappings, so their results can differ.
Error Handling
The referenced Heartland order is not open: an invoice may be created only for an order in an open state. If the order named by the OrderId mapping, or the sales order linked to a completed iPaaS.com order, is not open, Heartland rejects the request and the transfer fails with an error indicating the invoice could not be attempted for the order's current state. Confirm the Heartland order status, and confirm your sales order collection creates orders in a non-complete state so they remain invoiceable.
A line item is not linked to a Heartland sales order line: in the invoice-triggered flow, a line whose Heartland Invoice Order Line Id custom field is empty prevents the entire invoice. The error names the transaction number and the SKU of the affected line. Populate the custom field on every line before transferring, or adjust the collection filter if your workflow requires a different validation rule.
A SKU was not found in Heartland: when a line's SKU cannot be matched to a Heartland item, the transfer is prevented and the error names the SKU. Confirm the item exists in Heartland with that SKU, and that the SKU on the iPaaS.com line matches it exactly, before retrying.
Payment cannot exceed balance: Heartland rejects a payment whose amount is greater than the remaining invoice or order balance. The most common cause is hidden decimal precision — Heartland can store more than two decimal places even though its interface displays two. Round payment and tax amounts to two decimal places on the iPaaS.com side and transfer again.
A payment was rejected for a missing description: Heartland expects a description on an external payment. When the iPaaS.com payment description is empty, the value is written empty and Heartland may reject the payment. Populate the description on the iPaaS.com transaction payment and retry.
A payment method could not be found in Heartland: this occurs only when the optional payment-method lookup has been enabled on a PaymentTypeId mapping. The transfer is prevented for any payment whose iPaaS.com payment method has no Heartland match. Either add the matching Heartland payment method or leave the lookup commented so payments are recorded as external-style payments.
The station or source location is missing: Heartland requires both to create a transaction. When the Heartland Station Id or Heartland Source Location Id custom field is empty on the source transaction, the invoice cannot be created. Populate both custom fields, or adjust the mappings to determine the values through business logic, and transfer again.
The invoice transfer was stopped because its customer could not be created: when a transaction references a customer that is not yet linked, the integration transfers the customer first. If that customer transfer fails, the invoice transfer is stopped. Resolve the customer error and transfer the invoice again.
The invoice transfer was stopped because a gift card could not be created: when a payment references an iPaaS.com gift card that is not yet linked, the integration transfers the gift card first. If that transfer fails, the invoice transfer is stopped. Resolve the gift card error and transfer again.
A custom field value was not stored: when a destination Heartland custom field has not been created in Heartland, or the matching iPaaS.com subscription custom field does not exist, the invoice still transfers and the remaining fields are written; only that custom value is not stored. This affects the Transaction Source loop-prevention tag in particular. Create the custom field on both sides and transfer again.
Heartland temporarily unavailable: if the Heartland API cannot be reached when a transfer is triggered, the transfer fails, including its lines, payments, and tracking number. The error appears in the iPaaS.com Dashboard error logs, and the record can be retried through a new transfer or Manual Sync once the underlying condition is resolved.
Nothing happened and there is no error: a transaction that does not satisfy its parent's filter is skipped silently. Check the transaction's type, its status, and whether its Heartland Invoice Id custom field already holds a value.
Testing & Validation
Test Scenarios
Invoice-triggered flow creates an invoice — create an iPaaS.com transaction of type Invoice with a status of Complete, populate its station, source location, and Heartland Invoice Order Id custom fields, transfer it, and confirm a Heartland invoice is created and its identifier is saved as the transaction's external-id link.
Order-complete flow creates an invoice — transfer an iPaaS.com order to Heartland as an open sales order, mark the order Complete in iPaaS.com, transfer the update, and confirm a Heartland invoice is created and its identifier is written to the Heartland Invoice Id custom field rather than the external id.
The two flows do not overlap — confirm that an Invoice-type transaction is not picked up by the order-complete parent, and that an Order-type transaction is not picked up by the invoice-triggered parent.
Double invoicing is prevented — transfer an already-invoiced transaction a second time and confirm it is skipped, with no second Heartland invoice and no error in the logs.
Incomplete status is skipped — transfer a transaction that matches on type but is not Complete, and confirm it is skipped silently.
Invoice number override — confirm the invoice-triggered flow writes the plain iPaaS.com transaction number as the Heartland invoice number, and the order-complete flow writes it with the "-INV" suffix.
Auto-assigned invoice numbers — switch a PublicId formula to its commented alternative, transfer, and confirm Heartland assigns its own invoice number instead.
Customer resolved by external link — transfer a transaction whose customer is already linked to Heartland and confirm the invoice is billed to that Heartland customer.
Customer resolved by email — transfer a transaction whose customer is not linked but whose email matches a Heartland customer, and confirm the invoice is billed to that customer.
Customer prerequisite — transfer a transaction whose customer is neither linked nor matchable by email, and confirm the customer is created in Heartland automatically before the invoice, with no pre-sync step performed by hand.
Customer prerequisite failure stops the invoice — force the customer transfer to fail and confirm the invoice transfer is stopped with an error rather than being written against a missing customer.
Gift card prerequisite — transfer a transaction with a gift card payment whose card is not yet linked to Heartland and confirm the gift card is transferred first.
Zero-balance gift card — with the Adjust Empty Gift Card For Payment setting enabled, transfer a payment against a depleted gift card and confirm the payment is accepted and the card balance is restored afterward. Repeat with the setting disabled and record the difference.
Order-line link missing — remove the Heartland Invoice Order Line Id value from one line of an invoice-type transaction, transfer it, and confirm the whole invoice is prevented with an error naming the transaction number and the SKU.
SKU not found — transfer a line whose SKU does not exist in Heartland and confirm the transfer is prevented with an error naming the SKU, in both flows.
Payment before completion — confirm the Heartland invoice cannot be and is not completed until the payment has been added, and that the completed invoice shows the expected payment.
Payment exceeds balance — transfer a payment amount greater than the invoice balance and confirm Heartland rejects it with a balance error.
Decimal rounding — transfer line-item tax amounts carrying more than two decimal places and confirm whether a balance error results; round to two places and confirm the payment is accepted.
Payment type difference between flows — confirm the order-complete flow records its payment as an external payment type and the invoice-triggered flow records its payment with no built-in payment type, and that both are accepted by Heartland.
Optional payment-method lookup — enable the commented payment-method lookup on a PaymentTypeId mapping, transfer a payment whose method has no Heartland match, and confirm the transfer is prevented with the expected error.
Tracking number written — transfer a transaction with one tracking number and confirm it appears on the completed Heartland invoice.
Multiple tracking numbers — transfer a transaction with several tracking records and confirm only the last one processed appears on the Heartland invoice.
Empty tracking number — transfer a transaction with no tracking number and confirm the invoice still completes with no tracking information and no error.
Missing station or source location — clear the Heartland Station Id custom field, transfer, and confirm the invoice is not created and the error is reported in iPaaS.com. Repeat for Heartland Source Location Id.
Unmapped Heartland payment fields — inspect a Heartland invoice payment created by each flow and record which payment fields were left empty. Add DestinationValue preservation mappings for any value your business relies on.
Loop prevention — with both directions active, confirm an invoice created in Heartland by either flow is not transferred back into iPaaS.com, and that the Transaction Source custom field on the Heartland invoice holds the value iPaaS.com.
Manual Sync by ID — enter a known iPaaS.com transaction ID on the Manual Sync page and confirm the correct flow accepts it and the invoice, its lines, its payment, and its tracking number all transfer.
Order closes after invoicing — after the order-complete flow invoices all of an order's line items, confirm Heartland moves the sales order to a closed status.
Validation Checklist
Every transaction intended for invoicing carries a populated Heartland Station Id and Heartland Source Location Id custom field.
Transactions using the invoice-triggered flow carry a populated Heartland Invoice Order Id, and every one of their lines carries a populated Heartland Invoice Order Line Id.
Only one parent collection is enabled for any given transaction type, so a single invoice is not attempted through both paths.
Heartland sales orders intended for invoicing are created in an open, non-complete state.
The Transaction Source custom field exists in Heartland and under the Heartland subscription in iPaaS.com, and the loop-prevention tag is visible on invoices created from iPaaS.com.
Line-item tax and payment amounts are allocated per line and rounded to two decimal places before transfer.
Every SKU on an invoiced line resolves to an existing Heartland item.
Each invoice carries at least one payment, so the invoice can be completed in Heartland.
The Heartland Invoice Id custom field is populated after an order-complete transfer, and the external-id link is populated after an invoice-triggered transfer.
Heartland payment fields your business relies on have been checked after a transfer in staging, and preservation mappings added for any value that was sent empty.
The Adjust Empty Gift Card For Payment subscription setting is configured to match how your source platform handles depleted gift cards.
Additional Notes
The two flows are chosen by the transaction's type and status, not by the subscriber at transfer time. Subscribers configure which flows are enabled; the filters do the routing.
Both parents write the same static Transaction Source tag, so loop prevention works identically regardless of which flow created the invoice.
The six child collections carry no independent trigger. A line, payment, or tracking number reaches Heartland when its invoice does, and only then.
Invoice updates from iPaaS.com are not supported in either flow. Corrections after an invoice is created must be made in Heartland directly.
Deleting a transaction in iPaaS.com has no effect in Heartland. Removals and reversals must be handled in Heartland.
iPaaS.com is the source of truth for the fields listed under Mappings. Values edited directly on a Heartland invoice are not read back by these collections.
Related Documents
Setup & Reference
Mapping Documentation