Configuring tax calculation settings

Use these configurations to set up a third-party tax calculation provider, such as Avalara or Vertex, to calculate taxes.

Important

Check Avalara Developer documentation for configuring tax codes in Avalara or contact Vertex support for configuring tax codes in Vertex. These tax codes are used to apply appropriate tax rates for different products.

After you have configured tax codes in the third-party calculation providers' systems, reconcile them in NewStore by importing them during a product import. Use the tax_class_id property to specify the tax codes. See the Product JSON schema or this guide for more information on import guidelines.

Configuring settings for Avalara integration

To view the current tax calculation strategy for your business, use the Get tax calculation config method.

note

NewStore validates the Avalara credentials through a ping request to Avalara. The ping request validates the authenticity of Avalara credentials from the final version of the configuration.

As the store and the tenant configurations are merged for the retailer even after creating or updating with a different tax calculation strategy, NewStore triggers a ping request to Avalara for authentication if the tenant and/or store configuration contains the Avalara configuration.

The ping check is performed if the Avalara configuration is set in tenant and/or store level. NewStore performs the ping check:

• While creating or updating a tenant or store config, if the Avalara configuration is set at the tenant level.
• While creating or updating a store config, if the Avalara configuration is set at the store level.

For more information, see the Tax calculation API.

Configuring Avalara for tax calculation

You can set store or tenant-level tax configuration for Avalara.

To configure Avalara and calculate taxes automatically:

1. For the store-level, use the Create tax calculation config or Update tax calculation config method

   and/or

   for the tenant-level, use the Create tax calculation config or Update tax calculation config method.

2. Set tax_calculation_strategy to avalara.

3. In avalara > account_number, provide the retailer's AvaTax account number or account ID.

4. In avalara > company_code, provide the retailer's company code in the AvaTax account.

5. To set the license key to use Avalara's AvaTax for tax calculation, use the avalara > license_key property in the Tax calculation API.

6. In avalara > environment, provide Avalara's environment that NewStore uses to get taxes from AvaTax.

Configuring Avalara tax exemption class mapping

Tax exemption information can be configured for an order during checkout when the new tax exemption functionality is enabled. To enable tax exemption for your business, see Enabling tax exemption in the app .

When the tax exemption information is configured for an order in Associate App, this information is sent to Avalara during tax calculation:

• The entity use code that corresponds to the given tax exemption class
• The exemption number

note

When the Avalara tax exemption class mapping is not configured, the default list of tax exemption class options for Avalara will be rendered in Associate App while the tax exemption information is being configured.

The custom exemption classes are supported from Associate App v1.39.0 and later. The display name will not be rendered in the earlier versions of Associate App.

(Optional) To configure tax exemption class mapping for Avalara:

1. For stores, use the Create tax calculation config or Update tax calculation config method

   and/or

   For the whole business, use the Create tax calculation config or Update tax calculation config method.

2. In avalara > exemption_classes, provide the list of tax exemption class mappings.

   For example, use the following syntax to configure tax exemption class mappings for:

   • CHARITY_ORGANIZATION
     • Will be available in all countries.
     • Will be mapped to Avalara entity use code E.
   • FEDERAL_GOVERNMENT
     • Will be available in stores operating in United States.
     • Will be mapped to Avalara entity use code A.
   • CUSTOM_CANADA_FNC
     • Will be available in stores operating in Canada.
     • Will be mapped to a custom entity use code CANADA_FNC. A custom entity use code can be defined within an Exempt Entity Rule, which can be configured under the Settings > All settings > Custom rules > Manage section of the Avalara AvaTax admin portal. An Exempt Entity Rule can be used for defining a partial tax exemption rule that can exempt certain taxes.
     • Tax exemption class option will be rendered in the Associate App based on the given display text translations.

   [
     {
       "exemption_class": "CHARITY_ORGANIZATION",
       "avalara_entity_use_code": "E",
       "valid_countries": [
         "*"
       ]
     },
     {
       "exemption_class": "FEDERAL_GOVERNMENT",
       "avalara_entity_use_code": "A",
       "valid_countries": [
         "US"
       ]
     },
     {
       "exemption_class": "CUSTOM_CANADA_FNC",
       "avalara_entity_use_code": "CANADA_FNC",
       "valid_countries": [
         "CA"
       ],
       "display_text": {
         "en": "First Nations",
         "fr": "Premières Nations"
       }
     }
   ]

   For more details, see:

   • List of Avalara entity use codes
   • Avalara Exempt reason matrix for the U.S. and Canada
   • Create a custom tax rule to override AvaTax calculations

Enabling tax committing for Avalara integration

Tax committing can be enabled for the configured tax calculation strategy.

note

Tax committing is currently only supported for Avalara.

To enable tax committing for your business:

1. Use the Create tax calculation config or Update tax calculation config method.

2. Set tax_committing_enabled to true.

Important

Tax committing using the productized Avalara integration is limited to in-store orders, where taxes are calculated within the NewStore platform. For more details, see Tax committing use cases .

Configuring settings for Vertex integration

NewStore only supports integrating with the Vertex cloud instance for tax calculation services for retailers on the platform.

Use the Tax calculation API to manage these credentials at NewStore.

note

NewStore validates the Vertex credentials through a ping request to Vertex. The ping request validates the authenticity of Vertex credentials from the final version of the configuration.

As the store and the tenant configurations are merged for the retailer even after creating or updating with a different tax calculation strategy, NewStore triggers a ping request to Vertex for authentication if the tenant and/or store configuration contains the Vertex configuration.

The ping check is performed if the Vertex configuration is set in tenant and/or store level. NewStore performs the ping check:

• While creating or updating a tenant or store config, if the Vertex configuration is set at the tenant level.
• While creating or updating a store config, if the Vertex configuration is set at the store level.

For more information, see the Tax calculation API.

Retrieving the existing tax calculation strategy

To view the current tax calculation strategy for your business, use the Get tax calculation config method.

Configuring Vertex for tax calculation

To set up a new tax calculation strategy, configure the following values in Vertex via the Tax calculation API:

• For stores, use the Create tax calculation config or Update tax calculation config method
• For the whole business, use the Create tax calculation config or Update tax calculation config method.

To configure Vertex for tax calculation:

1. Set up the authentication flow for Vertex for your business using:

   • A TrustedId as vertex > login_type or,
   • A combination of a username and password in vertex

2. The tax_calculation_strategy config value decides which tax provider will be used for your tenant.

3. The vertex > login_type config value is used for the relevant authentication method. Possible values include a TrustedId parameter or a combination of username and password.

4. The vertex > soap_url config value contains the WSDL URL for Vertex SOAP, such as https://sandboxap2.ondemand.vertexinc.com/vertex-ws/services/CalculateTax90.

5. Set up the Vertex taxpayer codes for your business:

   • The vertex > company_code config value should be set to the taxpayer code of the top-level taxpayer (company) within Vertex.

   • (Optional) If exists, the vertex > division_code config value can be set to the taxpayer code of the mid-level taxpayer (division) under a top-level taxpayer (company) within Vertex.

     Important

     Vertex supports taxpayer codes up to three levels:

     • Top-level (company)
     • Mid-level (division)
     • Low-level (department)

     The taxpayer codes can be configured for top-level (company) and mid-level (department) within the NewStore platform.

Testing the Vertex integration

After the support team has configured the Vertex integration on the NewStore platform, verify that the tax calculation is working as intended.

In your test environment in NewStore Associate App, add an item to the cart and verify if the taxes for the item are displayed correctly.

To fix issues with the integration, contact the support team at NewStore.

Configuring Vertex tax exemption class mapping

Tax exemption information can be configured for an order during checkout when the new tax exemption functionality is enabled. See Enabling tax exemption in the app .

When the tax exemption information is configured for an order in Associate App, the following information is sent to Vertex during tax calculation:

• The customer class code that corresponds to the given tax exemption class
• The exemption certificate number

note

When the Vertex tax exemption class mapping is not configured, the tax exemption class field will not be rendered in Associate App while the tax exemption information is being configured.

The custom exemption classes are supported from Associate App v1.39.0 and later. The display name will not be rendered in the earlier versions of Associate App.

(Optional) To configure tax exemption class mapping for Vertex:

1. For stores, use the Create tax calculation config or Update tax calculation config method

   and/or

   For the whole business, use the Create tax calculation config or Update tax calculation config method.

2. In vertex > exemption_classes, provide the list of tax exemption class mappings.

   For example, use the following syntax to configure tax exemption class mappings for:

   • CHARITY_ORGANIZATION
     • Will be available in all countries.
     • Will be mapped to Vertex customer class code 02.
   • FEDERAL_GOVERNMENT
     • Will be available in stores operating in United States.
     • Will be mapped to Vertex customer class code 01.
   • CUSTOM_CANADA
     • Will be available in stores operating in Canada.
     • Will be mapped to Vertex customer class code 03.
     • Tax exemption class option will be rendered in the Associate App based on the given display text translations.

   [
     {
       "exemption_class": "CHARITY_ORGANIZATION",
       "vertex_class_code": "02",
       "valid_countries": [
         "*"
       ]
     },
     {
       "exemption_class": "FEDERAL_GOVERNMENT",
       "vertex_class_code": "01",
       "valid_countries": [
         "US"
       ]
     },
     {
       "exemption_class": "CUSTOM_CANADA",
       "vertex_class_code": "03",
       "valid_countries": [
         "CA"
       ],
       "display_text": {
         "en": "First Nations",
         "fr": "Premières Nations"
       }
     }
   ]

   • Customer classes can be configured from the My Enterprise > Customers section of the Vertex admin portal.
   • Tax rules for exemptions can be configured under the Tax Setup > Taxability Mapping section of the Vertex admin portal by using a customer class.

   For more details, see Vertex Taxability Mapping

Configuring a fixed tax rate fallback for Avalara or Vertex

If the retailer uses third party tax calculation provider, Avalara or Vertex to calculate taxes, you can set a fixed rate tax applicable when the third-party tax provider is unresponsive. For example, you can specify a percentage of the sale amount to charge as tax, such as 8%. See Using a fixed rate as a fallback .

note

It is mandatory to configure the fixed rate provider regardless of the usage of third party tax calculation providers.

To configure a fixed tax rate for the third party tax provider:

1. For the store-level, use the Create tax calculation config or Update tax calculation config method

   and/or

   for the tenant-level, use the Create tax calculation config or Update tax calculation config method.

2. Set tax_calculation_strategy to avalara or vertex.

3. Set the fixed_tax_rate property to indicate the percentage of the sale amount to charge as tax. For example, enter 0.08 to set the tax rate at 8%.

Configuring a fixed rate per country

note

This tax rate is not a fallback strategy and is for retailers who don't use a third party tax calculation provider.

To configure a fixed tax rate per country:

1. For the store-level, use the Create tax calculation config or Update tax calculation config method

   and/or

   for the tenant-level, use the Create tax calculation config or Update tax calculation config method.

2. Set tax_calculation_strategy to fixed_rate_per_country.

3. In the fixed_rate_per_country property, specify the country code and the fixed taxation rate.

   For example, use the following syntax to set the tax rate at 15% for all stores operating in USA. You can create a fixed tax rate for each country that the retailer does business in.

   {
     "fixed_rate_per_country": {
       "US": {
         "tax_rate": "0.15",
         "tax_name": "US VAT"
       }
     }
   }

Enabling tax exemption in the app

Tax exemption can be configured for an order during checkout when this functionality is enabled. To enable the new tax exemption functionality in Associate App:

1. Go to the Associate App configuration API.
2. Set release_toggles > new_tax_exemption to true.

note

In Associate App v1.43.0 to v1.44.0, the breakdown of taxes is displayed within Taxes for an order during checkout when you have enabled this feature. Tax breakdown details for each item are also displayed in the same screen. For more details, see Displaying tax breakdown for an order .

From Associate App v1.45.0 and later, tax breakdown is enabled for all retailers and does not require tax exemption to be enabled separately for it to work.

Tax exemption classes can be set up for supported tax providers:

• For the store-level, use the Create tax calculation config or Update tax calculation config method
• For the tenant-level, use the Create tax calculation config or Update tax calculation config method.

To set up tax exemption class mapping for a third party tax provider, see:

• Configuring Avalara tax exemption class mapping
• Configuring Vertex tax exemption class mapping

To configure tax exemption information for an order, see Adding tax exemption to an order .

The tax provider calculates the taxes for the order based on the tax classes of the items and store or shipping addresses.

• In countries with tax-exclusive pricing: The tax provider calculates the taxes by using the given tax exemption information of the customer.
• In countries with tax-inclusive pricing: The tax provider calculates the taxes and the calculated taxes will be exempted from the item prices by the NewStore platform.

Related topics

• About taxes
• Adding tax exemption to an order
• Retrieving tax information
• Importing data