About the Manual Tax Mappings API

The Manual Tax Mappings API allows you to enhance Wix's manual tax calculator by defining custom tax rates for specific combinations of tax groups and tax regions. This API is designed for businesses that need to define and manage custom tax rates and mappings for calculating taxes with Wix's manual tax calculator.

With the Manual Tax Mappings API, you can:

• Create custom tax rate mappings for specific tax group and region combinations.
• Bulk create multiple tax mappings for efficient setup and data imports.
• Retrieve and query existing tax mappings by various criteria.
• Update tax rates and associated details as regulations change.

This API is particularly useful for:

• Businesses operating across multiple jurisdictions with complex tax requirements.
• Companies importing tax rate data from external tax systems or spreadsheets.
• Organizations that need to set custom rates.
• Merchants with special tax arrangements or exemptions in certain regions.

Before you begin

It's important to note the following before starting to code:

• Prerequisites: Manual tax mappings require existing tax groups and tax regions. You must create these entities in the dashboard or by using their respective APIs before creating mappings.
• Tax group and region dependencies: Each manual tax mapping must reference existing tax group and tax region IDs. These entities define the scope where your custom tax rates will apply.
• Decimal precision: Tax rates are specified as decimal values with up to 6 decimal places precision (for example, 0.085000 for 8.5%).
• Bulk operations: Use bulk operations when setting up multiple mappings at once, such as during initial configuration or data imports. You can create up to 100 mappings in a single request.

Use cases

Common scenarios for using the Manual Tax Mappings API include:

• Set up custom tax rates for a new region.
• Import tax mappings from an external system.
• Update tax rates after regulatory changes.

Terminology

• Manual tax mapping: A custom configuration for a specific tax group and region combination. Contains the custom tax rate and jurisdiction details.
• Tax group: A collection of products or services that share the same tax treatment. Must be created using the Tax Groups API before referencing in mappings.
• Tax region: A geographical area where specific tax rules apply. Must be created using the Tax Regions API before referencing in mappings.
• Tax rate: The custom tax rate specified as a decimal value (for example, 0.080000 for 8%). Supports up to 6 decimal places for precision.
• Jurisdiction: The governmental entity responsible for collecting the tax, such as a country, state, county, city, or special district.
• Tax type: The category of tax being applied, such as VAT, GST, or Sales Tax, which depends on the jurisdiction's tax laws.