Tax Rates Feed & Setup

Point of Sale has the capability of calculating taxes via its tax engine. This tax engine relies on a tax feed that provides information about various taxes and rates that are applicable to products in different locations. If required, the tax engine can also compute the value-added tax (VAT) components out of a product price that already has VAT built into it for print and reporting purposes.

Important

As of 2025, support for the Native Tax Engine has been discontinued. Originally designed as a back-up tax solution and not a primary tax engine, the Native Tax Engine is no longer supported with technical updates or maintenance for any new or existing customers. To ensure uninterrupted business operations, all customers still using the Native Tax Engine must migrate to an alternative solution immediately.

Pre-built Integrations: Point of Sale includes native connectors to seamlessly support Avalara , OneSource (Sabrix), and Vertex.
Custom Solutions: For any other third-party tax provider, an SPI is available to facilitate your integration.

Feed Set Up

Follow these steps to set up the tax rate feed.

Set Up Value-Added tax (VAT)

VAT rates are required only if the merchant requires the tax engine to calculate, print, and/or report VAT breakup. VAT country also means that product prices already have VAT components built into the product prices which are fed into Point of Sale via the product feed.

To enable VAT:

In CMS, go to Store Management | Store Settings | Tax.
Enable the flag, Is VAT enabled for this merchant (valueAddedTaxEnabled).

To display VAT details on receipts:

In CMS, go to App | {your app config} | Modules | POS.
Under Receipt, click the pencil icon next to Receipt Configuration.
Enable the flag, Show VAT breakdown.

Note For app builds 9.4.1 or above, the VAT total (calculated as part of the subtotal) will be included for VAT-specific regions in the Cart Summary on the POS app.

Tax Rate Feed

The tax rate file can be uploaded manually or can be scheduled to get uploaded. All files should be saved in a UTF-8 (not to be confused with UTF-8 with BOM) format, or else you receive an error during upload.

One time manual upload
- Go to Feeds | Manual Upload | Stores | Tax Rates.
Scheduled upload
- Go to Feeds | Scheduled Upload.
- Click the + sign and select Tax Rates.

Note To change the VAT rate (e.g., 10% to 8%), a new feed file needs to be uploaded.

Tax Feed Specification

The tax feed drives the tax computation logic of the native tax engine. The engine computes the taxes based on tax class, tax type, and zip code.

Format

The feed formats are CSV (comma-separated) and SV (tab-separated).

Types

Full Feed Import - This is a complete tax feed with all tax rates and all mandatory columns.

Source Types

The feed source types are file transfer protocol (FTP) and secure file transfer protocol (SFTP).

Frequency

The frequency is configurable.

Content

CMS Field Display Name	Mandatory	Data Type	Description	Example Data
country_code	Yes	String	The two-letter country code.	US, CA, etc...
tax_rate	Yes	Number	This will be the tax rate for chosen TaxType. Specify any number value for tax rate without any special character or without % value in it.	9.5
tax_type	Yes	String	This is the type of tax. Only one of the following keywords is allowed: "STATE", "COUNTY", "CITY", "DISTRICT", or "CLASS".	CLASS/CITY/DISTRICT/COUNTY/STATE Important: The tax_type of "CLASS" on any product category will lead the tax engine to give precedence to this tax and the engine will ignore any other tax type i.e., STATE, CITY, etc. for products that belong to this particular product category (tax_class).
tax_class	Yes	String	This represents a category of products to which this particular tax will be applicable. A merchant might have products that belong to different tax buckets/categories (e.g., Generic, Food, All, Misc, Alcohol, Tour, etc.)	PS00000 Important: The tax class must be present in the product feed. In the field mappings, create a mapping that maps the tax class field onto a Point of Sale product field. Finally, configure the Product Field to read the tax class server setting so that it matches the Point of Sale product field name in the product Field Mappings.
city	No	String	The city where the taxes are applicable. This is required and applicable only if the chosen keyword for TaxType is "CITY".	Boston
county	No	String	The county where the taxes are applicable. This is required and applicable only if the chosen keyword for TaxType is "COUNTY".	Suffolk
district	No	String	The district where the taxes are applicable. This is required and applicable only if the chosen keyword for TaxType is "DISTRICT".	Dorchester
corporate_tax_id	No	String	The merchant identifier with tax authorities. If present, will be used and printed on receipts along with tax_name and tax_rate (e.g., GST - 1234309343 - 5% (tax_name - corporate_tax_id - tax_rate%))	1234309343
external_tax_id	No	String	The alternate tax name/identifier for the external system. Point of Sale does not use this field for any logic. This field is used to pass to the merchant's system for reference purposes.	1234
language	No	String	The language of the tax feed.
postal_code	No	String	The postal code where the taxes are applicable. It is used for tax rate lookup.	94022
state	No	String	The state code where the taxes are applicable. This is required and applicable only if the chosen keyword for TaxType is "STATE".	CA, CO, ANY, Empty String, etc... Important: The state of the store addresses in the store feed should match the state codes in the tax file for taxes to be calculated. If it is a VAT country or state that is not used in-store addresses and state is not used for tax purposes then this field in the feed can be empty or with the value 'ANY'.
tax_description	No	String	The description of the tax feed.
tax_name	No	String	The name of the tax. This is the tax name that will be displayed on-screen and also printed on the receipt. It should be unique for every tier tax breakup.	District Sale Tax
tier_tax_grouping_rule	No		This is required for tier tax and used to calculate the taxable amount. It can have either of the values: PRODUCT or TAX_CLASS.	- PRODUCT: The grouping to calculate taxable amounts is done based on the product. The cap and threshold will be applied separately to each product and always with a single quantity. For example, if the tier is for 0 to 100 with a rate of 0% then the product of price $60 having quantity 2 will not be taxed. - TAX_CLASS: The grouping to calculate taxable amounts is done based on the TAX_CLASS. For example, if the tier is for 0 to 100 with a rate of 0% then the product of price $60 having quantity 2 will be taxed either for $20 or the whole amount i.e., $120 based on tier tax special rule.
tier_tax_special_rule	No	String	This is required for tier tax. It can have either of the values: NONE (default) or TAX_ALL.	- NONE (default): The default rule where taxes are applied on the excess amount. For example, Tier: $175 and above => 10%, Amount: $200. Applying the tiered taxes using the special rule as below: 0% tax on the first $175. 10% tax on the remaining $25. - TAX_ALL: Apply tier taxes where taxes are applied on the full amount. For example, Tier: $175 and above => 10%, Amount: $200. Applying the tiered taxes using logic as below: 10% tax on the full amount i.e., $200.
jurisdiction	No	String	The jurisdiction type(s) to which taxes are applied (e.g., Federal, Provincial). Note: Values under this field will not be recorded on receipts or TLogs.	Federal, Provincial
registration_number	No	String	Registration number Note: Values under this field will not be recorded on receipts or TLogs.	848232190293R00T008
cap	No, but required for offline tier taxes	Number	Maximum amount that is subject to the specified tax rate. Any amount above this value isn't taxed at this rate. This field is required when uploading offline tier tax rates to the tax rate feed. It can't be manually mapped in the field mapping form but will be automatically mapped if the column is present and correctly named in the CSV file.	75.00
threshold	No, but required for offline tier taxes	Number	Minimum amount that is subject to the specified tax rate. Any amount below this value isn't taxed at this rate. This field is required when uploading offline tier tax rates to the tax rate feed. It can't be manually mapped in the field mapping form but will be automatically mapped if the column is present and correctly named in the CSV file.	0

Known Issues & Restrictions

Refer attached PSTaxFeedSample.csv as an example. Country-specific tax rates can be separated into different files. They are clubbed together in one file for representative purposes.
In the initial file upload, the required Target Fields (denoted by an asterisk) must be mapped so they can be available as columns. However, they don’t need to have values and just need to line up with the schema.
If using the tax engine along with a tax feed file, it is mandatory to have a product feed field that has taxClass. This needs to be mapped to a customfield in field mappings and this field then has to be configured.
1. In the CMS go to Store Management | Store Settings | Checkout | Tax.
2. Expand the file to show Product Field to read tax class.

Example

Fxample feed: PSTaxFeedSample.csv