Heartland product records are transferred into iPaaS.com as Product records. The same collection both creates new iPaaS.com products and updates existing ones, so it is used whether the Heartland item is new to iPaaS.com or already linked.

Heartland distinguishes two kinds of item, and that distinction drives the whole family. A simple item (including a simple associated item) becomes an iPaaS.com Product. A grid item is a configurable product whose sellable combinations are its variants; a grid item does not become a standalone iPaaS.com product. Instead, its combinations are transferred as iPaaS.com Product Variants through the Add/Update Heartland Product Variant TO iPaaS.com child collection. The parent collection's mapping filter is what enforces this split, and the variant child collection's filter is its exact mirror.

Four child collections ride along with the parent product transfer: the product's per-location inventory, its options, its variants, and the add-on items Heartland offers alongside it. None of them runs on its own. Alongside the native iPaaS.com product fields, the parent and variant collections store a set of Heartland-specific values — cost, financial class, online availability, long description, primary vendor id, primary vendor name, tags, and the track-inventory flag — on iPaaS.com custom fields.

This document covers the Heartland → iPaaS.com direction. A separate collection writes products in the opposite direction, from iPaaS.com into Heartland; it is a different flow with different trigger semantics and is listed under Duplicate or Conflicting Mappings.

Because Heartland uses different APIs for grid items and for simple or simple associated items, the Heartland item ID on its own is not enough to identify a record — the same ID number can exist under both types. A type suffix is therefore appended to every product identifier.

On the iPaaS.com Manual Sync page, enter the Heartland item or grid ID with its type suffix in the Heartland input field:

A record ID entered without one of these suffixes returns a not-implemented error, because the integration cannot determine which Heartland API to call. Transferring a product this way also transfers its inventory, options, variants, and add-on related products in the same operation.

After a successful transfer, iPaaS.com records the Heartland product's identifier with its type suffix as the external-id link between the two systems — for example, 101602_GRID or 12345_SIMPLE. Subsequent transfers of the same item match on that external id and update the existing iPaaS.com record rather than creating a second one. Whether an incoming product is created or updated is determined by whether that external id is already linked, not by which event triggered the transfer.

The _SIMPLE suffix also appears inside the add-on child collection's logic, where a non-grid add-on item's identifier has the suffix appended before the iPaaS.com lookup is performed.

Deleting a Heartland product is not supported by this integration, at any level of the family. The integration creates and updates iPaaS.com records only. Removing or deactivating a Heartland item, variant, inventory record, option, or add-on relationship does not delete or deactivate the corresponding iPaaS.com Product, Product Variant, Product Inventory, Product Option, or related-product record. Records that should no longer appear must be managed directly in iPaaS.com.

One partial exception is worth knowing about, and it is not a deletion the integration performs. When iPaaS.com updates a product option, option values that are not included in the incoming request are removed from that option. Because the option collection ships with no mappings, this behavior is not currently exercised by the template, but it becomes relevant the moment option mappings are added. See Mappings.

If a Heartland item is deactivated rather than deleted, the parent collection's Status mapping does carry that through: an inactive Heartland item is transferred with the iPaaS.com status Disabled. Deactivating in Heartland is therefore the reliable way to retire a product through the integration.

This family stores a consistent set of Heartland values on iPaaS.com custom fields at both the product and variant level:

Each requires a matching iPaaS.com subscription custom field on the relevant collection — Product for the parent, Product Variant for the variant child — before its value is stored. If the custom field does not exist, the product still transfers and the remaining fields are written; only that custom value is not retained.

The collections can also read arbitrary Heartland item custom field values. Add a mapping of type Dynamic Formula whose source calls GetValueFromCustomField with the name of the Heartland custom field, and choose any iPaaS.com destination. At transfer time the integration returns the value of the named Heartland custom field.

Important: grid item custom field values and simple item custom field values are returned by the Heartland API in different objects. Grid item values are found in the Heartland ItemCustom object; simple and simple associated item values are found in the Heartland Custom object. A formula that must handle both types has to check the product type and read from the appropriate object — the parent collection's shipped custom-field formula demonstrates exactly this pattern. A Heartland custom field must be created in Heartland before it is available to mappings.

Both the parent and variant collections ship a placeholder custom-field mapping — C5_Custom_Product and C5_Custom_Product_Variant — whose source names the sample field "My Custom Item Field". Replace that name with a real Heartland custom field, or remove the mapping, before going live.

Other mapping collections operate on the same iPaaS.com records. They fall into two groups.

The opposite direction — writing products into Heartland. Add/Update Heartland Product FROM iPaaS.com creates and updates Heartland items from iPaaS.com product data, with its own child collections for variants, inventory, options, option values, and variant options. It is not the reverse of this collection in a symmetric sense: its mappings, its trigger, and its record-matching behavior all differ.

Standalone inventory, same direction. Add Heartland Product Inventory Standalone TO iPaaS.com, Update Heartland Product Inventory Standalone TO iPaaS.com, Add Heartland Product Variant Inventory Standalone TO iPaaS.com, and Update Heartland Product Variant Inventory Standalone TO iPaaS.com transfer Heartland inventory levels into iPaaS.com on their own polling schedule, without re-transferring the whole product. These are documented separately in Heartland to iPaaS.com Standalone Inventory Mapping Documentation and should not be confused with the Add/Update Heartland Product Inventory TO iPaaS.com child collection documented here. The distinction is the trigger, not the destination: the child collection moves inventory only when its product moves, while the standalone collections poll inventory changes on their own. Both write to the same iPaaS.com Product Inventory records, so running both is a supported and common configuration — the standalone collections keep levels fresh between full product transfers.

Inventory in the opposite direction. Add/Update Heartland Product Inventory Adjustment FROM iPaaS.com and Add/Update Heartland Product Variant Inventory Adjustment FROM iPaaS.com write inventory changes from iPaaS.com back into Heartland as adjustments. Heartland levels read in through this family are read-only; outbound quantity changes are applied through the adjustment collections, never by writing these fields back.

Important: Template mapping collections are provided 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 for product and inventory data. If both directions are active with the default mappings, review your polling schedules with your integration specialist to prevent a feedback loop.

This integration does not use iPaaS.com collision handling for products. Whether an incoming product is created or updated is determined solely by whether its Heartland external id is already linked in iPaaS.com; there is no collision recovery step to configure.

The parent Add/Update Heartland Product TO iPaaS.com collection has four child collections. None of them runs independently, and none has its own schedule, webhook, or Manual Sync entry:

Two of those children carry nested collections of their own, which are dispatched under the same parent product transfer. The full hierarchy is three levels deep:

Every collection in that tree is documented in this article, under Mappings, in the order shown. None of them has a trigger, schedule, webhook, or Manual Sync entry of its own — a single parent product transfer drives the whole tree.

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.

Prerequisites:

No prerequisite records are transferred automatically in this direction. The product flow dispatches the product and its children directly, with no preliminary lookup-and-transfer step of the kind that runs on the Heartland transaction and customer address flows. The practical consequence is that two dependencies must already be satisfied before a product transfer produces complete results:

Scheduled polling:

Manual Sync:

Both paths converge on the same mapping logic, so a product's resulting iPaaS.com record is identical regardless of how the transfer was triggered.

Mapping Filter

The filter has a single branch: a Heartland item is transferred as an iPaaS.com product only when its product type is not "grid". Grid items are Heartland's configurable products, and their sellable combinations are transferred as iPaaS.com product variants by the Add/Update Heartland Product Variant TO iPaaS.com child collection rather than as standalone products. Simple items and simple associated items pass the filter and become iPaaS.com products.

The filter does not raise an error and throws no message. Grid items are passed over silently by this collection, so a grid item produces no entry in the error log here — it is expected to arrive as variants instead.

Description: Creates or updates the iPaaS.com Product record from the Heartland simple item, matched by the Heartland external id. This is the parent of the inventory, option, variant, and add-on product child collections.

This collection is a child of Add/Update Heartland Product 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 product, attaching that product's Heartland add-on items to the iPaaS.com product as related products. The association to the parent product is supplied automatically by the parent transfer and is not a subscriber mapping.

Mapping Filter

The filter decides whether an add-on item can be linked yet, and it evaluates each add-on item through these branches:

The filter does not raise an error and throws no message. The commented-out throw statement at the top is a diagnostic aid that is not active. An add-on item that does not resolve is passed over silently, so a missing related product produces no entry in the error log; it can be linked on a later transfer once the add-on product itself has been transferred to iPaaS.com.

Description: Attaches each Heartland add-on item to the iPaaS.com product as a related product of type Related Product, resolving the add-on to the iPaaS.com product or variant it points at.

This collection is a child of Add/Update Heartland Product 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 product, creating or updating one iPaaS.com Product Inventory record per Heartland location that stocks the item. The association to the parent product is supplied automatically by the parent transfer and is not a subscriber mapping.

This is not the same as the standalone inventory collections. Those poll inventory changes on their own schedule without re-transferring the product, and are documented in Heartland to iPaaS.com Standalone Inventory Mapping Documentation.

Mapping Filter

The filter evaluates each of the product's location inventory records through three branches:

The filter does not raise an error and throws no message. Skipped locations produce no entry in the error log, so if inventory for a location never appears in iPaaS.com, confirm that location is transferred and linked.

Description: Creates or updates one iPaaS.com Product Inventory record for each linked Heartland location that stocks the product, carrying the on-hand and available quantities and the unit cost.

This collection is a child of Add/Update Heartland Product TO iPaaS.com. It does not run on its own and 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: This collection is available and is dispatched with the product's options during every parent product transfer, but it ships with no mappings configured. Because a mapping collection writes only what its mappings tell it to write, nothing transfers through this collection as delivered.

This collection has no mappings. There is no mapping table below because there are no rows — this is the shipped state of the template, not an omission from this document. What that means in practice:

To make this collection do something, add a mapping of type Field whose source is the Heartland option Name and whose destination is OptionName. That single mapping is what iPaaS.com needs to create the option. Add Type and Order mappings as well if your catalog depends on them. Once option mappings are in place, be aware that iPaaS.com replaces an option's value list wholesale on update: any option value not present in the incoming request is deleted from that option, so the complete set of values must be sent every time.

Subscribers who do not use grid product options in iPaaS.com can leave this collection as delivered; it is inert and costs nothing.

This collection sits one level deeper than the other children. It is a nested child of Add/Update Heartland Product Option TO iPaaS.com, which is itself a child of Add/Update Heartland Product TO iPaaS.com. In other words: the product transfer dispatches the option collection, and the option collection dispatches this one for each allowed value under an option. It has no schedule, webhook, or Manual Sync entry of its own, and it cannot be run independently of either collection above it.

Mapping Filter

This mapping collection does not have a mapping filter applied. All records routed to it are processed without additional filtering conditions.

Description: Transfers each allowed value under a Heartland product option — the individual sizes under a "Size" option, or the colors under a "Color" option — to the matching iPaaS.com product option.

This collection depends on a parent that currently writes nothing. As established in the section above, Add/Update Heartland Product Option TO iPaaS.com ships with no mappings, so no iPaaS.com product option is created by the template as delivered. Because an option value in iPaaS.com must attach to an option, this collection's single mapping has nothing to attach to until the option collection is given at least an OptionName mapping. The mapping below is correctly configured and will work — it is simply gated on a parent that does not yet produce a record. If you want option values in iPaaS.com, fix the option collection first; this one needs no change.

The writable option value fields this collection does not map are detail and order. Note also that iPaaS.com replaces an option's value list wholesale on update: any option value not present in an incoming option update is deleted from that option. Once the option collection is mapped, the complete set of values must be sent on every transfer.

This collection is a child of Add/Update Heartland Product 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 grid product, creating each grid combination as an iPaaS.com Product Variant under the product the parent created or updated. It in turn dispatches the nested Add/Update Heartland Product Variant Option TO iPaaS.com and Add/Update Heartland Product Variant Inventory TO iPaaS.com collections for each variant.

Mapping Filter

The filter has a single branch and is the exact mirror of the parent's filter: a Heartland item is processed as a variant only when its product type is "grid". In Heartland a grid item is a configurable product whose sellable combinations become the iPaaS.com variants. Items that are not grid type are transferred as standalone iPaaS.com products by the parent collection instead, and are passed over here.

Between the two filters, every Heartland item takes exactly one path — product or variant — and no item can be transferred as both. The filter does not raise an error and throws no message; non-grid items are passed over silently.

Description: Creates or updates an iPaaS.com Product Variant for each combination of a Heartland grid item, carrying the variant's SKU, barcode, pricing, and dimensions, plus the Heartland-specific custom field values.

This collection sits one level deeper than the other children. It is a nested child of Add/Update Heartland Product Variant TO iPaaS.com, which is itself a child of Add/Update Heartland Product TO iPaaS.com. The product transfer dispatches the variant collection, and the variant collection dispatches this one for each option assignment on a variant. It has no schedule, webhook, or Manual Sync entry of its own and cannot be run independently of either collection above it.

Do not confuse this with Add/Update Heartland Product Option Value TO iPaaS.com. That collection carries the list of values a grid product offers under an option; this one carries the specific value a single variant is — the Large in a Size option, the Red in a Color option. Together they are what make a grid combination identifiable.

Mapping Filter

This mapping collection does not have a mapping filter applied. All records routed to it are processed without additional filtering conditions.

Description: Records each variant's option assignments on the iPaaS.com product variant, carrying the option name and the selected value that distinguish that variant within its grid product.

The variant that these options belong to is identified by the parent variant transfer, so this collection does not map the variant SKU itself. The writable variant option fields it does not map are detail and order.

This collection sits one level deeper than the other children. It is a nested child of Add/Update Heartland Product Variant TO iPaaS.com, which is itself a child of Add/Update Heartland Product TO iPaaS.com. It runs whenever the variant collection transfers a variant, creating or updating one iPaaS.com Product Variant Inventory record per Heartland location that stocks that variant. It has no schedule, webhook, or Manual Sync entry of its own.

It is the variant-level counterpart of Add/Update Heartland Product Inventory TO iPaaS.com, and the two never overlap: a simple item's stock flows through the product-level collection, and a grid combination's stock flows through this one. Neither is the same as the standalone inventory collections, which poll inventory changes on their own schedule and are documented in Heartland to iPaaS.com Standalone Inventory Mapping Documentation.

Mapping Filter

The filter is identical to the product-level inventory filter and evaluates each of the variant's location inventory records through the same three branches:

The filter does not raise an error and throws no message. Skipped locations produce no entry in the error log, so if inventory for a variant at a given location never appears, confirm that location is transferred and linked.

Description: Creates or updates one iPaaS.com Product Variant Inventory record for each linked Heartland location that stocks the variant, carrying the on-hand and available quantities and the unit cost.

Updates in this direction are full replacements. When iPaaS.com updates a record that already exists — which happens whenever a linked Heartland product 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.

Product. The writable product fields the parent collection does not map are:

The product record also carries child groups that this collection does not transfer at all: kit, categories, units, and alternate_ids. Values held in those on the iPaaS.com side are not maintained here. Product units and alternate ids can be transferred if you need them, but there is no corresponding Heartland source data for them, so no template mappings are provided; their configuration is specific to each use case.

Product Variant. The writable variant fields the variant child collection does not map are msrp and status. The unmapped status deserves attention: the parent collection sets a product status from the Heartland active flag, but no equivalent mapping exists at the variant level, so a variant status set in iPaaS.com is cleared on each update. The variant also carries kit, categories, and variant-level alternate_ids groups that this collection does not transfer.

Product Inventory. The inventory child collection maps every core writable inventory field that iPaaS.com exposes — location, on-hand quantity, available quantity, and cost. The product association is supplied by the parent transfer. Only inventory-level custom fields and external ids remain unmapped; if your integration stores values there, confirm they are set through another mapping before relying on repeated updates.

Related Product. The add-on child collection maps every core writable related-product field — related id, relationship type, and the variant indicator. The parent product association is supplied by the parent transfer. Only related-product custom fields and external ids remain unmapped and are cleared on update.

Product Option. Because the option collection ships with no mappings, OptionName, Type, and Order are all unmapped. This collection writes nothing, so it does not clear existing iPaaS.com option data — but it also cannot populate any of these values. Add the mappings you need. Once option mappings are in place, remember that iPaaS.com deletes any option value not present in an incoming update.

Product Option Value. The single mapping on this collection supplies the value itself, which is the only field iPaaS.com requires. The writable option value fields it does not map are detail and order. There is a second, larger effect to understand here: iPaaS.com replaces an option's value list wholesale on update, deleting any value not present in the incoming request. Once the option collection is mapped, an option value that Heartland stops reporting is removed from iPaaS.com — this is a genuine deletion, and it is the one place in this family where an iPaaS.com record disappears as a result of a transfer.

Product Variant Option. This collection maps the value and the option name. The writable variant option fields it does not map are detail and order. The variant association is supplied by the parent variant transfer.

Product Variant Inventory. This collection maps every core writable field that iPaaS.com exposes for variant inventory — location, on-hand quantity, available quantity, and cost. The variant association is supplied by the parent variant transfer. Only variant-inventory-level custom fields and external ids remain unmapped; if your integration stores values there, confirm they are set through another mapping before relying on repeated updates.

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.Description to preserve the native product description, DestinationValue.Msrp to preserve an MSRP, or DestinationValue.Status on the variant collection to preserve a variant status. 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.

No field in this family is ignored on update. Unlike some other iPaaS.com entities, none of the writable fields on the Product, Product Variant, Product Inventory, Related Product, Product Option, Product Option Value, Product Variant Option, or Product Variant Inventory records is flagged as accepted on create only. Every field these collections map takes effect on update as well as on create, so a change made in Heartland to any mapped field does propagate on the next transfer.

Setup & Reference

Mapping Documentation