Summary
Heartland ticket transactions are transferred into iPaaS.com as Transaction records of type Ticket. When a ticket is transferred, the integration retrieves the Heartland ticket and dispatches it to iPaaS.com together with its line items and its payments, through two child collections that ride with the parent transfer.
The parent mapping records the originating system, the transaction number, the linked iPaaS.com customer, and the ticket totals (total, subtotal, tax, discount, and total quantity), and sets a fixed Type of "Ticket" and Status of "Complete". It also stores the customer email address and three Heartland-specific values as iPaaS.com custom fields: the source location, the station, and a marker recording that the transaction originated in Heartland.
This article covers the Heartland-to-iPaaS.com direction only. There is a separate, opposite-direction family of collections that writes tickets into Heartland from iPaaS.com data; it is a different flow with different triggers and is documented separately.
A note on collection names
The three collections in this family do not share a single naming convention, and the difference is cosmetic rather than functional:
Add Heartland Ticket TO iPaaS.com: the parent transaction collection.
Add Heartland Sales Ticket Line Item TO iPaaS.com: a child of that parent, carrying the ticket's line items.
Add Heartland Sales Ticket Payment TO iPaaS.com: a child of that parent, carrying the ticket's payments.
The children are named "Sales Ticket" while the parent is named "Ticket". They refer to the same Heartland ticket. The word "Sales" in the child names distinguishes them from the sales order and invoice line and payment collections that exist for the other Heartland transaction types; it does not indicate a different parent record. Neither child transfers on its own.
ID Format
Manual Sync ID Format
On the iPaaS.com Manual Sync page, enter the Heartland ticket external ID in the form {ticket id}_TICKET — for example, 105432_TICKET. The _TICKET suffix keeps the identifier unique across Heartland transaction types, whose underlying numeric IDs can overlap. Entering a bare numeric ID without a suffix is not sufficient, because the integration uses the suffix to determine which Heartland transaction type to retrieve.
There is no separate Manual Sync ID for an individual line item or payment. Both children are transferred as part of the parent ticket, so syncing the ticket syncs its lines and payments with it.
External ID Format
After a successful transfer, iPaaS.com records the Heartland ticket external ID in the same {ticket id}_TICKET form as the external-id link between the two systems (for example, 105432_TICKET). That value is also what the parent collection's transaction number mapping writes by default, which keeps ticket numbers unique across the Heartland transaction types that share the iPaaS.com Transaction collection.
Deleted Record Support
Deleting a transaction is not supported in this direction. The integration creates iPaaS.com Transaction records from Heartland tickets; it does not delete them. Removing or voiding a ticket in Heartland does not delete or cancel the linked iPaaS.com Transaction record, and it does not remove the transaction lines or payments created from it. Transactions that should no longer be active in iPaaS.com must be managed there directly.
Custom Field Support
This family reads Heartland custom field values and writes iPaaS.com custom field values at both the transaction and the transaction line level.
Reading Heartland custom fields: add a mapping of type Dynamic Formula whose source calls GetValueFromCustomField(Custom, "[Heartland custom field name]") and choose any iPaaS.com destination. At transfer time the integration returns the value of the named Heartland custom field. A Heartland custom field must be created in Heartland before it is visible on the Heartland website and available to mappings.
Writing iPaaS.com custom fields: each iPaaS.com custom field used as a destination must already exist on the matching iPaaS.com collection — Transaction for the parent, Transaction Line for the line item child, Transaction Payment for the payment child. If the custom field does not exist, the record still transfers and its other fields are written; only that custom value is not stored.
The template ships with five custom field mappings already in place: Heartland Source Location Id, Heartland Station Id, and Transaction Created By on the parent; Line Created By and C5_Custom_Transaction_Line on the line item child; and Heartland Payment Type on the payment child. The source location and station values are captured because Heartland requires a station and an inventory source location whenever a transaction is created in Heartland, so having them on the iPaaS.com record makes a later outbound transfer possible.
The C5_Custom_Transaction_Line mapping is a working example of the read pattern, not a production mapping. The Heartland custom field name it reads is a placeholder and should be replaced during implementation.
Tickets and sales orders require separate custom field group definitions in Heartland, even though both use the Transaction collection type in iPaaS.com. Ticket lines and order lines share the same line custom field group definition.
Mapping Collection Status
Status: Enabled. All three collections — the parent and both children — are enabled in the template.
Trigger Events: Automatic transfers run on a schedule through polling on the transaction polling scope. Heartland's webhook format is not compatible with iPaaS.com instant webhooks, so tickets arrive through polling rather than instant push notifications. Polling does not run until the subscription is configured and enabled, and the polling event must use the parent collection's filter so that ticket records rather than another Heartland transaction type are selected. Individual tickets can also be transferred at any time from the iPaaS.com Manual Sync page using the ticket's external ID.
Child triggers: Neither child collection has a trigger of its own. They have no webhook, no polling schedule, and no Manual Sync entry point. They run whenever the parent ticket is transferred.
Duplicate or Conflicting Mappings
Several other mapping collections write to the iPaaS.com Transaction collection or operate on the same Heartland tickets. They are distinguished as follows.
Same direction, other Heartland transaction types. Add Heartland Sales Order TO iPaaS.com and Add Heartland Invoice TO iPaaS.com transfer the other Heartland transaction types into the same iPaaS.com Transaction collection. Each is separated from this collection by its external-ID suffix (_ORDER, _INVOICE) and by the Type it writes, so tickets and other transaction types do not collide. Their line and payment children — Add Heartland Sales Order Line TO iPaaS.com, Add Heartland Sales Order Deposit Line TO iPaaS.com, Add Heartland Invoice Line TO iPaaS.com, Add Heartland Sales Order Payment TO iPaaS.com, Add Heartland Sales Order Deposit Payment TO iPaaS.com, and Add Heartland Invoice Payment TO iPaaS.com — likewise run only under their own parent transaction and never against a ticket.
Opposite direction, the inbound ticket family. A separate set of collections writes tickets into Heartland from iPaaS.com data, led by Add Heartland Ticket FROM iPaaS.com with its own children for line items, tax and shipping amount lines, notes, and the five payment types (Add Heartland Ticket Cash Payment FROM iPaaS.com, Add Heartland Ticket Check Payment FROM iPaaS.com, Add Heartland Ticket Custom Payment FROM iPaaS.com, Add Heartland Ticket External Payment FROM iPaaS.com, and Add Heartland Ticket Gift Card Payment FROM iPaaS.com).
That inbound family is not the reverse view of this article's collections and should not be configured by reading this one. It is triggered by iPaaS.com transaction events rather than by Heartland polling, it writes into Heartland rather than reading from it, it splits payments across five type-specific collections rather than the single payment child described here, and it carries structures (tax amount lines, shipping amount lines, notes) that have no counterpart in the outbound direction. The two directions share only the underlying Heartland ticket.
Important: Before running the inbound and outbound directions together, review your mapping collection filters and clearly define which system is the source of truth for transaction data. If both directions are active with the default mappings, changes may propagate back and forth between the systems. The Transaction Created By custom field written by this collection exists for exactly this purpose: a transaction stamped "Heartland" can be excluded from the outbound direction by a mapping collection filter, breaking the feedback loop. Consult your integration provider when planning data flows, mapping configuration, webhook subscriptions, and polling schedules so the systems do not repeatedly update the same records.
Collision Handling
This integration does not implement iPaaS.com collision handling. There is no collision recovery step to configure for tickets. Whether an incoming ticket produces a new iPaaS.com transaction is determined by whether the Heartland ticket external ID is already linked, and by this collection's Add sync type — an already-linked ticket is not overwritten by a later transfer.
Supported Child Collections
The parent Add Heartland Ticket TO iPaaS.com collection has exactly two children:
Add Heartland Sales Ticket Line Item TO iPaaS.com: transfers the ticket's item and gift card lines. Only Heartland ticket lines whose type is an item line or a gift card line are included.
Add Heartland Sales Ticket Payment TO iPaaS.com: transfers every payment applied to the ticket.
Neither child has children of its own, and neither runs independently of the parent ticket transfer.
System Caveats
Heartland Caveats
Station and source location: Heartland requires a station ID and an inventory source location ID whenever a transaction is created in Heartland. This family captures both as custom fields on the iPaaS.com transaction so they are available for a later outbound transfer. The values are visible in the Heartland retail website under Settings, then Locations.
Transaction number override: by default Heartland auto-increments ticket numbers. The outbound-to-Heartland templates override the public-facing value by mapping the iPaaS.com transaction number to Heartland's public identifier on the transaction header. That behavior belongs to the opposite direction and can be adjusted or disabled there; it does not affect this collection.
Deposit tickets: Heartland creates deposit tickets as copies of sales orders, identified by a "-D" suffix on the external ID. The parent filter excludes them so they are not transferred as ordinary tickets.
Incomplete tickets: a ticket that is still in the incomplete state in Heartland is excluded by the parent filter, so unfinished tickets do not transfer before they are done.
Separate custom field groups: tickets and sales orders require separate custom field group definitions in Heartland even though both use the Transaction collection type in iPaaS.com.
Gift card lines and payments: the gift card number is carried at the end of the Heartland line description and at the end of the Heartland payment description. The integration reads the number from that position to resolve the linked iPaaS.com gift card. Gift card behavior on Heartland payments is not documented or formally supported by Heartland and is subject to change; validate it in a staging environment before relying on it in production.
Custom field visibility: a Heartland custom field must be created in Heartland before it is visible on the Heartland website and available to mappings.
Polling delay: Heartland does not deliver instant push notifications to iPaaS.com, so expect a delay between a ticket being completed in Heartland and its appearance in iPaaS.com, bounded by the polling schedule.
iPaaS.com Caveats
Required transaction fields: the iPaaS.com Transaction record requires a system, a transaction number, a type, and a status. This collection supplies all four, so no additional configuration is required for them.
Customer identification is required: every transaction must be tied to a customer or a company. At least one of a customer ID, a company ID, or an email address must be present, or the transaction is rejected. This collection maps both the customer ID and the email address, so the requirement is satisfied even when the customer is not yet linked.
The system is not updatable: iPaaS.com accepts the system value only when the transaction is created. On an update it is ignored. Because this collection uses the Add sync type it always creates, so this has no effect on the default template — but a subscriber who extends the family into an update collection should not expect a changed system value to propagate.
Transaction number must be unique: iPaaS.com requires a unique transaction number across transactions. Mapping the Heartland external ID in the {ticket id}_TICKET form keeps ticket numbers unique across Heartland transaction types.
Valid type and status values: the transaction Type must be one of the values iPaaS.com accepts, and "Ticket" is one of them. The transaction Status and every line Status must likewise be an accepted value; "Pending", "Complete", and "Cancelled" — the three values these mappings can produce — are all valid.
Line type and status are required: every transaction line requires a type and a status. The line item child sets both by formula, so they are always populated for qualifying lines.
Payment method is required and must match: the Method on every iPaaS.com payment is required and must match the name of a configured iPaaS.com Payment Method. If the resolved name does not match a configured method, the payment is not recorded correctly.
Gift card references: iPaaS.com expects a gift card line to carry a gift card reference, and a gift card payment to carry one as well. The template formulas populate that reference only when a matching linked iPaaS.com gift card is found; when none is found the reference is left empty. Keep your Heartland gift card mappings to iPaaS.com enabled so the referenced gift cards are created automatically, and validate gift card tickets in a staging environment before relying on them in production.
SKU resolution: the SKU stored on a line should resolve to an existing iPaaS.com product or variant so the line is tied to the correct catalog record.
Custom field prerequisites: every custom field used as a destination must already exist on the corresponding iPaaS.com collection before the mapped value is stored.
Integration-Specific Caveats
The parent collection uses the Add sync type. It creates new iPaaS.com transactions; it does not overwrite a ticket that is already linked by its external ID. A ticket edited in Heartland after it has transferred does not update the iPaaS.com transaction.
Both children ride with the parent. Any delay or failure on the parent ticket transfer delays or fails the lines and payments with it.
Only merchandise item lines and gift card lines transfer. Tax, shipping, and discount amounts that Heartland records as separate ticket line types are not transferred by the line item child.
Prerequisite records (customer, payment method, gift card) are transferred automatically as part of the ticket transfer. Subscribers do not pre-sync them.
Setup Requirements
Heartland Configuration
Confirm that the tickets you intend to transfer are complete in Heartland. Incomplete tickets are excluded by the parent filter.
Confirm each ticket carries a customer, so the customer identification requirement can be satisfied from the customer link rather than from the email address alone.
Create any Heartland custom fields you intend to map before configuring the mappings, so they are available for selection. Remember that tickets need their own custom field group definition, separate from sales orders.
Note your station and inventory source location IDs from Settings, then Locations, if you plan to use the captured values for a later outbound transfer.
iPaaS.com Configuration
Create the custom fields you intend to use before enabling transfers: Heartland Source Location Id, Heartland Station Id, and Transaction Created By on the Transaction collection; Line Created By and C5_Custom_Transaction_Line on the Transaction Line collection; and Heartland Payment Type on the Transaction Payment collection.
Replace the placeholder Heartland custom field name in the C5_Custom_Transaction_Line mapping with the Heartland custom field you actually want to read, or remove the mapping.
Confirm the payment methods your Heartland tickets use exist as configured iPaaS.com Payment Methods under the names the Method mapping will resolve to, and adjust the Method mapping if your workflow needs a different resolution.
Leave the Heartland customer, payment method, and gift card mappings to iPaaS.com enabled if you want prerequisite records created automatically. Disable them if you do not — and understand the consequences described under Integration Flow.
Enable the subscription and configure the transaction polling event with the parent collection's filter so ticket records are selected.
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
Scheduled polling:
On its polling schedule, the integration requests recently changed Heartland transactions.
Each candidate transaction is evaluated against the parent collection's filter. Transactions that are not completed tickets are skipped.
For each qualifying ticket, the integration retrieves the full Heartland ticket record, including its lines and payments.
Prerequisite records are resolved and transferred as described below.
The ticket is dispatched to iPaaS.com through the parent collection, and its qualifying lines and its payments are created through the two child collections in the same transfer.
Manual Sync:
A Heartland ticket external ID in the {ticket id}_TICKET form is entered on the iPaaS.com Manual Sync page.
The integration retrieves that single ticket from Heartland and dispatches it through the same path, including prerequisites, lines, and payments.
Automatic prerequisite transfers:
Before the ticket itself is written to iPaaS.com, the integration resolves the records the ticket depends on, in this order. All of these happen automatically as part of the ticket transfer — subscribers do not need to pre-sync them.
Customer. If the ticket references a Heartland customer, the integration checks whether that customer is already linked to an iPaaS.com customer. If it is not, the Heartland customer record is retrieved and transferred to iPaaS.com first. If that customer transfer fails, the ticket transfer is stopped and the ticket does not reach iPaaS.com. This is the only prerequisite that blocks the parent transfer. If the ticket carries no customer reference, this step is skipped entirely.
Payment methods. For each payment on the ticket that carries a Heartland payment type, the integration checks whether that payment type already resolves to a known payment method name. If it does not, the Heartland payment method record is retrieved and transferred to iPaaS.com. A failure here does not stop the ticket.
Gift cards referenced by payments. For each payment whose Heartland type indicates a gift card payment, the integration reads the gift card number from the end of the payment description, retrieves that gift card from Heartland, and transfers it to iPaaS.com. A failure here does not stop the ticket.
Gift cards referenced by lines. For a ticket specifically — this step does not run for the other Heartland transaction types — the integration then walks the ticket's lines. For each line that carries a gift card reference, it reads the gift card number from the end of the line description, retrieves that gift card from Heartland, and transfers it to iPaaS.com. A failure here does not stop the ticket.
Disabling the Heartland customer, payment method, or gift card mappings to iPaaS.com prevents the corresponding automatic transfer. Disabling the customer mappings means a ticket whose customer is not already linked will not associate to a customer as expected; disabling the payment method or gift card mappings means the ticket still transfers, but its payments or gift card lines may not resolve to the records you expect.
Mappings
Add Heartland Ticket TO iPaaS.com
Mapping Filter
External_Id.Contains("_TICKET")
&& !External_Id.Contains("-D")
&& Type is not null
&& Type == "Ticket"
&& Status != "incomplete"A Heartland transaction is processed by this collection only when every one of the following five conditions is true. A transaction that fails any one of them is skipped, and no iPaaS.com transaction is created for it. The filter does not raise an error or throw a message when it excludes a record; the record is simply not processed.
The external ID contains "_TICKET". This selects Heartland ticket transactions and excludes sales orders and invoices, whose external IDs carry the _ORDER and _INVOICE suffixes instead.
The external ID does not contain "-D". Heartland creates deposit tickets as copies of sales orders with a "-D" suffix. This condition excludes them, so a deposit ticket is not transferred here as if it were an ordinary sales ticket.
The Type is present. A transaction with no type at all is excluded before the type is compared, so an incomplete or malformed record does not reach the comparison.
The Type is exactly "Ticket". This is the type check proper. Only transactions Heartland classifies as tickets pass.
The Status is not "incomplete". A ticket still being built in Heartland is excluded, so unfinished tickets do not transfer before they are done. Every other Heartland status passes this condition.
Description: Creates an iPaaS.com Transaction record of type Ticket from a completed Heartland ticket, linked by the Heartland ticket external ID and dispatched together with its line items and payments. This collection uses the Add sync type: it creates transactions and does not overwrite a ticket that is already linked.
Mapping Type | Source Field (Heartland) | Destination Field (iPaaS.com) | Description |
Dynamic Formula |
| SystemId | Required. Supplies the iPaaS.com system identifier for the transaction. iPaaS.com requires a system on every transaction. This value is applied automatically by the integration and does not require configuration. iPaaS.com accepts the system only when the transaction is created; on an update it is ignored, so a changed system value would never propagate to an already-created transaction. |
Dynamic Formula | Ticket external ID (formula reproduced below) | TransactionNumber | Required. Sets the iPaaS.com transaction number. By default the formula uses the Heartland external ID, which produces the {ticket id}_TICKET form; that suffix keeps ticket numbers unique across Heartland transaction types, whose underlying numeric IDs can overlap. The formula also carries the Heartland public identifier as a commented-out alternative — switch the source to it if you prefer the human-friendly Heartland ticket number. iPaaS.com requires a transaction number and it must be unique across transactions. |
Dynamic Formula |
| CustomerId | Required as part of the customer-identification group. Resolves the Heartland customer referenced on the ticket to its linked iPaaS.com customer and stores that iPaaS.com customer ID on the transaction. If the Heartland customer is not yet linked, the integration attempts to transfer the customer first, and the ticket transfer is stopped if that customer transfer fails. To prevent the automatic customer transfer, disable the Heartland customer mappings to iPaaS.com. |
Static | "Ticket" | Type | Required. Sets the iPaaS.com transaction Type to the fixed value "Ticket", which is one of the transaction types iPaaS.com accepts. It identifies these records as tickets among the other Heartland transaction types that share the Transaction collection. |
Static | "Complete" | Status | Required. Sets the iPaaS.com transaction Status to the fixed value "Complete", which is one of the statuses iPaaS.com accepts. Tickets that pass this collection's filter have already progressed beyond the incomplete state in Heartland, so they are recorded as complete in iPaaS.com. |
Field | Total | Total | Recommended. Stores the ticket total from the Heartland Total field so the iPaaS.com transaction reflects the Heartland ticket amount. |
Dynamic Formula |
| Subtotal | Recommended. Calculates the ticket subtotal by adding the original cost of the items to the value of any gift cards sold on the ticket, so the iPaaS.com subtotal reflects both regular items and gift card sales. |
Dynamic Formula |
| TotalQty | Recommended. Calculates the total item count by adding the quantity of regular items to the count of gift cards sold, giving the overall number of items including gift cards. |
Dynamic Formula |
| TaxAmount | Recommended. Derives the ticket tax amount by taking the ticket total, removing the item and gift card subtotal, and adding back the total discounts, leaving the tax portion of the ticket. |
Dynamic Formula |
| EmailAddress | Required as part of the customer-identification group. Stores the Heartland customer's email address on the iPaaS.com transaction. iPaaS.com requires at least one of a customer ID, a company ID, or an email address on every transaction; carrying the email address lets the ticket satisfy that requirement even when the customer is not yet linked. |
Field | TotalDiscounts | DiscountAmount | Recommended. Stores the ticket's total discount amount from the Heartland TotalDiscounts field. |
Field | SourceLocationId | Heartland Source Location Id (custom field) | Optional. Stores the Heartland inventory source location ID, captured for reference and for later outbound use because Heartland requires an inventory source location when transactions are created there. Requires a custom field of this name on the Transaction collection before the value is stored. |
Field | StationId | Heartland Station Id (custom field) | Optional. Stores the Heartland station ID, captured for reference and for later outbound use because Heartland requires a station when transactions are created there. Requires a custom field of this name on the Transaction collection before the value is stored. |
Static | "Heartland" | Transaction Created By (custom field) | Optional. Records that the transaction originated in Heartland. This marker is useful when transactions move in both directions: transactions created by iPaaS.com can be excluded from the outbound transfer with a mapping collection filter, avoiding an endless feedback loop. Requires a custom field of this name on the Transaction collection before the value is stored. |
Transaction number formula
External_Id //PublicId
The active line is the first. The second line is a commented-out alternative: swap the two if you want the Heartland public ticket number rather than the suffixed external ID as the iPaaS.com transaction number. Doing so removes the suffix that keeps ticket numbers unique across Heartland transaction types, so confirm your Heartland numbering will not overlap before making the change.
Add Heartland Sales Ticket Line Item TO iPaaS.com
This is a child of Add Heartland Ticket TO iPaaS.com. It does not transfer on its own — it has no webhook, no polling schedule, and no Manual Sync entry point. Its lines are created whenever the parent ticket is transferred.
Mapping Filter
Type=="ItemLine" || Type == "GiftCardLine"
A Heartland ticket line is processed by this collection when either of the following is true. A line that satisfies neither is skipped, and no iPaaS.com transaction line is created for it. The filter does not raise an error or throw a message when it excludes a line; the line is simply not processed.
The line type is "ItemLine". These are the merchandise item lines of the ticket — the products actually sold.
The line type is "GiftCardLine". These are the gift card lines of the ticket, whether a gift card is being sold or redeemed.
Because these are the only two accepted types, every other Heartland ticket line type is excluded. In practice that means tax lines, shipping lines, and discount lines that Heartland records as separate line types are not transferred through this collection. Their amounts reach iPaaS.com through the parent ticket's total, tax, and discount mappings instead, not as individual lines.
Description: Creates one iPaaS.com transaction line for each qualifying Heartland ticket line, carrying the line type, SKU, description, quantities, and pricing, and — for gift card lines — the resolved iPaaS.com gift card reference. The parent link is set automatically from the parent ticket transfer and is not a configurable mapping row.
Mapping Type | Source Field (Heartland) | Destination Field (iPaaS.com) | Description |
Dynamic Formula | Heartland line type (formula reproduced below) | Type | Required. Sets the line type from the Heartland line type: a gift card line produces "Gift Card" and every other qualifying line produces "Product". iPaaS.com requires a type on every transaction line. |
Dynamic Formula |
| Status | Required. Sets the line's status from the parent Heartland ticket's status. A pending ticket produces "Pending", a complete ticket produces "Complete", and any other ticket status produces "Cancelled". iPaaS.com requires a status on every transaction line. |
Field | ItemPublicId | Sku | Recommended. Stores the Heartland line's item public identifier as the line SKU. The SKU should resolve to an existing product or variant in iPaaS.com so the line is associated with the correct catalog record. |
Field | OriginalUnitPrice | OriginalUnitPrice | Optional. Stores the Heartland line's original unit price, recording the price before any adjustments. |
Field | Value | ExtendedPrice | Optional. Stores the Heartland line's total value as the extended (line total) price. |
Dynamic Formula | Line value and quantity (formula reproduced below) | UnitPrice | Optional. Sets the line's unit price, with different handling for gift card lines. For a gift card line the unit price is the line's total value divided by its quantity, giving the price of a single gift card. For all other lines the formula uses the final unit price when one is available and falls back to the original unit price when it is empty. |
Field | Description | Description | Optional. Stores the Heartland line's description. For gift card lines this description is also where the integration reads the gift card number when resolving the line's gift card reference, so do not strip it. |
Field | QtyInvoiced | QtyShipped | Optional. Stores the Heartland line's invoiced quantity, treating the invoiced quantity as the quantity shipped. |
Dynamic Formula | Gift card number from the line description (formula reproduced below) | LineInfo | Optional. Resolves the gift card reference for a gift card line. When the line type indicates a gift card, the formula reads the gift card number from the end of the line description, looks up the matching iPaaS.com gift card, and if one is found stores its identifier in the line's LineInfo. If the line is not a gift card line, or no matching gift card is found, LineInfo is left empty and the line still transfers. Keep your Heartland gift card mappings to iPaaS.com enabled so the referenced gift cards are created automatically before the ticket transfers. |
Dynamic Formula |
| DiscountAmount | Optional. Calculates the total discount on the line by comparing the original price against the adjusted price across the ordered quantity. When the line has no adjusted price, the original unit price is used on both sides and the result is zero, meaning no discount. |
Static | "Heartland" | Line Created By (custom field) | Optional. Stamps the fixed value "Heartland" onto the line, recording that it originated from Heartland. Requires a custom field of this name on the Transaction Line collection before the value is stored. |
Dynamic Formula |
| C5_Custom_Transaction_Line (custom field) | Optional. Reads a named value from the Heartland line's custom fields and stores it on the iPaaS.com transaction line. This is a demonstration of the custom-field read pattern and carries a placeholder name: replace "My Sales Transaction Line Custom Field" with the Heartland custom field you want to read, and point the mapping at the iPaaS.com custom field where the value should be stored. The named Heartland custom field must exist in Heartland, and the destination custom field must exist on the Transaction Line collection. |
Field | Qty | Qty | Optional. Stores the Heartland line's ordered quantity. |
Line type formula
if(Type == "GiftCardLine")
return "Gift Card";
else
return "Product";Unit price formula
if(Type == "GiftCardLine") return (Value / Qty); else return Coalesce(FinalUnitPrice,OriginalUnitPrice);
Line gift card reference formula
if(Type != null && Type.ToString().ToLower().Contains("giftcard")){
var heartland_GiftCardNumber = Description.Split().LastOrDefault();
var giftCardId = await GetSpaceportIdAsync(heartland_GiftCardNumber, "Gift Card", SpaceportSystemId);
if(giftCardId > 0){
var dict = new Dictionary<string, string>();
dict.Add("GiftCardId",giftCardId.ToString());
return dict;
}
}Add Heartland Sales Ticket Payment TO iPaaS.com
This is a child of Add Heartland Ticket TO iPaaS.com. Like the line item child, it has no trigger of its own — payments transfer only as part of a parent ticket transfer. To control when payments transfer, configure the parent collection.
Mapping Filter
This mapping collection does not have a mapping filter applied. Every payment on a transferred Heartland ticket is processed without additional filtering conditions.
Description: Creates one iPaaS.com payment record for each payment on the transferred Heartland ticket, capturing the amount, method, status, and description, and — for gift card payments — the linked iPaaS.com gift card. The parent link and the external-ID link are set automatically by the integration and are not configurable mapping rows.
Mapping Type | Source Field (Heartland) | Destination Field (iPaaS.com) | Description |
Field | Description | Method | Required. Sets the iPaaS.com payment Method — the name of the iPaaS.com Payment Method the payment is recorded against — from the Heartland payment description. iPaaS.com requires a method on every payment, and the resolved value must match the name of a configured iPaaS.com Payment Method. If your workflow needs the payment recorded against a specific configured payment method rather than the Heartland description text, adjust this mapping so the resolved value matches that payment method's name. |
Dynamic Formula | Heartland payment status (formula reproduced below) | Status | Optional. Normalizes the Heartland payment status to the iPaaS.com equivalent. A Heartland status of "pending" is recorded as "authorized" and a Heartland status of "complete" is recorded as "captured"; any other Heartland status leaves the iPaaS.com status unset. |
Field | Amount | Amount | Optional. Stores the Heartland payment amount. |
Dynamic Formula | Gift card number from the payment description (formula reproduced below) | MethodInfo | Optional. Attaches additional method detail for gift card payments. When the Heartland payment type indicates a gift card, the formula reads the gift card number from the end of the payment description, resolves the iPaaS.com gift card linked to that number, and when one is found returns it as the payment's gift card reference. For non-gift-card payments, or when no linked gift card is found, no method detail is set. Gift card handling on Heartland payments is not documented or supported by Heartland and is subject to change; validate this behavior in a staging environment before relying on it in production. |
Dynamic Formula | Heartland payment type (formula reproduced below) | Heartland Payment Type (custom field) | Optional. Stores the Heartland payment type on the iPaaS.com payment, stripping the leading namespace prefix and leaving just the payment type name. If the Heartland payment type is empty, no value is stored. This preserves the underlying Heartland payment type for reference and for use in downstream mapping filters. Requires a custom field of this name on the Transaction Payment collection before the value is stored. |
Field | Description | Description | Optional. Stores the Heartland payment description as free text on the iPaaS.com payment. The same Heartland description also feeds the Method mapping, and for gift card payments it ends with the gift card number that the MethodInfo mapping reads. |
Payment status formula
if (Status == "pending") return "authorized"; if (Status == "complete") return "captured"; return null;
Payment gift card reference formula
if(Type != null && Type.ToString().ToLower().Contains("giftcard")){
var heartland_GiftCardNumber = Description.Split().LastOrDefault();
var giftCardId = await GetSpaceportIdAsync(heartland_GiftCardNumber, "Gift Card", SpaceportSystemId);
if(giftCardId > 0){
var dict = new Dictionary<string, string>();
dict.Add("GiftCardId",giftCardId.ToString());
return dict;
}
}Heartland payment type formula
if(Type != null && Type != ""){
return Type.Replace("Payments::","");
}
return null;Unmapped Field Overwrite Risk
When iPaaS.com writes a transaction in this direction, the write is a full replacement of the record's writable fields: any writable field the collection does not map is sent empty rather than being carried over from the existing record. Because all three collections here use the Add sync type, the practical exposure in the shipped template is that the listed fields are simply left empty on the newly created record. The overwrite risk becomes real the moment the family is extended to update existing transactions — at that point every unmapped writable field below would be cleared on each transfer.
Parent — Add Heartland Ticket TO iPaaS.com. The writable top-level Transaction fields this collection does not map are ParentId, CompanyId, ShippingAmount, TransactionCreatedDateTime, and TransactionUpdatedDateTime. In addition, the Transaction record accepts several nested structures that this family does not populate at all: taxes, tracking, addresses, notes, and transaction-level discounts. Heartland ticket shipping and tax amounts reach iPaaS.com only through the parent's Total, TaxAmount, and DiscountAmount values, not as itemized tax, shipping, or address records.
Line item child — Add Heartland Sales Ticket Line Item TO iPaaS.com. The writable line fields it does not map are sequence_number, unit, discount_percent, tax_percent, estimated_tax_amount, weight, options, and external_ids, along with the nested line address and line_discounts structures.
Payment child — Add Heartland Sales Ticket Payment TO iPaaS.com. This collection maps every subscriber-relevant writable field on the payment record: Amount, Status, Description, Method, MethodInfo, and the Heartland Payment Type custom field. The two remaining writable values — the parent transaction link and the external-ID link — are set and managed automatically by the integration as part of the parent ticket transfer and are not intended to be mapped here. No subscriber action is required for this collection.
The remedy. If your integration relies on any of the unmapped fields listed above, add a mapping for it in the owning collection so it is populated on every transfer. If the value is one that already exists in iPaaS.com and must survive a transfer — which is the case whenever you extend this family into an update collection — add a Dynamic Formula mapping whose source is DestinationValue.[FieldName], naming the field you want to keep. That formula reads the current iPaaS.com value and writes it straight back, so the transfer no longer clears it.
One field cannot be preserved this way. iPaaS.com marks the transaction SystemId as not updatable: it is accepted when the transaction is created and ignored on every subsequent update. A DestinationValue mapping for it is unnecessary on create and has no effect on update. Plan the system assignment at creation time; it cannot be changed later through this integration.
Error Handling
Customer prerequisite failed: when the ticket's Heartland customer is not yet linked and its automatic transfer to iPaaS.com fails, the ticket transfer is stopped and no iPaaS.com transaction is created. The error appears in the iPaaS.com Dashboard error logs. Resolve the underlying customer problem — or confirm the Heartland customer mappings to iPaaS.com are enabled — and retry the ticket through a new polling cycle or Manual Sync.
No customer identifier: iPaaS.com rejects a transaction that carries no customer ID, company ID, or email address. Because this collection maps both the customer ID and the email address, this occurs only when the Heartland ticket has neither a resolvable customer nor a customer email. Populate the customer email in Heartland or confirm the customer link, then retry.
Duplicate transaction number: iPaaS.com requires a unique transaction number. If the transaction number mapping has been changed to a value that is not unique — for example to the Heartland public ticket number when the same number exists on another transaction type — the transaction is rejected. Restore the external-ID form or make the alternative source unique.
Invalid type or status: the transaction Type and Status, and each line's Status, must be values iPaaS.com accepts. The shipped mappings always produce accepted values; a customized mapping that produces something else causes the record to be rejected.
Payment method does not match: the payment Method must match the name of a configured iPaaS.com Payment Method. When the Heartland payment description does not correspond to a configured method name, the payment is not recorded correctly. Adjust the Method mapping, or create the matching payment method in iPaaS.com.
Gift card not resolved: when a gift card number read from a line or payment description does not match a linked iPaaS.com gift card, the line or payment still transfers but carries no gift card reference. Keep the Heartland gift card mappings to iPaaS.com enabled so the gift card is created automatically first, and validate gift card tickets in a staging environment.
SKU does not resolve: a line SKU that does not correspond to an existing iPaaS.com product or variant leaves the line unassociated with a catalog record. Transfer the products first, or correct the Heartland item public identifier.
Custom value not stored: when a custom field named in a mapping does not exist on the corresponding iPaaS.com collection, the record still transfers and its other fields are written; only that custom value is not retained. Create the custom field and re-transfer the ticket to populate it.
Heartland API unavailable: if the Heartland API cannot be reached when a transfer is triggered, the transfer fails, including the ticket's lines and payments. The error appears in the iPaaS.com Dashboard error logs, and the ticket can be retried through a new polling cycle or Manual Sync.
Ticket not found: when a Manual Sync is run for a ticket external ID that does not exist in Heartland, or the identifier is missing its _TICKET suffix, the record cannot be retrieved and the transfer fails. Confirm the ID is correct and carries the suffix.
Testing & Validation
Test Scenarios
Completed ticket transfers — complete a ticket in Heartland with at least one item line and one payment, transfer it, and confirm an iPaaS.com Transaction of type Ticket is created with Status "Complete" and linked by the {ticket id}_TICKET external ID.
Line items created — confirm the transferred ticket has one iPaaS.com transaction line for each Heartland item line, with SKU, description, quantities, and pricing populated.
Payments created — confirm the transferred ticket has one iPaaS.com payment for each Heartland payment, with amount, method, and description populated.
Filter excludes an incomplete ticket — leave a ticket in the incomplete state in Heartland, run a transfer, and confirm no iPaaS.com transaction is created for it.
Filter excludes a deposit ticket — transfer a deposit ticket (whose external ID carries the "-D" suffix) and confirm it is skipped by this collection.
Filter excludes other transaction types — confirm a Heartland sales order and an invoice are not picked up by this collection.
Non-item line types skipped — build a ticket with tax, shipping, or discount line types alongside item lines, transfer it, and confirm only the item and gift card lines produce iPaaS.com transaction lines.
Customer prerequisite runs automatically — transfer a ticket for a Heartland customer that is not yet linked to iPaaS.com and confirm the customer is created first, without any pre-sync, and the ticket is associated with it.
Customer prerequisite blocks on failure — with a customer that cannot transfer (for example, with the Heartland customer mappings disabled or a customer that fails its own validation), transfer the ticket and confirm the ticket does not reach iPaaS.com and the failure appears in the Dashboard error logs.
Email satisfies customer identification — transfer a ticket whose customer carries an email address and confirm the iPaaS.com transaction records the email address alongside the customer ID.
Payment method prerequisite — transfer a ticket using a Heartland payment method not yet linked to iPaaS.com and confirm the payment method is transferred automatically and the ticket still completes.
Gift card sold — sell a gift card on a Heartland ticket, transfer it, and confirm the line type is a gift card line, the unit price equals the line value divided by the quantity, and the gift card reference is populated.
Gift card payment — pay a Heartland ticket with a gift card, transfer it, and confirm the payment carries the resolved iPaaS.com gift card reference.
Gift card not linked — transfer a gift card ticket whose gift card cannot be resolved and confirm the line and payment still transfer with the reference left empty.
Totals reconcile — compare the iPaaS.com Total, Subtotal, TaxAmount, DiscountAmount, and TotalQty against the Heartland ticket, including a ticket with both regular items and a gift card sale.
System is not updatable — after a ticket has transferred, confirm that a subsequent transfer does not change the iPaaS.com transaction's system value. iPaaS.com accepts the system only at creation and ignores it thereafter.
Add sync type does not overwrite — transfer the same ticket twice and confirm no duplicate iPaaS.com transaction is created and the existing one is not rewritten.
Custom fields populated — with all six template custom fields created, transfer a ticket and confirm the source location, station, created-by marker, line created-by marker, line custom value, and payment type are stored.
Custom field absent — remove one custom field, transfer a ticket, and confirm the record still transfers with the remaining fields written and no error raised for the missing custom value.
Manual Sync by external ID — enter a known ticket external ID in the {ticket id}_TICKET form on the Manual Sync page and confirm that ticket, its lines, and its payments transfer.
Polling — with the subscription enabled and the transaction polling event configured with this collection's filter, complete a ticket in Heartland and confirm it arrives in iPaaS.com on the next polling cycle.
Validation Checklist
Every transferred ticket is linked by its {ticket id}_TICKET external ID, and a re-transfer neither duplicates nor rewrites it.
The transaction Type is "Ticket" and the Status is "Complete" on every transferred record.
Each transaction carries a customer ID, an email address, or both, so the iPaaS.com customer identification requirement is satisfied.
Incomplete tickets, deposit tickets, sales orders, and invoices are all absent from the transferred set.
Every qualifying Heartland ticket line has exactly one matching iPaaS.com transaction line, and no tax, shipping, or discount line types have produced lines.
Every Heartland ticket payment has a matching iPaaS.com payment, and each Method matches the name of a configured iPaaS.com Payment Method.
Gift card lines and gift card payments carry a resolved gift card reference wherever the gift card exists in iPaaS.com.
The ticket totals in iPaaS.com reconcile with the Heartland ticket, including gift card amounts.
All six template custom fields exist on their respective iPaaS.com collections and hold the expected values.
The placeholder Heartland custom field name in the line item child has been replaced or the mapping removed.
Prerequisite customers, payment methods, and gift cards were created without any manual pre-sync.
Polling and Manual Sync produce the same resulting records for the same ticket.
Additional Notes
All three collections use the Add sync type. They create iPaaS.com records; they do not update tickets already linked. Edits made to a Heartland ticket after it has transferred do not flow through to the existing iPaaS.com transaction.
The children are named "Sales Ticket Line Item" and "Sales Ticket Payment" while their parent is named "Ticket". They belong to the parent ticket collection and nothing else; the naming difference carries no functional meaning.
Heartland is the source of truth for the fields listed under Mappings in this direction. Editing those values directly in iPaaS.com is safe only because this family does not update linked transactions — but that also means iPaaS.com edits will not be reconciled against Heartland.
Because tickets arrive by polling rather than instant push notifications, allow for the polling interval when validating a ticket completed in Heartland.
When transferring more than one Heartland transaction type, keep the external ID as the transaction number source. The _ORDER, _INVOICE, and _TICKET suffixes are what prevent numeric ID overlap between the types.
The Transaction Created By marker exists to make bi-directional configuration safe. Use it in a filter on the outbound direction to exclude transactions that originated in Heartland.
Related Documents
Setup & Reference
Mapping Documentation