Summary
iPaaS.com Transaction records are written out to Heartland as Heartland tickets. iPaaS.com is the source in this direction and Heartland is the system being written to. The parent collection writes the ticket header — inventory source location, station, customer, total, type, status, and public-facing ticket number — and records that the ticket originated in iPaaS.com through a Heartland custom field. The rest of the ticket is assembled by nine child collections that ride with the same transfer.
This is the largest collection family in the integration: one parent and nine children. The children fall into three groups.
Line items: three collections. One writes the transaction's product lines. Two more create dedicated Heartland lines for the transaction's shipping amount and tax amount, because Heartland tickets do not accept header-level shipping and tax totals.
Payments: five collections, one for each Heartland payment type — cash, check, custom, external, and gift card. Heartland requires a different request format per payment type, so each payment is routed to exactly one of the five by a custom field on the iPaaS.com payment.
Notes: one collection, which writes the transaction's notes onto the ticket.
This article covers all ten collections in this direction. Heartland tickets transferred into iPaaS.com are handled by a separate family of collections, headed by Add Heartland Ticket TO iPaaS.com, and are documented separately.
How a ticket is assembled
A single ticket transfer writes one Heartland ticket and then adds everything that hangs off it. The parent collection decides whether a given iPaaS.com transaction is a ticket at all; the children decide what goes on it. Nothing in this family transfers on its own — every child runs only as part of a parent ticket transfer, and none has a webhook, polling schedule, or Manual Sync entry of its own.
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. Transferring a transaction this way also transfers its line items, shipping and tax lines, payment, and notes through the child collections. Confirm the exact identifier to enter in a staging environment before relying on it in production.
External ID Format
After a successful transfer, the Heartland ticket's identifier is saved in iPaaS.com as the external-id link between the two systems. Because Heartland reuses numeric identifiers across different transaction types, the stored external ID carries a type suffix so the values stay unique — a ticket is stored in the form 105432_TICKET.
That suffix matters when you transfer several Heartland transaction types. iPaaS.com requires a unique transaction number, and referencing the external ID rather than a bare numeric identifier keeps ticket, order, and invoice values from colliding.
Deleted Record Support
Deleting a ticket is not supported in this direction. The integration creates Heartland tickets; deleting or voiding a Transaction record in iPaaS.com does not delete the linked Heartland ticket, and there is no delete path for tickets, their lines, their payments, or their notes. Tickets that should no longer stand in Heartland must be handled directly in Heartland.
Custom Field Support
This direction uses iPaaS.com custom fields both as sources and as a destination, and the family cannot function without the source custom fields.
Heartland Source Location Id (source): supplies the inventory source location on the ticket header. Heartland requires an inventory source location to create a ticket.
Heartland Station Id (source): supplies the station on the ticket header, and is read again by the cash and check payment collections from the parent transaction. Heartland requires a station to create a ticket.
Heartland Payment Type (source): set on the iPaaS.com transaction payment. This is the value that routes a payment to one of the five payment child collections. See Payment Routing below.
Transaction Source (destination): a Heartland custom field on the ticket, set to a static value of iPaaS.com so tickets created by iPaaS.com can be identified and, if needed, excluded from a transfer back to iPaaS.com.
Prerequisites. The source custom fields must exist on the iPaaS.com Transaction and Transaction Payment collections and hold the correct values before a ticket can be written. A Heartland custom field used as a destination must be created in Heartland first, or its value is not stored. Tickets and orders require separate custom-field group definitions in Heartland even though both use the Transaction collection type in iPaaS.com. The Heartland location and station identifiers are visible in the Heartland retail website under Settings, then Locations; station identifiers appear in a location's station list.
To supply a Heartland custom-field value from an iPaaS.com custom field, add a mapping whose source calls GetValueFromCustomField with the iPaaS.com custom field name, and choose the Heartland custom field as the destination.
Mapping Collection Status
Status: Enabled. The parent and all nine child collections are enabled in the template.
Trigger Events: Outbound transfers are triggered from iPaaS.com. When the subscription is configured and enabled, an eligible iPaaS.com Transaction is transferred to Heartland automatically; the integration recognizes transaction creation and transaction update events, along with transaction polling. No automatic transfers occur until the subscription is configured and enabled. A specific transaction can also be transferred on demand from the iPaaS.com Manual Sync page.
The nine child collections have no trigger of their own. They run whenever the parent collection transfers a ticket.
Duplicate or Conflicting Mappings
Ten mapping collections operate on ticket data in this outbound direction: the parent and its nine children. Within the family the children do not compete with each other, because each is scoped to a different part of the ticket and the five payment collections are made mutually exclusive by their filters.
Other collections operate on the same iPaaS.com transaction data and should be reviewed together with this family.
Add Heartland Ticket TO iPaaS.com: the opposite direction. It creates iPaaS.com transactions from Heartland tickets, and has its own child line-item and payment collections and its own article. It is the inbound counterpart of this family, not a member of it.
Add/Update Heartland Sales Order FROM iPaaS.com: writes sales orders to Heartland from iPaaS.com transactions. It handles a different transaction type but shares the same source custom fields and helper behavior, so review both when planning transaction data flows.
Add Heartland Sales Order Note FROM iPaaS.com: writes transaction notes to a Heartland sales order rather than a ticket. It applies to the sales order transfer path; Add Heartland Ticket Note FROM iPaaS.com applies to the ticket transfer path.
Important: template mapping collections are provided for every transaction type in both directions, but it is not recommended to run them all bidirectionally. Before running inbound and outbound directions together, review your mapping collection filters and clearly define which system is the source of truth for each transaction type, so changes do not propagate back and forth between the systems and create a feedback loop.
Collision Handling
This integration does not use iPaaS.com collision handling for tickets. Which Heartland records a ticket is attached to is determined by the external-id links and the lookups performed inside the mappings; there is no collision recovery step to configure.
Supported Child Collections
All nine collections below are children of Add Heartland Ticket FROM iPaaS.com. None of them transfers on its own.
Add Heartland Ticket Line Item FROM iPaaS.com: writes the ticket's product line items. Stops the transfer with an error when a line's SKU cannot be found in Heartland.
Add Heartland Ticket Shipping Amount Line Item FROM iPaaS.com: adds a dedicated shipping line to the ticket when the transaction has a shipping amount greater than zero.
Add Heartland Ticket Tax Amount Line Item FROM iPaaS.com: adds a dedicated tax line to the ticket when the transaction has a tax amount greater than zero.
Add Heartland Ticket Cash Payment FROM iPaaS.com: writes a cash payment on the ticket.
Add Heartland Ticket Check Payment FROM iPaaS.com: writes a check payment on the ticket.
Add Heartland Ticket Custom Payment FROM iPaaS.com: writes a custom payment on the ticket. Stops the transfer with an error when the payment method cannot be found in Heartland.
Add Heartland Ticket External Payment FROM iPaaS.com: writes an external payment on the ticket.
Add Heartland Ticket Gift Card Payment FROM iPaaS.com: writes a gift-card payment on the ticket. Stops the transfer with an error when the referenced gift card does not exist in Heartland.
Add Heartland Ticket Note FROM iPaaS.com: writes the transaction's notes to the ticket.
Error conditions raised by any child collection surface in the iPaaS.com Dashboard error logs and stop the whole ticket transfer, so no partial ticket is left in Heartland.
Payment Routing
Heartland requires a different payment request format for each payment type, which is why five payment collections exist instead of one. Each collection's filter reads the Heartland Payment Type custom field on the iPaaS.com transaction payment and processes the payment only when the value matches its own type: "CashPayment", "CheckPayment", "CustomPayment", "ExternalPayment", or "GiftCardPayment".
The routing is exclusive and exhaustive in one direction only. Because the five values are distinct, a payment can match at most one collection. But a payment whose Heartland Payment Type custom field is empty, missing, or holds a value that is not one of the five matches no collection — every filter returns false, no payment is written to the Heartland ticket, and no error is raised. The ticket is still created, silently, without that payment. Populate the Heartland Payment Type custom field on every iPaaS.com payment you expect to reach Heartland, and verify payments landed after a transfer rather than assuming they did.
Synthetic Shipping and Tax Lines
Unlike sales orders, Heartland tickets do not accept header-level shipping and tax totals. Heartland recalculates a ticket's total from its lines, so a shipping charge or a tax amount that exists only on the iPaaS.com transaction header is simply not applied to a Heartland ticket.
The template solves this by adding the amounts as lines of their own. The shipping-amount and tax-amount collections are parent-only collections: instead of iterating the transaction's product lines, each runs once against the transaction's header totals and creates a single Heartland line. Each filter requires the parent-only line, requires the corresponding header amount to be present, and requires it to be greater than zero, so no empty shipping or tax line is created for a transaction that has neither.
Three differences from a product line are worth knowing:
Line type: a product line is written with Heartland's ItemLine type and points at a Heartland item resolved from the line's SKU. The shipping line is written with the ShippingLine type and the tax line with the TaxLine type; neither references a Heartland item, because neither represents a product.
Amount, not price and quantity: a product line carries a quantity and per-unit prices. The shipping and tax lines carry a single value taken from the parent transaction header, and the tax line explicitly writes no quantity.
Persistence: the tax line must be flagged as manually added, or Heartland removes it during its own tax recalculation and the imported tax amount does not survive on the ticket. That flag is supplied by the template and should be left in place.
Round tax amounts to two decimal places before they reach Heartland. Heartland can store more precision than the two decimal places it displays, and the extra decimals show up later as a payment that Heartland refuses because it exceeds the ticket balance.
System Caveats
Heartland Caveats
Source location and station required: Heartland requires an inventory source location and a station to create a ticket. Both are supplied from iPaaS.com custom fields on the transaction; populate those custom fields with the correct Heartland identifiers.
Totals recalculated from line items: Heartland recalculates ticket totals from its lines and does not accept header-level shipping and tax on tickets. Shipping and tax must be added as lines.
Tax lines are removed unless flagged: Heartland strips an imported tax line during recalculation unless the line is flagged as manually added.
Payment cannot exceed the ticket total: a payment is accepted only when its amount does not exceed the ticket total, which Heartland calculates from line item prices, line item taxes, and shipping amounts. A value carrying more than two decimal places can trigger a "Payment cannot exceed balance of the ticket" error even though the extra decimals are not shown in the Heartland ticket.
Deposit eligibility is limited: Heartland allows only gift card, custom, or external payment types to be applied as ticket deposits. A cash or check payment sent as a deposit is rejected by Heartland.
Gift card balance required: Heartland requires an available gift card balance equal to or greater than the payment amount, regardless of whether the ticket ultimately reduces the balance.
Custom field visibility: a Heartland custom field must be created in Heartland before it is available to mappings, and tickets require their own custom-field group definitions separate from orders.
iPaaS.com Caveats
Manual Sync uses the iPaaS.com ID: Manual Sync in this direction takes the iPaaS.com transaction identifier, not a Heartland identifier.
Source custom fields are prerequisites: the Heartland Source Location Id, Heartland Station Id, and Heartland Payment Type custom fields must exist on the appropriate iPaaS.com collections and hold correct values before a ticket, or a payment on it, can be written.
Unique transaction number: iPaaS.com requires a unique transaction number. When transferring multiple Heartland transaction types, reference the external ID so the "_TICKET" designation keeps the value unique.
Empty source values are written through: where a payment amount or description is empty on the iPaaS.com side, the Heartland value is written empty, which can cause Heartland to reject the payment.
Integration-Specific Caveats
Gift-card balance behavior is undocumented: the combinations of payment status and deposit flag that reduce or preserve a Heartland gift card balance are not documented or supported by Heartland and are subject to change at any time. They are provided for demonstration and may be used at your own risk.
An optional setting handles depleted gift cards: an optional subscription setting, Adjust Empty Gift Card For Payment, addresses gift cards that have been fully depleted on another platform. When it is enabled and a gift-card payment references a card with a zero balance, the card balance in Heartland is raised enough to accept the full payment, the payment is added, and the zero balance is then restored. Set the subscription setting to "true" to enable it.
One failure stops the whole ticket: an unresolvable SKU, payment method, or gift card stops the entire ticket transfer rather than skipping the offending line or payment. That is deliberate — it prevents a partially assembled ticket in Heartland.
A payment that matches no collection is silent: as described under Payment Routing, a payment with no recognized Heartland Payment Type value produces no payment and no error.
Transfers are additive: an outbound transfer never removes a Heartland ticket, line, payment, or note.
Setup Requirements
Heartland Configuration
Note the Heartland location and station identifiers you intend to use, from Settings and then Locations in the Heartland retail website.
Create any Heartland custom field you intend to map — including the Transaction Source field used by the template — with a custom-field group definition for tickets.
Confirm every product that can appear on a transferred transaction exists in Heartland with a SKU that matches the iPaaS.com line SKU.
Confirm every payment method used on iPaaS.com transactions exists as a payment type in Heartland, so the custom payment lookup can resolve it by name.
Confirm any gift card referenced by a payment exists in Heartland, or allow the automatic gift-card prerequisite step to create it.
iPaaS.com Configuration
Enable the subscription so outbound transfers can run.
Create the Heartland Source Location Id and Heartland Station Id custom fields on the Transaction collection and populate them with the correct Heartland identifiers.
Create the Heartland Payment Type custom field on the Transaction Payment collection and set it on every payment that should reach Heartland.
Replace the placeholder custom-data values in the check and custom payment collections with the information you want stored, or switch each to the empty-object form.
Decide whether Heartland should keep its auto-assigned ticket number, and adjust the ticket-number mapping accordingly.
Set the Adjust Empty Gift Card For Payment subscription setting if you transfer gift-card payments against cards that may be depleted.
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
Automatic outbound transfer:
A Transaction record is created or changed in iPaaS.com and the subscription is enabled.
The parent mapping filter is evaluated. The transaction proceeds only when it is a ticket and its transaction number does not carry the gift-card or deposit suffix; otherwise no Heartland ticket is created by this family.
Before anything is written, the integration resolves the records the ticket depends on. First the customer: when the transaction references an iPaaS.com customer that has no external-id link to Heartland, the integration retrieves that customer and transfers it to Heartland. If the customer transfer fails, the ticket transfer is stopped with an error rather than being written against a missing customer.
Then any gift card referenced by a payment: for each payment carrying a gift-card reference, the integration checks whether that gift card is already linked to a Heartland gift card. When it is not linked, the gift card is retrieved and transferred to Heartland; if that transfer fails, the ticket transfer is stopped with an error. When it is already linked, no transfer occurs unless the Adjust Empty Gift Card For Payment setting is enabled and the card balance is zero, in which case the balance is raised to cover the payment and the gift card is re-transferred.
The ticket header is written to Heartland from the parent mappings, resolving the Heartland customer through the saved external-id link or, failing that, by the transaction's email address.
The child collections write the ticket's contents in the same operation: product lines, a shipping line and a tax line where the transaction has those amounts, the payment routed by its Heartland Payment Type value, and any notes.
The Heartland ticket's identifier is saved in iPaaS.com as the external-id link, with the ticket type suffix appended.
Manual Sync:
An iPaaS.com transaction ID is entered on the Manual Sync page.
The integration transfers that single transaction and its lines, payments, and notes through the same prerequisite and mapping path described above.
Transfer stopped by an unresolvable record:
A ticket transfer begins and the prerequisite steps complete.
A child mapping cannot resolve a required Heartland record — a line SKU with no matching Heartland item, a payment method name with no matching Heartland payment type, or a gift-card reference with no matching Heartland gift card.
The mapping raises an error and the whole ticket transfer stops. No partial ticket is created in Heartland.
The error appears in the iPaaS.com Dashboard error logs. After the missing record is created in Heartland, or the source value is corrected in iPaaS.com, the transaction can be transferred again.
The gift-card prerequisite in this outbound direction applies to any transaction that reaches this step and carries a gift-card payment reference; it is not restricted by transaction type. The type-restricted gift-card step that applies only when the transaction type is Ticket belongs to the opposite, inbound direction, where gift cards are resolved from ticket line items rather than from payments. Subscribers configuring this outbound family should not expect a ticket-type gate on the gift-card prerequisite here.
Mappings
Add Heartland Ticket FROM iPaaS.com
Mapping Filter
Type == "Ticket"
&& !TransactionNumber.Endswith("-GC")
&& !TransactionNumber.Endswith("-D")The filter admits a transaction only when all three conditions hold.
Type is "Ticket": iPaaS.com transactions of any other type — sales orders and invoices, for example — are not processed by this collection and are handled by their own collections.
The transaction number does not end with "-GC": this suffix identifies gift-card records, which are skipped so they are not recreated as tickets.
The transaction number does not end with "-D": this suffix identifies deposit-ticket copies. A deposit ticket is an exact copy of an original order, created in iPaaS.com with "-D" appended to the transaction number and to all external record identifiers so other integrations see a compatible record. Excluding it here prevents that copy from being written back to Heartland as a second ticket.
A transaction that fails any condition is not processed by this collection, and no error is raised. The filter throws no message of its own.
Description: Creates a Heartland ticket from an iPaaS.com Transaction, writing the ticket header. The parent of all nine child collections listed under Supported Child Collections, which assemble the ticket's lines, payment, and notes in the same transfer.
Mapping Type | Source Field (iPaaS.com) | Destination Field (Heartland) | Description |
Field | Heartland Source Location Id (custom field) | SourceLocationId | Required. Writes the ticket's inventory source location in Heartland from the iPaaS.com Heartland Source Location Id custom field. Heartland requires an inventory source location to create a ticket, so this value must be supplied; the custom field must exist on the Transaction collection in iPaaS.com and hold the correct Heartland location identifier. The Heartland location identifiers are visible in the Heartland retail website under Settings, then Locations. |
Field | Heartland Station Id (custom field) | StationId | Required. Writes the ticket's station in Heartland from the iPaaS.com Heartland Station Id custom field. Heartland requires a station to create a ticket, so this value must be supplied; the custom field must exist on the Transaction collection in iPaaS.com and hold the correct Heartland station identifier. The station identifiers are visible under Settings, then Locations, after selecting a location and viewing its station list. |
Static | "Ticket" | Type | Required. Writes a static value of Ticket to the Heartland transaction type so the record is created as a ticket. This value determines that the transaction is written to Heartland as a ticket rather than another transaction type. |
Static | "complete" | Status | Required. Writes a static value of complete to the Heartland ticket's status so the ticket is created in a completed state. Adjust this mapping if your workflow needs the ticket to be created in a different state; note that the ticket status interacts with gift-card balance behavior on the gift-card payment collection. |
Dynamic Formula |
| CustomerId | Recommended. Resolves the Heartland customer the ticket belongs to. The formula first looks up the Heartland customer already linked to the transaction's iPaaS.com customer; if no linked Heartland customer is found, it falls back to finding a Heartland customer by the transaction's email address. Map this so the ticket is associated with the correct customer. Whether Heartland requires a customer on every ticket is not documented for this integration, so validate the behavior in a staging environment before relying on it in production. |
Field | Total | Total | Recommended. Writes the ticket total in Heartland from the iPaaS.com transaction Total. Heartland recalculates the ticket total from its line items, and a payment can only be written when the payment amount does not exceed that total, so make sure line items, shipping, and tax are supplied so the recalculated total matches. |
Dynamic Formula |
| PublicId | Optional. Writes the iPaaS.com transaction number to the Heartland ticket's public-facing number, overriding the number Heartland would auto-assign. The formula returns the transaction number by default; a commented-out alternative is included that returns no value, which can be enabled instead to leave Heartland's auto-assigned ticket number in place. When transferring several Heartland transaction types, reference the external ID for the transaction number so the "_TICKET" designation keeps the value unique. |
Static | "iPaaS.com" | Transaction Source (custom field) | Optional. Writes a static value of iPaaS.com to the Transaction Source custom field on the Heartland ticket so tickets created by iPaaS.com can be identified and, if needed, excluded from a transfer back to iPaaS.com. The Heartland custom field must exist in Heartland before its value can be written. |
Add Heartland Ticket Line Item FROM iPaaS.com
This is a child collection of Add Heartland Ticket FROM iPaaS.com. 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: Writes the iPaaS.com transaction's lines to the Heartland ticket as product item lines, resolving each line's Heartland item from its SKU. This is the product-line collection; the shipping and tax amounts are handled by the two sibling line-item collections instead.
Mapping Type | Source Field (iPaaS.com) | Destination Field (Heartland) | Description |
Dynamic Formula |
| ItemId | Required. Sets the Heartland item the ticket line is for. The formula takes the SKU from the iPaaS.com transaction line and looks up the matching Heartland item using the GetItemIdBySku helper; when a matching item is found, its Heartland item id is written to the line. The referenced product must already exist in Heartland with a SKU that matches the iPaaS.com line SKU. If no matching item is found, the mapping raises the error "Sku: [SKU] was not found in Heartland preventing this transaction from transferring" and the entire ticket transfer stops, so no partial ticket is created. Resolve this in one of two ways before transferring: either add the missing product to Heartland with a matching SKU, or correct the SKU on the iPaaS.com transaction line. |
Static | "ItemLine" | Type | Required. Sets a fixed value of ItemLine on the Heartland ticket line, marking it as a product item line as opposed to the shipping and tax lines added by the sibling collections. This is a fixed Heartland line-type value, not a placeholder to change. |
Field | Qty | Qty | Required. Writes the iPaaS.com transaction line quantity to the Heartland ticket line, because a ticket line must carry the number of units being sold. Validate this in a staging environment before relying on it in production. |
Field | UnitPrice | AdjustedUnitPrice | Recommended. Writes the iPaaS.com transaction line's unit price to the Heartland ticket line as the adjusted, actually charged per-unit price, so the Heartland line reflects the price the customer was charged in the source system. There is no separately published Heartland field specification for ticket line items, so validate this in a staging environment before relying on it in production. |
Field | OriginalUnitPrice | OriginalUnitPrice | Recommended. Writes the iPaaS.com transaction line's original unit price to the Heartland ticket line as the reference, or list, per-unit price. There is no separately published Heartland field specification for ticket line items, so validate this in a staging environment before relying on it in production. |
Add Heartland Ticket Shipping Amount Line Item FROM iPaaS.com
This is a child collection of Add Heartland Ticket FROM iPaaS.com. It does not transfer on its own and has no Manual Sync ID, webhook, or polling schedule of its own.
Mapping Filter
SourceTypeName=="ParentOnly" && Parent.ShippingAmount != null && Parent.ShippingAmount > 0
The filter admits the line only when all three conditions hold.
The line is the parent-only line: this is the synthetic line that carries the transaction's header totals rather than a real product line. Requiring it means this collection runs once per ticket, not once per product line, so a transaction with ten products still produces exactly one shipping line.
The transaction's shipping amount is present: a transaction with no shipping amount at all produces no shipping line.
The shipping amount is greater than zero: a zero shipping amount produces no shipping line, so free shipping does not add an empty line to the Heartland ticket.
When the line is not created the ticket transfers normally without one, and no error is raised. The filter throws no message of its own. Subscribers who need a different rule for when a shipping line is added can adjust this filter.
Description: Creates a single dedicated Heartland ticket line carrying the transaction's shipping charge, because Heartland tickets do not accept a header-level shipping total.
Mapping Type | Source Field (iPaaS.com) | Destination Field (Heartland) | Description |
Static | "ShippingLine" | Type | Required. Sets the line type to the fixed value ShippingLine, identifying the line to Heartland as the ticket's shipping charge rather than a product line. Heartland uses the line type to treat the amount as shipping when it recalculates the ticket total. This is a fixed Heartland line type and is not customized per transaction. |
Dynamic Formula |
| Value | Required for the shipping line to be meaningful. Sets the shipping line's amount from the parent transaction's shipping total, so the Heartland ticket's shipping line carries the same shipping amount that appears on the iPaaS.com transaction header. The collection filter only creates this line when the transaction's shipping amount is present and greater than zero, so the line is not added for transactions without shipping. |
Add Heartland Ticket Tax Amount Line Item FROM iPaaS.com
This is a child collection of Add Heartland Ticket FROM iPaaS.com. It does not transfer on its own and has no Manual Sync ID, webhook, or polling schedule of its own.
Mapping Filter
SourceTypeName=="ParentOnly" && Parent.TaxAmount != null && Parent.TaxAmount > 0
The filter admits the line only when all three conditions hold.
The line is the parent-only line: the synthetic line carrying the transaction's header totals, so this collection runs once per ticket and produces a single tax line rather than one per product line.
The transaction's tax amount is present: a transaction with no tax amount produces no tax line.
The tax amount is greater than zero: a zero tax amount produces no tax line, so a tax-exempt transaction does not carry an empty tax line into Heartland.
When the line is not created the ticket transfers normally without one, and no error is raised. The filter throws no message of its own.
Description: Creates a single dedicated Heartland ticket line carrying the transaction's sales tax, because Heartland tickets do not accept a header-level tax total, and flags the line so Heartland's tax recalculation does not remove it.
Mapping Type | Source Field (iPaaS.com) | Destination Field (Heartland) | Description |
Static | "TaxLine" | Type | Required. Sets the line type to the fixed value TaxLine, identifying the line to Heartland as the ticket's tax charge rather than a product line. Heartland uses the line type to treat the amount as tax when it recalculates the ticket total. This is a fixed Heartland line type and is not customized per transaction. |
Dynamic Formula |
| Value | Required for the tax line to be meaningful. Sets the tax line's amount from the parent transaction's tax total, so the Heartland ticket's tax line carries the same tax amount that appears on the iPaaS.com transaction header. The collection filter only creates this line when the transaction's tax amount is present and greater than zero. Heartland can store more precision than the two decimal places it displays; round tax amounts to two decimal places to avoid ticket totals and payment amounts that do not reconcile. |
Dynamic Formula |
| ManuallyAdded | Required to add tax amounts to imported tickets. Flags the tax line as manually added by always returning true. Heartland removes tax lines during its own tax recalculation unless the line is flagged as manually added, so without this flag the imported tax amount does not persist on the ticket. Leave this mapping in place; removing it causes Heartland to strip the tax line. |
Static | "Imported Tax Amount" | Description | Recommended. Sets a fixed label of Imported Tax Amount on the tax line so the added line is identifiable on the Heartland ticket. This is a fixed label applied to every tax line this collection creates; it is not customized per transaction. Subscribers who prefer a different label can change the static value. |
Dynamic Formula |
| Qty | Optional. Leaves the tax line without a quantity by returning null. This is appropriate for a tax line, which represents a tax amount rather than a count of units. |
Add Heartland Ticket Cash Payment FROM iPaaS.com
This is a child collection of Add Heartland Ticket FROM iPaaS.com. 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 Payment Type");
if(!string.IsNullOrEmpty(value)){
if(value == "CashPayment"){return true;}
}
return false;The filter reads the Heartland Payment Type custom field from the iPaaS.com transaction payment and takes one of three paths.
The custom field holds "CashPayment": the filter returns true and this collection writes the payment as a Heartland cash payment.
The custom field holds any other value: the filter returns false. The payment is skipped here and handled by whichever sibling payment collection matches its value.
The custom field is empty or missing: the filter returns false without evaluating further. If no sibling collection matches either, no payment is written at all.
The filter raises no error and throws no message in any branch.
Description: Writes a cash payment onto the Heartland ticket created by its parent collection. One of five type-specific payment children; Heartland requires a different request format for each payment type.
Mapping Type | Source Field (iPaaS.com) | Destination Field (Heartland) | Description |
Static | "CashPayment" | Type | Required. Identifies the payment as a cash payment and selects the Heartland cash payment request format. Heartland's built-in payment types are CashPayment (payment type identifier 1), CheckPayment (identifier 2), and GiftCardPayment (identifier 3); this collection uses CashPayment. This value works together with the Heartland Payment Type custom field, which routes cash payments to this collection. |
Static | "1" | PaymentTypeId | Required for cash payments. Sets the Heartland payment type identifier to 1, which is Heartland's built-in identifier for the cash payment type. This is a fixed Heartland system value for cash and should not be changed for this collection. |
Field | Amount | Amount | Required. Writes the iPaaS.com transaction payment amount to the Heartland cash payment. A payment must carry an amount to be applied, so this value should always be present. Heartland rejects a payment whose amount exceeds the ticket balance, so confirm the payment amount does not exceed the ticket total and round amounts to two decimal places to avoid a "payment cannot exceed balance" error. Because there is no separate local Heartland payment specification available for this documentation, validate this field in a staging environment before relying on it in production. |
Static | "complete" | Status | Recommended. Sets the Heartland payment status to complete so the cash payment is recorded as fully applied on the ticket. Because there is no separate local Heartland payment specification available for this documentation, validate this value in a staging environment before relying on it in production. |
Dynamic Formula |
| Deposit | Required. Always returns false so the cash payment is never applied as a deposit. Heartland does not allow cash payments to be added as deposits; if a cash payment is flagged as a deposit, the Heartland Order API returns an error and the failure surfaces in the iPaaS.com Dashboard error logs. Leave this mapping set to false for cash payments. |
Dynamic Formula |
| StationId | Required. Supplies the Heartland station identifier that is required when applying a cash payment. The formula reads the Heartland Station Id custom field from the parent ticket transaction; if that custom field holds a value, it is passed to Heartland as a numeric station identifier, and if it is empty, no station identifier is sent. Confirm that the parent ticket supplies the Heartland Station Id custom field. Station identifiers are visible in the Heartland retail website under Settings and Locations, in the station list for a location. Validate this behavior in a staging environment before relying on it in production. |
Add Heartland Ticket Check Payment FROM iPaaS.com
This is a child collection of Add Heartland Ticket FROM iPaaS.com. 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 Payment Type");
if(!string.IsNullOrEmpty(value)){
if(value == "CheckPayment"){return true;}
}
return false;The filter reads the Heartland Payment Type custom field from the iPaaS.com transaction payment and takes one of three paths.
The custom field holds "CheckPayment": the filter returns true and this collection writes the payment as a Heartland check payment.
The custom field holds any other value: the filter returns false and the payment is left to the sibling collection that matches its value.
The custom field is empty or missing: the filter returns false immediately.
The filter raises no error and throws no message in any branch.
Description: Writes a check payment onto the Heartland ticket created by its parent collection, including the custom object Heartland requires on a check payment.
Mapping Type | Source Field (iPaaS.com) | Destination Field (Heartland) | Description |
Static | "CheckPayment" | Type | Required. Sets the Heartland payment type to the fixed value CheckPayment, designating the payment as a check. Heartland's built-in payment types are identified by both a name and a numeric identifier: CashPayment (identifier 1), CheckPayment (identifier 2), and GiftCardPayment (identifier 3). This value pairs with the PaymentTypeId mapping, which supplies the matching identifier 2. The value is a fixed part of this template's check payment flow. |
Static | "2" | PaymentTypeId | Required. Sets the Heartland built-in payment type identifier for the payment to the fixed value 2, which is Heartland's identifier for the check payment type. The value corresponds to the check payment type set on the Type mapping and is a fixed part of this template's check payment flow. |
Field | Amount | Amount | Required. Writes the iPaaS.com transaction payment amount to the Heartland check payment; a payment cannot be added without an amount. Heartland rejects a payment whose amount exceeds the ticket total, returning an error such as "Payment cannot exceed balance of the ticket," where the ticket 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, rounding the amount to two decimal places is recommended to avoid an unexpected balance error. If the iPaaS.com amount is empty, the Heartland value is written empty; validate this behavior in a staging environment before relying on it in production. |
Dynamic Formula |
| StationId | Required. Supplies the station identifier that Heartland requires on a check payment. The formula reads the Heartland Station Id custom field from the parent ticket, and when a value is present it converts it to a whole number and writes it to the payment; when no value is present it writes nothing. Ensure the parent ticket carries a Heartland Station Id value. If the parent ticket has no Heartland Station Id, no station is written and Heartland may reject the payment; validate this behavior in a staging environment before relying on it in production. |
Dynamic Formula |
| Custom | Required. Supplies the custom object that Heartland requires on a check payment, even when it is empty. As delivered, the formula builds a small object containing a single example detail value and returns it as the payment's custom data; it also includes a commented-out alternative that returns an empty object instead. The example check detail is a template placeholder — replace it with the check information you want to store on the Heartland payment, or switch to the empty-object form if you do not need to store any. Leave a value returned even if it is empty. |
Static | "complete" | Status | Recommended. Sets the Heartland check payment status to the fixed value complete, marking the payment as fully applied to the ticket. The value is a fixed part of this template's check payment flow. |
Add Heartland Ticket Custom Payment FROM iPaaS.com
This is a child collection of Add Heartland Ticket FROM iPaaS.com. 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 Payment Type");
if(!string.IsNullOrEmpty(value)){
if(value == "CustomPayment"){return true;}
}
return false;The filter reads the Heartland Payment Type custom field from the iPaaS.com transaction payment and takes one of three paths.
The custom field holds "CustomPayment": the filter returns true and this collection writes the payment as a Heartland custom payment, resolving the Heartland payment type from the payment method name.
The custom field holds any other value: the filter returns false and the payment is handled by the matching sibling collection.
The custom field is empty or missing: the filter returns false immediately.
The filter raises no error and throws no message in any branch. Note that this collection is the one whose mappings can stop a transfer: an unmatched payment method name raises an error from the payment-type mapping, not from this filter.
Description: Writes a custom payment onto the Heartland ticket created by its parent collection, resolving the Heartland payment type by name from the iPaaS.com payment method. Custom payment types are eligible to be applied as Heartland ticket deposits, and the template applies this one as a deposit.
Mapping Type | Source Field (iPaaS.com) | Destination Field (Heartland) | Description |
Static | "CustomPayment" | Type | Required. Sets the payment Type to the static value CustomPayment so Heartland applies the custom payment request format. Heartland's built-in payment types are CashPayment (payment type id 1), CheckPayment (id 2), and GiftCardPayment (id 3); custom payment types are defined in Heartland and resolved by name through the PaymentTypeId mapping. Leave this value set to CustomPayment for this collection; the sibling cash, check, gift card, and external payment collections set their own type values. |
Dynamic Formula |
| PaymentTypeId | Required. Sets the Heartland payment type id for the custom payment by resolving the iPaaS.com payment method name to a Heartland payment type through a built-in lookup helper. A custom payment must be tied to an existing Heartland payment type. If the payment method name cannot be matched, the transfer is prevented and the condition surfaces in the iPaaS.com Dashboard error logs as an error stating that the payment method could not be found in Heartland. Confirm that every payment method used on iPaaS.com transactions exists as a payment type in Heartland, and validate this behavior in a staging environment before relying on it in production. |
Field | Amount | Amount | Required. Writes the payment amount from the iPaaS.com transaction payment to the Heartland custom payment. The amount cannot exceed the remaining balance of the Heartland ticket, which Heartland calculates from line item prices, taxes, and shipping amounts; 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. Validate this behavior in a staging environment before relying on it in production. |
Static | "complete" | Status | Required. Sets the custom payment Status to the static value complete, so the payment is recorded as completed when the ticket is created. This value is set for every payment, and subscribers do not normally change it. |
Dynamic Formula |
| Deposit | Optional. Marks the custom payment as a ticket deposit. The template returns true, so the payment is applied as a Heartland ticket deposit. Heartland allows only gift card, custom, or external payment types to be applied as deposits, and custom payment types are eligible. Adjust the value for your workflow if you do not want the custom payment treated as a deposit. |
Dynamic Formula |
| Custom | Optional. Attaches a custom data object to the Heartland custom payment. The formula builds a data object from an example value and returns it, so the payment carries whatever custom details you supply. The example content is a template placeholder — replace it with the data your workflow needs, or return an empty object if no custom data is required. A custom payment accepts a custom object even when it is empty. Validate this behavior in a staging environment before relying on it in production. |
Add Heartland Ticket External Payment FROM iPaaS.com
This is a child collection of Add Heartland Ticket FROM iPaaS.com. It does not transfer on its own and has no Manual Sync ID, webhook, or polling schedule of its own.
Mapping Filter
//Heartland requires different formats depending on the type
var valueE = GetCustomFieldValue(CustomFields, "Heartland Payment Type");
if(!string.IsNullOrEmpty(valueE)){
if(valueE == "ExternalPayment"){return true;}
}
return false;The filter opens with a comment noting that Heartland requires a different request format per payment type, then reads the Heartland Payment Type custom field from the iPaaS.com transaction payment and takes one of three paths.
The custom field holds "ExternalPayment": the filter returns true and this collection writes the payment as a Heartland external payment.
The custom field holds any other value: the filter returns false and the payment goes to the matching sibling collection.
The custom field is empty or missing: the filter returns false immediately.
The filter raises no error and throws no message in any branch.
Description: Writes an external payment onto the Heartland ticket created by its parent collection. External payment types are eligible to be applied as Heartland ticket deposits, and the template applies this one as a deposit; a dedicated custom or external payment type is the recommended way to represent payments taken outside Heartland.
Mapping Type | Source Field (iPaaS.com) | Destination Field (Heartland) | Description |
Static | "ExternalPayment" | Type | Required. Sets the Heartland payment type to the fixed value ExternalPayment, designating the payment as an external payment so Heartland applies its external payment request format. The value is a fixed part of this template's external payment flow. |
Field | Amount | Amount | Required. Writes the iPaaS.com transaction payment amount to the Heartland external payment; a payment cannot be added without an amount. Heartland rejects a payment whose amount exceeds the ticket total, returning an error such as "Payment cannot exceed balance," where the ticket 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, rounding the amount to two decimal places is recommended to avoid an unexpected balance error. If the iPaaS.com amount is empty, the Heartland value is written empty; validate this behavior in a staging environment before relying on it in production. |
Field | Description | Description | Required. Writes the iPaaS.com transaction payment description to the Heartland external payment, which Heartland requires on an external payment. If the iPaaS.com description is empty, the Heartland value is written empty, which can cause Heartland to reject the payment; supply a description on the iPaaS.com payment, and validate this behavior in a staging environment before relying on it in production. |
Dynamic Formula |
| Deposit | Optional. Marks the Heartland external payment as a ticket deposit. Heartland allows only gift card, custom, or external payment types to be applied as deposits, and external is one of those types, so this template returns true to apply the external payment as a deposit. If you do not want external payments treated as deposits in your workflow, change this mapping to return false; validate the result in a staging environment before relying on it in production. |
Add Heartland Ticket Gift Card Payment FROM iPaaS.com
This is a child collection of Add Heartland Ticket FROM iPaaS.com. 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 Payment Type");
if(!string.IsNullOrEmpty(value)){
if(value == "GiftCardPayment"){return true;}
}
return false;The filter reads the Heartland Payment Type custom field from the iPaaS.com transaction payment and takes one of three paths.
The custom field holds "GiftCardPayment": the filter returns true and this collection writes the payment as a Heartland gift-card payment.
The custom field holds any other value: the filter returns false and the payment is written by the sibling collection matching its value.
The custom field is empty or missing: the filter returns false immediately.
The filter raises no error and throws no message in any branch. The gift-card existence check that can stop a transfer lives in the gift-card number mapping, not here.
Description: Writes a gift-card payment onto the Heartland ticket created by its parent collection, resolving the Heartland gift card the payment draws from. Whether the payment reduces the Heartland gift card balance depends on the combination of the Status and Deposit values; see Gift Card Balance Behavior below.
Mapping Type | Source Field (iPaaS.com) | Destination Field (Heartland) | Description |
Static | "GiftCardPayment" | Type | Required. Identifies the payment as a Heartland gift-card payment so Heartland applies the correct request format. Heartland's built-in payment types are CashPayment (identifier 1), CheckPayment (identifier 2), and GiftCardPayment (identifier 3). This value is fixed at GiftCardPayment for this collection and pairs with the PaymentTypeId value of 3; do not change it here. |
Static | "3" | PaymentTypeId | Required for gift-card payments. Supplies the Heartland payment type identifier for a gift-card payment. Heartland's built-in payment types pair each type with a fixed identifier: CashPayment is 1, CheckPayment is 2, and GiftCardPayment is 3. This value is fixed at 3 to match the gift-card payment type and should not be changed for this collection. |
Field | Amount | Amount | Required. Writes the payment amount from the iPaaS.com transaction payment to the gift-card payment on the Heartland ticket. Heartland requires an available gift card balance equal to or greater than this amount, and rejects the payment when the amount exceeds the ticket balance. If the amount is empty on the iPaaS.com side, it is written empty, which can cause Heartland to reject the payment. |
Dynamic Formula |
| GiftCardNumber | Required for gift-card payments. Resolves the Heartland gift card that the payment draws from. The formula reads the gift card referenced by the iPaaS.com payment and looks up its matching Heartland gift card identifier, which it writes to the payment. When the payment carries no gift-card reference, no identifier is returned and no gift-card number is sent. When the payment references a gift card that cannot be found in Heartland, the mapping stops the transfer with an error stating that the gift card does not exist in Heartland and cannot be used for the payment, which prevents writing a payment against a gift card that does not exist. Before this step, the integration attempts to resolve the referenced gift card and transfer it to Heartland automatically if it is not already linked, so a valid gift card is normally available. Any error raised here surfaces in the iPaaS.com Dashboard error logs. |
Static | "complete" | Status | Optional to change. Sets the status Heartland applies to the ticket when the gift-card payment is written. The template value of complete creates and completes the ticket in one step, which, with the template Deposit value of false, does not reduce the Heartland gift card balance. See Gift Card Balance Behavior below before changing it. |
Dynamic Formula |
| Deposit | Optional to change. Sets whether the gift-card payment is applied as a ticket deposit. The template formula always returns false, so under the default configuration the payment is not treated as a deposit. Together with the template Status of complete, this means the ticket is created and completed in one step and the Heartland gift card balance is not reduced. See Gift Card Balance Behavior below before changing it. |
Gift Card Balance Behavior
Whether a gift-card payment reduces the Heartland gift card balance depends on the combination of the payment's Status and Deposit values.
Status "complete", Deposit false (template default): the ticket is created and completed in one step, and the Heartland gift card balance is not reduced.
Status "complete", Deposit true: the ticket is created and completed, and the Heartland gift card balance is not reduced.
Status "pending", Deposit true: the Heartland gift card balance is reduced when the ticket is created.
Status "pending", Deposit false: the Heartland gift card balance is reduced when the ticket is completed.
These gift-card balance behaviors are not documented or supported by Heartland and are subject to change at any time. They are provided for demonstration purposes and may be used at your own risk; validate the behavior in a staging environment before relying on it in production.
Even when the settings above preserve a gift card balance, Heartland still requires an available balance equal to or greater than the payment amount to accept the payment at all. That is a problem for gift cards shared with other platforms, where a card may be fully depleted elsewhere. The optional Adjust Empty Gift Card For Payment subscription setting handles this case: when it is enabled and a gift-card payment references a card with a zero balance, the card balance in Heartland is raised enough to accept the full payment, the payment is added to the ticket, and the zero balance is restored afterward.
Add Heartland Ticket Note FROM iPaaS.com
This is a child collection of Add Heartland Ticket FROM iPaaS.com. 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: Writes the iPaaS.com transaction's notes onto the Heartland ticket created by its parent collection, adding one Heartland ticket note for each iPaaS.com transaction note.
Mapping Type | Source Field (iPaaS.com) | Destination Field (Heartland) | Description |
Field | Text | Content | Recommended. Writes the iPaaS.com transaction note text to the Heartland ticket note Content, so comments captured on the iPaaS.com transaction travel with the ticket into Heartland. A note with no content is not meaningful, so a value should always be present for a note to be created on the Heartland ticket. Because there is no separate local Heartland specification available for this documentation, validate this field in a staging environment before relying on it in production. |
Unmapped Field Overwrite Risk
This direction writes to Heartland, and the transfer sends a partial payload built from the mapped values. Heartland fields these collections do not map are generally not cleared — this is not the full-replace behavior that applies when records are written into iPaaS.com. Three qualifications matter, and all three are subscriber-visible.
Every mapped field is overwritten. The ticket header fields listed under Add Heartland Ticket FROM iPaaS.com — inventory source location, station, customer, total, type, status, public-facing ticket number, and the Transaction Source custom field — are set from the incoming iPaaS.com values on every transfer. Re-transferring a transaction that is already linked can overwrite values previously set in Heartland. If Heartland is where any of those values is maintained, remove or re-point the mapping.
Payment records are the documented exception to partial-payload behavior. When a payment child collection writes a payment to Heartland, only the fields that collection maps are sent, and any Heartland payment field the collection does not map is sent without a value. That is documented behavior for these collections, not an assumption. Review the mapped set for the payment type you use against the payment fields your workflow relies on in Heartland.
Heartland owns everything it recalculates. Heartland recalculates ticket totals from its lines, so the total you send is not necessarily the total Heartland keeps. Shipping and tax supplied only as header totals never reach a ticket at all, and an imported tax line is removed by Heartland's recalculation unless it carries the manually-added flag.
Preservation remedy. For any Heartland field you need to keep across transfers, add a Dynamic Formula mapping whose source is DestinationValue.[FieldName] for that field. That reads the current Heartland value and writes it back, so the field is not cleared or replaced.
Validate in staging. Partner-side clearing behavior should be confirmed rather than assumed. Before enabling this family in production, transfer a ticket into a staging Heartland environment, then inspect the resulting ticket, its lines, its payment, and its notes to confirm which Heartland values were written, which were left alone, and which were sent empty. Add preservation mappings for anything that did not survive.
Error Handling
SKU was not found in Heartland: a transaction line's SKU has no matching Heartland item. The error names the SKU and states that the transaction cannot transfer. The entire ticket transfer stops, so no partial ticket is created. Add the missing product to Heartland with a matching SKU, or correct the SKU on the iPaaS.com transaction line, then transfer again.
Payment method could not be found in Heartland: a custom payment's method name does not match any Heartland payment type. The transfer is prevented. Create the payment type in Heartland, or correct the payment method name on the iPaaS.com payment, then transfer again.
Gift card does not exist in Heartland: a gift-card payment references a gift card that could not be resolved to a Heartland gift card, and the transfer is prevented so no payment is written against a nonexistent card. Confirm the gift card exists in Heartland and is linked, then transfer again.
Unable to create the customer: the transaction references an iPaaS.com customer that is not linked to Heartland, and the automatic customer transfer that runs first failed. The ticket transfer is stopped rather than being written against a missing customer. Resolve the customer error — most often a missing name or an invalid email address — and transfer the transaction again.
Unable to create the gift card: the automatic gift-card transfer that runs before the ticket failed, and the ticket transfer is stopped. Resolve the gift-card error and transfer again.
Payment cannot exceed the balance of the ticket: the payment amount is greater than the ticket total Heartland calculated from its lines. This is frequently caused by amounts carrying more than the two decimal places Heartland displays. Round tax and payment amounts to two decimal places, confirm the shipping and tax lines were created, and transfer again.
Payment rejected as a deposit: a cash or check payment was flagged as a deposit. Heartland allows only gift card, custom, or external payment types as deposits. Leave the deposit mapping set to false on the cash and check collections.
No payment written and no error raised: the payment's Heartland Payment Type custom field was empty or held a value that is not one of the five recognized types, so no payment collection matched. Populate the custom field correctly on the iPaaS.com payment and transfer again.
Ticket transfers but the tax amount is missing: Heartland removed the tax line during its own recalculation because the line was not flagged as manually added. Restore that mapping on the tax-amount collection and transfer again.
Custom field value not stored: the destination Heartland custom field has not been created in Heartland. The ticket still transfers and the remaining fields are written; only that custom value is not stored. Create the custom field in Heartland, with a ticket custom-field group definition, and transfer again.
Heartland temporarily unavailable: if the Heartland API cannot be reached when a transfer is triggered, the transfer fails, including all of its lines, payments, and notes. The error appears in the iPaaS.com Dashboard error logs, and the record can be retried through a new transfer or Manual Sync.
Testing & Validation
Test Scenarios
Ticket created — transfer an iPaaS.com transaction whose type is Ticket, with the source location and station custom fields populated, and confirm a Heartland ticket is created with the mapped header values and that the Heartland identifier is saved as the external-id link with the ticket type suffix.
Non-ticket transaction skipped — transfer a sales order or invoice transaction and confirm this family does not create a Heartland ticket for it.
Suffix exclusions honored — transfer transactions whose numbers end with "-GC" and with "-D" and confirm neither produces a Heartland ticket.
Missing source location or station — clear one of the two custom fields, transfer, and confirm the ticket is not created and the error is reported in iPaaS.com.
Product lines written — transfer a multi-line transaction and confirm each line appears on the Heartland ticket as an item line with the correct item, quantity, and both unit prices.
Unknown SKU stops the transfer — transfer a transaction with a SKU that does not exist in Heartland and confirm the whole ticket transfer fails with the SKU error and no partial ticket is created.
Shipping line created — transfer a transaction with a shipping amount greater than zero and confirm exactly one shipping line appears on the Heartland ticket carrying the header shipping amount.
No shipping line when not applicable — transfer transactions with a zero shipping amount and with no shipping amount, and confirm no shipping line is created and no error is raised.
Tax line created and persists — transfer a transaction with a tax amount greater than zero and confirm one tax line appears, labeled as the imported tax amount, with no quantity, and that it is still present after Heartland recalculates the ticket.
Tax line without the manually-added flag — in a staging environment, remove the manually-added mapping, transfer, and confirm Heartland strips the tax line. Restore the mapping afterward.
Rounding — transfer a transaction whose tax amount carries more than two decimal places and confirm whether the payment is accepted; round to two decimals and confirm the balance error clears.
Cash payment routed — set the payment type custom field to "CashPayment", transfer, and confirm a cash payment is written with the cash payment type identifier and the station taken from the parent ticket.
Check payment routed — set the custom field to "CheckPayment", transfer, and confirm a check payment is written with its custom object and station.
Custom payment routed — set the custom field to "CustomPayment" with a payment method name that exists in Heartland, transfer, and confirm the Heartland payment type is resolved by name and the payment is applied as a deposit.
Unmatched payment method — set a payment method name that does not exist in Heartland and confirm the transfer is prevented with the payment-method error.
External payment routed — set the custom field to "ExternalPayment" with a description, transfer, and confirm the payment is written as a deposit with the description.
External payment without a description — clear the description and confirm whether Heartland accepts the payment.
Gift-card payment routed — set the custom field to "GiftCardPayment" on a payment referencing a linked gift card, transfer, and confirm the payment is written against the correct Heartland gift card.
Unlinked gift card auto-transferred — reference a gift card that is not yet linked to Heartland and confirm the integration transfers it before the ticket, with no manual pre-sync step.
Missing gift card stops the transfer — reference a gift card that cannot be resolved in Heartland and confirm the transfer is prevented with the gift-card error.
Gift-card balance combinations — in a staging environment, transfer with each of the four status and deposit combinations and record which reduce the Heartland gift card balance and when.
Depleted gift card — with the Adjust Empty Gift Card For Payment setting enabled, transfer a payment against a zero-balance card and confirm the payment is accepted and the zero balance is restored afterward.
Unrecognized payment type is silent — clear the payment type custom field, transfer, and confirm the ticket is created with no payment and no error, then correct the custom field and confirm the payment lands.
Deposit rejection — flag a cash payment as a deposit in a staging environment and confirm Heartland rejects it.
Notes written — transfer a transaction carrying two notes and confirm both appear on the Heartland ticket.
Customer prerequisite — transfer a transaction whose customer is not yet linked to Heartland and confirm the customer is created in Heartland automatically before the ticket.
Ticket number override — transfer with the ticket-number mapping as delivered and confirm the Heartland ticket carries the iPaaS.com transaction number; then enable the commented alternative and confirm Heartland assigns its own number.
Transaction Source custom field — confirm the Heartland ticket carries the iPaaS.com source value, and that a ticket created directly in Heartland does not.
Manual Sync by ID — enter a known iPaaS.com transaction ID on the Manual Sync page and confirm the ticket and all of its contents transfer.
Re-transfer behavior — transfer a linked transaction a second time and record which Heartland ticket values are rewritten and which are left alone. Add DestinationValue preservation mappings for anything that should be preserved.
Validation Checklist
The Heartland Source Location Id and Heartland Station Id custom fields exist on the iPaaS.com Transaction collection and hold valid Heartland identifiers.
The Heartland Payment Type custom field exists on the Transaction Payment collection and is populated with one of the five recognized values on every payment expected to reach Heartland.
Every product that can appear on a transferred transaction exists in Heartland with a matching SKU.
Every payment method used on iPaaS.com transactions exists as a payment type in Heartland.
Gift cards referenced by payments exist in Heartland, or the automatic gift-card prerequisite has been confirmed to create them.
Tax and payment amounts are rounded to two decimal places before transfer.
Shipping and tax lines appear on transferred tickets where the transaction carries those amounts, and the tax line survives Heartland's recalculation.
The placeholder custom-data values in the check and custom payment collections have been replaced or switched to the empty-object form.
Any Heartland custom field used as a mapping destination exists in Heartland with a ticket custom-field group definition.
The gift-card status and deposit combination in use has been validated in staging and its balance behavior is understood and accepted as unsupported by Heartland.
Heartland ticket values your business maintains in Heartland are either unmapped or preserved with a DestinationValue mapping.
Additional Notes
All nine child collections are children of Add Heartland Ticket FROM iPaaS.com. None has an independent transfer path; each runs only as part of a parent ticket transfer.
Exactly one of the five payment collections writes a given payment, and only when the payment's Heartland Payment Type custom field matches. A payment with no recognized value produces no payment and no error, which makes that custom field the single most important configuration item in this family.
Shipping and tax become Heartland lines rather than header totals, and they are created only when the corresponding header amount is present and greater than zero. This is a structural difference from sales orders, which do accept header-level shipping and tax.
A tax line that is not flagged as manually added does not survive Heartland's tax recalculation. Leave that mapping in place.
Failures are all-or-nothing by design: an unresolvable SKU, payment method, or gift card stops the whole ticket rather than producing a partially assembled Heartland ticket.
Customers and gift cards are transferred to Heartland automatically as prerequisites of the ticket transfer when they are not yet linked. No separate sync needs to be scheduled ahead of ticket transfers.
Deleting a transaction in iPaaS.com has no effect in Heartland. Removals must be made in Heartland directly.
Related Documents
Setup & Reference
Mapping Documentation