BigCommerce
Store Operations
Tax
Tax Rates and Zones

Tax Rates and Tax Zones

Tax rates (opens in a new tab) are percentages a store uses to calculate taxes due for products and services. Tax zones are geographic regions defined in a store. Tax zones (opens in a new tab) allow you to apply different tax rates to different customer groups and locations. All the tax rates and zones you configure for a store are available on each storefront.

This guide demonstrates how to use the Tax Rates and Zones API. The Tax Rates and Zones API allows you to configure manual taxes (opens in a new tab) for a store. For more information, see the Tax Rates and Zones API Reference.

Tax zones

A zone must be defined by one of the following location parameters:

  • Countries: Specify one or more countries for a zone.
  • Subdivisions: Specify one or more states, provinces, or territories. You can include subdivisions for more than one country in a subdivision-based zone.
  • Postal codes: Specify one or more postal codes within a country. Currently, zones based on postal codes are limited to a single country.

You can further narrow the scope of a zone by specifying one or more customer groups to whom the zone applies. You can also use zones to choose how a store displays prices to different customer groups; for example, whether prices are inclusive or exclusive of tax.

Default tax zone

The default tax zone, which has a zone id of 1, covers locations that other zones don't cover. Shoppers who don't meet the criteria for any manually-defined tax zone fall under the default tax zone. You cannot disable or delete the default tax zone. When updating the default tax zone, you cannot adjust the locations or customer groups that it covers.

Create tax zones

To add tax zones to a store, send a request to the Create tax zones endpoint. The following example creates a subdivision-based zone.

The response includes an id for each tax zone. Use the id to get, update, or delete a specific tax zone.

Example request: Create tax zones
POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/tax/zones
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json
 
[
  {
    "name": "example zone",
    "enabled": true,
    "price_display_settings": {
      "show_inclusive": true,
      "show_both_on_detail_view": true,
      "show_both_on_list_view": true
    },
    "shopper_target_settings": {
      "locations": [
        {
          "country_code": "AR",
          "subdivision_codes": [
            "T",
            "V"
          ]
        },
        {
          "country_code": "AU",
          "subdivision_codes": [
            "WA",
            "VIC"
          ]
        }
      ],
      "customer_groups": [
        0
      ]
    }
  }
]

Update tax zones

To modify a tax zone, send a request to the Update tax zones endpoint. In the request body, specify the id of the zones you want to update. The request updates only the fields for which you supply values.

Example request: Update tax zones
PUT https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/tax/zones
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json
 
[
  {
    "id": 2,
    "enabled": false,
    "price_display_settings": {
      "show_inclusive": false,
      "show_both_on_detail_view": false,
      "show_both_on_list_view": false
    },
    "shopper_target_settings": {
      "customer_groups": [
        2
      ]
    }
  }
]

Updating a tax zone

  • You cannot adjust the shopper_target_settings for the default tax zone.
  • All zones must cover a specified location; locations cannot be an empty array in the request body.

Get tax zones

Get tax zones returns all tax zones by default. To return select tax zones, include the id:in query parameter.

Example request: Get tax zones
GET https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/tax/zones?id:in=2
X-Auth-Token: {{ACCESS_TOKEN}}
Accept: application/json

Delete tax zones

To delete tax zones, send a request to the Delete tax zones endpoint. Use the id:in query parameter to specify the tax zones you want to delete. Deleting a tax zone cascades to remove all associated tax rates.

Example request: Delete tax zones
DELETE https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/tax/zones?id:in=3,7
X-Auth-Token: {{ACCESS_TOKEN}}
Accept: application/json

Tax rates

After creating a zone, you can add rates to the zone. You can add multiple rates to a zone to help the store collect and report taxes to one or more taxation authorities. You can add a rate for each tax class in your store.

Create tax rates

To create tax rates, send a request to the Create tax rates endpoint. Specify the rate name, rates of each tax class, and the associated tax zone. The tax_zone_id is the id received from calls to the Get tax zones endpoint.

The response includes an id for each tax rate. Use the tax rate id to get, update, or delete the associated tax rate.

Example request: Create tax rates
POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/tax/rates
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json
 
[
  {
    "class_rates": [
      {
        "rate": 5,
        "tax_class_id": 0
      },
      {
        "rate": 5,
        "tax_class_id": 1
      }
    ],
    "enabled": true,
    "name": "Sales Tax",
    "priority": 1,
    "tax_zone_id": 2
  }
]

Update tax rates

To update tax rates, send a request to the Update tax rates endpoint. In the request body, specify the id of the rates you want to update. The tax_zone_id is the id received from calls to the Get tax zones endpoint.

Example request: Update tax rates
PUT https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/tax/rates
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json
 
[
  {
    "class_rates": [
      {
        "rate": 10,
        "tax_class_id": 0
      }
    ],
    "enabled": false,
    "id": 3,
    "name": "Excise Tax",
    "priority": 2,
    "tax_zone_id": 4
  }
]

Get tax rates

To get tax rates, send a request to the Get tax rates endpoint. To get the tax rates for a subset of zones, pass a comma-separated string of the tax zone ids using the tax_zone_id:in query parameter.

Example request: Get tax rates
GET https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/tax/rates?tax_zone_id:in=2
X-Auth-Token: {{ACCESS_TOKEN}}
Accept: application/json

Delete tax rates

To delete tax rates, send a request to the Delete tax rates endpoint. Use the id:in query parameter to specify the tax rates you want to delete.

Example request: Delete tax rates
DELETE https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/tax/rates?id:in=3,5
X-Auth-Token: {{ACCESS_TOKEN}}
Accept: application/json

Resources

Tax Zones reference

Tax Rates reference

Did you find what you were looking for?