Skip to content

Elective Item Group Tax Exemptions

Jumpmind Commerce supports a form of Tax Exemption referred to as an Elective Item Group Exemption. This configuration option allows the retailer to specify a particular Item Group (via a taxGroupId), of which each item of that group may be eligible for Tax Exemption prior to checkout. The configuration for this feature also requires identifying which Tax Authorities are permitted to allow this exemption, as well as which tax types are to be exempted.

Item Group Tax Exemption configurations enable the feature at the transaction level, but tax exemptions are applied at the item level. The intent of the configuration is to be able to identify which individual eligible items can be toggled as Tax Exempt for specific tax types.


For example:

Retailers in particular regions of Canada must support a form of tax exemption which identifies that a certain Tax Type (PST) must not be applied at its normal tax rate for clothing and footwear purchased for children under the age of 15. This Elective Item Group Tax Exemption feature allows a store to identify that items under a Clothing item tax group are eligible to be exempt from the PST tax in order to stay in compliance with that law.

Qualification Strategies

Should retailers require additional logic to determine item eligibility, Jumpmind Commerce exposes an ITaxExemptionQualificationStrategy interface which can be implemented to perform retailer-specific logic for the purpose of determining item tax exemption eligibility. This implementation can then be configured on any Item Group Tax Exemption configuration as part of the QualificationStrategy details (see configuration details for more information).

The MaxPriceExemptionQualificationStrategy is an example of an ITaxExemptionQualificationStrategy implementation, which enables the retailer to also require that select Item Group Exemptions must fall under a configured maximum actual unit price to be eligible for exemption.

Configuration Details

Below is a sample out-of-the-box configuration which enables a store to allow customers to be exempt from the General Sales and Use Tax for items that fall under the "145" Tax Group Id (General Merchandise). 

openpos:
  tax:
    group-item-tax-exemptions:
      - taxExemptId: 40
        DOC__configKeyPart: "Identifies the configuration key part for this exemption when retrieving CTX and I18N resources"
        configKeyPart: generalItemsTaxExemption
        displayedItemOptionValue: brand
        itemEligibilityRules:
          - taxGroupIds: 145
            permittedAuthorities: 5107,3043,2930
            exemptedTaxTypes: General Sales and Use Tax
            qualificationStrategies: MaxPriceExemptionQualificationStrategy

    qualificationStrategies:
      generalItemsTaxExemption:
        maxActualItemPrice: 15.00

There can be any number of group item tax exemption configurations, so the base config group-item-tax-exemptions key is a list of values. The keys and their values are:

openpos.tax.group-item-tax-exemptions: The root of Group Item Tax Exemptions configurations. This is a list of exemption configurations, in which all list items must have a unique taxExemptId.

Each group-item-tax-exemption list item has the following property structure:

openpos.tax.group-item-tax-exemptions

taxExemptId

Tax Exempt sales are driven by a REASON CODE value; these group item tax exemptions follow the same pattern. In this case, we have a CTX_REASON_CODE with an ID of 40 representing this exemption. When the transaction has this ID on it, the new checkout flow state will recognize this association and show the item selection prompt based on the rest of the config.

configKeyPart

To keep this configurable to different stores/regions/etc and to support i18n, this configKeyPart value will be used when doing any kind of CTX or i18n lookup related to this feature and the associated taxExemptId qualification. For example; when looking for the add customer form, it will look for a groupItemTaxExemptionCustomer.{configKeyPart} form and related form fields.

displayedItemOptionValue

The item selection screen displays basic item info including the item name/description, the price, the SKU, and then this additional contextual value. The screen will look in the item's augments for the key specified in this field.

itemEligibilityRules

This is another list of related data groupings representing what items are eligible for tax exemption. Each item in the transaction is filtered for selection eligibility using the eligibility rules here as OR logic - any item that passes any of its eligibility rules will be eligible for exemption selection.

taxGroupIds

Identifies which Tax Group IDs the exemption applies to; an item's TaxGroupId must be one of these IDs to be eligible for exemption selection.

permittedAuthorities [Optional]

Identifies which tax authorities the tax may be exempted from. The tax data identifying which tax rates/rules are applied to which item(s) are also associated with a tax authority. In order to identify which tax types we can toggle for exemption on a selected item, we have to know which authority to exempt the item from to avoid unintentionally "over-exempting" items in case of tax rule overlays (e.g. if the same tax applies to two authorities, but we only want to exempt from one of those authorities).

exemptedTaxTypes

Identifies which taxes are exempted during tax calculation.

qualificationStrategies [Optional]

Specifies which QualificationStrategy implementations to run, allowing the creation of custom eligibility rules. All specified strategies must return true for the item to be eligible. Config parameters for QualificationStrategies should respect the configKeyPart config value pattern specified above to allow for granular CTX config.

openpos.tax.qualificationStrategies: The root of parameters for each of the named exemption programs derived from each configKeyPart.

Each qualificationStrategies list item has the following property structure:

qualificationStrategies

{configKeyPart}

Identifies which matching group-item-tax-exemptions configured list element (comparing against the configKeyPart) these parameters should apply to.

{fieldValue}

Each qualification strategy will have its own unique set of configuration parameters. In the case of the MaxPriceExemptionQualificationStrategy, it looks for a maxActualItemPrice config value under the configPartKey provided to it during checkout exemption checks (in the case of the configuration above, "generalItemsTaxExemption").

Other Required Configurations

TAX Records (Jurisdiction, Authority, GroupRule, RateRule, etc.)

The configuration details provided above assume that valid tax data has been set up for the Business Unit and Device that any Item Group Tax Exemption is configured for.

Tax Authorities must exist for the referenced permittedAuthorities properties, otherwise taxes will not calculate properly and the system will not be able to map the program with the intended Tax Authorities.

Sale and Order Sidenav Drawer Buttons

As is done for baseline Tax Exemptions, CTX_BUTTON records needs to be created in order for the tax exemption button to populate in the left sidenav drawer during a transaction.

The button record for each unique Item Group Tax Exemption configuration should have a DEFAULT_PAYLOAD value matching the CTX_REASON_CODE

CTX_FORM and CTX_FORM_FIELD Records

These forms of Tax Exemptions do not associate a Tax Exemption Certificate with the exemption or transaction. Because of this, new customer information is required when applying this exemption to a transaction. A valid Form and accommodating FormField records need to be created to capture relevant customer data.

CTX_FORM

The CTX_FORM record for a single tax exemption program of this type is expected to exist with a FORM_ID value of groupItemTaxExemptionCustomer.{0} where {0} is equal to the configKeyPart of the exemption program. In the example YML above, the FORM_ID value for the Form record would be "groupItemTaxExemptionCustomer.generalItemsTaxExemption".

The FORM_GROUP_ID should be the same value as the FORM_ID.

CTX_FORM_FIELD

Because the application is capturing customer-related information, the Form Fields for this form should be appropriate enough to create Customer and Tax Account records. An example of this information would be:

First Name, Last Name, Address Lines 1 & 2, City, State, and Zip/PostalCode

Internationalization [I18n] and Properties Strings

Aside from standard i18n records or properties for the transaction navigation drawer buttons and form field labels, the forms and dialogs for this feature expects a handful of additional labels. Note that all the following property keys expect to replace the {0} placeholder with the value of configKeyPart property of the tax exemption program.

  • groupItemTaxExemption.{0}.customer.header.label
    The header of the "Enter Customer Information" Form when activating this type of tax exemption on the transaction.
  • groupItemTaxExemption.{0}.customer.instructions.label
    Contextual instructions for the same "Enter Customer Information" form.
  • groupItemTaxExemption.{0}.selection.instructions.noItems.label
    The information label displayed at checkout when no items on the transaction are eligible for exemption.
  • groupItemTaxExemption.{0}.selection.header.label
    The header of the dialog displayed at checkout for selecting which eligible items are to be tax-exempt.
  • groupItemTaxExemption.{0}.selection.instructions.hasItems.label
    Contextual instructions prompting the user/cashier to select which eligible listed sale items that should be exempt from the tax types configured for this tax exemption program.
  • groupItemTaxExemption.{0}.selection.checkAll.label
    The label for the convenience "Select All" checkbox at the top of the item selection list at checkout.