Summary
Heartland shipping methods are transferred into iPaaS.com as Shipping Method records. A single Add/Update collection handles both creating new iPaaS.com shipping methods and updating those already linked to Heartland, so the same flow covers a shipping method's whole life cycle. Alongside the name and service description, the integration stores two Heartland-specific values — the shipping amount and the Heartland income account identifier — on the iPaaS.com shipping method as custom fields.
This is an inbound-only area (Heartland → iPaaS.com). There is no opposite-direction collection that writes shipping methods back to Heartland.
ID Format
Manual Sync ID Format
On the iPaaS.com Manual Sync page, enter the Heartland shipping method ID — for example, 100005.
External ID Format
After a successful transfer, the Heartland shipping method ID is saved as the external-id link between the two systems (for example, 100005). Subsequent transfers update the same iPaaS.com Shipping Method record rather than creating a duplicate. Whether an incoming shipping method is created or updated in iPaaS.com is determined by whether it is already linked by an external id, not by which event triggered the transfer.
Deleted Record Support
Deleting a shipping method is not supported in this direction. The integration creates and updates iPaaS.com Shipping Method records only — removing a shipping method in Heartland does not delete or deactivate the linked iPaaS.com Shipping Method record. Shipping methods that are no longer in use should be managed directly in iPaaS.com.
Custom Field Support
Two Heartland values are stored on the iPaaS.com Shipping Method as custom fields:
Heartland Amount: the shipping amount held on the Heartland shipping method.
Heartland Income Amount ID: the Heartland income account identifier.
Each requires a matching iPaaS.com subscription custom field on the Shipping Method collection before its value is stored. If the custom field does not exist, the shipping method still transfers and the remaining fields are written; only the custom value is not retained. Create these custom fields during setup if you intend to use these values.
A Heartland custom field must be created in Heartland before it becomes visible on the Heartland website and available to mappings.
Mapping Collection Status
Status: Enabled.
Trigger Events: Automatic transfers run on a schedule through polling. Heartland's webhook format is not compatible with iPaaS.com instant webhooks, so shipping methods arrive through polling rather than instant push notifications. Polling does not run until the subscription is configured and enabled. All eligible shipping methods can also be transferred immediately from the Initialize Data section of the Heartland subscription in iPaaS.com, and individual shipping methods can be transferred at any time from the Manual Sync page.
Duplicate or Conflicting Mappings
No other mapping collection operates on Heartland shipping methods. This is the only Shipping Method collection in the integration, and there is no opposing iPaaS.com → Heartland Shipping Method collection, so there is no two-direction overwrite concern.
Because a single Add/Update collection serves both new and existing records, there is no separate Add collection that could compete with an Update collection for the same shipping method.
Collision Handling
This integration does not use iPaaS.com collision handling for shipping methods. Whether an incoming shipping method is created or updated is determined solely by whether it is already linked by an external id; there is no collision recovery step to configure.
Supported Child Collections
None. This is a standalone collection with no dependent child collections.
System Caveats
Heartland Caveats
Heartland requires both a Name and an Amount to create a shipping method. Supply both through the mappings.
A Heartland custom field must be created in Heartland before it is visible on the Heartland website and available to mappings.
Heartland's webhook format is not compatible with iPaaS.com instant webhooks, so shipping methods are picked up by polling rather than pushed instantly. Expect a delay between a change in Heartland and its arrival in iPaaS.com, bounded by the polling schedule.
iPaaS.com Caveats
The Name field is required on every iPaaS.com Shipping Method record. Without it the shipping method is not created.
The Description field is optional in iPaaS.com.
The Name is accepted only when the Shipping Method record is created. iPaaS.com ignores an incoming Name on update, so a rename in Heartland does not propagate to an already-linked record.
Custom values are stored only when a matching subscription custom field exists on the Shipping Method collection.
Integration-Specific Caveats
Transfers are additive and update-in-place: an incoming shipping method never removes an existing iPaaS.com Shipping Method record.
Only the fields listed under Mappings are written. Any other field on the iPaaS.com Shipping Method record is left untouched by this collection.
Setup Requirements
Heartland Configuration
Ensure each shipping method has a Name and an Amount, both of which Heartland requires to create the record.
Create any Heartland custom fields you intend to map before configuring the mappings, so they are available for selection.
iPaaS.com Configuration
Create the Heartland Amount and Heartland Income Amount ID custom fields on the Shipping Method collection if you want those Heartland values retained.
Ensure the Name mapping resolves — it is required for the record to be created.
Enable the subscription so polling can run, or use Initialize Data to transfer all existing shipping methods on demand.
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
Scheduled polling:
On its polling schedule, the integration requests the current set of shipping methods from Heartland.
For each shipping method returned, it retrieves the full Heartland shipping method record.
Each record is dispatched to iPaaS.com through the Shipping Method collection, where it is created if not yet linked, or updated if the Heartland shipping method ID is already saved as the external id.
Initialize Data:
From the Initialize Data section of the Heartland subscription, the integration requests all shipping methods from Heartland in one pass.
Each is retrieved and dispatched exactly as in the polling flow, so a subscription can be brought up to date without waiting for the next poll.
Manual Sync:
A Heartland shipping method ID is entered on the iPaaS.com Manual Sync page.
The integration retrieves that single shipping method from Heartland and dispatches it through the same create-or-update path.
All three paths converge on the same mapping logic, so a shipping method's resulting iPaaS.com record is identical regardless of how the transfer was triggered.
Mappings
Add/Update Heartland Shipping Method TO iPaaS.com
Mapping Filter
This mapping collection does not have a mapping filter applied. All Heartland shipping method records received through polling, Initialize Data, or Manual Sync are processed without additional filtering conditions.
Description: Creates or updates the iPaaS.com Shipping Method record from the Heartland shipping method, matched durably by the Heartland shipping method ID. That ID is saved as the record's external id and is the durable match key; it is not a configurable mapping row.
Mapping Type | Source Field (Heartland) | Destination Field (iPaaS.com) | Description |
Field | Name | Name | Required. Stores the Heartland shipping method's name in the iPaaS.com Name field. iPaaS.com will not create a shipping method without a name. Heartland likewise requires a Name (and an Amount) to create a shipping method. The Name is applied when the record is created; on a later update iPaaS.com ignores it, so renaming a shipping method in Heartland does not rename the linked iPaaS.com record. |
Field | Service | Description | Recommended. Stores the Heartland shipping method's service description in the iPaaS.com Description field so the record carries a readable description. The Description field is optional in iPaaS.com. |
Field | Amount | Heartland Amount (custom field) | Optional. Stores the Heartland shipping method's amount. Requires a subscription custom field of this name on the Shipping Method collection before the value is stored. |
Field | IncomeAccountId | Heartland Income Amount ID (custom field) | Optional. Stores the Heartland income account identifier. Requires a subscription custom field of this name on the Shipping Method collection before the value is stored. |
Unmapped Field Overwrite Risk
The iPaaS.com Shipping Method record exposes only four writable values: Name, Description, custom fields, and external ids. This collection maps all of them, so there is no unmapped writable field left that a transfer could clear. Subscribers do not need to add preservation mappings for this collection.
Note that Name is set only when the record is created. On an update it is ignored, so renaming a shipping method in Heartland does not rename the linked iPaaS.com Shipping Method record. To change the name in iPaaS.com, edit it there directly.
Error Handling
Missing shipping method name: the Name is required in iPaaS.com. When Heartland does not supply a name, or the Name mapping does not resolve, the iPaaS.com Shipping Method record is not created. Populate the Name in Heartland and confirm the mapping resolves before retrying.
Missing amount in Heartland: Heartland requires an Amount to create a shipping method. A shipping method that lacks one will not exist in Heartland to be transferred.
Shipping method not found: when a Manual Sync is run for a shipping method ID that does not exist in Heartland, or the record cannot be retrieved, the transfer fails and no iPaaS.com record is created or updated. Confirm the ID is correct and that the shipping method is still present in Heartland.
Custom value not stored: when the Heartland Amount or Heartland Income Amount ID subscription custom field has not been created on the Shipping Method collection, the shipping method still transfers and its other fields are written; only that custom value is not retained. Create the custom field and re-transfer to populate it.
Testing & Validation
Test Scenarios
New shipping method created — create a shipping method in Heartland with a Name and Amount, transfer it, and confirm an iPaaS.com Shipping Method record is created with the matching name and linked by the Heartland shipping method ID.
Existing shipping method updated — change the service on a linked Heartland shipping method, transfer it again, and confirm the same iPaaS.com record is updated with no duplicate created.
Rename does not propagate — rename a linked shipping method in Heartland, transfer it again, and confirm the iPaaS.com Name is unchanged. The Name is applied on create only.
No duplicate on re-transfer — transfer the same shipping method twice and confirm only one iPaaS.com Shipping Method record exists.
Description optional — transfer a shipping method with no service value and confirm the record is still created with the Description left empty.
Custom fields populated — with both custom fields created on the Shipping Method collection, transfer a shipping method and confirm the Heartland amount and income account identifier are stored.
Custom field absent — remove or omit one of the custom fields, transfer a shipping method, and confirm the record still transfers with the remaining fields written and no error raised for the missing custom value.
Manual Sync by ID — enter a known Heartland shipping method ID on the Manual Sync page and confirm that specific shipping method transfers.
Initialize Data — run Initialize Data and confirm all eligible Heartland shipping methods are transferred in one pass.
Polling — with the subscription enabled, create a shipping method in Heartland and confirm it arrives in iPaaS.com on the next polling cycle without manual intervention.
Validation Checklist
The Name is populated in Heartland and resolves through the mapping on every transferred record.
Each transferred shipping method is linked by the Heartland shipping method ID, and re-transfers update rather than duplicate.
The Description resolves when a service value is present and is left empty when it is not.
Both custom fields exist on the Shipping Method collection and hold the expected Heartland values.
Fields not listed under Mappings are unchanged after a transfer.
Polling, Initialize Data, and Manual Sync all produce the same resulting record for the same shipping method.
Additional Notes
A single Add/Update collection covers both creation and updates. There is no separate Add or Update collection for shipping methods, so no configuration choice is needed between them.
Heartland is the source of truth for the fields listed under Mappings. Editing those values directly in iPaaS.com will be overwritten on the next transfer of that shipping method.
Because shipping methods arrive by polling rather than instant webhooks, allow for the polling interval when validating a change made in Heartland.
Related Documents
Setup & Reference