Summary
iPaaS.com Product records are written out to Heartland as Heartland products. iPaaS.com is the source in this direction and Heartland is the system being written to. A single parent collection, Add/Update Heartland Product FROM iPaaS.com, handles both new products and updates to products that are already linked; there is no separate Add collection and Update collection for this direction.
The mapping writes core product fields to Heartland — the public SKU, product name, price, cost, dimensions, barcode, and the online-availability, active, and inventory-tracking flags — and supplies several Heartland-specific values (cost, long description, financial class, primary vendor, tags, and track-inventory) from iPaaS.com custom fields. When a product transfers, its inventory, variants, and options travel with it through three child collections.
How a product is written depends on whether it carries options. A product with options is transferred to Heartland as a grid (variant) product; a product with no options is transferred as a simple product. That one distinction drives most of the behavior described in this article, including which fields are written and which child collections do any work.
This article covers all seven collections in this direction: the parent, its three child collections, and the three nested collections that hang beneath two of those children. The opposite direction — Heartland products transferred into iPaaS.com — is handled by a separate set of collections and is documented separately.
Grid and Simple Products
Options determine the product type: if an iPaaS.com product includes any options, the integration attempts the transfer to Heartland as a grid (variant) product. A product with no options is transferred as a simple product. To keep a product with options from transferring as a grid product, adjust the product option child collection filters.
Values copied to grid fields: when a product with options is transferred, the values mapped to Price, Cost, Original Price, Financial Class, and Primary Vendor are automatically copied to the corresponding grid-item fields, so a single set of mappings serves both simple and grid products.
Fields not set on grid products: Heartland does not accept Depth, Width, Height, Weight, Track Inventory, or Primary Barcode on grid items and will error if they are supplied. The template mappings for these fields deliberately return no value for variant-tracked products so the transfer succeeds; those values are written for simple products only.
Option limit: Heartland supports a maximum of three grid options per product.
This Is Not the Inventory Adjustment Family
Two of the collections in this article write Heartland inventory adjustments, and each has a similarly named standalone counterpart that this article does not cover:
Add/Update Heartland Product Inventory FROM iPaaS.com (covered here, runs only as part of a product transfer) is a different collection from Add/Update Heartland Product Inventory Adjustment FROM iPaaS.com (not covered here, runs on its own).
Add/Update Heartland Product Variant Inventory FROM iPaaS.com (covered here, runs only as part of a variant transfer) is a different collection from Add/Update Heartland Product Variant Inventory Adjustment FROM iPaaS.com (not covered here, runs on its own).
The two standalone Adjustment collections write inventory to Heartland independently of a full product transfer and are documented in Heartland from iPaaS.com Inventory Adjustment Mapping Documentation. The difference is the trigger, not the outcome: all four routes ultimately create Heartland inventory adjustments against the same locations. Decide which route owns inventory before enabling them together, and check the collection name carefully — the word "Adjustment" is what distinguishes the standalone collections from the ones described here.
ID Format
Manual Sync ID Format
On the iPaaS.com Manual Sync page, enter the iPaaS.com product's internal ID in the iPaaS.com input field. This outbound direction uses the iPaaS.com identifier, not a Heartland identifier. Transferring a product this way also transfers that product's inventory, variants, and options through the child collections.
External ID Format
After a successful transfer, iPaaS.com records the Heartland product's unique identifier as the external-id link between the two systems. Because Heartland uses different APIs for grid and simple products, the stored external ID carries a type suffix so overlapping Heartland ID numbers can be distinguished — for example, 101602_grid for a grid product or 12345_simple for a simple product.
The integration uses that link to locate the correct Heartland product on every later transfer, so subsequent transfers update the same Heartland product rather than creating a duplicate. When an iPaaS.com product is not yet linked, the integration searches Heartland by SKU before creating a new product; see Integration Flow.
Variants are linked individually. Each iPaaS.com variant that transfers as part of a grid product gets its own external-id link to the matching Heartland grid item, so later transfers update the same variant.
Deleted Record Support
Deleting a product is not supported in this direction. The integration creates and updates Heartland products only — deleting or deactivating a Product record in iPaaS.com does not delete the linked Heartland product. The same applies to product inventory, variants, and options: none of the child collections remove records from Heartland.
Products that should no longer be sold in Heartland must be managed directly in Heartland. Note that the parent collection writes a static value of true to the Heartland Active flag on every transfer, so a product deactivated by hand in Heartland is reactivated the next time it transfers unless that mapping is changed. Option values are a further case: because Heartland stores options and their values globally, values added by earlier transfers are never removed, even when they no longer apply to a product.
Custom Field Support
This direction reads from iPaaS.com custom fields and can also write to a Heartland custom field on the product.
iPaaS.com custom fields as the source. Several Heartland product attributes are supplied from iPaaS.com custom fields of the same name. The Heartland Cost, Long Description, Primary Vendor, and Available Online fields are mapped from the iPaaS.com Heartland Cost, Heartland Long Description, Heartland Primary Vendor Id, and Heartland Item Available Online custom fields, and the Heartland Financial Class, Track Inventory, and Tags fields read the iPaaS.com Heartland Financial Class, Heartland Track Inventory, and Heartland Tags custom field values through a formula. The variant child collection uses the same set of named custom fields on the Product Variant collection.
Prerequisite: each custom field used as a source must exist as a custom field on the iPaaS.com Product collection (or Product Variant collection, for the variant child) to supply its value. Until the custom field exists in iPaaS.com, the corresponding Heartland value cannot be supplied by the transfer.
Heartland custom fields as the destination. A Heartland custom field must be created in Heartland manually before it is visible on the Heartland website and available as a mapping destination. Until the field exists in Heartland, a value mapped to it is not stored.
Both the parent and the variant child ship with a Product Example mapping that writes a static placeholder value. These are template examples that demonstrate the pattern, not production configuration. Replace the value with the data you want to write and point the mapping at the Heartland custom field where it should be stored, or remove the mapping if it is not needed.
Mapping Collection Status
Status: Enabled. The parent collection and all three child collections are enabled in the template.
Trigger Events: Outbound transfers are triggered from iPaaS.com. When the subscription is configured and enabled, the integration recognizes product creation and product update events, along with the corresponding product inventory, product variant, and product option events. No automatic transfers occur until the subscription is configured and enabled. A specific product can also be transferred on demand at any time from the iPaaS.com Manual Sync page.
The three child collections have no trigger of their own. They run whenever their parent product collection transfers a product.
Duplicate or Conflicting Mappings
Four mapping collections operate on product data in this outbound direction: the parent described above and its three child collections. Because a single Add/Update parent handles both creation and update, the two paths never compete for the same record on the same transfer.
Other collections also touch the same Heartland data:
Add/Update Heartland Product TO iPaaS.com: creates or updates iPaaS.com products from Heartland data — the opposite direction, with its own child collections.
Add/Update Heartland Product Inventory Adjustment FROM iPaaS.com and Add/Update Heartland Product Variant Inventory Adjustment FROM iPaaS.com: standalone collections that write inventory adjustments to Heartland independently of a full product transfer, and so also affect Heartland product and variant inventory.
Add Heartland Product Inventory TO iPaaS.com and Update Heartland Product Inventory TO iPaaS.com: bring Heartland inventory into iPaaS.com.
Important: before running the inbound and outbound directions together, review your mapping collection filters and clearly define which system is the source of truth for product data. It is not recommended to run every template direction bidirectionally; if both directions are active with the default mappings, changes may propagate back and forth between the systems.
Inventory feedback-loop risk. This direction makes iPaaS.com the source of truth for on-hand quantity at the target location — each transfer drives Heartland's quantity available toward the value iPaaS.com supplies. Do not run the inventory child collection at the same time as the Heartland-to-iPaaS.com inventory collections against the same locations unless you have defined which system owns inventory; otherwise the two directions can continually adjust each other. Review your data flows and polling schedules with your integration specialist before enabling both directions.
Collision Handling
This integration does not use iPaaS.com collision handling for products. Whether a product is created or updated in Heartland is determined by the external-id link and, when that is absent, the SKU match performed before the transfer; there is no collision recovery step to configure.
Supported Child Collections
The collection hierarchy in this direction is two levels deep beneath the parent. Every collection below runs only as part of the parent product transfer; none of them has a webhook, polling schedule, or Manual Sync entry of its own, and none can be triggered directly.
Level 1 — children of Add/Update Heartland Product FROM iPaaS.com
Add/Update Heartland Product Inventory FROM iPaaS.com: writes an inventory adjustment for the product. This collection processes simple products only — its filter transfers inventory when the parent tracking method is a product rather than a variant — requires the product's location to be linked to Heartland, and requires an adjustment reason. Heartland compares the supplied quantity to the current quantity available at the location and creates an adjustment only when the two differ. It has no nested collections.
Add/Update Heartland Product Variant FROM iPaaS.com: writes the grid product's variants to Heartland as grid items. It has two nested collections of its own.
Add/Update Heartland Product Option FROM iPaaS.com: writes the grid product's options to Heartland as pick-list item custom fields. It has one nested collection of its own.
Level 2 — nested children of Add/Update Heartland Product Variant FROM iPaaS.com
Add/Update Heartland Product Variant Inventory FROM iPaaS.com: writes each variant's inventory to Heartland as an inventory adjustment at the resolved location. It runs once for each variant its parent writes, which means it runs only for grid products. This is not the standalone Add/Update Heartland Product Variant Inventory Adjustment FROM iPaaS.com collection.
Add/Update Heartland Product Variant Option FROM iPaaS.com: writes each variant's option selections — the option name and value pairs that distinguish one grid item from another — to the Heartland variant.
Level 2 — nested child of Add/Update Heartland Product Option FROM iPaaS.com
Add/Update Heartland Product Option Value FROM iPaaS.com: writes each option's allowed values into the Heartland pick-list item custom field that its parent option collection created or reused.
Because these three sit at level 2, they are two removes from any trigger. An option value reaches Heartland only when its option is written, which happens only when its product is transferred; a variant's inventory or option selection reaches Heartland only when that variant is written, which likewise happens only when its product is transferred. All seven collections are documented in this article.
System Caveats
Heartland Caveats
Description required: Heartland requires a description on every product. The parent collection supplies the iPaaS.com Name so the product can be created.
Price and cost required: Heartland requires a current price and a default cost on every product.
Barcode length: Heartland enforces an undocumented barcode format that limits barcode length and allows only underscores, dashes, and alphanumeric characters. The template barcode mappings stop the transfer with an error when a product or one of its variants has a barcode longer than nine characters. Adjust the mapping to fit your source data, or leave the barcode empty to accept the barcode Heartland generates automatically. Because a disallowed barcode set on first creation can cause validation errors on later transfers, validate barcode handling in a staging environment before relying on it in production.
Options saved globally: product options and option values are saved globally in Heartland as allowed values on item custom fields. When a product is transferred, a matching item custom field is created if none exists and any new option values are added to the allowed list. Option values are not removed, so Heartland may list more valid option values than apply to a single product. Use caution with the Heartland grid "Generate items" function, which creates products for every option value, to avoid creating products for option values not assigned to variants transferred from iPaaS.com.
Only pick-list options are supported: Heartland supports only pick-list item custom fields for options and option values, which is why the option child collection writes a fixed validation type.
Grid field restrictions: Heartland does not accept Depth, Width, Height, Weight, Track Inventory, or Primary Barcode on grid items. See Grid and Simple Products above.
Difference-only inventory adjustments: Heartland records inventory changes as adjustments against a reason code, not as an absolute quantity. An adjustment is created only when the iPaaS.com quantity differs from Heartland's current quantity available at the location, and only one item is adjusted per adjustment record.
Adjustment reason required: Heartland requires a reason code on every inventory adjustment.
Location must be linked: an adjustment can only be created against a Heartland location that is linked to the iPaaS.com location. Unlinked locations prevent the inventory transfer.
Custom field visibility: a Heartland custom field must be created in Heartland before it is visible on the Heartland website and available to mappings.
iPaaS.com Caveats
Manual Sync uses the iPaaS.com ID: Manual Sync in this direction takes the iPaaS.com product's internal ID, not a Heartland identifier.
Custom field source: a Heartland value supplied from an iPaaS.com custom field requires that custom field to exist on the iPaaS.com Product collection, or on the Product Variant collection for the variant child, to supply the outbound value.
Custom prices not supported: uploading custom prices or price lists from iPaaS.com to Heartland is not supported at this time.
Children follow the iPaaS.com product: only the inventory, variants, and options recorded on the iPaaS.com product are written to Heartland. A product with no variants in iPaaS.com writes no variants; a product with no options writes no options and transfers as a simple product.
Location linkage: the iPaaS.com location referenced by an inventory record must already be linked to its Heartland counterpart before inventory can be adjusted. Transfer and link locations first.
Integration-Specific Caveats
SKU is the matching key, not only a data field: the SKU written to the Heartland public identifier is also the value the integration uses to find an existing Heartland product when no external-id link exists. Changing a SKU in iPaaS.com affects both what is written and how an unlinked product is matched.
No prerequisite records are transferred for products: unlike the outbound order path, a product transfer does not create any other record in Heartland ahead of itself. The step that runs before a product transfer only reconciles identity — it searches Heartland by SKU and writes the external-id link. Locations, in particular, are not created automatically; the inventory child collection requires a location that is already linked.
Variant matching runs inside the grid: an unlinked variant is matched only against the items belonging to the Heartland grid product resolved for its parent, and only by SKU. A variant whose SKU does not match an existing grid item is created rather than matched.
Transfers are additive: an outbound transfer never removes a Heartland product, variant, option, or option value.
Heartland does not publish a field-level specification: requirements and update behavior for the Heartland product, variant, and item custom field records are drawn from the integration's own mappings and behavior. Validate them in a staging environment before relying on them in production.
Setup Requirements
Heartland Configuration
Create any Heartland custom field you intend to map before configuring the mappings, so it is visible on the Heartland website and available as a mapping destination.
Confirm the inventory adjustment reason codes you want to use, and note the identifier of the reason the inventory child collection should apply.
Confirm the Heartland locations that correspond to your iPaaS.com locations, and link them before running inventory.
Note any product fields maintained only in Heartland so they can be preserved on update.
iPaaS.com Configuration
Enable the subscription so outbound transfers can run.
Create the named Heartland custom fields on the iPaaS.com Product and Product Variant collections so they can supply their outbound values.
Ensure iPaaS.com products carry a unique SKU and a Name, and that price and cost values are available.
Confirm each iPaaS.com location referenced by inventory is linked to a Heartland location.
Replace the placeholder Product Example static mappings in the parent and variant collections with real configuration, or remove them.
Replace the default by-name adjustment reason lookup in the inventory child collection with the fixed Heartland reason code identifier you want to use.
Review the mappings and add preservation mappings for any Heartland values you do not want written over. See Unmapped Field Overwrite Risk below.
Authentication & Security
Heartland uses OAuth 2.0 to obtain an access token, which authorizes the Heartland API requests made during a transfer. Credentials are configured on the Heartland subscription — see the Heartland Installation Instructions.
Integration Flow
Automatic outbound transfer (new product):
A Product record is created or changed in iPaaS.com and the subscription is enabled.
Before writing anything, the integration checks whether the iPaaS.com product already has an external-id link to a Heartland product.
No link is found, so the integration determines the product type: if the iPaaS.com product carries variants it searches Heartland for a matching grid item by SKU; otherwise it searches for a matching simple item by SKU.
No Heartland match is found, so the transfer proceeds and a new Heartland product is created from the mapped values — as a grid product if the iPaaS.com product carries options, otherwise as a simple product.
The product's inventory, variants, and options are written in the same operation through the three child collections.
The Heartland product's identifier, with its grid or simple type suffix, is saved in iPaaS.com as the external-id link for future transfers.
Automatic outbound transfer (existing product):
A linked iPaaS.com Product record is changed.
The integration resolves the Heartland product through the saved external-id link.
The mapped values are applied to that Heartland product.
The product's inventory, variants, and options are written in the same operation through the three child collections.
Unlinked product matched by SKU:
An iPaaS.com product with no external-id link is transferred.
The integration searches Heartland by SKU — among grid items when the iPaaS.com product has variants, among simple items when it does not — and finds a match.
The two records are linked using the Heartland identifier plus its type suffix, and the transfer proceeds as an update to that existing Heartland product instead of creating a second one. This is what prevents duplicate Heartland products for a SKU that already exists there.
If the link cannot be written for the matched Heartland product, the transfer stops with an error rather than continuing, because continuing could create a duplicate product record.
Variant linking within a grid product:
Once the parent product is linked, and only if the iPaaS.com product carries variants, the integration checks each variant for an external-id link of its own.
For each variant with no link, the integration retrieves the items belonging to the resolved Heartland grid product and looks for one whose public identifier matches the variant's SKU. The comparison ignores letter case.
When a match is found, the variant is linked to that Heartland grid item so later transfers update it rather than creating a duplicate. Variants with no match are created by the variant child collection during the transfer.
If a variant link cannot be written, the transfer stops with an error rather than continuing.
Manual Sync:
An iPaaS.com product ID is entered in the iPaaS.com input field on the Manual Sync page.
The integration transfers that single product, together with its inventory, variants, and options, through the same matching and create-or-update path described above.
This identity step runs before the product itself is written, and it is the only work performed ahead of a product transfer. No other Heartland record — location, vendor, financial class, or adjustment reason — is created automatically as part of a product transfer. All paths then converge on the same mapping logic, so the resulting Heartland product is the same regardless of how the transfer was triggered.
Mappings
Add/Update Heartland Product FROM iPaaS.com
Mapping Filter
return true;
//Optional - throw error when option limit is exceeded
//if(Options != null){ if(Options.count>3){throw new exception($"Heartland only supports 3 grid options maximum so {Sku} could not be transferred")}}The filter has one active branch and one inactive example.
Active branch: the filter returns true for every product, so all iPaaS.com products transferred through automatic transfers or Manual Sync are processed without additional filtering conditions.
Inactive example: the commented-out lines show how to stop a product from transferring when it carries more than three options, because Heartland supports a maximum of three grid options. If enabled, that branch would stop the transfer with the message "Heartland only supports 3 grid options maximum so {Sku} could not be transferred", where {Sku} is the SKU of the product being transferred. This example does nothing as shipped; enable and adjust it only if it fits your data.
Description: Creates or updates a Heartland product from an iPaaS.com Product, as a grid product when the product carries options and as a simple product when it does not. The parent of the Add/Update Heartland Product Inventory FROM iPaaS.com, Add/Update Heartland Product Variant FROM iPaaS.com, and Add/Update Heartland Product Option FROM iPaaS.com child collections, which write the product's inventory, variants, and options in the same transfer.
Mapping Type | Source Field (iPaaS.com) | Destination Field (Heartland) | Description |
Field | Sku | PublicId | Required. Writes the iPaaS.com product's SKU to the Heartland product's PublicId field. This is the product's public identifier in Heartland and the key used to match an existing Heartland product when the record is updated, so map it on every product. A product cannot be created or matched without it. |
Field | Heartland Cost (custom field) | Cost | Required. Writes the Heartland product's default cost from the iPaaS.com Heartland Cost custom field. Heartland requires a default cost on every product. The custom field must exist on the iPaaS.com Product collection to supply the value. When a product with options is transferred, this value is automatically copied to the grid-item cost field, so the same mapping serves both simple and grid products. |
Dynamic Formula |
| Price | Required. Writes the Heartland product's current price, using the iPaaS.com sale price when present and otherwise the iPaaS.com default price. Heartland requires a current price on every product. When a product with options is transferred, this value is automatically copied to the grid-item price field. |
Field | Name | Description | Required. Writes the Heartland product's description from the iPaaS.com product Name. Heartland requires a description on every product, so map this field so the product can be created. |
Dynamic Formula |
| OriginalPrice | Optional. Sets the Heartland product's original price to indicate whether the product is on sale. The formula compares the iPaaS.com default price and sale price: when both are present and equal the product is not on sale and no original price is written; when they differ the default price is written as the original price. If either price is missing, no value is written. When a product with options is transferred, this value is automatically copied to the grid-item original price field. |
Dynamic Formula |
| Depth | Recommended for simple products. Writes the Heartland product depth. Heartland does not accept a depth on grid (variant-tracked) items and will error if one is supplied, so the formula returns no value when the product's tracking method is Variant and otherwise writes the iPaaS.com depth. |
Dynamic Formula |
| Weight | Recommended for simple products. Writes the Heartland product weight. Heartland does not accept a weight on grid (variant-tracked) items and will error if one is supplied, so the formula returns no value when the product's tracking method is Variant and otherwise writes the iPaaS.com weight. |
Dynamic Formula |
| Width | Recommended for simple products. Writes the Heartland product width. Heartland does not accept a width on grid (variant-tracked) items and will error if one is supplied, so the formula returns no value when the product's tracking method is Variant and otherwise writes the iPaaS.com width. |
Dynamic Formula |
| Height | Recommended for simple products. Writes the Heartland product height. Heartland does not accept a height on grid (variant-tracked) items and will error if one is supplied, so the formula returns no value when the product's tracking method is Variant and otherwise writes the iPaaS.com height. |
Dynamic Formula |
| PrimaryBarcode | Recommended for simple products. Writes the Heartland product's primary barcode. Heartland does not accept a barcode on grid (variant-tracked) items, so the formula returns no value when the product's tracking method is Variant. For simple products it writes the iPaaS.com barcode, but first stops the transfer with an error when the barcode is longer than nine characters, because Heartland enforces an undocumented barcode length limit that would otherwise cause validation errors on later transfers. Adjust this mapping to fit your source data, or leave the barcode empty to accept the barcode Heartland generates automatically. Validate barcode handling in a staging environment before relying on it in production. |
Field | Heartland Long Description (custom field) | LongDescription | Optional. Writes the Heartland product's long description from the iPaaS.com Heartland Long Description custom field. The custom field must exist on the iPaaS.com Product collection to supply the value. |
Dynamic Formula |
| FinancialClassId | Optional. Writes the Heartland product's financial class from the iPaaS.com Heartland Financial Class custom field: the formula reads that custom field value and writes it when it is present, and otherwise writes no value. The custom field must exist on the iPaaS.com Product collection to supply the value. When a product with options is transferred, this value is automatically copied to the grid-item financial class field. |
Field | Heartland Primary Vendor Id (custom field) | PrimaryVendorId | Optional. Writes the Heartland product's primary vendor identifier from the iPaaS.com Heartland Primary Vendor Id custom field. The custom field must exist on the iPaaS.com Product collection to supply the value, and the vendor it references must exist in Heartland. When a product with options is transferred, this value is automatically copied to the grid-item primary vendor field. |
Field | Heartland Item Available Online (custom field) | AvailableOnline | Optional. Writes the Heartland product's online-availability flag from the iPaaS.com Heartland Item Available Online custom field. The custom field must exist on the iPaaS.com Product collection to supply the value. |
Dynamic Formula |
| TrackInventory | Optional. Sets the Heartland product's inventory-tracking flag for simple products only. Heartland does not accept this flag on grid (variant-tracked) items and will error if it is supplied, so the formula returns no value when the product's tracking method is Variant. For simple products it uses the iPaaS.com Heartland Track Inventory custom field value when present, and otherwise defaults to true so inventory is tracked. The custom field must exist on the iPaaS.com Product collection to supply a value other than the default. |
Dynamic Formula |
| Tags | Optional. Writes the Heartland product's tags from the iPaaS.com Heartland Tags custom field. The formula reads that custom field value and, when it is present, converts the comma-separated text into the list of tags Heartland expects; when it is empty, no value is written. The custom field must exist on the iPaaS.com Product collection to supply the value. |
Static | "true" | Active | Optional. Writes a static value of true to the Heartland product's Active field so products transferred from iPaaS.com are active in Heartland. Change this mapping if you need the active state to come from the iPaaS.com product instead of a fixed value; as shipped, a product deactivated by hand in Heartland is reactivated on the next transfer. |
Static | "product values" | Product Example (custom field) | Optional. Writes a value to the Product Example custom field on the Heartland product. This static value is a template placeholder that demonstrates the custom-field pattern — replace it with the value you want to write, or change the mapping to supply the value from an iPaaS.com custom field, and point it at the Heartland custom field you intend to populate. The Heartland custom field must be created in Heartland before its value can be written. |
Add/Update Heartland Product Inventory FROM iPaaS.com
This is a child collection of Add/Update Heartland Product FROM iPaaS.com. It does not transfer on its own and has no Manual Sync ID, webhook, or polling schedule of its own. It is a different collection from the standalone Add/Update Heartland Product Inventory Adjustment FROM iPaaS.com, which is documented separately.
Mapping Filter
var locationId = await GetExternalIdAsync(LocationId, "Location", SpaceportSystemId);
if(locationId != null && !string.IsNullOrEmpty(locationId)){
return Parent.TrackingMethod =="Product";
}
throw new Exception("Inventory location id is not found in Heartland");The filter resolves the iPaaS.com location on the inventory record to its linked Heartland location, then branches:
Location is linked: the filter returns the result of a second test — whether the parent product's tracking method is "Product". Inventory is processed for standard tracked products and skipped without error for variant-tracked products, whose inventory is handled by the separate variant inventory collection instead.
Location is not linked: the filter stops the transfer with the message "Inventory location id is not found in Heartland". The condition is reported in the iPaaS.com Dashboard error logs. Transfer and link your locations before adjusting inventory.
Description: Writes the product's inventory level from iPaaS.com to Heartland as an inventory adjustment at a specific location, as part of its parent's product transfer. Heartland does not accept a "set the quantity to this number" instruction, so the integration compares the iPaaS.com quantity against Heartland's current quantity available at the target location and creates an adjustment only for the difference; when the two already match, no adjustment is created.
Mapping Type | Source Field (iPaaS.com) | Destination Field (Heartland) | Description |
Dynamic Formula |
| LocationId | Required. Determines the Heartland location the adjustment applies to. The formula takes the iPaaS.com location on the inventory record, resolves it to that location's linked Heartland external identifier, and returns that identifier as the adjustment's location. The iPaaS.com location must already be linked to a Heartland location; if it is not, the collection filter prevents the transfer and the condition is reported as an error in the iPaaS.com Dashboard error logs. |
Dynamic Formula |
| AdjustmentReasonId | Required. Supplies the reason code for the Heartland inventory adjustment. Heartland requires a reason on every inventory adjustment. The default formula looks the reason up by the name Correction at transfer time and returns the matching Heartland reason code identifier. Because this lookup adds one extra request per adjustment, replace it with the fixed Heartland reason code identifier for the reason you want to use, which improves performance. The reason code identifier can be found in Heartland under Settings, Reason Codes, Inventory Adjustments by opening the reason you want and reading the identifier at the end of the resulting page address. This is a template placeholder — replace the Correction reason with the reason your adjustments should use. |
Field | QtyAvailable | Qty | Required. Supplies the inventory quantity from iPaaS.com that Heartland should be reconciled to at the target location. The integration compares this value against the quantity Heartland currently has available at the location and creates an adjustment only for the difference; if the iPaaS.com quantity already equals Heartland's quantity available, no adjustment is created. Only one item is adjusted per adjustment record. |
Static | "complete" | Status | Required. Sets the adjustment status to a fixed value of complete so the inventory adjustment is finalized in Heartland rather than left in an open state. Leave it as complete unless your Heartland workflow specifically requires adjustments to be created in a different status. |
Field | Cost | UnitCost | Optional. Carries the unit cost from the iPaaS.com inventory record onto the Heartland adjustment. If your Heartland configuration requires a cost on inventory adjustments, treat this as required and confirm the iPaaS.com source consistently provides a cost; validate the behavior in a staging environment before relying on it in production. |
Add/Update Heartland Product Variant FROM iPaaS.com
This is a child collection of Add/Update Heartland Product FROM iPaaS.com. It does not transfer on its own and has no Manual Sync ID, webhook, or polling schedule of its own.
Mapping Filter
This mapping collection does not have a mapping filter applied. All records routed to it are processed without additional filtering conditions.
Description: Writes the iPaaS.com product's variants to Heartland as grid items belonging to the grid product created or resolved by its parent collection. Its sync method is Add/Update: a variant is created on the Heartland grid product when it does not yet exist and updated in place when it does. The values written here are copied to the corresponding grid item version of each field when Heartland detects variants and options in the transfer.
Mapping Type | Source Field (iPaaS.com) | Destination Field (Heartland) | Description |
Field | Sku | PublicId | Required. Writes the iPaaS.com Sku to the Heartland variant's PublicId, the variant's public identifier in Heartland and the value used to match an existing grid item. The same Sku is also written to the variant Description. |
Field | Sku | Description | Required. Writes the iPaaS.com Sku to the Heartland variant Description, which identifies the variant in Heartland. The same Sku is also written to the variant PublicId. |
Field | SalePrice | Price | Recommended. Writes the variant's selling price to Heartland from the iPaaS.com Sale Price field so the variant is priced in Heartland. |
Field | DefaultPrice | OriginalPrice | Recommended. Writes the variant's original price to Heartland from the iPaaS.com Default Price field, alongside Price, so the variant's pricing is complete. |
Field | Heartland Cost (custom field) | Cost | Recommended. Writes the variant cost to Heartland from the iPaaS.com Heartland Cost custom field, so the variant's cost is recorded in Heartland. The custom field must exist on the iPaaS.com Product Variant collection to supply a value. |
Field | Depth | Depth | Recommended. Writes the variant depth to the Heartland variant from the iPaaS.com Depth field so the variant's shipping and fulfillment dimensions are complete. Optional if your Heartland configuration does not use depth. |
Field | Height | Height | Recommended. Writes the variant height to the Heartland variant from the iPaaS.com Height field so the variant's shipping and fulfillment dimensions are complete. Optional if your Heartland configuration does not use height. |
Field | Width | Width | Recommended. Writes the variant width to the Heartland variant from the iPaaS.com Width field so the variant's shipping and fulfillment dimensions are complete. Optional if your Heartland configuration does not use width. |
Field | Weight | Weight | Recommended. Writes the variant weight to the Heartland variant from the iPaaS.com Weight field so the variant's shipping and fulfillment dimensions are complete. Optional if your Heartland configuration does not use weight. |
Dynamic Formula |
| PrimaryBarcode | Optional. Sets the variant's primary barcode in Heartland. When the parent product is tracked at the variant level, no barcode is sent for the variant and Heartland manages it. Otherwise, when a barcode is present it is validated against Heartland's undocumented barcode length limit: a barcode longer than nine characters stops the transfer with an error, and a shorter barcode is written as-is. Adjust this mapping to change the barcode source, relax the length check, or send no barcode and accept the barcode Heartland generates. |
Field | Heartland Long Description (custom field) | LongDescription | Optional. Writes an extended description to the Heartland variant from the iPaaS.com Heartland Long Description custom field. The custom field must exist on the iPaaS.com Product Variant collection to supply a value. |
Dynamic Formula |
| FinancialClassId | Optional. Sets the variant's financial class in Heartland from the value held in the iPaaS.com Heartland Financial Class custom field. When that custom field holds a value it is written to the variant; when it is empty, no financial class is sent and Heartland leaves the value unset. The custom field must exist on the iPaaS.com Product Variant collection to supply a value. |
Field | Heartland Primary Vendor Id (custom field) | PrimaryVendorId | Optional. Writes the variant's primary vendor to Heartland from the iPaaS.com Heartland Primary Vendor Id custom field. The custom field must exist on the iPaaS.com Product Variant collection to supply a value, and the vendor it references must exist in Heartland. |
Field | Heartland Item Available Online (custom field) | AvailableOnline | Optional. Writes the online-availability flag to the Heartland variant from the iPaaS.com Heartland Item Available Online custom field. The custom field must exist on the iPaaS.com Product Variant collection to supply a value; when it holds no value, no online-availability flag is sent. |
Dynamic Formula |
| TrackInventory | Optional. Sets whether Heartland tracks inventory for the variant from the value held in the iPaaS.com Heartland Track Inventory custom field. When that custom field holds a value it is used; when it is empty, the variant is set to track inventory by default. The custom field must exist on the iPaaS.com Product Variant collection to supply a value. |
Dynamic Formula |
| Tags | Optional. Sets the variant's tags in Heartland from the value held in the iPaaS.com Heartland Tags custom field. When that custom field holds a comma-separated value the formula converts it into the tag-list format Heartland expects; when it is empty, no tags are sent. The custom field must exist on the iPaaS.com Product Variant collection to supply a value. |
Static | "true" | Active | Optional. Sets the Heartland variant to active by writing a fixed value of true, so variants created from iPaaS.com are active in Heartland. Adjust the mapping if you need variants to be created in a different state. |
Static | "variant values" | Product Example (custom field) | Optional. Demonstrates writing a fixed value to a Heartland custom field on the variant. This is a template placeholder — replace the fixed value with the value you want written, point the mapping at the Heartland custom field where it should be stored, or remove the mapping if it is not needed. The destination Heartland custom field must exist in Heartland before its value can be written. |
Add/Update Heartland Product Variant Inventory FROM iPaaS.com
This is a nested child collection of Add/Update Heartland Product Variant FROM iPaaS.com, which is itself a child of Add/Update Heartland Product FROM iPaaS.com. It sits two levels below the product parent and does not transfer on its own: it has no Manual Sync ID, webhook, or polling schedule of its own, and it runs once for each variant its parent writes.
It is a different collection from the standalone Add/Update Heartland Product Variant Inventory Adjustment FROM iPaaS.com, which performs the same kind of variant inventory adjustment as an independent transfer rather than riding with a product transfer, and which is documented in Heartland from iPaaS.com Inventory Adjustment Mapping Documentation. Use the standalone collection when you want to push a variant inventory change without transferring the whole product.
Mapping Filter
This mapping collection does not have a mapping filter applied. All records routed to it are processed without additional filtering conditions.
Description: Writes a variant's inventory level from iPaaS.com to Heartland as an inventory adjustment at a specific location, as part of its parent's variant transfer. As with product inventory, Heartland does not accept a "set the quantity to this number" instruction, so the integration compares the iPaaS.com quantity against the variant's current quantity available at the target Heartland location and creates an adjustment only for the difference; when the two already match, no adjustment is created, and each adjustment contains a single item.
Note one behavioral difference from the product-level inventory collection: that collection carries a filter that stops the transfer when the location is not linked to Heartland, whereas this collection has no filter. Here the location formula simply returns an empty value for an unlinked location and does not stop the transfer on its own. Confirm every location you intend to adjust is linked, and validate the behavior for unlinked locations in a staging environment before relying on it in production.
Mapping Type | Source Field (iPaaS.com) | Destination Field (Heartland) | Description |
Dynamic Formula |
| LocationId | Required. Identifies the Heartland location whose variant inventory is adjusted. The formula takes the iPaaS.com location on the record and resolves it to the linked Heartland location identifier, returning that value for the adjustment. The adjustment is applied to this location's quantity available. This mapping returns an empty value when the iPaaS.com location is not linked to a Heartland location, and unlike the product inventory collection it does not stop the transfer on its own; confirm every location you intend to adjust is linked, and validate the behavior for unlinked locations in a staging environment before relying on it in production. |
Dynamic Formula |
| AdjustmentReasonId | Required. Supplies the Heartland reason code for the inventory adjustment. Heartland requires a reason on every inventory adjustment. The formula looks up the reason named Correction and returns its Heartland reason-code identifier. Because the lookup calls Heartland once for every adjustment, it adds a request per adjustment; for better performance, replace it with a Static mapping set to the fixed reason-code identifier you want to use. You can find a reason-code identifier in Heartland under Settings, Reason Codes, Inventory Adjustments by opening the reason code and reading the identifier shown for it. Because each adjusting variant creates its own Heartland adjustment request, large inventory transfers can generate substantial request volume; stagger large jobs and prefer a fixed reason-code identifier. |
Field | QtyAvailable | Qty | Required. Supplies the inventory quantity iPaaS.com holds for the variant at the location. The integration compares this value with the variant's current Heartland quantity available and creates an adjustment for the difference; when the two already match, no adjustment is created. This value drives the adjustment. |
Static | "complete" | Status | Required. Sets the adjustment status to the fixed value complete so the adjustment is finalized when it is created in Heartland. Leave this value as shipped unless Heartland directs otherwise; validate in a staging environment before relying on it in production. |
Field | Cost | UnitCost | Optional. Records the unit cost on the inventory adjustment from the iPaaS.com variant cost. Map it when iPaaS.com carries an accurate cost for the variant so the adjustment reflects the correct value; validate in a staging environment before relying on it in production. |
Add/Update Heartland Product Variant Option FROM iPaaS.com
This is a nested child collection of Add/Update Heartland Product Variant FROM iPaaS.com, which is itself a child of Add/Update Heartland Product FROM iPaaS.com. It sits two levels below the product parent and does not transfer on its own: it has no Manual Sync ID, webhook, or polling schedule of its own, and it runs once for each variant its parent writes.
Mapping Filter
This mapping collection does not have a mapping filter applied. All records routed to it are processed without additional filtering conditions.
Description: Writes a variant's option selections to the Heartland variant created or updated by its parent collection. A variant option is the option name and value pair that distinguishes one variant of a grid product from another — an option named Size with a value of Large, or an option named Color with a value of Red. Its sync method is Add/Update: an option selection is created on the Heartland variant when it does not yet exist and updated in place when it does. The option name and value together define a single selection, so both mappings are needed for a selection to be complete.
Mapping Type | Source Field (iPaaS.com) | Destination Field (Heartland) | Description |
Field | OptionName | OptionName | Required. Writes the option name to the Heartland variant option from the iPaaS.com variant option name, identifying which option the selection applies to — for example, Size or Color. Supply an option name so Heartland can record the selection against the correct option on the variant. The option selections written here should stay within the options defined on the parent grid product, which Heartland limits to three. Heartland does not publish a field-level specification for the variant option record, so validate this in a staging environment before relying on it in production. |
Field | Value | Value | Required. Writes the selected value to the Heartland variant option from the iPaaS.com variant option value, recording the choice made for the option — for example, Large or Red. Supply a value so the option identifies the specific variant. The option name and value together define a single option selection, so map both. Heartland does not publish a field-level specification for the variant option record, so validate this in a staging environment before relying on it in production. |
Add/Update Heartland Product Option FROM iPaaS.com
This is a child collection of Add/Update Heartland Product FROM iPaaS.com. It does not transfer on its own and has no Manual Sync ID, webhook, or polling schedule of its own.
Mapping Filter
This mapping collection does not have a mapping filter applied. All records routed to it are processed without additional filtering conditions.
Description: Writes the iPaaS.com product's options to Heartland as pick-list item custom fields on the grid product created or resolved by its parent collection. Its sync method is Add/Update: when a matching item custom field already exists in Heartland it is reused, and when no match is found a new one is created. The individual allowed values that belong to each option are written by the nested Add/Update Heartland Product Option Value FROM iPaaS.com collection.
Mapping Type | Source Field (iPaaS.com) | Destination Field (Heartland) | Description |
Field | OptionName | Name | Required. Writes the iPaaS.com option name to the Heartland option's Name, the label shown for the option in Heartland. The same option name is also written to the option Key. Supply an option name so the option can be created and matched. |
Field | OptionName | Key | Required. Writes the iPaaS.com option name to the Heartland option's Key, which identifies the option in Heartland. The same option name is also written to the option Name. Because Heartland stores options as global item attributes, an option name that matches an existing item custom field reuses that field rather than creating a new one. |
Static | "item" | GroupId | Required. Writes the fixed value item to the Heartland option's GroupId, which identifies the option as an item custom field in Heartland. This is a fixed value the template supplies so options are created in the correct Heartland item custom field group; leave it in place unless Heartland directs otherwise. |
Static | "list" | ValidationType | Required. Writes the fixed value list to the Heartland option's ValidationType, which makes the option a pick list. Heartland supports only pick-list item custom fields for options and option values, so this value should be left in place. |
Add/Update Heartland Product Option Value FROM iPaaS.com
This is a nested child collection of Add/Update Heartland Product Option FROM iPaaS.com, which is itself a child of Add/Update Heartland Product FROM iPaaS.com. It sits two levels below the product parent and does not transfer on its own: it has no Manual Sync ID, webhook, or polling schedule of its own, and it runs once for each option its parent writes.
Mapping Filter
This mapping collection does not have a mapping filter applied. All records routed to it are processed without additional filtering conditions.
Description: Writes an option's allowed values into the Heartland pick-list item custom field that its parent option collection created or reused. A product option value is one of the choices belonging to an option — Small, Medium, and Large under a Size option, or Red and Blue under a Color option. Its sync method is Add/Update: when a matching allowed value already exists on the Heartland item custom field it is reused, and when no match is found the value is added to the list. Because Heartland stores options and their values globally as item attributes, existing values are never removed when a product is transferred.
Mapping Type | Source Field (iPaaS.com) | Destination Field (Heartland) | Description |
Field | Value | Value | Required. Writes the iPaaS.com product option value to the Heartland option's Value, adding it as an allowed value on the pick-list item custom field created or reused for the option by the parent option collection. This is the choice a shopper can select under the option, such as Small under a Size option or Red under a Color option. Supply a value so each choice can be created and matched. Because Heartland stores option values as global item attributes, a value that matches an existing allowed value reuses that entry rather than adding a duplicate, and values already present in Heartland are not removed when a product is transferred. Heartland does not publish a field-level specification for the item custom field allowed-value record, so this requirement should be validated in a staging environment before being relied on in production. |
Unmapped Field Overwrite Risk
This direction writes to Heartland, and the transfer sends a partial payload built from the mapped values. As a result, Heartland fields that these collections do not map are generally not cleared on update — the behavior is not the full-replace behavior that applies when records are written into iPaaS.com. Three qualifications matter, and all three are subscriber-visible.
Every mapped field is overwritten on update. The SKU, description, price, original price, cost, dimensions, barcode, long description, financial class, primary vendor, online-availability flag, tags, inventory-tracking flag, and the mapped Heartland custom field are replaced with the incoming iPaaS.com values each time Add/Update Heartland Product FROM iPaaS.com runs. The same applies to every field the variant and option child collections write. If Heartland is where any of those values is maintained, edits made there will be written over on the next outbound transfer. The Active flag deserves particular attention: it is a static true, so a product deactivated in Heartland is reactivated on the next transfer.
Heartland product fields these collections never write. The following Heartland product fields are not mapped by any collection in this family and are the ones to check first when validating update behavior:
the default lookup identifier
the sort key
the item type
the allow-fractional-quantity indicator
the prompt-for-price and prompt-for-description indicators
the use-dynamic-margin indicator and the dynamic margin value
the add-on item filter
the manufacturer part number
the primary image
the default price list and any custom prices
Custom prices in particular cannot be written from iPaaS.com at all; uploading custom prices or price lists to Heartland is not supported.
Variant update behavior is not fully specified. Heartland does not publish a field-level specification for the grid item record, so unmapped Heartland variant fields may be affected on update depending on how Heartland handles the grid item transfer. Do not assume unmapped variant values survive an update without confirming it.
The three nested collections carry a different shape of risk. Each writes only one or two fields, so there is no long list of unwritten fields to enumerate — and because Heartland publishes no field-level specification for these records, this article does not invent one. What matters for each is what happens to the Heartland record they touch:
Add/Update Heartland Product Variant Inventory FROM iPaaS.com: the risk here is not a cleared field but a replaced quantity. Each run moves the Heartland quantity available for that variant and location toward the value iPaaS.com supplies, so iPaaS.com effectively becomes the source of truth for variant inventory at every location it touches. A stale or incomplete iPaaS.com quantity will be written into Heartland as a real adjustment. Confirm iPaaS.com holds correct quantities before enabling this direction. The unlinked-location behavior compounds this: because this collection has no filter, an unlinked location yields an empty location value rather than a stopped transfer, so validate that path in staging.
Add/Update Heartland Product Variant Option FROM iPaaS.com: both mapped fields overwrite the current Heartland values when the option selection already exists on the variant. Because a selection is only meaningful as an option-and-value pair, changing one without the other in iPaaS.com produces a selection in Heartland that no longer describes the variant correctly.
Add/Update Heartland Product Option Value FROM iPaaS.com: the mapped value overwrites the matching Heartland entry when one exists. The more consequential behavior is what this collection cannot do: because Heartland stores option values globally, values are only ever added or reused, never removed. Withdrawing a value in iPaaS.com does not withdraw it in Heartland, so the Heartland allowed-value list drifts wider over time. That is the behavior to plan around before using the Heartland grid "Generate items" function.
For all three, the same qualification applies as for the variant record: Heartland's handling of fields these collections do not send has not been confirmed against a published specification, so treat it as unknown until you have observed it.
Preservation remedy. For each Heartland field you need to keep, add a Dynamic Formula mapping whose source is DestinationValue.[FieldName]. That reads the current Heartland value and writes it back, so the field is not cleared. Because this direction uses a single Add/Update collection rather than separate Add and Update collections, a preservation mapping applies to creation as well as update; confirm the value you write back is correct for a product being created for the first time.
Validate in staging. Partner-side clearing behavior should be confirmed rather than assumed. Before enabling outbound updates in production, run an update against a Heartland product that has values in the fields listed above and in any Heartland field you care about, and confirm afterward which values survived. Add preservation mappings for anything that did not.
Error Handling
Product could not be created in Heartland because a required value is missing: Heartland requires a public identifier, a description, a current price, and a default cost on every product. When any of these is absent in iPaaS.com or its mapping does not resolve, the Heartland product is not created or updated. Populate the missing value in iPaaS.com — including the Heartland Cost custom field, which supplies the default cost — and confirm the mapping resolves before retrying.
Barcode exceeded the allowable length: the barcode mappings stop the transfer with the message "Check with Heartland support for barcode requirements. This product or one of its variants has exceeded the allowable barcode length in Heartland." Shorten the barcode on the iPaaS.com product or variant, adjust the mapping to use a different barcode source or relax the check, or leave the barcode empty and accept the barcode Heartland generates.
Unable to link to an existing Heartland product by SKU: when an unlinked iPaaS.com product matches a Heartland product by SKU but the link cannot be written, the transfer stops with an error rather than continuing, because continuing could create a duplicate Heartland product. Retry the transfer; if it recurs, confirm that the Heartland product found by that SKU is the intended match.
Unable to link to an existing Heartland variant by SKU: the same applies to a variant matched inside a grid product. The transfer stops rather than risking a duplicate variant. Confirm the Heartland grid item found by that SKU is the intended match and retry.
Inventory location id is not found in Heartland: the inventory child collection stops when the iPaaS.com location on the inventory record is not linked to a Heartland location. Transfer and link the location, then transfer the product again.
Adjustment reason could not be resolved: Heartland requires a reason code on every inventory adjustment. When the reason named in the mapping does not exist in Heartland, no adjustment is created. Confirm the reason exists in Heartland under Settings, Reason Codes, Inventory Adjustments, or replace the by-name lookup with the fixed reason code identifier.
Grid field rejected by Heartland: Heartland errors if Depth, Width, Height, Weight, Track Inventory, or Primary Barcode is supplied on a grid item. The template mappings suppress these values for variant-tracked products; if you replace one of those mappings with an unconditional value, this error can appear. Restore the conditional behavior so the value is written for simple products only.
Option limit exceeded: Heartland supports a maximum of three options on a grid product. A product carrying more than three options cannot transfer as a grid product. Reduce the number of options on the iPaaS.com product, or enable and adjust the commented-out branch in the parent mapping filter so such products are stopped with a clear message before the transfer is attempted.
Custom field value not stored: when the destination Heartland custom field has not been created in Heartland, the product still transfers and the remaining fields are written; only that custom value is not stored. Create the custom field in Heartland and transfer again to populate it.
Custom field value not supplied: when a source iPaaS.com custom field does not exist on the Product or Product Variant collection, the corresponding Heartland value is simply not sent. Create the custom field in iPaaS.com and populate it, then transfer again.
Heartland temporarily unavailable: if the Heartland API cannot be reached when a transfer is triggered, the transfer fails, including its inventory, variants, and options. The error appears in the iPaaS.com Dashboard error logs, and the record can be retried through a new transfer or Manual Sync of the product.
Testing & Validation
Test Scenarios
New simple product created — create an iPaaS.com product with a SKU, a name, a price, a cost, and no options, transfer it, and confirm a new simple product is created in Heartland with the matching values and that the Heartland identifier plus its simple suffix is saved as the external-id link.
New grid product created — create an iPaaS.com product that carries options and variants, transfer it, and confirm a grid product is created in Heartland with its options and variants, and that the external-id link carries the grid suffix.
Existing product updated — change the name on a linked iPaaS.com product, transfer it again, and confirm the same Heartland product is updated and no second product is created.
SKU match prevents a duplicate — create a product in Heartland, then create an unlinked iPaaS.com product with the same SKU, transfer it, and confirm the two are linked and the existing Heartland product is updated rather than duplicated.
Variant matched inside a grid — add a variant in iPaaS.com whose SKU already exists as an item on the linked Heartland grid product, transfer the product, and confirm the variant is linked to the existing grid item rather than duplicated.
Missing required value rejected — transfer an iPaaS.com product with no cost supplied by the Heartland Cost custom field and confirm the transfer fails with a Heartland validation error and no product is created.
Barcode too long rejected — transfer a product whose barcode is longer than nine characters and confirm the transfer stops with the barcode error and the message appears in the iPaaS.com Dashboard error logs.
Dimensions suppressed on a grid product — transfer a variant-tracked product with dimensions populated in iPaaS.com and confirm the transfer succeeds and no dimension values are sent to the grid item.
Dimensions written on a simple product — transfer a simple product with dimensions populated and confirm depth, width, height, and weight are written to the Heartland product.
Inventory adjustment created — transfer a simple product whose iPaaS.com quantity differs from the Heartland quantity available at a linked location, and confirm one adjustment is created for the difference with the expected reason code and a complete status.
No adjustment when quantities already match — transfer the same product again without changing the quantity and confirm no new adjustment is created.
Unlinked location blocks inventory — transfer a product whose inventory references an iPaaS.com location that is not linked to Heartland, and confirm the location error is reported.
Variant-tracked product skips the inventory child — transfer a grid product and confirm the product inventory child collection creates no adjustment, and that variant inventory is handled by the nested variant inventory collection instead.
Variant inventory adjustment created — transfer a grid product whose variant quantity in iPaaS.com differs from the Heartland quantity available at a linked location, and confirm one adjustment is created for that variant for the difference, with the expected reason code and a complete status.
No variant adjustment when quantities already match — transfer the same grid product again without changing quantities and confirm no new variant adjustments are created.
Unlinked location on variant inventory — transfer a grid product whose variant inventory references an iPaaS.com location that is not linked to Heartland, and confirm what actually happens. Unlike the product inventory collection, this one has no filter to stop the transfer, so record whether the adjustment is skipped, fails, or is written against an empty location before relying on the behavior.
Variant inventory request volume — transfer a grid product with many variants across several locations and confirm the transfer completes, then replace the by-name reason lookup with a fixed reason-code identifier and confirm the request volume drops.
Variant option selections written — transfer a grid product and confirm each Heartland grid item carries the expected option name and value pairs that distinguish it from the other variants.
Variant option selection updated — change a variant's option value in iPaaS.com, transfer again, and confirm the Heartland variant's selection is updated in place rather than duplicated.
Options created as pick lists — transfer a product with options and confirm each option appears in Heartland as a pick-list item custom field with the expected name.
Option values populate the pick list — transfer a product whose options carry several values each, and confirm every value appears as an allowed value on the matching Heartland pick-list item custom field.
Option value reused, not duplicated — transfer a product whose option value already exists as an allowed value in Heartland, and confirm the existing entry is reused rather than a second identical entry being added.
Option values persist — remove an option value from an iPaaS.com product, transfer again, and confirm the value remains in Heartland's global allowed list, so the behavior is understood before using the Heartland grid "Generate items" function.
Three-option limit — transfer a product carrying four options and confirm the behavior you expect, then enable and adjust the commented-out filter branch if you prefer the transfer to be stopped with a clear message.
Unmapped Heartland product fields — set the default lookup identifier, sort key, item type, prompt-for-price indicator, and add-on item filter on a Heartland product, run an update from iPaaS.com, and confirm which of them survive. Add DestinationValue preservation mappings for any that were cleared.
Unmapped Heartland variant fields — repeat the previous test against a grid item, because variant update behavior is not fully specified by Heartland.
Preservation mapping works — add a Dynamic Formula mapping sourced from DestinationValue for a field you need to keep, run an update, and confirm the Heartland value is unchanged.
Active flag behavior — deactivate a product in Heartland, transfer it again from iPaaS.com, and confirm it is reactivated by the static Active mapping. Change that mapping if this is not what you want.
Custom field written — create the destination custom field in Heartland, replace the placeholder static mapping with a real value, transfer a product, and confirm the value is stored on the Heartland product.
Custom field absent — with the Heartland custom field not created, transfer a product and confirm the remaining fields are written and the transfer is not blocked.
Custom field source absent — with the Heartland Long Description custom field not created in iPaaS.com, transfer a product and confirm the long description is simply not sent and the transfer succeeds.
Manual Sync by ID — enter a known iPaaS.com product ID in the iPaaS.com input field on the Manual Sync page and confirm that product, its inventory, its variants, and its options transfer.
Validation Checklist
Every transferred product has a unique SKU, a name, a price, and a cost available in iPaaS.com.
Each transferred product is linked by the Heartland product identifier with the correct grid or simple suffix, and re-transfers update rather than duplicate.
Variants are linked individually and re-transfers update the same grid items.
Barcodes on iPaaS.com products and variants are within Heartland's length limit, or the barcode mappings have been adjusted to suit your data.
Dimension, track-inventory, and barcode values are suppressed for variant-tracked products and written for simple products.
Every iPaaS.com location referenced by product inventory or variant inventory is linked to a Heartland location before inventory runs, and the unlinked-location path has been validated for both collections.
The adjustment reason used by both the product inventory and variant inventory collections exists in Heartland, and the by-name lookup has been replaced with a fixed reason code identifier in each.
Variant option selections arrive as complete option-and-value pairs, and each grid item is distinguished by the expected selections.
Option values appear on the correct Heartland pick list, and the team understands that values are never removed from Heartland by a transfer.
Products carry no more than three options if they are to transfer as grid products.
The named Heartland custom fields exist on the iPaaS.com Product and Product Variant collections.
Any Heartland custom field used as a mapping destination exists in Heartland before the transfer runs.
The placeholder Product Example static mappings have been replaced or removed in the parent and variant collections.
The unmapped Heartland product and variant fields listed under Unmapped Field Overwrite Risk have been checked after an update in staging, and preservation mappings added for any value that was cleared.
Heartland fields your business maintains in Heartland are either unmapped or preserved with a DestinationValue mapping.
Additional Notes
One Add/Update collection handles both creation and update in this direction. Subscribers do not select between an add path and an update path; the integration decides based on whether the iPaaS.com product is linked to Heartland or matches an existing Heartland product by SKU.
Whether a product becomes a grid product or a simple product in Heartland is decided by whether it carries options in iPaaS.com, not by a subscription setting. Adjust the product option child collection filters if you need products with options to transfer as simple products.
iPaaS.com is the source of truth for the fields listed under Mappings. Editing those values directly in Heartland will be written over on the next transfer of that product.
Inventory reaches Heartland as a difference-based adjustment, not as an absolute count. This collection reconciles Heartland's quantity available toward the iPaaS.com value; it does not write inventory history.
Neither inventory collection described here is part of the standalone inventory adjustment family. Use Add/Update Heartland Product Inventory Adjustment FROM iPaaS.com or Add/Update Heartland Product Variant Inventory Adjustment FROM iPaaS.com when you want to adjust inventory without transferring the entire product. The presence of the word "Adjustment" in the collection name is what tells the two families apart.
The two inventory collections in this article do not behave identically when a location is unlinked. The product-level collection stops the transfer through its filter; the variant-level collection has no filter and resolves the location to an empty value instead. Link your locations first and validate the unlinked path in staging.
Because Heartland saves options and option values globally, option values added by earlier transfers remain in Heartland even when they no longer apply to a product.
Deleting a product, variant, option, or option value in iPaaS.com has no effect in Heartland. Removals must be made in Heartland directly.
Outbound transfers are triggered from iPaaS.com when the subscription is enabled; there may be a delay between a change in iPaaS.com and its appearance in Heartland.
Related Documents
Setup & Reference
Mapping Documentation