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.
• Tax rate format: taxRate is a decimal string representing a fraction, not a percentage. For example, "0.085" is 8.5% and "0.2" is 20%. Don't pass a number (0.085), an integer (5), or a percentage string ("8.5%"). Up to 6 decimal places are supported.
• 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.
• Tax exemptions: To exempt specific buyer groups from a mapping's tax, assign exempt-group rate overrides to the mapping. Apps can provide tax exempt groups through the Tax Exempt Groups Provider service plugin.

Tax breakdowns (advanced mode)

To show a customer several tax components on one line item (for example, GST and PST, or state and county tax), create multiple manual tax mappings for the same taxGroupId and taxRegionId, one per component, each with its own taxName and taxRate. Tax calculation applies all of them, and each taxName becomes its own line at checkout (an empty taxName shows a default label such as Sales Tax). The set of records is the breakdown by design; there's no deduplication. Create Manual Tax Mapping rejects an exact duplicate: it returns an already-exists error when another mapping matches on taxRegionId, taxGroupId, taxName, taxType, jurisdiction, and jurisdictionType.

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.