Summary
Heartland sales orders are transferred into iPaaS.com as Transaction records of type Order. Along with the order header, the integration transfers the order's line items, addresses, notes, payments, and taxes through five child mapping collections, and it records several Heartland-specific values — the raw Heartland order status, the source location, and the station — on iPaaS.com custom fields.
This document also covers a second, companion family of collections: Add Heartland Sales Order Deposit TO iPaaS.com and its four children. A deposit ticket is a copy of the sales order that the integration produces automatically after the order itself has been transferred, so that downstream integrations expecting a separate deposit or ticket document have one to work with. It is not a separate Heartland record and it is never transferred on its own — it always rides on the back of a sales order transfer. The Sales Order Deposit Companion Flow section under Integration Flow explains when it fires and how the two records are linked.
iPaaS.com requires a unique transaction number on every Transaction record. Because Heartland auto-increments order, ticket, and invoice numbers separately, the same numeric value can appear on more than one transaction type. To keep the numbers unique, the template maps the Heartland external identifier — which carries an _ORDER suffix — to the iPaaS.com transaction number. If a transaction with that transaction number already exists in iPaaS.com, the transfer updates that record rather than creating a second one.
This document covers the Heartland to iPaaS.com direction. A separate family of collections writes sales orders in the opposite direction, from iPaaS.com into Heartland; that is a different flow with different trigger semantics and is listed under Duplicate or Conflicting Mappings.
ID Format
Manual Sync ID Format
On the iPaaS.com Manual Sync page, enter the Heartland order's external identifier in the {order number}_ORDER format — for example 100312_ORDER. The suffix is what tells the integration which Heartland record type to retrieve; an identifier without an _ORDER, _INVOICE, or _TICKET suffix is rejected with the message "The transaction id must contain _ORDER _INVOICE or _TICKET suffix to determine proper source". That single order is then transferred along with its lines, addresses, notes, payments, and taxes.
There is no Manual Sync entry for a deposit ticket. Syncing the order produces the deposit ticket at the same time, provided the order qualifies.
External ID Format
After a successful transfer, iPaaS.com records the order's external-id link in the {order number}_ORDER format, where {order number} is the Heartland order number. The _ORDER suffix keeps the order's transaction number distinct from Heartland ticket and invoice numbers that may share the same numeric value; Heartland applies the equivalent _TICKET and _INVOICE suffixes to those types.
The companion deposit ticket takes the same identifier with a -D suffix appended — the {order number}_ORDER-D format, for example 100312_ORDER-D. The suffix is appended to the deposit's own identifier and to the identifier of every line, line discount, payment, address, and tax record it carries, so nothing on the deposit collides with the order it was copied from. The deposit's ParentId mapping recovers the parent order by removing the trailing two characters from its own identifier.
Subsequent transfers of the same order match on the transaction number and update the existing iPaaS.com Transaction record rather than creating a duplicate. Whether an incoming order is created or updated is determined by whether that transaction number is already present in iPaaS.com, not by which event triggered the transfer.
Deleted Record Support
Deleting a Heartland sales order is not supported by this integration. The integration creates and updates iPaaS.com Transaction records only — removing or voiding an order in Heartland does not delete or deactivate the linked iPaaS.com Transaction record. Orders that should no longer appear must be managed directly in iPaaS.com.
One indirect deletion path does exist. The companion deposit ticket is created as a child of the order's iPaaS.com Transaction through its ParentId mapping. Deleting the order in iPaaS.com therefore also deletes the deposit ticket linked to it. Remove the deposit's ParentId mapping if you do not want the deposit deleted when its order is deleted — but note that doing so also removes the association that makes the deposit traceable back to its order.
Custom Field Support
These collections store fixed Heartland values on iPaaS.com custom fields at both the header and the child level:
Heartland Order Status: the raw Heartland transaction status, preserved alongside the translated iPaaS.com Status. Written by both the sales order and the deposit parent.
Heartland Source Location Id: the Heartland inventory source location identifier for the order. The Heartland transaction APIs require a source location identifier when orders are created in Heartland, so preserving it here keeps the value available for the return trip. It is visible in the Heartland retail website under Settings / Locations.
Heartland Station Id: the Heartland station identifier for the order, required by Heartland on the return trip for the same reason and visible in the same place.
Transaction Created By: the static value "Heartland", marking Heartland as the system that originated the order. This origin marker is what an outbound filter can read to avoid transferring iPaaS.com-created transactions back into iPaaS.com.
Line Created By, Heartland Invoice Order Line Id, and Heartland Ship From Location Id: stored per line by the sales order line child collection. The deposit line child collection stores Line Created By and Heartland Ship From Location Id only.
Heartland Payment Applied As Deposit and Heartland Payment Type: stored per payment by both the sales order payment and the deposit payment child collections.
Each requires a matching iPaaS.com subscription custom field on the relevant collection — Transaction, Transaction Line, or Transaction Payment — before its value is stored. If the custom field does not exist, the order still transfers and the remaining fields are written; only that custom value is not retained.
Both parent collections can also read arbitrary Heartland transaction custom field values. Add a mapping of type Dynamic Formula whose source calls await 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, and tickets and orders require separate custom field group definitions in Heartland even though both use the Transaction collection type in iPaaS.com.
Mapping Collection Status
Status: Enabled. Both parent collections carry a mapping filter that decides which Heartland records they accept; those filters are reproduced under Mappings.
Trigger Events: The integration registers transaction created, updated, and polling events. In practice automatic transfers run on a schedule through polling: Heartland's webhook format is not compatible with iPaaS.com instant webhooks, so orders arrive through polling rather than instant push notifications. Polling does not run until the subscription is configured and enabled. Individual orders can also be transferred at any time from the iPaaS.com Manual Sync page. The child collections have no trigger of their own; they run only as part of a parent transfer. Add Heartland Sales Order Deposit TO iPaaS.com likewise has no trigger of its own — it is invoked by the integration immediately after a qualifying sales order has been transferred.
Duplicate or Conflicting Mappings
Several other mapping collections operate on iPaaS.com Transaction records. They fall into three groups.
Other Heartland transaction types, same direction. Add Heartland Invoice TO iPaaS.com and Add Heartland Ticket TO iPaaS.com transfer the other Heartland transaction types inbound to the same iPaaS.com Transaction collection. Update Heartland Transaction Status TO iPaaS.com updates the status of transactions already linked to iPaaS.com, and its filter deliberately excludes the -D deposit records so it does not act on deposit tickets. These do not conflict with the sales order collections because each filters to its own Heartland transaction type, and the _ORDER, _INVOICE, and _TICKET external-id suffixes keep their transaction numbers from colliding.
The two families documented here. Add Heartland Sales Order TO iPaaS.com and Add Heartland Sales Order Deposit TO iPaaS.com both write iPaaS.com Transaction records from the same underlying Heartland sales order, and they are complementary rather than competing. The sales order filter requires that the identifier does not contain -D; the deposit filter requires that it does. Each record therefore reaches exactly one of them.
The opposite direction — writing orders into Heartland. Add/Update Heartland Sales Order FROM iPaaS.com creates and updates Heartland sales orders from iPaaS.com data, with its own children for addresses, notes, line items, and a separate payment collection per Heartland payment type (cash, check, custom, external, and gift card). That family is not the reverse of the collections documented here: the mappings, the trigger, and the record-matching behavior all differ.
Child-level overlap. Other Transaction Line, Transaction Address, Transaction Note, Transaction Payment, and Transaction Tax collections exist for the other Heartland transaction types — for example Add Heartland Invoice Payment TO iPaaS.com and Add Heartland Sales Ticket Payment TO iPaaS.com. Each rides its own parent transaction and processes only that parent's children, so they do not compete with the sales order or deposit children.
Important: Template mapping collections are provided for every transaction type in both directions, but running them all bi-directionally is not recommended. Before running the inbound and outbound directions together, review your mapping collection filters and clearly define which system is the source of truth. The Transaction Created By custom field exists specifically so that orders created by iPaaS.com are not transferred back into iPaaS.com; keep it mapped whenever both directions are active.
Collision Handling
This integration does not use iPaaS.com collision handling for sales orders. Whether an incoming order is created or updated is determined solely by whether its transaction number is already present in iPaaS.com; there is no collision recovery step to configure.
Supported Child Collections
The parent Add Heartland Sales Order TO iPaaS.com collection has five child collections. None of them runs independently, and none has its own schedule, webhook, or Manual Sync entry:
Add Heartland Sales Order Line TO iPaaS.com: transfers the order's line items. This collection has one child of its own, Add Heartland Sales Order Line Discount TO iPaaS.com, which records the discounts applied to each line.
Add Heartland Sales Order Address TO iPaaS.com: transfers the order's billing and shipping addresses.
Add Heartland Sales Order Note TO iPaaS.com: transfers notes recorded on the order.
Add Heartland Sales Order Payment TO iPaaS.com: transfers payments applied to the order.
Add Heartland Sales Order Tax TO iPaaS.com: transfers the order's tax records.
The companion parent Add Heartland Sales Order Deposit TO iPaaS.com has four child collections of its own. They are separate collections with similar names — do not confuse them with the sales order children above, and do not edit one expecting the other to change:
Add Heartland Sales Order Deposit Line TO iPaaS.com: transfers the deposit ticket's line items. This collection has one child of its own, Add Heartland Sales Order Deposit Line Discount TO iPaaS.com.
Add Heartland Sales Order Deposit Address TO iPaaS.com: transfers the deposit ticket's billing and shipping addresses.
Add Heartland Sales Order Deposit Payment TO iPaaS.com: transfers the deposit ticket's payments.
Add Heartland Sales Order Deposit Tax TO iPaaS.com: transfers the deposit ticket's tax records.
The deposit family has no note collection. Notes recorded on a Heartland sales order are transferred once, onto the order's own iPaaS.com transaction, and are not copied onto the deposit ticket.
System Caveats
Heartland Caveats
Transaction numbering: By default Heartland auto-increments order, ticket, and invoice numbers, and the same numeric value can appear across different types. Map the Heartland external identifier, which includes the _ORDER suffix, to the iPaaS.com transaction number to keep order numbers unique. Mapping the human-friendly Heartland public identifier instead is possible but risks numeric overlap between transaction types, and is only advisable when a single Heartland transaction type is transferred.
Pending orders are held back: the sales order filter excludes Heartland records whose status is "pending". An order in that state is skipped until it progresses, at which point a later polling cycle picks it up. The deposit filter does not apply the same condition — the pending exclusion is commented out in it — so the qualifying condition for the deposit differs from the order's.
Deposit payment types: Heartland allows only Gift Card, Custom, or External payment types to be applied as order deposits. Cash and check payments applied as deposits cause the Heartland order API to return an error. A dedicated Custom or External payment type is recommended to represent deposit payments.
Gift card handling on order payments is undocumented: the actions Heartland performs for gift card payment types on sales orders are not documented or supported by Heartland and are subject to change. Validate this behavior 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. Tickets and orders require separate custom field group definitions in Heartland even though both use the Transaction collection type in iPaaS.com.
Polling delay: Because Heartland does not deliver instant push notifications to iPaaS.com, expect a delay between an order being created or changed in Heartland and its arrival in iPaaS.com, bounded by the polling schedule.
iPaaS.com Caveats
Transaction number required and unique: iPaaS.com requires a transaction number on every Transaction record, and it must be unique across iPaaS.com transactions.
Required header values: Every iPaaS.com transaction requires a system id, transaction number, type, and status, plus at least one of a customer, company, or email address. If none of the customer, company, or email address is supplied, the request is rejected. Both parent collections supply all of these.
System id is not updatable: iPaaS.com accepts the system id when the Transaction record is created and ignores it on update. The SystemId mapping therefore has no effect on an already-linked order or deposit ticket, and a transaction cannot be moved between subscriptions by re-transferring it.
Payment method name is not updatable: when the integration auto-transfers a Heartland payment method, iPaaS.com accepts the method name on create only and ignores an incoming name on update. Renaming a payment method in Heartland does not rename the already-linked iPaaS.com Payment Method record, and the payment Method value on orders will continue to resolve to the original name.
Line status and type required: every iPaaS.com transaction line requires a status and a type. The type must be Product or Giftcard; both line child collections supply "Product" as a static value and derive the status from the Heartland line's open quantity.
Note type required: every iPaaS.com note requires a type, drawn from a fixed list (Gift, Customer Note, Status, Order, Private, Job Note, Job Description). The note child collection supplies "Private".
SKU resolution: the SKU on a product line should resolve to an existing iPaaS.com product or variant so the line is tied to the correct catalog item. A line whose SKU does not resolve is still created, but is not linked to a product record.
Payment method required: iPaaS.com requires a method on every payment, and it must match the name of a payment method configured in iPaaS.com.
Gift card requirement: when a payment's method is a gift card method, iPaaS.com requires a gift card id on that payment. Both payment child collections supply it through the MethodInfo mapping.
Custom field prerequisites: every custom field mapped by these collections must already exist on the corresponding iPaaS.com collection before the mapped value is stored.
Integration-Specific Caveats
Products are not auto-transferred. Unlike the customer, payment method, and gift card prerequisites described under Integration Flow, no product prerequisite runs in this direction. The SKU on an order line will only resolve if the product or variant already exists in iPaaS.com, so keep your Heartland product collections running ahead of order transfers.
Gift cards on line items are a ticket-only prerequisite. The gift-card-from-line-items prerequisite is gated on the Heartland transaction type being "Ticket". Because this collection transfers sales orders, that step does not run here; on the sales order flow gift cards are resolved only from payments.
The deposit is a copy, not a second Heartland record. Its lines, payments, taxes, and addresses intentionally duplicate the order's. If you do not want deposit tickets at all, disable or delete the parent Add Heartland Sales Order Deposit TO iPaaS.com collection and its four children rather than editing individual mappings.
The deposit depends on the order having transferred first. Its ParentId mapping looks up the already-transferred sales order. If the order transfer failed, the deposit has nothing to link to.
Updates replace the record. Re-transferring an order that already exists in iPaaS.com replaces the Transaction header and its children. See Unmapped Field Overwrite Risk under Mappings before re-transferring.
Non-qualifying orders are simply skipped. Both parent filters pass over records that do not qualify without raising an error, so a skipped order produces no entry in the error log.
Setup Requirements
Heartland Configuration
Ensure orders progress past the pending status in Heartland; the sales order filter skips orders whose status is still "pending".
Create any Heartland custom fields you intend to map before configuring the mappings, so they are available for selection. Remember that orders and tickets need separate custom field group definitions.
Keep the Heartland payment methods you use on orders available, so the payment method prerequisite can resolve or transfer them.
Use a Gift Card, Custom, or External payment type for any payment that is applied as an order deposit; cash and check payments cannot be.
For gift card payments, ensure the gift card number is the last word of the Heartland payment description — that is where the integration reads it from.
Note the station and source location identifiers your orders use, visible under Settings / Locations, if you plan to write orders back into Heartland later.
iPaaS.com Configuration
Create the custom fields listed under Custom Field Support on the Transaction, Transaction Line, and Transaction Payment collections if you want those Heartland values retained.
Confirm a payment method named "Gift Card_Heartland" exists in iPaaS.com, so the payment Method fallback resolves to a real method rather than failing. Change the fallback in the mapping if your gift card method is named differently.
Transfer your Heartland products to iPaaS.com before transferring orders, so order line SKUs resolve to existing products or variants.
Confirm the Transaction Status lookup translation covers every Heartland status you expect. A Heartland status that is not listed does not resolve to a valid iPaaS.com status.
Decide whether you want deposit tickets before the first transfer. If you do not, disable the deposit parent and its four children up front rather than cleaning up deposit records afterwards.
Replace the placeholder Heartland custom field name in the C5_Custom_Transaction mapping, or remove that mapping, on both parent collections.
Enable the subscription so polling can run.
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
Prerequisites, run before the order itself:
Before an order is sent to iPaaS.com, the integration resolves the records the order depends on. These run automatically — subscribers do not pre-sync them by hand — and they run in this order:
Customer. If the order carries a Heartland customer, the integration checks whether that customer is already linked to an iPaaS.com customer. If it is already linked, nothing further happens. If it is not linked, the integration retrieves the Heartland customer and transfers it through the Customer collection first. If that customer transfer reports errors, the order transfer is stopped and the order is not created in iPaaS.com. Resolve the customer error and re-transfer the order. This is the only prerequisite that can block the transfer.
Payment methods. For each payment on the order that carries a Heartland payment method, the integration checks whether a linked iPaaS.com payment method name resolves. If one does, nothing further happens. If none resolves, the integration retrieves the Heartland payment method and transfers it through the Payment Method collection so the payment can reference it. A failure here does not stop the order.
Gift cards on payments. For each payment whose Heartland payment type indicates a gift card payment, the integration reads the gift card number from the last word of the payment description, retrieves that gift card from Heartland, and transfers it through the Gift Card collection. A failure here does not stop the order either.
A fourth prerequisite exists in the integration that resolves gift cards from a transaction's line items. It is gated on the Heartland transaction type being "Ticket", so it does not run on the sales order flow.
Scheduled polling:
On its polling schedule, the integration requests the Heartland transactions changed within the configured search window.
Each transaction is evaluated against the parent mapping filter. Only records that are orders, are not deposits, carry no Heartland sub-type, and have moved past the pending status continue; everything else is passed over.
The prerequisites above are resolved for each qualifying order.
The order header is dispatched to iPaaS.com, where a Transaction of type Order is created if the transaction number is not yet present, or the existing record is updated if it is.
The order's line items, addresses, notes, payments, and taxes are dispatched through the five child collections under that transaction, and each line's discounts through the line discount collection beneath it.
Once the order has been transferred, the companion deposit flow described below runs.
Manual Sync:
A Heartland order external identifier in the {order number}_ORDER format is entered on the iPaaS.com Manual Sync page.
The integration retrieves that single order from Heartland, along with its payments, taxes, customer, notes, and shipping and billing addresses.
The order is evaluated against the same parent filter, the same prerequisites are resolved, and the order and its children are dispatched through the same create-or-update path, followed by the same companion deposit flow.
Both paths converge on the same mapping logic, so an order's resulting iPaaS.com record is identical regardless of how the transfer was triggered.
Sales Order Deposit Companion Flow
A deposit ticket is not a Heartland record that the integration goes and fetches. It is a copy of the sales order that iPaaS.com has just received, re-submitted under a distinct identifier so that downstream integrations expecting a separate deposit or ticket document have one to consume. It exists purely for that compatibility, which is why its lines, payments, taxes, and addresses duplicate the order's by design.
The companion flow runs immediately after a sales order has been transferred to iPaaS.com, and only when both of the following are true:
The transferred record's external identifier does not already end with -D (it is not itself a deposit copy) and does not end with -GC. This is what stops the deposit from cloning itself endlessly.
The record has at least one line item that is not a gift card and carries a quantity greater than zero. An order with no sold product — for example one consisting solely of gift card lines — produces no deposit ticket.
When both conditions hold, the integration takes the order it just transferred, appends -D to the order's external identifier and to the identifier of every line, line discount, payment, address, and tax record it carries, and submits the copy as a new transfer. That copy is what Add Heartland Sales Order Deposit TO iPaaS.com accepts, because its filter looks for exactly the -D marker that the copy now carries.
The deposit ticket is written to iPaaS.com as a Transaction of type Ticket — not Order — and it is linked back to the sales order through its ParentId mapping, which strips the trailing -D from its own identifier to recover the order's identifier and look up the transaction that was created a moment earlier. The two records therefore remain associated in iPaaS.com, and the order's four deposit children attach the copied addresses, lines, payments, and taxes beneath the deposit ticket.
Two consequences follow from that parent/child link. Deleting the sales order in iPaaS.com also deletes the deposit ticket beneath it. And because the deposit is created after the order, an order transfer that fails leaves no deposit ticket behind.
Mappings
Add Heartland Sales Order TO iPaaS.com
Mapping Filter
External_Id.Contains("_ORDER")
&& !External_Id.Contains("-D")
&& Type is null
&& Status != "pending"The filter is a single expression with four conditions, all of which must hold for the record to transfer:
The external identifier contains _ORDER. Only order-type Heartland records are processed. Invoices and tickets, which carry the _INVOICE and _TICKET suffixes, are passed over here and handled by their own collections.
The external identifier does not contain -D. This excludes the deposit copies, which are handled by Add Heartland Sales Order Deposit TO iPaaS.com. Without this condition, the deposit copy would be re-transferred as another sales order.
The Heartland record carries no sub-type. Records with a specific Heartland transaction sub-type assigned are not sales orders and are skipped.
The Heartland status is not "pending". An order still in the pending state is held back until it progresses; a later polling cycle picks it up once its status changes.
Records that fail any one of the four conditions are skipped. The filter does not raise an error and throws no message, so a skipped order produces no entry in the error log.
Description: Creates or updates the iPaaS.com Transaction record of type Order from the Heartland sales order, matched by the transaction number carried in the Heartland external identifier. This is the parent of the sales order line, address, note, payment, and tax child collections.
Mapping Type | Source Field (Heartland) | Destination Field (iPaaS.com) | Description |
Dynamic Formula |
| SystemId | Required. Supplies the iPaaS.com system identifier the transaction belongs to. iPaaS.com requires a system id greater than zero on every transaction. The value is provided automatically by the integration; leave this mapping in place. iPaaS.com accepts the system id on create only and ignores it on update, so it has no effect on an already-linked order. |
Dynamic Formula |
| TransactionNumber | Required. Sets the iPaaS.com transaction number, which must be unique across iPaaS.com transactions. The template maps the Heartland external identifier, producing the number in the {order number}_ORDER format. The suffix keeps the order number distinct from Heartland ticket and invoice numbers that may share the same numeric value. The commented alternative points the mapping at the Heartland public-facing order number; switch to it only when a single Heartland transaction type is transferred, because it does not carry the suffix that prevents numeric overlap. |
Static | "Order" | Type | Required. Classifies every record transferred by this collection as an order. iPaaS.com requires a transaction type, and "Order" is one of its valid values. Leave this value in place for the sales order workflow. |
Lookup Translation | Transaction Status translation, applied to the Heartland Status | Status | Required. Converts the Heartland order status into the corresponding iPaaS.com transaction status, which must be one of the values iPaaS.com accepts. The translation pairs canceled to Cancelled, open and pending to Pending, and closed and complete to Complete. A Heartland status with no matching entry does not resolve, so confirm the translation covers every status your orders use and add a pair for any that is missing. |
Dynamic Formula |
| CustomerId | Required. Looks up the linked iPaaS.com customer for the order using the Heartland customer identifier, and stores it on the transaction. iPaaS.com requires at least one of a customer, company, or email address on every transaction; this collection supplies both this and the email address. If the Heartland customer is not yet linked, the customer prerequisite transfers it before the order is sent. Disable your Heartland customer mappings to iPaaS.com if you do not want order transfers to create customers. |
Dynamic Formula |
| EmailAddress | Required. Reads the customer email address from the Heartland customer information on the order. Together with the CustomerId mapping this satisfies the iPaaS.com requirement for at least one of a customer, company, or email address. |
Field | Subtotal | Subtotal | Recommended. Stores the order's subtotal — the line total before tax and shipping — so the order's financial totals are complete in iPaaS.com. |
Field | Total | Total | Recommended. Stores the order's grand total. |
Field | TotalQty | TotalQty | Recommended. Stores the total quantity of items on the order. |
Field | ShippingCharge | ShippingAmount | Recommended. Stores the Heartland order's shipping charge as the iPaaS.com shipping amount. |
Dynamic Formula |
| DiscountAmount | Recommended. Calculates the order's total discount from its line items — for each line, the difference between the price before and after discounts — and stores the sum on the transaction. An order with no line items produces zero. |
Dynamic Formula |
| TaxAmount | Recommended. Calculates the order's total tax by summing the value of each tax record on the Heartland order. An order with no tax records produces zero. |
Field | Status | Heartland Order Status (custom field) | Optional. Stores the raw Heartland order status, preserving the original Heartland value alongside the translated iPaaS.com Status. Requires a custom field of this name on the Transaction collection before the value is stored. |
Field | SourceLocationId | Heartland Source Location Id (custom field) | Optional. Stores the Heartland inventory source location identifier for the order. Heartland requires a source location identifier when orders are created in Heartland, so preserving it here keeps the value available for the return trip. 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 identifier for the order, which Heartland also requires when orders 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. Marks Heartland as the system that originated the order. This origin marker is what an outbound filter reads to avoid transferring iPaaS.com-created transactions back into iPaaS.com. Requires a custom field of this name on the Transaction collection before the value is stored. |
Dynamic Formula |
| C5_Custom_Transaction (custom field) | Optional. Reads a named value from the Heartland order's custom fields. This is the custom-field formula pattern for the Transaction collection, shipped with a placeholder name — replace "My Sales Order List 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 collection. |
Add Heartland Sales Order Line TO iPaaS.com
This collection is a child of Add Heartland Sales Order TO iPaaS.com. It does not run on its own and has no schedule, webhook, or Manual Sync entry of its own; it runs whenever the parent transfers a sales order, creating the order's line items as iPaaS.com Transaction Lines under the transaction the parent created or updated.
Mapping Filter
This mapping collection does not have a mapping filter applied. All records routed to it are processed without additional filtering conditions.
Description: Creates an iPaaS.com Transaction Line for each line on the Heartland sales order, carrying the product identity, quantity, and pricing values.
Mapping Type | Source Field (Heartland) | Destination Field (iPaaS.com) | Description |
Static | "Product" | Type | Required. Identifies the line as a product line. iPaaS.com requires a type on every transaction line, and accepts Product or Giftcard. Subscribers do not normally change this value. |
Dynamic Formula |
| Status | Required. Sets the line's fulfillment status from the Heartland line's open quantity. If any quantity remains unfulfilled the line is reported as "Pending"; once all quantity has been fulfilled it is reported as "Complete". iPaaS.com requires a status on every transaction line, and both values are accepted. |
Field | ItemPublicId | Sku | Recommended. Stores the Heartland item's public identifier as the line SKU. iPaaS.com uses the SKU to resolve the line to an existing product or variant; no product prerequisite runs in this direction, so the product must already be present in iPaaS.com. A line whose SKU does not resolve is still created but is not linked to a product record. |
Field | Qty | Qty | Recommended. Stores the ordered quantity from the Heartland line. The UnitPrice formula on this line divides by this value, so leave it mapped. |
Dynamic Formula |
| UnitPrice | Recommended. Calculates the net unit price by dividing the Heartland line's total price by its quantity, giving the per-item cost after any line discount. |
Field | CurrentUnitPrice | OriginalUnitPrice | Recommended. Captures the item's list price before any line-level discount is applied, so both the pre-discount and net unit prices are available on the line. |
Field | TotalPrice | ExtendedPrice | Recommended. Stores the Heartland line's total price — quantity times unit price, after discounts. |
Field | Description | Description | Recommended. Stores the Heartland order line's item description so the line reads the same in both systems. |
Dynamic Formula |
| DiscountAmount | Optional. Calculates the discount applied to the line by subtracting the discounted line total from the line total before discounts. It populates only when Heartland supplies both price values. |
Field | Id | Heartland Invoice Order Line Id (custom field) | Optional. Stores the Heartland order line's identifier. When a Heartland invoice is later created for the order, Heartland requires the originating order line identifier on each invoice line; carrying it here makes that value available downstream. Requires a custom field of this name on the Transaction Line collection before the value is stored. |
Field | ShipFromLocationId | Heartland Ship From Location Id (custom field) | Optional. Stores the identifier of the Heartland location the line ships from. Requires a custom field of this name on the Transaction Line collection before the value is stored. |
Static | "Heartland" | Line Created By (custom field) | Optional. Records that the line originated from Heartland. Requires a custom field of this name on the Transaction Line collection before the value is stored. |
Add Heartland Sales Order Line Discount TO iPaaS.com
This collection is a child of Add Heartland Sales Order Line TO iPaaS.com, and therefore a grandchild of Add Heartland Sales Order TO iPaaS.com. It runs whenever a sales order line is transferred and records the discounts applied to that line. It has no schedule, webhook, or Manual Sync entry 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: Creates an iPaaS.com Transaction Line Discount for each discount recorded against a Heartland sales order line.
Mapping Type | Source Field (Heartland) | Destination Field (iPaaS.com) | Description |
Field | Amount | DiscountAmount | Recommended. Stores the Heartland line discount amount so each transferred line records the discount that was applied to it. iPaaS.com does not require this field, but it carries the substantive value of the discount record. The discount's association to its transaction line is supplied automatically by the parent line transfer and is not a subscriber mapping. |
Add Heartland Sales Order Address TO iPaaS.com
This collection is a child of Add Heartland Sales Order TO iPaaS.com. It does not run on its own and has no schedule, webhook, or Manual Sync entry of its own; it runs whenever the parent transfers a sales order, attaching the order's billing and shipping addresses to the transaction the parent created or updated. The association to that transaction is supplied automatically by the parent transfer and is not a subscriber mapping.
Mapping Filter
This mapping collection does not have a mapping filter applied. All records routed to it are processed without additional filtering conditions.
Description: Attaches each address on the Heartland sales order to the iPaaS.com transaction, carrying the postal fields, the billing and shipping role indicators, and the order's shipping method name. iPaaS.com marks no address field as required, so every field below is optional at the platform level.
Mapping Type | Source Field (Heartland) | Destination Field (iPaaS.com) | Description |
Field | Line1 | Address1 | Recommended. Stores the first street line of the Heartland order address so the iPaaS.com address is complete and usable for shipping and billing. |
Field | City | City | Recommended. Stores the city of the Heartland order address. |
Field | State | Region | Recommended. Stores the Heartland order address State in the iPaaS.com Region field. |
Field | Country | Country | Recommended. Stores the country of the Heartland order address. |
Field | PostalCode | PostalCode | Recommended. Stores the postal or ZIP code of the Heartland order address. |
Field | Line2 | Address2 | Optional. Stores the second street line of the Heartland order address — suite, unit, or similar. |
Field | FirstName | FirstName | Optional. Stores the first name recorded on the Heartland order address. This is the name on the address itself, which can differ from the customer's name. |
Field | LastName | LastName | Optional. Stores the last name recorded on the Heartland order address. This is the name on the address itself, which can differ from the customer's name. |
Field | IsPrimaryBilling | IsPrimaryBilling | Optional. Indicates whether this address is the order's billing address. Adjust this mapping if you use a field other than the Heartland IsPrimaryBilling field to indicate the billing address. |
Field | IsPrimaryShipping | IsPrimaryShipping | Optional. Indicates whether this address is the order's shipping address. Adjust this mapping if you use a field other than the Heartland IsPrimaryShipping field to indicate the shipping address. |
Dynamic Formula |
| ShippingMethod | Optional. Heartland stores the shipping method as an internal identifier. The formula takes that identifier from the parent order, looks it up, and returns the shipping method's readable name so the iPaaS.com address records a meaningful value. When the identifier is missing or cannot be matched, no value is recorded and the transfer is not blocked. |
Add Heartland Sales Order Note TO iPaaS.com
This collection is a child of Add Heartland Sales Order TO iPaaS.com. It does not run on its own and has no schedule, webhook, or Manual Sync entry of its own; it runs whenever the parent transfers a sales order, creating an iPaaS.com note on the transaction for each note recorded on the Heartland order. The companion deposit family has no note collection, so notes are transferred once, onto the order's transaction only.
Mapping Filter
This mapping collection does not have a mapping filter applied. All records routed to it are processed without additional filtering conditions.
Description: Creates an iPaaS.com Transaction Note for each note on the Heartland sales order, carrying the note text and its original Heartland creation time.
Mapping Type | Source Field (Heartland) | Destination Field (iPaaS.com) | Description |
Static | "Private" | Type | Required. Sets the iPaaS.com note type. iPaaS.com requires a note type and accepts only Gift, Customer Note, Status, Order, Private, Job Note, and Job Description. Change this only to another allowed value if your workflow needs a different note type. |
Field | Content | Text | Recommended. Stores the Heartland note's content so each transferred note preserves its text. |
Dynamic Formula |
| NoteCreatedDateTime | Optional. Reads the note's Heartland creation timestamp, treats it as Coordinated Universal Time, and returns it as a time-zone-aware value so the iPaaS.com note records when it was created in Heartland. Leave this mapping in place so each transferred note carries its original creation time. |
Add Heartland Sales Order Payment TO iPaaS.com
This collection is a child of Add Heartland Sales Order TO iPaaS.com. It does not run on its own and has no schedule, webhook, or Manual Sync entry of its own; it runs whenever the parent transfers a sales order, creating a payment record on the transaction for each Heartland payment.
Mapping Filter
This mapping collection does not have a mapping filter applied. All records routed to it are processed without additional filtering conditions.
Description: Creates an iPaaS.com payment for each payment on the Heartland sales order, resolving the payment method to a configured iPaaS.com method and, for gift card payments, referencing the linked iPaaS.com gift card.
Mapping Type | Source Field (Heartland) | Destination Field (iPaaS.com) | Description |
Dynamic Formula |
| Method | Required. Sets the payment method on the iPaaS.com payment. The formula looks up the iPaaS.com payment method linked to this Heartland payment method — matching the Heartland payment method id against an iPaaS.com payment method's external id — and uses its name. When no linked method is found, it falls back to "Gift Card_Heartland". iPaaS.com requires a payment method on every payment, and it must match the name of a payment method configured in iPaaS.com. Confirm a method of that name exists, or change the fallback to one you have configured. When the Heartland payment method is not yet linked, the payment method prerequisite transfers it before the order is transferred. |
Field | Amount | Amount | Recommended. Stores the Heartland payment amount so the payment total is complete on the iPaaS.com transaction. |
Dynamic Formula |
| Status | Optional. Translates the Heartland payment status into the iPaaS.com payment status. A Heartland "pending" payment becomes "authorized" and a Heartland "complete" payment becomes "captured"; any other Heartland status leaves the iPaaS.com payment status unset. |
Field | Description | Description | Optional. Stores the Heartland payment description. For gift card payments the description is also the source the integration reads to find the gift card number, so keep it mapped if you process gift card payments. |
Dynamic Formula |
| MethodInfo | Optional in configuration, but required by iPaaS.com whenever the payment method is a gift card method. When the Heartland payment type indicates a gift card, the formula reads the gift card number from the last word of the payment description, looks up the linked iPaaS.com gift card, and records its gift card id as the payment's gift card reference. For non-gift-card payments, or when no matching gift card is found, nothing is set. Gift card handling on Heartland sales order payments is not documented or supported by Heartland and is subject to change; validate it in a staging environment before relying on it in production. |
Field | Deposit | Heartland Payment Applied As Deposit (custom field) | Optional. Records whether the Heartland payment was applied as an order deposit. Requires a custom field of this name on the Transaction Payment collection before the value is stored. |
Dynamic Formula |
| Heartland Payment Type (custom field) | Optional. Records the Heartland payment type, stripping the leading "Payments::" prefix from the raw value; when Heartland provides no payment type, nothing 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. |
Add Heartland Sales Order Tax TO iPaaS.com
This collection is a child of Add Heartland Sales Order TO iPaaS.com. It does not run on its own and has no schedule, webhook, or Manual Sync entry of its own; it runs whenever the parent transfers a sales order, creating a tax record on the transaction for each Heartland tax entry. The tax record's association to its transaction is supplied automatically by the parent transfer.
Mapping Filter
This mapping collection does not have a mapping filter applied. All records routed to it are processed without additional filtering conditions.
Description: Creates an iPaaS.com Transaction Tax record for each tax entry on the Heartland sales order, naming the authority and the amount charged.
Mapping Type | Source Field (Heartland) | Destination Field (iPaaS.com) | Description |
Field | Value | Amount | Recommended. Stores the Heartland tax amount so each transferred transaction records the tax that was charged on the order. iPaaS.com does not require this field, but a tax record without an amount carries no information. |
Field | Description | Authority | Recommended. Stores the name of the Heartland taxing authority the amount applies to, taken from the Heartland tax record's description. When an order carries more than one tax record, the authority is what distinguishes them. iPaaS.com does not require this field. |
Add Heartland Sales Order Deposit TO iPaaS.com
This is the companion parent collection described under Sales Order Deposit Companion Flow. It is not triggered by polling or Manual Sync on its own. The integration invokes it immediately after a qualifying sales order has been transferred, presenting it with a copy of that order whose identifiers all carry a -D suffix. It writes the copy to iPaaS.com as a Transaction of type Ticket and links it back to the sales order it was copied from.
Mapping Filter
External_Id.Contains("-D")
&& !External_Id.Contains("_TICKET")
&& Type is null
//&& Status != "pending"The filter is a single expression with three active conditions and a fourth that is commented out:
The external identifier contains -D. This is the marker the integration appends when it produces the deposit copy, so this condition is what confines the collection to deposit copies and keeps it from picking up ordinary sales orders.
The external identifier does not contain _TICKET. Heartland ticket records are excluded, so a deposit copy produced from a ticket transfer is not accepted here.
The Heartland record carries no sub-type. Records with a specific Heartland transaction sub-type assigned are skipped.
The status condition is disabled. The line excluding records whose status is "pending" is commented out, so unlike the sales order parent this collection does accept a deposit copy of an order in the pending state. That difference is deliberate in the shipped template; if you want the two to behave identically, uncomment the line.
Records that fail any active condition are skipped. There are no conditions in this filter that stop a transfer with an error, so a skipped record produces no entry in the error log.
Description: Creates or updates the iPaaS.com Transaction record of type Ticket that represents the sales order's deposit, matched by the deposit's own transaction number, and links it to the original sales order. This is the parent of the deposit address, line, payment, and tax child collections.
Mapping Type | Source Field (Heartland) | Destination Field (iPaaS.com) | Description |
Dynamic Formula |
| SystemId | Required. Supplies the iPaaS.com system identifier the deposit ticket belongs to. iPaaS.com requires a system id greater than zero on every transaction. Set automatically by the integration; leave this mapping in place. iPaaS.com accepts the system id on create only and ignores it on update. |
Dynamic Formula |
| TransactionNumber | Required. Sets the deposit ticket's transaction number to the copy's external identifier, which carries the -D suffix that keeps it distinct from its parent order. iPaaS.com requires a unique transaction number on every transaction. The commented alternative appends the suffix to the Heartland public-facing order number instead; confirm the resulting numbers stay unique across your iPaaS.com transactions before switching to it. |
Static | "Ticket" | Type | Required. Records the deposit copy as a ticket-type transaction, which is the form downstream integrations expect a deposit document to take. iPaaS.com requires a transaction type, and "Ticket" is one of its valid values. This is the mapping that makes the deposit a distinct kind of record from the order it copies. |
Lookup Translation | Transaction Status translation, applied to the Heartland Status | Status | Required. Converts the Heartland order status into the corresponding iPaaS.com transaction status so the deposit ticket carries a status iPaaS.com recognizes. The translation pairs canceled to Cancelled, open and pending to Pending, and closed and complete to Complete. A Heartland status with no entry is not converted; add a pair for any status your business uses. |
Dynamic Formula |
| CustomerId | Required. Resolves the iPaaS.com customer the deposit ticket belongs to by looking up the Heartland customer's linked iPaaS.com record. iPaaS.com requires at least one of a customer, company, or email address on every transaction. For this lookup to succeed the Heartland customer must already be linked — which it will be, because the sales order transfer that precedes the deposit resolves the customer first. |
Dynamic Formula |
| ParentId | Recommended. Links the deposit ticket to the sales order it copies. The formula takes the deposit's external identifier, removes the trailing two characters to recover the original order's identifier, looks up the already-transferred sales order in iPaaS.com, and stores that transaction as the deposit's parent. The original sales order must have transferred first for the lookup to succeed. Because this creates a parent/child relationship, deleting the order in iPaaS.com also deletes the deposit ticket beneath it. |
Dynamic Formula |
| EmailAddress | Recommended. Stores the email address of the customer on the Heartland order. Together with the resolved customer reference it satisfies the iPaaS.com requirement that every transaction be tied to a customer, and it provides a fallback way to identify the customer when the deposit ticket is reviewed. |
Field | Subtotal | Subtotal | Optional. Copies the Heartland order subtotal so the deposit ticket reflects the order's pre-tax, pre-shipping amount. |
Field | Total | Total | Optional. Copies the Heartland order total so the deposit ticket reflects the order's final amount. |
Field | TotalQty | TotalQty | Optional. Copies the total quantity of items on the Heartland order. |
Field | ShippingCharge | ShippingAmount | Optional. Copies the Heartland order's shipping charge so the deposit ticket reflects the order's shipping cost. |
Dynamic Formula |
| DiscountAmount | Optional. Calculates the deposit ticket's total discount from its line items. When the copy has no line items, no discount amount is written. |
Dynamic Formula |
| TaxAmount | Optional. Calculates the deposit ticket's total tax by summing the value of each tax record on the Heartland order. When there are no tax records, zero is written. |
Field | Status | Heartland Order Status (custom field) | Optional. Stores the raw Heartland order status, preserving the original Heartland value alongside the translated iPaaS.com Status. Requires a custom field of this name on the Transaction collection before the value is stored. |
Field | SourceLocationId | Heartland Source Location Id (custom field) | Optional. Records which Heartland location the order originated from. Requires a custom field of this name on the Transaction collection before the value is stored. |
Field | StationId | Heartland Station Id (custom field) | Optional. Records which Heartland station recorded the order. 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 deposit ticket originated from the Heartland integration. Requires a custom field of this name on the Transaction collection before the value is stored. |
Dynamic Formula |
| C5_Custom_Transaction (custom field) | Optional. Reads a named value from the Heartland transaction's custom fields. Shipped with a placeholder name — replace "My Sales Order List 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 collection. |
Add Heartland Sales Order Deposit Line TO iPaaS.com
This collection is a child of Add Heartland Sales Order Deposit TO iPaaS.com — not of the sales order parent. It runs whenever the deposit parent transfers a deposit ticket, creating the ticket's product lines as iPaaS.com Transaction Lines. Its lines intentionally duplicate the sales order's lines, because the deposit ticket is a copy of the order.
Mapping Filter
Type=="ItemLine"
The filter has a single branch: a Heartland transaction line is processed only when its line type is exactly the item type. Every other line type is skipped and is not created as an iPaaS.com transaction line here. The filter does not raise an error and throws no message; non-item lines are passed over silently. Note that this filter has no counterpart on Add Heartland Sales Order Line TO iPaaS.com, which has no filter at all — so the deposit ticket can carry fewer lines than the order it copies.
Description: Creates an iPaaS.com Transaction Line for each item line on the deposit ticket, carrying the product identity, quantity, and pricing values.
Mapping Type | Source Field (Heartland) | Destination Field (iPaaS.com) | Description |
Static | "Product" | Type | Required. Identifies the line as a product line. iPaaS.com requires a type on every transaction line and accepts Product or Giftcard; the lines this collection transfers are product lines. |
Dynamic Formula |
| Status | Required. Sets the line status from the Heartland line's remaining open quantity — "Pending" when any quantity is still open, "Complete" when the line has been fully fulfilled. iPaaS.com requires a status on every transaction line, and both values are accepted. |
Field | ItemPublicId | Sku | Recommended. Stores the Heartland item's public identifier as the line SKU. iPaaS.com expects the SKU to resolve to an existing product or variant; a line whose SKU does not resolve still transfers but is not linked to a catalog record. |
Field | Qty | Qty | Optional. Stores the ordered quantity from the Heartland line. The UnitPrice formula on this line divides by this value. |
Dynamic Formula |
| UnitPrice | Optional. Calculates the per-unit price by dividing the line total price by the quantity, giving the effective cost per item after any line-level discount is spread across the units. |
Field | CurrentUnitPrice | OriginalUnitPrice | Optional. Captures the item's unit price before any line-level discount is applied. |
Field | TotalPrice | ExtendedPrice | Optional. Stores the Heartland line's total price for the full quantity. |
Field | Description | Description | Optional. Stores the Heartland line's item description on the iPaaS.com transaction line. |
Dynamic Formula |
| DiscountAmount | Optional. Records the total discount applied to the line by subtracting the discounted line total from the line total before discounts. |
Field | ShipFromLocationId | Heartland Ship From Location Id (custom field) | Optional. Stores the identifier of the Heartland location the line ships from. Requires a custom field of this name on the Transaction Line collection before the value is stored. |
Static | "Heartland" | Line Created By (custom field) | Optional. Records that the line originated from Heartland. Requires a custom field of this name on the Transaction Line collection before the value is stored. |
Add Heartland Sales Order Deposit Line Discount TO iPaaS.com
This collection is a child of Add Heartland Sales Order Deposit Line TO iPaaS.com, and therefore a grandchild of Add Heartland Sales Order Deposit TO iPaaS.com. It is a separate collection from Add Heartland Sales Order Line Discount TO iPaaS.com, which serves the sales order family. It runs whenever a deposit line is transferred.
Mapping Filter
This mapping collection does not have a mapping filter applied. All records routed to it are processed without additional filtering conditions.
Description: Creates an iPaaS.com Transaction Line Discount for each discount recorded against a deposit ticket line.
Mapping Type | Source Field (Heartland) | Destination Field (iPaaS.com) | Description |
Field | Amount | DiscountAmount | Recommended. Stores the monetary amount of the Heartland line discount, recording how much the deposit line's price was reduced. iPaaS.com does not mark this field as required, but it carries the substantive value of the discount record. The discount is attached to its parent transaction line automatically by the parent deposit line transfer; there is no mapping in this collection for that link. |
Add Heartland Sales Order Deposit Address TO iPaaS.com
This collection is a child of Add Heartland Sales Order Deposit TO iPaaS.com — not of the sales order parent, and not the same collection as Add Heartland Sales Order Address TO iPaaS.com. It runs whenever the deposit parent transfers a deposit ticket, attaching the copied billing and shipping addresses to the iPaaS.com Transaction the deposit parent created or updated.
Mapping Filter
This mapping collection does not have a mapping filter applied. All records routed to it are processed without additional filtering conditions.
Description: Attaches each address on the deposit ticket to its iPaaS.com transaction, carrying the postal fields, the billing and shipping role indicators, and the shipping method name. iPaaS.com marks no address field as required, so every field below is optional at the platform level.
Mapping Type | Source Field (Heartland) | Destination Field (iPaaS.com) | Description |
Field | Line1 | Address1 | Recommended. Stores the first street line of the deposit address so the iPaaS.com address is complete and usable for shipping and billing. |
Field | City | City | Recommended. Stores the city of the deposit address. |
Field | State | Region | Recommended. Stores the deposit address State in the iPaaS.com Region field. |
Field | Country | Country | Recommended. Stores the country of the deposit address. |
Field | PostalCode | PostalCode | Recommended. Stores the postal or ZIP code of the deposit address. |
Field | Line2 | Address2 | Optional. Stores the second street line of the deposit address — suite, unit, or similar. |
Field | FirstName | FirstName | Optional. Stores the first name recorded on the deposit address. This is the name on the address itself, which can differ from the customer's name. |
Field | LastName | LastName | Optional. Stores the last name recorded on the deposit address. This is the name on the address itself, which can differ from the customer's name. |
Field | IsPrimaryBilling | IsPrimaryBilling | Optional. Indicates whether this address is the deposit's billing address. Adjust this mapping if you use a field other than the Heartland IsPrimaryBilling field to indicate the billing address. |
Field | IsPrimaryShipping | IsPrimaryShipping | Optional. Indicates whether this address is the deposit's shipping address. Adjust this mapping if you use a field other than the Heartland IsPrimaryShipping field to indicate the shipping address. |
Dynamic Formula |
| ShippingMethod | Optional. Takes the shipping method identifier from the parent deposit, looks it up, and returns the shipping method's readable name. When the parent deposit has no shipping method, or the identifier does not resolve, no shipping method value is recorded on the address. |
Add Heartland Sales Order Deposit Payment TO iPaaS.com
This collection is a child of Add Heartland Sales Order Deposit TO iPaaS.com — not the same collection as Add Heartland Sales Order Payment TO iPaaS.com, and it maps one field fewer. It runs whenever the deposit parent transfers a deposit ticket, creating a payment record on the deposit for each copied Heartland payment.
Mapping Filter
This mapping collection does not have a mapping filter applied. All records routed to it are processed without additional filtering conditions.
Description: Creates an iPaaS.com payment on the deposit ticket for each payment copied from the Heartland sales order, resolving the payment method and, for gift card payments, referencing the linked iPaaS.com gift card.
Mapping Type | Source Field (Heartland) | Destination Field (iPaaS.com) | Description |
Dynamic Formula |
| Method | Required. Resolves the iPaaS.com payment method name for the deposit payment by matching the Heartland payment method id against an iPaaS.com payment method's external id and using that method's name. When no linked method is found, the mapping falls back to "Gift Card_Heartland". iPaaS.com requires a method on every payment, and the resolved name must match a payment method configured in iPaaS.com or the payment is not created. Ensure a method of that name exists, or change the fallback. When the Heartland payment method is not yet linked, the integration transfers it automatically first; if you disable your Heartland payment method mappings to prevent that, point this mapping at an existing iPaaS.com payment method instead of relying on the id relationship. |
Field | Amount | Amount | Recommended. Stores the Heartland deposit payment amount so the deposit payment reflects the correct value. |
Dynamic Formula |
| Status | Recommended. Translates the Heartland payment status into the iPaaS.com payment status: pending becomes "authorized" and complete becomes "captured". Any other Heartland status leaves the iPaaS.com status unset. |
Dynamic Formula |
| MethodInfo | Optional in configuration, but required by iPaaS.com whenever the payment method is a gift card method. When the Heartland payment type is a gift card, the formula reads the gift card number from the end of the payment description, looks up the linked iPaaS.com gift card, and records its gift card reference on the payment. For non-gift-card payments, or when the gift card cannot be resolved, nothing is stored. When the gift card is not yet linked, the integration transfers it automatically first. Note that this formula reads the Heartland payment description even though this collection does not map that description onto the iPaaS.com payment. |
Field | Deposit | Heartland Payment Applied As Deposit (custom field) | Optional. Stores the Heartland value indicating that the payment was applied as a deposit. Requires a custom field of this name on the Transaction Payment collection before the value is stored. |
Dynamic Formula |
| Heartland Payment Type (custom field) | Optional. Records the Heartland payment type with the leading "Payments::" prefix removed — for example GiftCardPayment. If the Heartland payment type is empty, nothing is stored. Requires a custom field of this name on the Transaction Payment collection before the value is stored. |
Add Heartland Sales Order Deposit Tax TO iPaaS.com
This collection is a child of Add Heartland Sales Order Deposit TO iPaaS.com — not the same collection as Add Heartland Sales Order Tax TO iPaaS.com. It runs whenever the deposit parent transfers a deposit ticket, creating the ticket's tax records on the iPaaS.com transaction. The tax record's association to its transaction is supplied automatically by the parent transfer.
Mapping Filter
This mapping collection does not have a mapping filter applied. All records routed to it are processed without additional filtering conditions.
Description: Creates an iPaaS.com Transaction Tax record for each tax entry copied onto the deposit ticket, naming the authority and the amount collected.
Mapping Type | Source Field (Heartland) | Destination Field (iPaaS.com) | Description |
Field | Description | Authority | Recommended. Stores the Heartland tax record's description, naming the taxing authority the amount belongs to. When a deposit ticket carries more than one tax record, the authority is what distinguishes them. |
Field | Value | Amount | Recommended. Stores the Heartland tax record's value, recording how much tax was collected for the authority. The value is a decimal amount; map a numeric tax amount so it stores correctly. |
Unmapped Field Overwrite Risk
Updates in this direction are full replacements. When iPaaS.com updates a Transaction record that already exists — which happens whenever an order with a matching transaction number is re-transferred — the full record is replaced. Every writable iPaaS.com field that these collections do not map is overwritten with an empty value. Do not assume unmapped values are preserved. The same applies to the deposit ticket, which is re-created on every order transfer that qualifies.
Transaction header, sales order parent. The writable header fields Add Heartland Sales Order TO iPaaS.com does not map are:
parent_id: the link to a parent transaction. This collection does not set one, so a parent relationship established by another process is cleared on update.
company_id: the alternative to a customer on the transaction. This collection supplies a customer and an email address instead, so an iPaaS.com company association set by another process is cleared on update.
transaction_created_datetime
transaction_updated_datetime
The header also carries child groups that this collection does not transfer at all: tracking and order-level discounts. Values held in those on the iPaaS.com side are not maintained here. The lines, taxes, payments, addresses, and notes groups are transferred by the five child collections.
Transaction header, deposit parent. Add Heartland Sales Order Deposit TO iPaaS.com maps parent_id, so its unmapped writable header fields are company_id, transaction_created_datetime, and transaction_updated_datetime. It does not transfer the notes, tracking, or order-level discounts groups at all — so notes attached to the deposit ticket in iPaaS.com are not maintained, and no note is copied over from the sales order.
Transaction Line. Both Add Heartland Sales Order Line TO iPaaS.com and Add Heartland Sales Order Deposit Line TO iPaaS.com leave the same writable line fields unmapped: sequence_number, qty_shipped, unit, discount_percent, tax_percent, estimated_tax_amount, weight, the line-level address, line_info, and options. The line_discounts group is handled by the line discount child collection beneath each of them.
Transaction Line Discount. Both line discount collections map only discount_amount. The writable fields they do not map are coupon_id, coupon_code, discount_type_id, discount_method, and discount_percent.
Transaction Address. Both Add Heartland Sales Order Address TO iPaaS.com and Add Heartland Sales Order Deposit Address TO iPaaS.com leave the same writable address fields unmapped: shipping_method_description, shipping_amount, ship_date, type, company, phone_number, name, address_3, and the address-level customer_id.
Transaction Note. Add Heartland Sales Order Note TO iPaaS.com maps the note text, type, and creation time. The writable note fields it does not map are sequence_number and is_public, so each note is created with the default visibility. Add an IsPublic mapping if your notes need a specific public or private visibility on the iPaaS.com side.
Transaction Payment. Add Heartland Sales Order Payment TO iPaaS.com maps every writable payment field that iPaaS.com exposes — method, amount, status, description, and method detail — plus its two custom fields, so there is no unmapped writable payment field a re-transfer could clear. Add Heartland Sales Order Deposit Payment TO iPaaS.com is one field short: it does not map description, so deposit payments are written with an empty description even though the Heartland payment carries one. Add a Description mapping to that collection if you rely on the payment description on deposit tickets.
Transaction Tax. Both Add Heartland Sales Order Tax TO iPaaS.com and Add Heartland Sales Order Deposit Tax TO iPaaS.com map the authority and the amount. The writable tax fields neither maps are original_amount and tax_percent.
The remedy. To keep a value that iPaaS.com holds but Heartland does not supply, add a mapping of type Dynamic Formula for that field whose source is DestinationValue.[FieldName] — for example DestinationValue.CompanyId to preserve the company association, or DestinationValue.Weight on a line collection to preserve a line weight. The formula reads the value currently on the iPaaS.com record and writes it back, so the update carries it forward instead of clearing it. Add one such mapping for each field you need to keep, on each collection that owns it.
One field behaves differently. SystemId is flagged by iPaaS.com as not updatable and is ignored on update, so it is neither written nor cleared on an existing transaction. It takes effect only when the Transaction record is first created, which means a transaction cannot be moved between subscriptions by re-transferring it. The same is true of the payment method name on the Payment Method records the prerequisite creates: a rename in Heartland never propagates to an already-linked iPaaS.com payment method.
Error Handling
Customer prerequisite failed: when the order's Heartland customer is not yet linked and the automatic customer transfer reports errors, the order transfer is stopped and no iPaaS.com Transaction is created or updated — and because the deposit runs after the order, no deposit ticket is created either. The error appears in the iPaaS.com Dashboard error logs. Resolve the customer error, most often a missing required customer value, and re-transfer the order.
Missing or invalid Manual Sync identifier: a Manual Sync value that does not carry an _ORDER, _INVOICE, or _TICKET suffix is rejected with the message "The transaction id must contain _ORDER _INVOICE or _TICKET suffix to determine proper source". Enter the identifier in the {order number}_ORDER format.
Missing transaction number: iPaaS.com requires a transaction number on every transaction. If the mapping does not resolve, the transaction is not created. Confirm the Heartland external identifier is present on the order.
Duplicate transaction number: the transaction number must be unique across iPaaS.com transactions. If the plain Heartland public identifier is mapped instead of the external identifier, a ticket or invoice sharing the same numeric value can collide with the order. Map the external identifier, which carries the _ORDER suffix.
No customer, company, or email address: iPaaS.com rejects a transaction that carries none of these. If neither the linked customer nor the customer email resolves, the transaction is not created. Confirm the order has a customer in Heartland and that the customer carries an email address.
Unrecognized status: a Heartland status not present in the Transaction Status lookup translation does not resolve to a valid iPaaS.com status, which causes the transaction to be rejected. Add a translation pair for any additional Heartland status you encounter.
SKU does not resolve: an order line SKU that does not match an existing iPaaS.com product or variant leaves the line unassociated with a catalog item; the line is still created. No product prerequisite runs in this direction, so transfer your Heartland products to iPaaS.com before transferring orders.
Payment method not configured: the payment method name must match a payment method configured in iPaaS.com. When no linked method resolves, the mapping falls back to "Gift Card_Heartland"; if no method of that name exists in iPaaS.com, the payment is rejected. Create it, change the fallback, or keep the Heartland payment methods linked.
Gift card reference missing: iPaaS.com requires a gift card id on any payment whose method is a gift card method. If the gift card number cannot be read from the last word of the payment description, or the gift card is not linked in iPaaS.com, the payment is rejected. Confirm the Heartland payment description ends with the gift card number.
Deposit payment type rejected by Heartland: Heartland allows only Gift Card, Custom, or External payment types to be applied as order deposits. A cash or check payment applied as a deposit causes the Heartland order API to return an error. Use a dedicated Custom or External payment type for deposit payments.
Deposit parent link not found: if the sales order was not transferred to iPaaS.com before its deposit copy, the ParentId lookup finds no transaction and the deposit ticket is created without a parent link. Confirm the sales order transferred successfully, then re-transfer the order to regenerate the deposit.
Custom value not stored: when a custom field mapped by these collections does not exist on the corresponding iPaaS.com collection, the order still transfers and its other fields are written; only that custom value is not retained. Create the custom field and re-transfer to populate it.
Order not found: when a Manual Sync is run for a Heartland identifier that does not exist, or the record cannot be retrieved, the transfer fails and no iPaaS.com record is created or updated. Confirm the identifier is correct and that the order is still present in Heartland.
Heartland API unavailable: if the Heartland API is temporarily unavailable when a transfer is triggered, the transfer fails, including its lines, addresses, notes, payments, and taxes. The error appears in the iPaaS.com Dashboard error logs, and the record can be retried through a new polling cycle or Manual Sync.
Order silently skipped: an order that does not satisfy the parent filter produces no error at all. If an expected order never arrives, confirm its status has moved past "pending" in Heartland, that its external identifier contains _ORDER and does not contain -D, and that it carries no Heartland transaction sub-type.
Deposit ticket never appears: a deposit is produced only for an order that carries at least one non-gift-card line with a quantity greater than zero. An order made up solely of gift card lines, or with no lines at all, produces no deposit ticket, and no error is raised.
Testing & Validation
Test Scenarios
New order created — create an order in Heartland past the pending status, transfer it, and confirm an iPaaS.com Transaction of type Order is created with the transaction number in the {order number}_ORDER format.
Existing order updated — change a value on a linked Heartland order, transfer it again, and confirm the same iPaaS.com Transaction is updated with no duplicate created.
System id ignored on update — re-transfer a linked order and confirm the iPaaS.com transaction remains on the same subscription. The system id is applied on create only and is ignored on update, so it cannot be used to move a transaction between subscriptions.
Payment method rename does not propagate — rename a linked Heartland payment method, transfer an order that uses it, and confirm the iPaaS.com Payment Method name is unchanged. The name is applied on create only.
Pending order skipped — transfer an order whose Heartland status is still "pending" and confirm no iPaaS.com Transaction of type Order is created and no error is logged.
Order and its deposit both created — transfer an order carrying at least one non-gift-card product line and confirm two iPaaS.com transactions result: one of type Order with the {order number}_ORDER number, and one of type Ticket with the {order number}_ORDER-D number.
Deposit parent link — confirm the deposit ticket's parent is the sales order transaction, not another record.
Cascade deletion — delete the sales order transaction in iPaaS.com and confirm the deposit ticket beneath it is deleted with it. Run this in staging only.
No deposit for a gift-card-only order — transfer an order whose only lines are gift cards and confirm no deposit ticket is created and no error is logged.
Deposit does not clone itself — after a deposit ticket is created, confirm no second-generation copy with a doubled suffix appears.
Deposit accepts a pending order — transfer an order in the pending state and confirm the behavior of the two parents differs as documented: the order is skipped by its own collection while the deposit filter does not exclude the pending status.
Invoice and ticket skipped — transfer a Heartland invoice and a ticket and confirm neither is picked up by the sales order collection.
Customer auto-transferred — transfer an order for a Heartland customer not yet linked to iPaaS.com and confirm the customer is created in iPaaS.com automatically, before the order, without any manual pre-sync.
Customer prerequisite failure blocks the order — force the customer transfer to fail and confirm neither the order nor its deposit ticket is created, and the error is logged.
Payment method auto-transferred — transfer an order paid with a Heartland payment method not yet linked to iPaaS.com and confirm the payment method is created in iPaaS.com and the payment references it. Confirm the order still transfers if that step fails.
Gift card payment — transfer an order with a gift card payment and confirm the gift card is linked, the payment references its gift card id, and the payment method resolves.
Gift card fallback — transfer a gift card payment whose method does not resolve and confirm it is recorded under the "Gift Card_Heartland" payment method.
Gift-card-from-lines prerequisite does not run — transfer an order carrying a gift card line item and confirm no gift card transfer is triggered from the line, since that step applies only to Heartland tickets.
Line status derived from open quantity — transfer an order with one fully fulfilled line and one partially fulfilled line, and confirm the iPaaS.com line statuses are Complete and Pending respectively.
Line discount calculated — transfer an order line with a price before discounts greater than its final price and confirm the line discount amount equals the difference, and that the line discount child record is created.
Deposit line filter — transfer an order carrying a non-item line and confirm that line appears on the order's iPaaS.com transaction but not on the deposit ticket, since the deposit line collection accepts only item lines.
Notes transferred once — transfer an order with notes and confirm each note appears on the order's transaction with type Private and its original creation time, and that no note is copied to the deposit ticket.
Addresses attached — transfer an order with distinct billing and shipping addresses and confirm both are attached to the order's transaction and to the deposit ticket with the correct role indicators.
Shipping method resolves — transfer an order with a shipping method set in Heartland and confirm the readable method name appears on the iPaaS.com address. Then transfer one with no shipping method and confirm the address is created with the field empty and no error.
Taxes transferred — transfer an order with more than one tax authority and confirm each becomes a separate iPaaS.com tax record with its authority and amount, and that the header tax amount equals their sum.
Deposit payment description empty — transfer an order with a payment carrying a description and confirm the description appears on the order's payment but is empty on the deposit ticket's payment, which does not map it.
Unmapped field cleared — set a value on an unmapped writable field in iPaaS.com (for example a line weight), re-transfer the order, and confirm the value is cleared. Then add the DestinationValue preservation mapping and confirm it survives the next re-transfer.
Custom fields populated — with all custom fields created on the Transaction, Transaction Line, and Transaction Payment collections, transfer an order and confirm each Heartland value is stored on both the order and its deposit ticket.
Custom field absent — remove one custom field, transfer an order, and confirm the record still transfers with the remaining fields written and no error raised for the missing custom value.
Manual Sync by identifier — enter a known Heartland identifier in the {order number}_ORDER format on the Manual Sync page and confirm that order, its children, and its deposit ticket transfer. Then enter a value without the suffix and confirm it is rejected.
Polling — with the subscription enabled, create an order in Heartland and confirm it arrives in iPaaS.com on the next polling cycle without manual intervention.
Deposit disabled — disable the deposit parent and its four children, transfer an order, and confirm the order transfers normally and no deposit ticket is produced.
Validation Checklist
Every transferred order carries a transaction number in the {order number}_ORDER format, and re-transfers update rather than duplicate.
Every deposit ticket carries the same number with a -D suffix, is of type Ticket, and is linked to its sales order as a child.
Only orders past the pending status appear as iPaaS.com transactions of type Order; invoices, tickets, and deposit copies do not.
Each transaction has a resolved customer or an email address, and a status that is valid in iPaaS.com.
Header tax and discount amounts match the sum of the order's tax records and line discounts in Heartland.
Each line SKU resolves to an existing product or variant, and each line status reflects its open quantity.
Billing and shipping addresses are attached to both the order and its deposit with the correct role indicators.
Notes appear once, on the order's transaction, with type Private.
Every payment carries a method that matches a configured iPaaS.com payment method, and gift card payments carry a gift card reference.
Customers, payment methods, and gift cards that were not previously linked were created automatically, without manual pre-sync.
Every writable field you rely on is either mapped or has a DestinationValue preservation mapping, verified by re-transferring an existing order and confirming nothing you need was cleared.
Polling and Manual Sync produce the same resulting records for the same order.
Additional Notes
Heartland is the source of truth for the fields listed under Mappings. Editing those values directly in iPaaS.com will be overwritten on the next transfer of that order.
The child collections are transferred as part of a parent transfer. They cannot be run, scheduled, or manually synced on their own, and neither can the deposit parent.
The deposit family duplicates the sales order by design. If your workflow has no use for deposit or ticket documents, disable or delete Add Heartland Sales Order Deposit TO iPaaS.com and its four children rather than editing individual mappings.
The two families use similarly-named child collections. Before editing a line, address, payment, or tax mapping, confirm which parent the collection belongs to — a change to the sales order children has no effect on the deposit ticket, and the reverse is also true.
Because orders arrive by polling rather than instant webhooks, allow for the polling interval when validating a change made in Heartland.
The Transaction Created By custom field is not decorative. It is the marker an outbound direction reads to avoid sending iPaaS.com-created transactions back into iPaaS.com; leave it mapped whenever both directions are active.
The C5_Custom_Transaction mapping ships with a placeholder Heartland custom field name on both parent collections. Replace it with a real Heartland custom field name, or remove the mapping, before going live.
The Heartland Station Id and Heartland Source Location Id custom fields exist so that the values Heartland requires when creating orders remain available if you later write orders back into Heartland. Keep them mapped if a return trip is in scope.
Related Documents
Setup & Reference
Mapping Documentation