The Heartland integration provides ready-made functions you can call when building mappings. They handle common lookups and conversions against your Heartland account and your iPaaS.com data, such as reading a custom field value, resolving items, customers, vendors, payment methods, and shipping methods by ID or name, converting locations, and totaling discounts, taxes, and payments on a transaction, so you do not have to write that logic yourself.

These functions are available anywhere you write a formula for the Heartland integration:

The functions are grouped below by the area of the integration they support.

What it does: Returns the value of a named custom field from a custom fields object, matching the field name after normalizing it so differences in spacing, casing, and punctuation do not matter.

Signature: Task<object> GetValueFromCustomField(object customFieldObj, object textFieldName)

How to call it: await GetValueFromCustomField(customFieldObj, textFieldName)

Returns: object. The custom field's value, or null when the field is not found.

Example: for a field named CustomerType, reading CustomerType returns its value (for example B2B).

When to use it: Use it to pull a single custom field value into a destination field, without worrying about the exact formatting of the field name.

What it does: Reads all custom fields from an object and returns them as a dictionary of normalized field names to values. Fields with an empty name or value are skipped.

Signature: Task<Dictionary<string, string>> GetPropertiesFromCustomFields(object customFieldObj)

How to call it: await GetPropertiesFromCustomFields(customFieldObj)

Returns: Dictionary<string, string>. The custom fields keyed by their normalized names; null when the input has no fields.

When to use it: Use it to turn an object's custom fields into a normalized name and value dictionary for mapping.

What it does: Reads an object's custom fields and returns only those that belong to a given group, as a dictionary of normalized field names to values. Fields with an empty name or value are skipped.

Signature: Task<Dictionary<string, string>> GetPropertiesFromCustomFieldsComplexFiltering(object customFieldObj, string groupId)

How to call it: await GetPropertiesFromCustomFieldsComplexFiltering(customFieldObj, groupId)

Returns: Dictionary<string, string>. The matching custom fields keyed by their normalized names; null when the input has no fields.

When to use it: Use it when you only want the custom fields that belong to a specific group.

What it does: Normalizes a string into a custom-field key by replacing whitespace with single underscores, dropping other non-alphanumeric characters, and lowercasing the result.

Signature: string NormalizeCustomFieldString(string input)

How to call it: NormalizeCustomFieldString(input)

Returns: string. The normalized key.

Example: Customer Name Field returns customer_name_field.

When to use it: Use it to produce a consistent custom-field key from a display name.

What it does: Looks up a Heartland item by SKU and returns the ID of the first match.

Signature: Task<long> GetItemIdBySku(object sku)

How to call it: await GetItemIdBySku(sku)

Returns: long. The Heartland item ID of the first match, or 0 when the SKU is blank or no item matches.

When to use it: Use it to resolve a Heartland item ID from a product SKU.

What it does: Looks up a Heartland item by SKU and returns the matching item records.

Signature: Task<object> GetItemBySku(object sku)

How to call it: await GetItemBySku(sku)

Returns: object. The Heartland item search result containing the matching items.

When to use it: Use it when you need the full Heartland item record for a SKU, not just its ID.

What it does: Looks up a Heartland grid item by SKU and returns the ID of the first match.

Signature: Task<long> GetGridItemIdBySku(object sku)

How to call it: await GetGridItemIdBySku(sku)

Returns: long. The Heartland grid item ID of the first match, or 0 when the SKU is blank or no item matches.

When to use it: Use it to resolve a Heartland grid item ID from a product SKU.

What it does: Looks up a Heartland grid item by SKU and returns the matching grid item records.

Signature: Task<object> GetGridItemBySku(object sku)

How to call it: await GetGridItemBySku(sku)

Returns: object. The Heartland grid item search result containing the matching items.

When to use it: Use it when you need the full Heartland grid item record for a SKU.

What it does: Retrieves all product variants under a Heartland grid ID.

Signature: Task<GetAllProductVariant> GetAllItemByGridId(object Id)

How to call it: await GetAllItemByGridId(Id)

Returns: GetAllProductVariant. The product variants that belong to the grid.

When to use it: Use it to fetch every variant of a Heartland grid product, for inventory or synchronization steps.

What it does: Looks up a Heartland inventory adjustment reason by name and returns its ID.

Signature: Task<int> GetAdjustmentReason(string reason)

How to call it: await GetAdjustmentReason(reason)

Returns: int. The Heartland adjustment reason ID, or 0 when no reason matches.

When to use it: Use it to supply the correct adjustment reason ID when recording an inventory change.

What it does: Converts an iPaaS.com location ID into the matching Heartland location ID.

Signature: Task<string> ConvertLocationToHeartlandId(string locationId)

How to call it: await ConvertLocationToHeartlandId(locationId)

Returns: string. The matching Heartland location ID, or an empty string when no mapping exists.

When to use it: Use it in product and inventory flows to translate an iPaaS.com location into its Heartland location.

What it does: Searches Heartland for a customer by email address and returns the ID of the first match.

Signature: Task<string> GetCustomerIdByEmail(object emailAddress)

How to call it: await GetCustomerIdByEmail(emailAddress)

Returns: string. The Heartland customer ID of the first match, or null when none is found.

When to use it: Use it to resolve a Heartland customer ID from an email address.

What it does: Searches Heartland for a customer by email address and returns the matching customer records.

Signature: Task<object> GetCustomerByEmail(object emailAddress)

How to call it: await GetCustomerByEmail(emailAddress)

Returns: object. The Heartland customer search result containing the matching customers.

When to use it: Use it when you need the full Heartland customer record for an email address.

What it does: Looks up a Heartland vendor by ID and returns the vendor's name.

Signature: Task<string?> HeartlandVendorNameById(long vendorId)

How to call it: await HeartlandVendorNameById(vendorId)

Returns: string?. The Heartland vendor name, or null when no vendor has that ID.

When to use it: Use it to show a Heartland vendor's name when you only have its ID.

What it does: Looks up Heartland vendors by name and returns the ID of the last matching vendor.

Signature: Task<long?> HeartlandVendorIdByName(string vendorName)

How to call it: await HeartlandVendorIdByName(vendorName)

Returns: long?. The ID of the last matching Heartland vendor, or null when none matches.

When to use it: Use it to resolve a Heartland vendor ID from a vendor name.

What it does: Resolves a Heartland payment method ID to the payment method's name.

Signature: Task<string> GetPaymentMethodNameById(string PaymentId)

How to call it: await GetPaymentMethodNameById(PaymentId)

Returns: string. The payment method's name, or null when it cannot be resolved.

When to use it: Use it to show a readable payment method name when you only have its Heartland ID.

What it does: Resolves a payment method name to its Heartland payment method ID.

Signature: Task<long> PaymentTypeIdByName(string PaymentName)

How to call it: await PaymentTypeIdByName(PaymentName)

Returns: long. The Heartland payment method ID, or 0 when it cannot be resolved.

When to use it: Use it to supply a Heartland payment method ID when you only have the method's name.

What it does: Resolves a Heartland payment method ID to the payment method's description.

Signature: Task<string> GetPaymentMethodDescriptionById(string PaymentId)

How to call it: await GetPaymentMethodDescriptionById(PaymentId)

Returns: string. The payment method's description, or null when it cannot be resolved.

When to use it: Use it to show a payment method's description when you only have its Heartland ID.

What it does: Standardizes a raw payment method string to one of the recognized payment method names, or returns null when it is not recognized.

Signature: string PaymentMethodType(string input)

How to call it: PaymentMethodType(input)

Returns: string. The standardized payment method name (Cash, Check, Gift Card, Credit Card, or Debit Card), or null when the input is empty or unrecognized.

Example: cash returns Cash; GiftCard returns Gift Card.

When to use it: Use it to normalize inconsistent payment method text into a standard name.

What it does: Sums the amounts of all payments in a transaction, treating a missing amount as zero.

Signature: double GetAllPaymentsAmount(List<TransactionPayment> transactionPayment)

How to call it: GetAllPaymentsAmount(transactionPayment)

Returns: double. The total of all payment amounts.

When to use it: Use it to compute the total amount paid across a transaction's payments.

What it does: Resolves a shipping method name to its Heartland shipping method ID.

Signature: Task<long> HeartlandShippingMethodIdByName(string ShippingMethodName)

How to call it: await HeartlandShippingMethodIdByName(ShippingMethodName)

Returns: long. The Heartland shipping method ID, or 0 when it cannot be resolved.

When to use it: Use it to supply a Heartland shipping method ID when you only have the method's name.

What it does: Resolves a shipping method ID to the shipping method's name.

Signature: Task<object> GetShippingMethod(object shippingMethodId)

How to call it: await GetShippingMethod(shippingMethodId)

Returns: object. The shipping method's name, or null when it cannot be resolved.

When to use it: Use it to show a readable shipping method name when you only have its ID.

What it does: Sums the discount applied across a transaction's lines, computed as the price before discounts minus the final price for each line.

Signature: object GetDiscountAmount(object transactionLineObj)

How to call it: GetDiscountAmount(transactionLineObj)

Returns: object. The total discount amount, or 0 when there are no lines.

When to use it: Use it to compute the total discount on a transaction.

What it does: Sums the tax values across a transaction's tax records.

Signature: object GetTaxAmount(object transactionTaxObj)

How to call it: GetTaxAmount(transactionTaxObj)

Returns: object. The total tax amount, or 0 when there are no tax records.

When to use it: Use it to compute the total tax on a transaction.

What it does: Returns whether a deposit ticket is required, which is true when the transaction includes at least one sold, non-gift-card product.

Signature: bool RequiresDepositTicket(List<TransactionLine> products_Data)

How to call it: RequiresDepositTicket(products_Data)

Returns: bool. True when at least one non-gift-card product was sold, otherwise false.

When to use it: Use it to decide whether a deposit ticket should be generated for a transaction.

What it does: Totals the quantity of sold, non-gift-card products across a transaction's lines.

Signature: double ProductSoldCount(List<TransactionLine> products_Data)

How to call it: ProductSoldCount(products_Data)

Returns: double. The total quantity of non-gift-card products sold.

When to use it: Use it to count how many products (excluding gift cards) were sold in a transaction.

What it does: Counts the transaction lines that are gift cards.

Signature: int GiftCardSoldCount(List<TransactionLine> products_Data)

How to call it: GiftCardSoldCount(products_Data)

Returns: int. The number of gift card lines (not the total quantity of gift cards).

When to use it: Use it to count how many gift card lines are in a transaction.

What it does: Sums the monetary value of the gift card lines in a transaction.

Signature: double GiftCardSoldAmount(List<TransactionLine> products_Data)

How to call it: GiftCardSoldAmount(products_Data)

Returns: double. The total value of the gift card lines.

When to use it: Use it to compute total gift card sales in a transaction.

What it does: Returns the value of the first transaction line that matches a given line type, when that value is greater than zero.

Signature: double? HeartlandLineValueByType(List<TransactionLine> transactionLine, string lineType)

How to call it: HeartlandLineValueByType(transactionLine, lineType)

Returns: double?. The value of the first matching line when it is greater than zero, otherwise 0.

When to use it: Use it to pull a specific line's value (such as a tax or shipping line) out of a transaction.