Summary
This is an outbound area (iPaaS.com → Heartland). iPaaS.com is the source, and Heartland is written to. Two standalone mapping collections write inventory adjustments to Heartland: one for simple (non-variant) products, and one for product variants.
An inventory adjustment is not a full inventory sync. Rather than replacing Heartland's stock record, the integration reads the quantity Heartland currently holds for the item at the target location, compares it with the quantity supplied by iPaaS.com, and creates a Heartland inventory adjustment for the difference between the two. If the two quantities already match, no adjustment is created. The effect is that Heartland's on-hand quantity for that item and location is brought in line with the quantity iPaaS.com supplied, while the rest of the Heartland item record is untouched.
The split between the two collections follows Heartland's product model. Add/Update Heartland Product Inventory Adjustment FROM iPaaS.com adjusts stock for simple products, identified by the linked Heartland item. Add/Update Heartland Product Variant Inventory Adjustment FROM iPaaS.com adjusts stock for individual variants of a grid product, identified by the linked Heartland variant. Use the one that matches the kind of product whose stock you are correcting; they are not interchangeable.
Both collections are standalone: they run independently of the full Add/Update Heartland Product FROM iPaaS.com transfer, so stock levels can be kept in step without re-sending complete product records. The full product transfer carries its own inventory child collections for adjustments that accompany a product transfer.
Heartland requires a reason on every inventory adjustment, so both collections supply an adjustment reason and mark the resulting adjustment complete.
ID Format
Manual Sync ID Format
On the iPaaS.com Manual Sync page, enter the iPaaS.com record identifier — not a Heartland identifier — because this direction is triggered from iPaaS.com.
Add/Update Heartland Product Inventory Adjustment FROM iPaaS.com: enter the iPaaS.com Product Inventory record's internal ID.
Add/Update Heartland Product Variant Inventory Adjustment FROM iPaaS.com: enter the iPaaS.com Product Variant Inventory record's internal ID.
In both cases the referenced product (or variant) and its location must already be linked between iPaaS.com and Heartland, or the adjustment cannot resolve its target.
External ID Format
These collections write an adjustment event rather than creating a new linked catalog record, so neither establishes a new product or location link of its own. They rely on links established by earlier transfers: the Heartland item is resolved from the linked iPaaS.com product or variant, and the Heartland location is resolved from the linked iPaaS.com location.
The inventory position the adjustment acts on is identified by the combination of the Heartland item ID and the Heartland location ID — for example, an item ID of 123456 at location 7 is tracked as 123456|7. That pairing is what identifies the inventory record on either side of the transfer; it is not a configurable mapping row.
For simple products, the integration strips the product-type suffix the integration appends to product external IDs — the _SIMPLE suffix used for simple products and the _GRID suffix used for grid products — so the value written to Heartland is the plain item ID.
Deleted Record Support
Deleting is not supported by either collection. Removing or zeroing an inventory record in iPaaS.com does not delete anything in Heartland. The only write these collections perform is the creation of an inventory adjustment; there is no delete path.
To reduce stock in Heartland, supply a lower quantity from iPaaS.com — the integration will create a negative adjustment for the difference. To remove an item from Heartland entirely, do so directly in Heartland.
Custom Field Support
Neither collection maps custom fields. All six mappings on each collection write standard Heartland inventory adjustment fields. If you need additional values carried onto a Heartland adjustment, they are not covered by these collections.
Mapping Collection Status
Status: Enabled. Both collections are enabled in the template.
Trigger Events: Outbound transfers are triggered from iPaaS.com. When the subscription is configured and the outbound data flow to Heartland is enabled, a change to an iPaaS.com Product Inventory or Product Variant Inventory record is transferred to Heartland as an adjustment. No automatic transfers occur until the subscription is configured and enabled. A specific record can also be transferred on demand at any time from the iPaaS.com Manual Sync page.
Duplicate or Conflicting Mappings
Several mapping collections operate on Heartland inventory. Review them together before enabling outbound adjustments.
Add/Update Heartland Product Inventory Adjustment FROM iPaaS.com and Add/Update Heartland Product Variant Inventory Adjustment FROM iPaaS.com: the two collections documented here. They cover different product types — simple products and variants respectively — and do not overlap with one another.
Add/Update Heartland Product FROM iPaaS.com: writes the full product to Heartland and carries its own inventory child collections, which can also create inventory adjustments during a product transfer. A product transfer and a standalone adjustment can both act on the same item.
Add Heartland Product Inventory Standalone TO iPaaS.com, Update Heartland Product Inventory Standalone TO iPaaS.com, and the related Product Variant Inventory TO iPaaS.com collections: read Heartland inventory levels into iPaaS.com in the opposite direction.
Important: because these collections make Heartland's on-hand quantity match the quantity supplied by iPaaS.com, decide which system is the source of truth for inventory before running them alongside the inbound inventory collections. If both directions are active with the default mappings, quantities may be reconciled back and forth between the systems. It is not recommended to run every template direction bidirectionally.
Because each is a single Add/Update collection, there is no separate Add collection that could compete with an Update collection for the same inventory record.
Collision Handling
This integration does not use iPaaS.com collision handling for inventory adjustments. The adjustment target is resolved from the existing product, variant, and location links rather than by a matching or recovery step, so there is no collision handling to configure.
Supported Child Collections
None. Both collections are standalone and have no child collections. Each transferred record produces at most one Heartland inventory adjustment, containing a single item.
System Caveats
Heartland Caveats
Heartland requires a reason on every inventory adjustment. Without a valid reason the adjustment cannot be created.
Adjustments created from iPaaS.com contain only one item each.
An adjustment is location-specific. Heartland tracks stock per location, so the target location must be resolvable for the adjustment to be created.
Resolving the adjustment reason by name adds one extra Heartland request per adjustment. Mapping a specific Heartland reason code identifier instead avoids that request. Reason code identifiers are found in Heartland under Settings, then Reason Codes, then Inventory Adjustments; open the reason you want to use and read its identifier from the resulting page.
iPaaS.com Caveats
Manual Sync for this outbound direction uses the iPaaS.com record's internal ID, not a Heartland identifier.
The quantity and cost written to Heartland come from the iPaaS.com inventory record — its quantity available and its cost. Confirm the iPaaS.com record carries accurate values before transferring.
The product or variant and the location on the iPaaS.com record must already be linked to their Heartland counterparts. If either is not linked, the integration cannot resolve the Heartland target and the adjustment does not complete.
Integration-Specific Caveats
Adjustments are difference-only. The integration reads Heartland's current quantity available for the item at the location and creates an adjustment for the difference. When the supplied quantity already matches, no adjustment is created, which makes repeated transfers of an unchanged quantity safe.
The write is an adjustment, not a full record replacement. The integration sends only the adjustment values listed under Mappings; it does not send a complete item record, so other Heartland item fields are not part of the payload.
Adjustments are created complete. The status mapping finalizes the adjustment in Heartland at the time it is created, so there is no draft adjustment left open for review.
These collections do not automatically transfer prerequisites. The product, variant, and location links they depend on are not created on the fly during an adjustment transfer — establish them by transferring products, variants, and locations first.
Transfers are event-driven from iPaaS.com rather than scheduled by Heartland, so allow for normal transfer latency between a change in iPaaS.com and the adjustment's appearance in Heartland.
Setup Requirements
Heartland Configuration
Create the inventory adjustment reason codes you intend to use under Settings, then Reason Codes, then Inventory Adjustments. The template resolves a reason named "Correction"; either create a reason with that name or change the mapping.
Confirm the Heartland locations whose stock you intend to adjust exist and are active.
Confirm the items or variants whose stock you intend to adjust exist in Heartland.
iPaaS.com Configuration
Transfer products, variants, and locations before enabling adjustments, so the links the adjustment depends on are in place.
Review the adjustment reason mapping on both collections and replace the name lookup with a specific Heartland reason code identifier for better performance.
Confirm the quantity available and cost on the iPaaS.com inventory records are accurate, since those values drive the adjustment.
Enable the outbound data flow on the subscription so automatic transfers can run, or use Manual Sync to transfer specific records on demand.
Decide which system is authoritative for inventory before enabling these collections alongside the inbound inventory collections.
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 (simple product inventory):
A Product Inventory record changes in iPaaS.com and the outbound data flow to Heartland is enabled.
The integration resolves the Heartland item from the linked iPaaS.com product, removing the product-type suffix so the plain Heartland item ID is used.
It resolves the Heartland location from the linked iPaaS.com location.
It reads the item's current quantity available at that location in Heartland.
It compares that quantity with the quantity supplied by iPaaS.com and calculates the difference.
When the two differ, it creates a Heartland inventory adjustment for the difference, using the configured reason, adds a single line for the item at the calculated difference and the supplied unit cost, and marks the adjustment complete. When the two match, no adjustment is created and the existing Heartland inventory position is returned unchanged.
Automatic outbound transfer (product variant inventory):
A Product Variant Inventory record changes in iPaaS.com and the outbound data flow to Heartland is enabled.
The integration resolves the Heartland variant from the linked iPaaS.com variant and the Heartland location from the linked iPaaS.com location.
It reads the variant's current quantity available at that location in Heartland.
It compares that quantity with the quantity supplied by iPaaS.com and calculates the difference.
When the two differ, it creates a Heartland inventory adjustment for the difference, using the configured reason, adds a single line for the variant, and marks the adjustment complete. When the two match, no adjustment is created.
Manual Sync:
The iPaaS.com Product Inventory or Product Variant Inventory record's internal ID is entered on the Manual Sync page.
The integration transfers that single record through the same resolve, compare, and adjust path described above.
Both trigger paths converge on the same logic, so the resulting Heartland adjustment is identical regardless of how the transfer was triggered.
Mappings
Add/Update Heartland Product Inventory Adjustment FROM iPaaS.com
Mapping Filter
This mapping collection does not have a mapping filter applied. All iPaaS.com Product Inventory records received through automatic transfers or Manual Sync are processed without additional filtering conditions.
Description: Creates a Heartland inventory adjustment for a simple (non-variant) product, correcting the on-hand quantity for the linked Heartland item at the linked Heartland location to match the quantity supplied by iPaaS.com. An adjustment is created only when the supplied quantity differs from Heartland's current quantity available.
Mapping Type | Source Field (iPaaS.com) | Destination Field (Heartland) | Description |
Dynamic Formula |
| ItemId | Required. Identifies the Heartland item the adjustment applies to. The formula looks up the Heartland external product ID for the parent iPaaS.com product and removes the product-type suffix the integration appends to product external IDs — the |
Dynamic Formula |
| AdjustmentReasonId | Required. Supplies the Heartland reason code for the adjustment. Heartland requires a reason on every inventory adjustment. The reason name "Correction" is a template example — replace it with the reason you use, or better, replace this mapping with a specific Heartland reason code identifier. The name lookup adds one extra Heartland request per adjustment, so mapping a fixed identifier is highly recommended for performance. Reason code identifiers are found in Heartland under Settings, then Reason Codes, then Inventory Adjustments. |
Field | QtyAvailable | Qty | Required. Supplies the target quantity that iPaaS.com expects Heartland to hold for the item at the location. This number is not written directly; the integration compares it with Heartland's current quantity available and creates an adjustment for the difference. When the supplied quantity already matches, no adjustment is created. |
Dynamic Formula |
| LocationId | Required. Identifies the Heartland location whose on-hand quantity the adjustment changes. The formula looks up the Heartland external location ID for the iPaaS.com location on the inventory record. An adjustment is location-specific, so the location must be linked to Heartland for the transfer to resolve its target. |
Static | "complete" | Status | Required. Sets the adjustment's status so it is finalized in Heartland when it is created. This is a fixed status value, not an editable placeholder — leave it as complete unless you have a specific reason to create adjustments in a different state. |
Field | Cost | UnitCost | Recommended. Writes the unit cost recorded on the Heartland adjustment from the iPaaS.com inventory record's cost, so the adjustment carries an accurate cost. If no cost is supplied by iPaaS.com, no cost is written on the adjustment. |
Add/Update Heartland Product Variant Inventory Adjustment FROM iPaaS.com
Mapping Filter
This mapping collection does not have a mapping filter applied. All iPaaS.com Product Variant Inventory records received through automatic transfers or Manual Sync are processed without additional filtering conditions.
Description: Creates a Heartland inventory adjustment for a single product variant, correcting the on-hand quantity for the linked Heartland variant at the linked Heartland location to match the quantity supplied by iPaaS.com. Only one variant is adjusted per adjustment, and an adjustment is created only when the supplied quantity differs from Heartland's current quantity available.
Mapping Type | Source Field (iPaaS.com) | Destination Field (Heartland) | Description |
Dynamic Formula |
| AdjustmentReasonId | Required. Supplies the Heartland adjustment reason. Heartland requires a reason on every inventory adjustment. The formula looks up the reason by its display name, "Correction", and returns the matching Heartland reason code identifier. The name lookup adds one extra Heartland request per adjustment; for better performance, replace this mapping with the specific Heartland reason code identifier as a static value. Reason code identifiers are found in Heartland under Settings, then Reason Codes, then Inventory Adjustments. |
Dynamic Formula |
| LocationId | Required. Identifies the Heartland location where the variant quantity is adjusted. The formula takes the iPaaS.com location on the record and returns its linked Heartland location identifier. The location must already be linked between iPaaS.com and Heartland; if it is not, the integration cannot resolve the Heartland location and the adjustment does not complete. |
Dynamic Formula |
| ItemId | Required. Identifies the Heartland product variant the adjustment applies to. The formula takes the parent product variant on the iPaaS.com record and returns its linked Heartland identifier. The variant must already be linked between iPaaS.com and Heartland; if it is not, the integration cannot resolve the Heartland variant and the adjustment does not complete. |
Field | QtyAvailable | Qty | Required. Provides the target quantity available for the variant at the intended location. The integration compares this value with the variant's current quantity available in Heartland and creates an adjustment only for the difference. When the provided quantity already matches, no adjustment is created. |
Static | "complete" | Status | Required. Marks the Heartland inventory adjustment as finalized when it is created. The value complete is a fixed Heartland status and should not be changed. |
Field | Cost | UnitCost | Recommended. Records the unit cost on the Heartland inventory adjustment, mapped from the iPaaS.com variant cost. Map it when accurate cost should be carried onto the adjustment. When the iPaaS.com record has no cost, no unit cost is written. |
Unmapped Field Overwrite Risk
These collections write an inventory adjustment; they do not replace a Heartland item, variant, or product record. Only the six values listed for each collection are sent, and the request is a partial payload — values the integration does not supply are omitted from it rather than sent as empty. As a result, unmapped fields on the Heartland item or variant are not cleared by an adjustment transfer.
Two points still deserve attention:
The quantity is the point of the transfer. The one value these collections deliberately change in Heartland is the on-hand quantity for the item or variant at the target location. That is not an accidental overwrite, but it is authoritative: the quantity supplied by iPaaS.com becomes the quantity Heartland holds. If Heartland stock is also counted or edited directly, or maintained by another collection, adjustments from iPaaS.com will repeatedly correct it. Confirm the source of truth for inventory before enabling automatic transfers.
Partner-side clearing behavior is worth confirming. Because there is no separately published Heartland field specification for inventory adjustments available to this integration, subscribers should validate in a staging environment that no other Heartland field is affected by an adjustment before relying on this behavior in production.
Error Handling
Product or variant not linked: when the iPaaS.com product or variant has no Heartland link, the formula produces no item identifier and the adjustment cannot identify its target, so the transfer fails and no adjustment is created. Transfer the product or variant to Heartland first, then retry.
Location not linked: when the iPaaS.com location has no Heartland link, the adjustment cannot resolve the location whose stock should change and the transfer fails. Transfer the location to Heartland first, then retry.
Adjustment reason not found: when the reason name in the mapping does not match an active Heartland inventory adjustment reason, no reason code is resolved. Heartland requires a reason, so the adjustment is not created. Create a matching reason in Heartland, correct the name in the mapping, or map a specific reason code identifier.
Quantity already matches: when the quantity supplied by iPaaS.com equals Heartland's current quantity available for the item at the location, no adjustment is created. This is expected behavior, not an error; the existing Heartland inventory position is returned unchanged.
Inventory position not found in Heartland: when Heartland holds no inventory record for the item at the requested location, the transfer cannot complete the comparison and fails. Confirm the item exists in Heartland and is stocked at that location.
Heartland API unavailable: if the Heartland API is temporarily unavailable when a transfer is triggered, the transfer fails. The error appears in the iPaaS.com Dashboard error logs, and the record can be retried through Manual Sync or a subsequent outbound transfer.
Testing & Validation
Test Scenarios
Increase for a simple product — set a higher quantity available on an iPaaS.com Product Inventory record for a linked simple product and location, transfer it, and confirm a Heartland inventory adjustment is created for the difference and that Heartland's on-hand quantity now matches the supplied quantity.
Decrease for a simple product — set a lower quantity, transfer, and confirm a negative adjustment is created and Heartland's on-hand quantity is reduced to the supplied value.
No difference, no adjustment — transfer an inventory record whose quantity already matches Heartland's quantity available and confirm that no new Heartland adjustment is created.
Repeat transfer is safe — transfer the same unchanged record twice and confirm only the first transfer, if any, produced an adjustment.
Variant adjustment — repeat scenarios 1 through 3 against a linked product variant through the variant collection and confirm the adjustment applies to that variant only, leaving sibling variants untouched.
Correct collection per product type — confirm simple-product inventory routes through the Product Inventory Adjustment collection and variant inventory through the Product Variant Inventory Adjustment collection.
Location specificity — with the same item stocked at two Heartland locations, transfer an adjustment for one location and confirm the other location's quantity is unchanged.
Unit cost carried — transfer a record with a cost value and confirm the resulting Heartland adjustment line records that unit cost; transfer one without a cost and confirm the adjustment is still created.
Adjustment completed — confirm the resulting Heartland adjustment is in a completed state rather than left open.
Reason code applied — confirm the adjustment carries the expected Heartland reason, then replace the reason mapping with a specific reason code identifier and confirm the adjustment still carries the correct reason.
Unlinked product — transfer inventory for a product that is not linked to Heartland and confirm the transfer fails with an error in the Dashboard error logs and no adjustment is created.
Unlinked location — transfer inventory for a location that is not linked to Heartland and confirm the same.
Manual Sync by ID — enter an iPaaS.com Product Inventory record's internal ID on the Manual Sync page and confirm that specific record transfers and produces the expected adjustment.
Unmapped fields preserved — record the Heartland item's other field values before and after an adjustment and confirm none of them changed.
Validation Checklist
Products, variants, and locations are linked between iPaaS.com and Heartland before adjustments are enabled.
Every transferred record resolves an item identifier, a location identifier, and a reason code.
Adjustments are created only when the supplied quantity differs from Heartland's current quantity available.
Each adjustment contains a single item and is marked complete.
Heartland's on-hand quantity for the item or variant at the target location matches the quantity supplied by iPaaS.com after transfer.
Simple-product inventory and variant inventory are routed through their respective collections.
Unit cost, where supplied, is recorded on the adjustment line.
Fields on the Heartland item or variant that are not listed under Mappings are unchanged after a transfer.
The direction of authority for inventory has been decided, and the inbound and outbound inventory collections are not fighting over the same quantities.
Additional Notes
An adjustment is a correction, not a full inventory sync. It changes the on-hand quantity for one item at one location and leaves the rest of the Heartland record alone. Use the full product transfer when you need the whole product record written to Heartland.
The product-level and variant-level collections exist because Heartland tracks stock against the item that is actually sold. For a grid product that is the individual variant, not the parent product, so variant stock must go through the variant collection.
Because a single Add/Update collection serves each product type, no configuration choice is needed between an Add collection and an Update collection.
Replacing the adjustment reason name lookup with a specific Heartland reason code identifier removes one Heartland request per adjustment. On subscriptions that transfer inventory frequently, this is the single most effective performance change available on these collections.
These collections make iPaaS.com authoritative for the quantities they transfer. Stock counted directly in Heartland will be corrected back to the iPaaS.com value on the next transfer of that record.
Related Documents
Setup & Reference