Summary
iPaaS.com Transaction records are written out to Heartland as Heartland sales orders. iPaaS.com is the source in this direction and Heartland is the system being written to. The order header carries the customer, the shipping method, the shipping charge, and the Heartland station and inventory source location that Heartland requires to create an order, and it is marked as originating from iPaaS.com so the opposite direction can recognize it.
New orders are deliberately created in a "pending" status. Heartland will not invoice a completed order, and an order must be created in a status other than complete before payments can be added, so a pending status satisfies both. Once payment is added, Heartland moves the order to an open status; once all line items are invoiced, Heartland closes the order automatically.
This article covers nine mapping collections: the parent Add/Update Heartland Sales Order FROM iPaaS.com and its eight child collections. Five of those children are payment collections, one for each Heartland payment type, because Heartland requires a different request format per type.
How payments are routed
This is the single most important thing to understand about this family. The integration does not choose a payment collection for you. Each of the five payment child collections carries a filter that reads one value — the Heartland Payment Type custom field on the iPaaS.com transaction payment — and processes the payment only when that value matches its own type:
CashPayment routes to Add Heartland Sales Order Cash Payment FROM iPaaS.com
CheckPayment routes to Add Heartland Sales Order Check Payment FROM iPaaS.com
CustomPayment routes to Add Heartland Sales Order Custom Payment FROM iPaaS.com
ExternalPayment routes to Add/Update Heartland Sales Order External Payment FROM iPaaS.com
GiftCardPayment routes to Add Heartland Sales Order Gift Card Payment FROM iPaaS.com
The five filters are mutually exclusive, so exactly one collection writes any given payment. If a payment's Heartland Payment Type custom field is empty, missing, or holds any value other than the five above, every filter returns false and no collection writes that payment. The order still transfers, no error is raised, and the payment simply does not reach Heartland — leaving the Heartland order with an unpaid balance. Populating Heartland Payment Type correctly on every iPaaS.com payment is therefore a configuration requirement, not an optional refinement.
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 addresses, line items, notes, and payments through the child collections.
External ID Format
After a successful transfer, iPaaS.com records the Heartland order's identifier as the external-id link between the two systems. Because Heartland order, ticket, and invoice numbers can overlap, the transaction external id carries an order designation: the Heartland order identifier followed by an _ORDER suffix. The suffix is what keeps the reference unique across Heartland transaction types, and the integration will not resolve a transaction identifier that does not carry an _ORDER, _INVOICE, or _TICKET suffix.
When you write mappings in the opposite direction that need the iPaaS.com transaction number, reference the external id rather than a bare number, for the same reason.
Deleted Record Support
Deleting a sales order is not supported in this direction. The integration creates and updates Heartland orders only — deleting or voiding a Transaction record in iPaaS.com does not delete the linked Heartland sales order. Orders that should no longer stand in Heartland must be managed directly in Heartland.
The same applies to every child: removing a line item, note, address, or payment from an iPaaS.com transaction does not remove the corresponding record from the Heartland order. The child collections write records; they do not remove them.
Custom Field Support
This direction both reads and writes custom field values, and several of them are load-bearing rather than optional.
Read from the iPaaS.com transaction:
Heartland Station Id: supplies the station Heartland requires to create the order. It is also read by the cash and check payment collections, which take the station from the parent transaction rather than from the payment.
Heartland Source Location Id: supplies the inventory source location Heartland requires to create the order.
Heartland Invoice Id: read by the parent filter. When it already holds a value, the order is skipped so a completed order is not invoiced twice.
Read from the iPaaS.com transaction payment:
Heartland Payment Type: routes each payment to one of the five payment child collections, as described above.
Written to Heartland:
Transaction Source: written with the value "iPaaS.com" to mark the order as originating from iPaaS.com, so the opposite direction can recognize and skip it.
Prerequisite: a Heartland custom field must be created in Heartland manually before it is visible on the Heartland website and available to mappings, and a matching custom field must exist on the corresponding collection in iPaaS.com to supply or store the value. Orders and tickets require separate custom field group definitions in Heartland even though both use the Transaction collection type in iPaaS.com.
Mapping Collection Status
Status: Enabled. All nine collections — the parent and its eight children — are enabled in the template.
Trigger Events: Outbound transfers are triggered from iPaaS.com. When the subscription is configured and enabled, an iPaaS.com Transaction that satisfies the parent mapping filter is transferred to Heartland automatically; the integration recognizes transaction creation, transaction update, and transaction polling events. No automatic transfers occur until the subscription is configured and enabled. A specific transaction can also be transferred on demand at any time from the iPaaS.com Manual Sync page.
None of the eight child collections has a trigger, polling schedule, or Manual Sync entry of its own. Each runs only as part of its parent's transfer.
Duplicate or Conflicting Mappings
Nine mapping collections operate on transaction data in this inbound direction: the parent and its eight children described here.
Other collections in the template also operate on Transaction records and must be coordinated with this family:
Add Heartland Sales Order TO iPaaS.com, with its own child address, line, line discount, note, payment, and tax collections, brings Heartland sales orders into iPaaS.com. That opposite direction is documented separately and is not covered here.
Add Heartland Sales Order Deposit TO iPaaS.com, with its own deposit address, deposit line, deposit line discount, deposit payment, and deposit tax children, creates a deposit ticket copy in iPaaS.com when a sales order is transferred to iPaaS.com. The deposit ticket is an exact copy of the original order with a deposit suffix appended to the transaction number and to all external record identifiers. Disable or delete those collections if you do not want the deposit ticket copy.
Update Heartland Invoice FROM iPaaS.com (Order Complete) and Add Heartland Invoice FROM iPaaS.com (Invoice) create Heartland invoices from iPaaS.com transactions. They share the transaction data type with this family. The parent order collection's CreateInvoice mapping is defaulted so that no invoice is created alongside the order precisely so these two do not collide. If you change CreateInvoice to create invoices here, disable the invoice-from-order-update collection, or the same order can be invoiced twice.
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 order data. A template collection is provided for every transaction type in both directions; enabling all of them bi-directionally is not recommended. The Transaction Source value written by the parent is the marker that lets the outbound direction skip orders iPaaS.com created, and it is the main defense against a feedback loop.
Collision Handling
This integration does not use iPaaS.com collision handling for transactions. Whether an order is created or updated in Heartland is determined by the external-id link and the parent mapping filter; there is no collision recovery step to configure.
Supported Child Collections
All eight of the following are children of Add/Update Heartland Sales Order FROM iPaaS.com. None transfers on its own.
Add/Update Heartland Sales Order Address FROM iPaaS.com: writes the order's billing and shipping addresses. Only addresses flagged primary billing or primary shipping are processed. The shipping method on the primary shipping address also drives the order's shipping method on the parent.
Add Heartland Sales Order Cash Payment FROM iPaaS.com: writes payments routed as cash.
Add Heartland Sales Order Check Payment FROM iPaaS.com: writes payments routed as check.
Add Heartland Sales Order Custom Payment FROM iPaaS.com: writes payments routed as custom, resolving the iPaaS.com payment method name to a Heartland payment type.
Add/Update Heartland Sales Order External Payment FROM iPaaS.com: writes payments routed as external.
Add Heartland Sales Order Gift Card Payment FROM iPaaS.com: writes payments routed as gift card, resolving the Heartland gift card number.
Add/Update Heartland Sales Order Line Item FROM iPaaS.com: writes the order's line items, resolving each iPaaS.com SKU to a Heartland item and distributing tax across the lines.
Add Heartland Sales Order Note FROM iPaaS.com: writes the order's note.
Three of these can stop the whole order transfer rather than failing quietly: the line item collection when a SKU cannot be resolved to a Heartland item, the custom payment collection when a payment method name cannot be resolved to a Heartland payment type, and the gift card payment collection when it is configured to require a card that already exists in Heartland. Those conditions surface in the iPaaS.com Dashboard error logs.
System Caveats
Heartland Caveats
Customer, billing address, and shipping address required: Heartland requires all three on every sales order. The customer is resolved on the parent; the two addresses are supplied by the address child collection.
Station and source location required: Heartland requires a station and an inventory source location to create an order. Both come from iPaaS.com custom fields, so those values must exist in the source data or be produced by mapping logic. Heartland station and location IDs are visible in the Heartland retail website under Settings and Locations, in the station list shown after selecting a location.
Shipping method must exist: when a shipping method is present on the primary shipping address, it must match an existing Heartland shipping method. If it does not, the transfer is prevented.
SKU must exist: every line's SKU must correspond to an existing Heartland item. There is no automatic product transfer in this direction — an unresolved SKU stops the entire order, not just the one line.
Payments cannot exceed the order balance: Heartland computes the sales order total from line item prices, line item taxes, and shipping amounts, and rejects a payment that exceeds it.
Two-decimal precision: although Heartland's order screens display two decimal places, Heartland can retain more internally. An over-precise tax or payment amount can surface later as a balance error that is difficult to diagnose. Round tax and payment amounts sent to Heartland to two decimal places.
Per-line tax is required: Heartland expects a tax amount on each line rather than a single order-level total. Source platforms that only provide header tax need the tax proportioning the line item collection performs.
Deposits are restricted by payment type: Heartland allows only gift card, custom, and external payment types to be applied as order deposits. A cash or check payment sent as a deposit is rejected by the Heartland Order API. Using a dedicated custom or external payment type is the recommended way to represent externally captured order payments imported from iPaaS.com.
Completed orders cannot be invoiced: new orders are created in a "pending" status so payments can be added and the order can later be invoiced.
One invoice per order: when invoices are created from a linked order update, Heartland allows only one invoice per order and partial invoicing is not possible. Invoice only completed orders.
Order number auto-increment: Heartland auto-increments order numbers by default. This family overrides the number with the iPaaS.com transaction number; the override can be disabled in the mapping.
Address matching: when a sales order is created, Heartland first checks whether the customer already has an exactly matching address and reuses it; if there is no exact match, a new address is added and linked to the order. Supplying complete addresses keeps this matching predictable.
Gift card balance behavior is undocumented: the way a gift card payment affects the Heartland gift card balance depends on the combination of the payment's Status and Deposit values. These behaviors are not documented or supported by Heartland and may change without notice. See Integration-Specific Caveats for the combinations.
iPaaS.com Caveats
Manual Sync uses the iPaaS.com ID: Manual Sync in this direction takes the iPaaS.com transaction's internal ID, not a Heartland identifier.
Custom field prerequisites: the Heartland Station Id, Heartland Source Location Id, Heartland Invoice Id, and Transaction Source custom fields must exist on the Transaction collection in iPaaS.com, and Heartland Payment Type must exist on the transaction payment, so their values can be supplied or stored.
Only filtered records transfer: the parent processes a transaction only when its Type is "Order" and it has no Heartland Invoice Id. Tickets, invoices, and already-invoiced orders are skipped here and handled by other collections.
Placeholder customers: Heartland requires a customer on every order, but a source platform generating guest orders may not supply one. In that case it may be necessary to create a placeholder customer account in iPaaS.com and map guest orders to it, then review mapping filters to exclude the placeholder's addresses where they are not wanted.
Integration-Specific Caveats
Payment type routing is filter-driven: the five payment collections are selected entirely by the Heartland Payment Type custom field. A payment with no matching value is silently not written.
Gift card Status and Deposit combinations: the two values together control whether and when the Heartland gift card balance is reduced. With Status "pending" and Deposit true, the balance is reduced at order creation. With Status "pending" and Deposit false, the balance is reduced at invoicing. With Status "complete", neither Deposit value reduces the balance at order creation or at invoicing. The template ships Status "complete" with Deposit true. These behaviors are not documented or supported by Heartland and may change at any time; validate the combination your workflow depends on in a staging environment.
Empty gift cards: even with the combinations above chosen to preserve balances, the Heartland API still requires an available balance at least equal to the payment amount. Gift cards integrated with other platforms are often fully depleted, which blocks the payment. The optional subscription setting Adjust Empty Gift Card For Payment addresses this: when it is enabled and a gift card payment references a zero-balance card, the Heartland card is adjusted so the full payment amount can be applied, and the zero balance is then re-transferred to set it back. Set the subscription setting to True to enable it.
Automatic customer prerequisite: when the order references a customer that is not yet linked to Heartland, the integration transfers that customer to Heartland before the order. Subscribers do not pre-sync customers. See Integration Flow.
Automatic gift card prerequisite: gift cards referenced by the order's payments are transferred to Heartland automatically before the order. See Integration Flow.
No automatic product prerequisite: products and items are not auto-transferred by the order transfer. Every SKU on the order must already exist in Heartland.
Transfers are additive: an outbound transfer never removes a Heartland order, line, note, address, or payment.
Setup Requirements
Heartland Configuration
Create any Heartland custom field you intend to use before configuring the mappings, so it is visible on the Heartland website and available to mappings. Remember that orders and tickets need separate custom field group definitions.
Note the Heartland station and inventory source location IDs your orders should use. They are visible under Settings and Locations.
Confirm that every item referenced by an iPaaS.com order exists in Heartland with the SKU the order will supply.
Confirm that every shipping method name your source data uses exists as a Heartland shipping method.
Confirm that every payment method name your source data uses exists as a Heartland payment type, if you are routing payments through the custom payment collection.
iPaaS.com Configuration
Enable the subscription so outbound transfers can run.
Create the Heartland Station Id, Heartland Source Location Id, Heartland Invoice Id, and Transaction Source custom fields on the Transaction collection, and Heartland Payment Type on the transaction payment.
Populate Heartland Payment Type on every payment that should reach Heartland. A payment with no matching value is not written.
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.
Choose one of the two example approaches in the gift card number mapping and remove the other.
Decide whether invoices are created here or by the dedicated invoice collection, and enable only one of the two.
Review the parent and child mappings for any Heartland values you do not want written over on update. See Unmapped Field Overwrite Risk below.
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 transfer proceeds only when the transaction's Type is "Order" and its Heartland Invoice Id custom field is empty; otherwise the record is skipped without error.
Before anything is written to Heartland, the integration runs its prerequisite steps in the order below.
The Heartland sales order is created or updated from the parent mappings, in a "pending" status.
The address, line item, note, and payment child collections write their records as part of the same operation. Each payment is offered to all five payment collections, and the one whose filter matches writes it.
The Heartland order identifier is saved in iPaaS.com as the external-id link for future transfers.
Prerequisite step 1 — customer:
The integration checks whether the order's iPaaS.com customer already has an external-id link to a Heartland customer.
If a link exists, nothing is done and the transfer continues.
If no link exists, the integration retrieves the iPaaS.com customer and transfers it to Heartland first, through the customer collections. Subscribers do not need to pre-sync customers ahead of orders.
If that customer transfer fails, the order transfer is stopped with an error rather than being written against a missing customer.
Prerequisite step 2 — gift cards:
After the customer step, the integration examines each payment on the order for a linked iPaaS.com gift card.
For a gift card that is not yet linked to Heartland, the integration retrieves the iPaaS.com gift card and transfers it to Heartland. If the gift card's balance is zero and the Adjust Empty Gift Card For Payment subscription setting is enabled, the balance sent to Heartland is raised to the payment amount first so the payment can be applied.
For a gift card that is already linked, no action is taken unless its balance is zero and Adjust Empty Gift Card For Payment is enabled; in that case the card is re-transferred with the balance raised to the payment amount.
If a gift card transfer fails, the order transfer is stopped with an error.
Note that this gift card step is driven by the gift card reference carried on the iPaaS.com payment, not by the Heartland Payment Type custom field. A payment can therefore trigger a gift card prerequisite even if its payment type value does not route it to the gift card payment collection.
There is no equivalent prerequisite for products. Items must already exist in Heartland before the order transfers.
Manual Sync:
An iPaaS.com transaction ID is entered on the Manual Sync page.
The integration transfers that single transaction and all of its children through the same filter, prerequisite, and mapping path described above.
After the order is in Heartland:
Once payment is added, Heartland moves the order from "pending" to an open status.
If the invoice workflow is in use, a separate collection creates the Heartland invoice from a linked order update, and the resulting invoice identifier is stored so the order is not invoiced again.
Once all line items are invoiced, Heartland closes the order automatically.
Mappings
Add/Update Heartland Sales Order FROM iPaaS.com
Mapping Filter
var value = GetCustomFieldValue(CustomFields, "Heartland Invoice Id");
if (Type == "Order" && string.IsNullOrEmpty(value)){
return true;//Only invoice completed orders once
}
return false;The filter reads the Heartland Invoice Id custom field from the iPaaS.com transaction and then decides along two branches. When the transaction's Type is "Order" and the Heartland Invoice Id custom field is empty, the filter returns true and the transaction is processed as a new or updated Heartland sales order. In every other case the filter returns false and the transaction is skipped: that covers a transaction of any type other than "Order" (a ticket or an invoice, which other collections handle), and an order that already carries a Heartland Invoice Id, which is skipped so a completed order is invoiced only once. The filter raises no error on either branch; a skipped transaction simply does not transfer through this collection.
Description: Creates or updates a Heartland sales order from an iPaaS.com Transaction, in a "pending" status so payments can be added and the order can later be invoiced. The parent of all eight child collections listed below.
Mapping Type | Source Field (iPaaS.com) | Destination Field (Heartland) | Description |
Field | Heartland Source Location Id (custom field) | SourceLocationId | Required. Writes the Heartland inventory source location to the order, read from the iPaaS.com transaction's Heartland Source Location Id custom field. Heartland requires an inventory source location to create an order, so supply this value in the source data or produce it through mapping logic. Heartland source location IDs are visible in the Heartland retail website under Settings and Locations. The custom field must exist on the Transaction collection in iPaaS.com to supply the value. |
Field | Heartland Station Id (custom field) | StationId | Required. Writes the Heartland station to the order, read from the iPaaS.com transaction's Heartland Station Id custom field. Heartland requires a station to create an order. Station IDs are visible in the Heartland retail website under Settings and Locations, in the station list shown after selecting a location. The custom field must exist on the Transaction collection in iPaaS.com to supply the value. The cash and check payment collections read this same custom field from the parent transaction. |
Dynamic Formula |
| CustomerId | Required. Resolves the Heartland customer to assign to the order. The formula first looks for the Heartland customer already linked to the iPaaS.com customer; if none is linked, it falls back to finding a Heartland customer by the transaction's email address. Heartland requires a customer on every sales order, so if neither method resolves a customer the order cannot be created. The integration also transfers an unlinked customer to Heartland automatically before the order — see Integration Flow. |
Static | "Order" | Type | Required. Sets the transaction type to "Order" so the record is created as a Heartland sales order. This value routes the transfer to the sales order workflow and is also the value the mapping filter checks. |
Static | "pending" | Status | Required for the invoice workflow. Sets the new Heartland order to a "pending" status. Heartland will not allow a completed order to be invoiced, and an order must be created in a status other than complete before payments can be added; a pending status satisfies both. After payment is added, Heartland moves the order to an open status, and once all line items are invoiced the order is closed automatically. Adjust this static value only if your workflow requires a different starting status. |
Dynamic Formula |
| ShippingMethodId | Recommended when your orders carry a shipping method. Determines the Heartland shipping method for the order by reading the shipping method from the order's primary shipping address and converting that name to the matching Heartland shipping method. If a shipping method name is present but cannot be matched, the transfer is prevented with the message "[shipping method] shipping method could not be found in Heartland and will prevent this transfer" and the condition appears in the iPaaS.com Dashboard error logs. If no shipping method is present, no value is set. |
Field | ShippingAmount | ShippingCharge | Optional. Writes the iPaaS.com transaction's shipping amount to the Heartland order's shipping charge. Heartland calculates the order total from line item prices, line item taxes, and the shipping amount, and a payment cannot exceed the order total, so an accurate shipping amount helps payments apply correctly. |
Dynamic Formula |
| PublicId | Optional. Sets the human-friendly Heartland order number to the iPaaS.com transaction number, overriding the number Heartland would otherwise assign automatically. The formula includes a commented-out alternative that returns no value; switch to that alternative if you prefer Heartland to auto-assign the order number. |
Dynamic Formula |
| CreateInvoice | Optional. Controls whether an invoice is created in Heartland immediately after the sales order is created. Defaulted so that no invoice is created alongside the order. Set this mapping to return true only if you want to create an invoice from a completed sales order right after creating the order. A dedicated companion collection already creates invoices from linked order updates; if you enable invoice creation here, disable that companion collection so the same order is not invoiced twice. |
Static | "iPaaS.com" | Transaction Source (custom field) | Optional but recommended when running both directions. Writes the value "iPaaS.com" to the Transaction Source custom field on the Heartland order, marking the order as originating from iPaaS.com. This marker lets the reverse-direction collections recognize and skip orders that iPaaS.com created, which prevents a feedback loop. The custom field must exist in Heartland and on the Transaction collection in iPaaS.com before the value can be stored. |
Add/Update Heartland Sales Order Address FROM iPaaS.com
This is a child collection of Add/Update Heartland Sales Order 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
IsPrimaryBilling || IsPrimaryShipping
The filter has two branches, and either one is sufficient. An address on the iPaaS.com transaction is processed when it is flagged as the primary billing address, or when it is flagged as the primary shipping address. An address flagged as both is processed once. An address flagged as neither is skipped and never reaches Heartland. This keeps Heartland to exactly the billing and shipping addresses it requires on the order and prevents extra addresses it cannot use. The filter raises no error; it only determines which addresses are processed. Adjust it if you use different fields to indicate the billing and shipping address.
Description: Writes the iPaaS.com transaction's billing and shipping addresses to the Heartland sales order created or updated by its parent. The shipping method recorded on the primary shipping address also drives the parent order's shipping method.
Mapping Type | Source Field (iPaaS.com) | Destination Field (Heartland) | Description |
Field | Address1 | Line1 | Recommended. Writes the first street line from the iPaaS.com transaction address to the Heartland order address Line1 field. Because Heartland matches the address against the customer's existing addresses and adds a new one only when no exact match is found, supplying the full street address keeps matching predictable. Validate field requirements in a staging environment before relying on them in production. |
Field | Address2 | Line2 | Optional. Writes the second street line from the iPaaS.com transaction address to the Heartland order address Line2 field. Used when the address has a suite, unit, or similar second line. |
Field | City | City | Recommended. Writes the city from the iPaaS.com transaction address to the Heartland order address. Heartland reuses an existing customer address when it finds an exact match and otherwise adds a new one, so a complete address keeps that matching predictable. |
Field | Region | State | Recommended. Writes the state or region from the iPaaS.com transaction address to the Heartland order address State field. A complete address helps Heartland match against the customer's existing addresses rather than creating an unexpected new one. |
Field | PostalCode | PostalCode | Recommended. Writes the postal code from the iPaaS.com transaction address to the Heartland order address. A complete address helps Heartland match against existing addresses rather than creating a new one. |
Field | Country | Country | Recommended. Writes the country from the iPaaS.com transaction address to the Heartland order address. A complete address helps Heartland match against existing addresses rather than creating a new one. |
Field | FirstName | FirstName | Optional. Writes the first name recorded on the iPaaS.com transaction address to the Heartland order address. |
Field | LastName | LastName | Optional. Writes the last name recorded on the iPaaS.com transaction address to the Heartland order address. |
Field | IsPrimaryBilling | IsPrimaryBilling | Required in practice. Writes the primary-billing indicator to the Heartland order address, telling Heartland that this address is the order's billing address. The mapping filter processes an address only when it is flagged as primary billing or primary shipping, so an address with neither flag never reaches Heartland — and Heartland requires a billing address on every sales order. Adjust this mapping if you use a different field to indicate the billing address. |
Field | IsPrimaryShipping | IsPrimaryShipping | Required in practice. Writes the primary-shipping indicator to the Heartland order address, telling Heartland that this address is the order's shipping address. As with billing, an address flagged as neither is skipped by the filter, and Heartland requires a shipping address on every sales order. The shipping method on the primary shipping address also drives the order's shipping method on the parent order. Adjust this mapping if you use a different field to indicate the shipping address. |
Add Heartland Sales Order Cash Payment FROM iPaaS.com
This is a child collection of Add/Update Heartland Sales Order 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 branches. When that custom field is empty or missing, the filter returns false and the payment is not written by this collection. When it holds a value that is not "CashPayment", the filter also returns false, and the payment is left to whichever sibling payment collection matches its value. Only when the value is exactly "CashPayment" does the filter return true and the payment is written to Heartland as a cash payment. The filter raises no error on any branch; a payment whose value matches none of the five payment collections is simply not written to Heartland at all.
Description: Writes a cash payment onto the Heartland sales order created by its parent, using the request format Heartland requires for cash. The sync method is Add.
Mapping Type | Source Field (iPaaS.com) | Destination Field (Heartland) | Description |
Field | Amount | Amount | Required. Writes the iPaaS.com transaction payment amount to the Heartland cash payment; a payment cannot be added without one. Heartland rejects a payment whose amount exceeds the order balance, returning an error such as "Payment cannot exceed balance of sales order," where the order total is the sum of line item prices, line item taxes, and shipping amounts. Because amounts can carry more than two decimal places internally even though Heartland displays two, round the amount to two decimal places to avoid an unexpected balance error. 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. |
Static | "1" | PaymentTypeId | Required for cash payment types. Sets the Heartland payment type identifier to Heartland's built-in identifier for a cash payment. Heartland's built-in payment types are identified by numeric identifiers — CashPayment is 1, CheckPayment is 2, and GiftCardPayment is 3 — and this value must match the payment type used by this collection. |
Static | "CashPayment" | Type | Required. Sets the Heartland payment type so Heartland applies its cash payment request format. This value must agree with the Heartland Payment Type custom field the mapping filter checks, so a payment marked "CashPayment" is routed here. It is a fixed part of this template's cash payment flow. |
Static | "complete" | Status | Sets the Heartland cash payment status to "complete," marking the payment as fully applied. A fixed part of this template's cash payment flow. |
Dynamic Formula |
| Deposit | Keeps the cash payment from being applied as an order deposit. Heartland's Order API returns an error if a cash payment is added as a deposit, so this mapping always sends the payment as a non-deposit. Leave it as delivered for cash payments. If you need a deposit payment, use a payment type Heartland allows as a deposit — gift card, custom, or external — through its dedicated payment collection. |
Dynamic Formula |
| StationId | Required for cash payment types. Supplies the Heartland station the cash payment is taken at. The formula reads the Heartland Station Id custom field from the parent transaction: when that custom field holds a value it is converted to a whole number and sent as the station; when it is empty, no station is sent. Ensure the custom field is populated on the parent transaction so the cash payment can be created. The station is read from the parent transaction rather than the payment itself, so it is shared with the sales order and its other payments. |
Add Heartland Sales Order Check Payment FROM iPaaS.com
This is a child collection of Add/Update Heartland Sales Order 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 branches three ways. An empty or missing value returns false and this collection writes nothing. A value that is present but is not "CheckPayment" also returns false, leaving the payment to the sibling collection that matches it. Only an exact value of "CheckPayment" returns true, and the payment is written to Heartland as a check payment. No branch raises an error.
Description: Writes a check payment onto the Heartland sales order created by its parent, using the request format Heartland requires for checks. The sync method is Add.
Mapping Type | Source Field (iPaaS.com) | Destination Field (Heartland) | Description |
Field | Amount | Amount | Required. Writes the iPaaS.com transaction payment amount to the Heartland check payment; a payment cannot be added without one. Heartland rejects a payment whose amount exceeds the order balance, returning an error such as "Payment cannot exceed balance of sales order," where the order total is the sum of line item prices, line item taxes, and shipping amounts. Round the amount to two decimal places 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. |
Static | "2" | PaymentTypeId | Required. Sets Heartland's built-in payment type identifier for a check payment. 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. |
Static | "CheckPayment" | Type | Required. Designates the payment as a check so Heartland applies its check payment request format. Heartland's built-in payment types carry both a name and a numeric identifier: CashPayment (1), CheckPayment (2), and GiftCardPayment (3). This value pairs with the PaymentTypeId mapping and with the Heartland Payment Type custom field the filter checks. |
Static | "complete" | Status | Sets the Heartland check payment status to "complete," marking the payment as fully applied to the order. A fixed part of this template's check payment flow. |
Dynamic Formula |
| Deposit | Sets the deposit flag on the Heartland check payment to false. Heartland does not allow a check payment to be applied as an order deposit; only gift card, custom, or external payment types may be. If a check payment is sent as a deposit, the Heartland Order API returns an error, which appears in the iPaaS.com Dashboard error logs. Leave this behavior in place for check payments. |
Dynamic Formula |
| StationId | Required. Supplies the station identifier Heartland expects on a check payment. The formula reads the Heartland Station Id custom field from the parent order; when a value is present it is converted to a whole number and written to the payment, and when none is present nothing is written. If the parent order 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 — Heartland expects a custom object on a check payment, so leave a value returned even if 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. This is a placeholder to replace during implementation: substitute the check information you want stored on the Heartland payment, or switch to the empty-object form if you do not need to store any. |
Add Heartland Sales Order Custom Payment FROM iPaaS.com
This is a child collection of Add/Update Heartland Sales Order 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. An empty or missing value returns false and nothing is written here. A value present but not equal to "CustomPayment" also returns false, and the payment is handled by the cash, check, gift card, or external sibling collection whose value it matches. An exact value of "CustomPayment" returns true and the payment is written to Heartland as a custom payment. No branch raises an error.
Description: Writes a custom payment onto the Heartland sales order created by its parent, resolving the iPaaS.com payment method name to a Heartland payment type. Custom is one of the three payment types Heartland permits as an order deposit, and the template marks these payments as deposits. The sync method is Add.
Mapping Type | Source Field (iPaaS.com) | Destination Field (Heartland) | Description |
Field | Amount | Amount | Required. Writes the payment amount from the iPaaS.com transaction payment to the Heartland custom payment. The amount cannot exceed the remaining balance of the Heartland order; 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. |
Dynamic Formula |
| PaymentTypeId | Required. Resolves the iPaaS.com payment method name to a Heartland payment type. A custom payment must be tied to an existing Heartland payment type. If the name cannot be matched, the transfer is prevented with the message "Payment method "[method]" could not be found in Heartland and is preventing transfer of this order" and the condition appears in the iPaaS.com Dashboard error logs. Confirm that every payment method used on iPaaS.com transactions exists as a payment type in Heartland. |
Static | "CustomPayment" | Type | Required. Sets the payment type so Heartland applies its custom payment request format. Heartland's built-in payment types are CashPayment (1), CheckPayment (2), and GiftCardPayment (3); custom payment types are defined in Heartland and resolved by name through the PaymentTypeId mapping. Leave this value as delivered for this collection; the sibling cash, check, gift card, and external collections set their own type values. |
Static | "complete" | Status | Required. Records the payment as completed when the order is created. This value is set for every payment through this collection, and subscribers do not normally change it. |
Dynamic Formula |
| Deposit | Optional. Marks the custom payment as an order deposit. The template returns true, so the payment is applied as a Heartland sales order deposit. Heartland allows only gift card, custom, or external payment types to be applied as deposits, and custom types are eligible. Adjust the value if you do not want the custom payment treated as a deposit. |
Dynamic Formula |
| Custom | Optional — a custom payment accepts a custom object even when it is empty. The formula builds a data object from an example value and returns it, so the payment carries whatever custom details you supply. This is a placeholder to replace during implementation: substitute the data your workflow needs, or return an empty object if none is required. Validate this behavior in a staging environment before relying on it in production. |
Add/Update Heartland Sales Order External Payment FROM iPaaS.com
This is a child collection of Add/Update Heartland Sales Order 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 value = GetCustomFieldValue(CustomFields, "Heartland Payment Type");
if(!string.IsNullOrEmpty(value)){
if(value == "ExternalPayment"){return true;}
}
return false;The comment at the top states the reason the five payment collections exist at all: Heartland requires a different request format depending on the payment type. The filter then reads the Heartland Payment Type custom field from the iPaaS.com transaction payment. An empty or missing value returns false. A value present but not equal to "ExternalPayment" also returns false, and the payment is handled by the sibling collection matching its value. An exact value of "ExternalPayment" returns true and the payment is written to Heartland as an external payment. No branch raises an error. Set Heartland Payment Type to "ExternalPayment" on any iPaaS.com payment that should be recorded in Heartland as captured outside Heartland.
Description: Writes an external payment onto the Heartland sales order created by its parent — an amount captured outside Heartland, for example through a separate payment processor, being recorded against the order. The sync method is Add/Update.
Mapping Type | Source Field (iPaaS.com) | Destination Field (Heartland) | Description |
Field | Amount | Amount | Required. Sets the Heartland external payment amount from the iPaaS.com transaction payment; a payment cannot be recorded on the Heartland sales order without one. Heartland rejects a payment that exceeds the remaining balance of the order, so confirm the amount does not exceed the order balance. Rounding order and tax amounts to two decimal places helps avoid a payment that appears within the balance but slightly exceeds it. Validate this behavior in a staging environment before relying on it in production. |
Field | Description | Description | Required. Sets the Heartland external payment description from the iPaaS.com transaction payment. Heartland requires a description on external payment types, so supply a value or the payment is not accepted. |
Static | "ExternalPayment" | Type | Required. Identifies the payment to Heartland as an external payment, which is what tells Heartland to apply its external payment request format. It corresponds to the Heartland Payment Type custom field value the collection filter checks. This value applies to every payment added through this collection. |
Static | "complete" | Status | Required for the payment to be recorded as finished rather than pending. Records the payment as completed on the Heartland sales order. This value applies to every external payment added through this collection. |
Dynamic Formula |
| Deposit | Optional. Controls whether the payment is applied to the Heartland sales order as a deposit. The formula returns false, so by default the external payment is not treated as an order deposit. Heartland allows only gift card, custom, or external payment types to be applied as deposits, so an external payment is eligible. Change the formula to return true if the payment should be recorded as a deposit. |
Add Heartland Sales Order Gift Card Payment FROM iPaaS.com
This is a child collection of Add/Update Heartland Sales Order 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. An empty or missing value returns false and this collection writes nothing. A value present but not equal to "GiftCardPayment" also returns false, and the cash, check, custom, or external sibling collection matching that value handles the payment instead. An exact value of "GiftCardPayment" returns true and the payment is written to Heartland as a gift card payment. Every sibling collection filters on the same custom field for its own type, so the value on each iPaaS.com payment determines which single collection writes it. No branch raises an error.
Description: Writes a gift card payment onto the Heartland sales order created by its parent, resolving the Heartland gift card number the payment draws against. The sync method is Add.
Mapping Type | Source Field (iPaaS.com) | Destination Field (Heartland) | Description |
Field | Amount | Amount | Required. Sets the amount applied to the Heartland sales order as a gift card payment. The gift card must hold an available balance at least equal to this amount, unless the Adjust Empty Gift Card For Payment subscription setting is enabled. |
Static | "3" | PaymentTypeId | Required, and paired with the Type field. Heartland's built-in payment type identifiers are 1 for cash, 2 for check, and 3 for gift card, so this collection sends 3. Leave this value as delivered for gift card payments. |
Static | "GiftCardPayment" | Type | Required, and paired with the PaymentTypeId field. Identifies the Heartland payment type as a gift card payment so Heartland records the payment against the gift card. Leave this value as delivered for gift card payments. |
Static | "complete" | Status | Recommended — review against your workflow. Sets the payment status sent to Heartland; the template default is complete. Combined with the Deposit value, Status controls whether and when the Heartland gift card balance is reduced: with complete, order and invoice creation do not reduce the balance; with pending, the balance is reduced either at order creation or at invoicing depending on the Deposit value. Validate the combination in a staging environment before relying on it in production. |
Dynamic Formula |
| Deposit | Recommended — review against your workflow. Marks the gift card payment as a deposit. Heartland allows gift card, custom, and external payment types to be applied as order deposits. The Deposit value works together with Status to control the gift card balance: with Status "pending", a Deposit of true reduces the balance at order creation and false reduces it at invoicing; with Status "complete", neither value reduces the balance at order or invoice creation. These balance behaviors are not documented or supported by Heartland and may change without notice; validate the combination in a staging environment before relying on it in production. |
Dynamic Formula |
| GiftCardNumber | Required — the Heartland API requires a gift card number on a gift card payment. A Heartland gift card number is stored in iPaaS.com as the gift card record's external id, and the formula resolves the number from the gift card linked to the iPaaS.com payment. The template ships two example approaches; keep and adjust the one that suits your workflow and remove the other. The first returns the gift card redemption number for the payment. The second returns the gift card's external id and, when the card cannot be found in Heartland, prevents the transfer with the message "Gift Card Id [id] does not exist in Heartland and will prevent transfer of this order payment". If you use the second approach, the linked gift card must have been transferred to Heartland before the order payment is sent, or the payment transfer is prevented and the condition is reported in the iPaaS.com Dashboard error logs. |
Add/Update Heartland Sales Order Line Item FROM iPaaS.com
This is a child collection of Add/Update Heartland Sales Order 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 order's line items to the Heartland sales order created by its parent, resolving each iPaaS.com SKU to a Heartland item and distributing the order's tax across the lines. Because Heartland builds the order total from line prices, line taxes, and shipping, the values written here determine what payments the Heartland order will accept.
Mapping Type | Source Field (iPaaS.com) | Destination Field (Heartland) | Description |
Dynamic Formula |
| ItemId | Required for every line. Resolves the Heartland item for the line from the iPaaS.com line item SKU. When a match is found the formula returns that item's identifier; when no match is found it stops the transfer with the error "Sku: [SKU] was not found in Heartland preventing this transaction from transferring" and no sales order is created — the failure stops the entire order, not just the one line. To resolve it, either create the item in Heartland with the SKU the iPaaS.com line uses, or adjust the source data or mapping so the line supplies a SKU that already exists in Heartland. There is no automatic product transfer in this direction, so confirm every line's SKU resolves before transferring an order that references it. |
Field | Qty | Qty | Required in practice. Writes the iPaaS.com line item quantity to the Heartland line. Heartland needs the quantity to compute the line and order totals, so map it for every line. Validate the field's behavior in a staging environment before relying on it in production. |
Field | UnitPrice | AdjustedUnitPrice | Recommended. Writes the iPaaS.com line item unit price to the Heartland line's effective per-unit price. Together with Qty it contributes to the Heartland order subtotal, which Heartland uses to validate that payments do not exceed the order total, so map an accurate unit price. |
Field | OriginalUnitPrice | OriginalUnitPrice | Recommended. Writes the iPaaS.com line item original unit price — the per-unit price before any adjustment. Map both this and AdjustedUnitPrice so the Heartland line reflects the original and effective prices. |
Dynamic Formula |
| TotalTax | Recommended. Sets the line's tax amount in Heartland. Heartland requires a tax amount on each line rather than a single order-level total, so when the source platform does not provide per-line tax the formula allocates the order's header tax across the lines: each line receives a share of the header tax in proportion to its extended price relative to the order subtotal, rounded to two decimal places. When the order subtotal is zero, the line's own estimated tax amount is used instead. As delivered, the formula always uses the allocated amount; it can be adjusted to prefer a line-level tax value from iPaaS.com when one is present. Round tax amounts sent to Heartland to two decimal places — Heartland can retain more precision than its order screens display, and an over-precise tax value can later surface as a payment exceeding the sales order balance. If your source platform already supplies accurate per-line tax, review this mapping and validate the outcome in a staging environment before relying on it in production. |
Add Heartland Sales Order Note FROM iPaaS.com
This is a child collection of Add/Update Heartland Sales Order 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 note recorded on the iPaaS.com transaction to the Heartland sales order created by its parent. The sync method is Add, so the note content is added to the Heartland order as the order is created or updated.
Mapping Type | Source Field (iPaaS.com) | Destination Field (Heartland) | Description |
Field | Text | Content | Required in practice — a note with no content carries no information into Heartland. Writes the note text from the iPaaS.com transaction note to the Heartland sales order note Content field, so the note travels into Heartland with its order. This is the only field the collection maps. Because the sync method is Add, the note content is added to the Heartland order each time the parent order is transferred. Validate how Heartland handles an empty note value, and how it handles the note when the same order is transferred more than once, in a staging environment before relying on this behavior in production. |
Unmapped Field Overwrite Risk
This direction writes to Heartland, and the transfer sends a partial payload built from the mapped values. As a result, Heartland order fields that these collections do not map are generally not cleared on update — this is not the full-replace behavior that applies when records are written into iPaaS.com. Several qualifications matter, and all of them are subscriber-visible.
Every mapped field is overwritten on update. The parent collection uses an Add/Update sync. When a transfer writes to a Heartland order that is already linked, each mapped field replaces the current Heartland value: the customer, station, source location, status, type, shipping method, shipping charge, order number, and the Transaction Source custom field. If Heartland is where any of those values is maintained, edits made there will be written over on the next outbound transfer.
Line items can lose unmapped Heartland values. The line item collection also uses an Add/Update sync. When a linked order's lines are updated, the values sent replace the corresponding values on the Heartland line item, and any Heartland line field this collection does not map may be overwritten or reset. The collection maps only the item, quantity, both unit prices, and the line tax. Review the Heartland line item fields your workflow relies on and confirm each is either mapped here or maintained on the Heartland side before running updates.
Notes are added, not replaced. The note collection uses an Add sync and maps only the note content. Repeated transfers of the same order can therefore add the note again rather than replace an existing one, and any other note attributes Heartland supports are left to Heartland's defaults.
Addresses are matched, not necessarily updated. The address collection supplies the current iPaaS.com values, but Heartland resolves the address by looking for an exact match among the customer's existing addresses: it reuses a matching address when one is found and adds a new one when none is. A partially changed address can therefore produce an additional Heartland address rather than an edit to the existing one.
Payments are re-sent on every parent transfer. The external payment collection uses an Add/Update sync, so each re-transfer of the parent order re-sends its mapped payment values, and a change made directly to that payment in Heartland can be replaced. The cash, check, custom, and gift card payment collections use an Add sync, so re-transfers can add a payment rather than update one — and because Heartland rejects a payment that exceeds the order balance, a duplicated payment typically surfaces as a balance error rather than as silent data loss.
Preservation remedy. For any Heartland field you need to keep, add a Dynamic Formula mapping whose source is DestinationValue.[FieldName] in the collection that writes it. That reads the current Heartland value and writes it back, so the field is not cleared or replaced. Alternatively, remove the mapping for the field entirely so nothing is sent for it.
Validate in staging. There is no Heartland API specification bundled with this documentation, so the full list of writable Heartland order and line fields cannot be enumerated here, and partner-side clearing behavior must be confirmed rather than assumed. Before enabling outbound updates in production, populate the Heartland order and line fields your business relies on in a staging environment, run an update from iPaaS.com, and confirm afterward which values survived. Add preservation mappings for anything that did not.
Error Handling
SKU was not found in Heartland: a line item's SKU does not correspond to an existing Heartland item. The transfer stops with the message "Sku: [SKU] was not found in Heartland preventing this transaction from transferring" and no sales order is created. Create the item in Heartland with that SKU, or correct the SKU on the iPaaS.com line, then transfer again.
Shipping method could not be found in Heartland: the shipping method name on the primary shipping address does not match a Heartland shipping method. The transfer is prevented with the message "[shipping method] shipping method could not be found in Heartland and will prevent this transfer". Create the shipping method in Heartland or correct the name in the source data.
Payment method could not be found in Heartland: a custom payment's method name does not match a Heartland payment type. The transfer is prevented with the message "Payment method "[method]" could not be found in Heartland and is preventing transfer of this order". Create the payment type in Heartland or correct the method name.
Gift card does not exist in Heartland: when the gift card mapping is configured to require an existing card, a card that has not been transferred to Heartland prevents the payment transfer with the message "Gift Card Id [id] does not exist in Heartland and will prevent transfer of this order payment". Transfer the gift card to Heartland first, or switch to the redemption-number approach in the mapping.
Payment cannot exceed balance of sales order: the payment amount is greater than the Heartland order total, which Heartland computes from line item prices, line item taxes, and shipping amounts. This most often comes from tax or price values carrying more than two decimal places. Round tax and payment amounts to two decimals and confirm the line values reaching Heartland are correct.
Order transfer stopped because its customer could not be created: when the order references a customer that is not yet linked, the integration transfers that customer first. If the customer transfer fails, the order transfer is stopped. Resolve the customer error — most often a missing name or an invalid email address — and transfer the order again.
Order transfer stopped because a gift card could not be created: when a payment references a gift card that is not yet linked, the integration transfers the gift card first. If that transfer fails, the order transfer is stopped. Resolve the gift card error and transfer the order again.
Payment silently missing from the Heartland order: if the order transferred successfully but a payment did not reach Heartland, check the Heartland Payment Type custom field on that iPaaS.com payment. An empty value, or any value other than the five recognized types, matches no payment collection and the payment is skipped without an error.
Order was skipped without an error: the parent filter processes only transactions whose Type is "Order" and whose Heartland Invoice Id custom field is empty. Tickets, invoices, and orders that have already been invoiced are skipped by design.
Cash or check payment rejected as a deposit: Heartland allows only gift card, custom, and external payment types as order deposits. Leave the deposit value false in the cash and check collections.
Heartland temporarily unavailable: if the Heartland API cannot be reached when a transfer is triggered, the transfer fails, including all of its children. The error appears in the iPaaS.com Dashboard error logs, and the record can be retried through a new transfer or Manual Sync of the transaction.
Testing & Validation
Test Scenarios
New order created — transfer an iPaaS.com transaction of Type "Order" with a customer, both addresses, at least one line, and a payment, and confirm a Heartland sales order is created in a "pending" status with the correct station and source location.
External-id link written — confirm the Heartland order identifier is saved in iPaaS.com with the order suffix, and that a second transfer of the same transaction updates the same Heartland order rather than creating a new one.
Filter skips a ticket — transfer a transaction whose Type is not "Order" and confirm it is skipped with no Heartland order created and no error raised.
Filter skips an already-invoiced order — populate the Heartland Invoice Id custom field on a transaction and confirm the order is skipped.
Customer prerequisite — transfer an order whose customer is not yet linked to Heartland and confirm the customer is created in Heartland automatically before the order, with no pre-sync step performed by hand.
Customer prerequisite failure blocks the order — transfer an order whose customer cannot be created in Heartland and confirm the order transfer stops with an error rather than creating an order without a customer.
Gift card prerequisite — transfer an order with a gift card payment whose card is not yet linked to Heartland and confirm the gift card is transferred before the order.
Empty gift card adjustment — with Adjust Empty Gift Card For Payment enabled, transfer an order paying with a zero-balance gift card and confirm the payment applies and the balance is set back afterward.
Missing SKU stops the order — transfer an order containing a line whose SKU does not exist in Heartland and confirm no order is created and the SKU error is reported.
Unknown shipping method stops the order — transfer an order whose primary shipping address carries a shipping method name that does not exist in Heartland and confirm the transfer is prevented.
Cash payment routing — set Heartland Payment Type to CashPayment on a payment and confirm it is written to Heartland as a cash payment with the station taken from the parent transaction.
Check payment routing — set the value to CheckPayment and confirm the payment is written with its custom object and its station.
Custom payment routing — set the value to CustomPayment and confirm the payment method name resolves to a Heartland payment type and the payment is applied as a deposit.
External payment routing — set the value to ExternalPayment and confirm the payment is written with its description.
Gift card payment routing — set the value to GiftCardPayment and confirm the payment is written against the correct Heartland gift card number.
Unrouted payment — leave Heartland Payment Type empty on a payment, transfer the order, and confirm the order succeeds, no payment is written, and the Heartland order balance is correspondingly unpaid. This is the failure mode most likely to go unnoticed in production.
Unrecognized payment type — set Heartland Payment Type to a value that is none of the five recognized types and confirm the same skip behavior.
Gift card balance combinations — with the same gift card payment, test the Status and Deposit combinations your workflow may use and record which reduce the Heartland gift card balance and when.
Address filter — transfer an order carrying an address flagged as neither primary billing nor primary shipping, and confirm that address is not written to Heartland.
Address reuse — transfer an order whose address exactly matches one already on the Heartland customer and confirm Heartland reuses it rather than adding a duplicate; then transfer a slightly changed address and observe whether a new Heartland address is added.
Tax proportioning — transfer an order that carries only header-level tax across several lines of differing extended prices, and confirm each Heartland line receives a proportional share rounded to two decimals summing to the header total.
Balance error reproduction — transfer an order whose tax carries more than two decimal places and a payment equal to the displayed total, and confirm whether Heartland raises a balance error.
Order number override — confirm the Heartland order number matches the iPaaS.com transaction number, then switch the mapping to the commented alternative and confirm Heartland auto-assigns instead.
Note behavior on re-transfer — transfer the same order twice and confirm whether the Heartland order carries one note or two.
Unmapped Heartland line fields — populate Heartland line fields this family does not map, run an update from iPaaS.com, and confirm which survive. Add DestinationValue preservation mappings for any that were cleared.
Preservation mapping works — add a Dynamic Formula mapping sourced from DestinationValue for a field you need to keep, run an update, and confirm the Heartland value is unchanged.
Manual Sync by ID — enter a known iPaaS.com transaction ID on the Manual Sync page and confirm the order and all of its children transfer.
Invoice double-creation guard — confirm that only one of the two invoice approaches is enabled, and that an order created here is not invoiced twice.
Feedback loop guard — with both directions enabled, confirm the Transaction Source value written on the Heartland order causes the outbound direction to skip that order.
Heartland unavailable — trigger a transfer while Heartland cannot be reached and confirm the failure is reported in the iPaaS.com Dashboard error logs and can be retried.
Validation Checklist
Every transferred transaction has Type "Order" and an empty Heartland Invoice Id, or it is intentionally excluded.
Heartland Station Id and Heartland Source Location Id are populated on every transaction that should transfer.
Heartland Payment Type is populated with one of the five recognized values on every payment that must reach Heartland, and unrouted payments have been checked for.
Every SKU on every transferring order exists in Heartland.
Every shipping method name and every custom payment method name used by the source data exists in Heartland.
Line tax reaching Heartland is rounded to two decimal places, and line totals plus shipping reconcile with the payments being sent.
Each order carries exactly one primary billing address and one primary shipping address in iPaaS.com.
The gift card Status and Deposit combination has been chosen deliberately and validated in staging.
The placeholder custom-data values in the check and custom payment collections have been replaced or switched to the empty-object form.
One of the two gift card number approaches has been kept and the other removed.
Only one invoice-creation approach is enabled.
Heartland order and line fields your business maintains in Heartland are either unmapped here or preserved with a DestinationValue mapping.
Any Heartland custom field used as a mapping destination exists in Heartland, and its iPaaS.com counterpart exists on the matching collection, before the transfer runs.
Additional Notes
The whole family moves as one operation. A sales order reaches Heartland with its addresses, lines, notes, and payments together, or it does not reach Heartland at all — several child conditions stop the entire parent transfer.
iPaaS.com is the source of truth for the fields listed under Mappings. Editing those values directly in Heartland will be written over on the next transfer of that order.
Customers and gift cards referenced by an order are transferred to Heartland automatically as part of the order transfer when they are not yet linked. Products are not — items must already exist in Heartland.
The order status progression is Heartland's, not the integration's: pending on creation, open once payment is added, closed once all lines are invoiced.
The gift card balance behaviors described in this article are not documented or supported by Heartland and are subject to change at any time. Treat them as behavior to verify in your own environment rather than as a contract.
Deleting or voiding a transaction in iPaaS.com has no effect in Heartland. Removals must be made in Heartland directly.
Related Documents
Setup & Reference
Mapping Documentation