Tax Rates and Tax Zones

Tax rates are percentages a store uses to calculate taxes due for products and services. Tax zones are geographic regions defined in a store. Tax zones 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 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.

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.

1
POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/tax/zones
2
X-Auth-Token: {{ACCESS_TOKEN}}
3
Content-Type: application/json
4
Accept: application/json
5
6
[
7
  {
8
    "name": "example zone",
9
    "enabled": true,
10
    "price_display_settings": {
11
      "show_inclusive": true,
12
      "show_both_on_detail_view": true,
13
      "show_both_on_list_view": true
14
    },
15
    "shopper_target_settings": {
16
      "locations": [
17
        {
18
          "country_code": "AR",
19
          "subdivision_codes": [
20
            "T",
21
            "V"
22
          ]
23
        },
24
        {
25
          "country_code": "AU",
26
          "subdivision_codes": [
27
            "WA",
28
            "VIC"
29
          ]
30
        }
31
      ],
32
      "customer_groups": [
33
        0
34
      ]
35
    }
36
  }
37
]

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.

1
PUT https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/tax/zones
2
X-Auth-Token: {{ACCESS_TOKEN}}
3
Content-Type: application/json
4
Accept: application/json
5
6
[
7
  {
8
    "id": 2,
9
    "enabled": false,
10
    "price_display_settings": {
11
      "show_inclusive": false,
12
      "show_both_on_detail_view": false,
13
      "show_both_on_list_view": false
14
    },
15
    "shopper_target_settings": {
16
      "customer_groups": [
17
        2
18
      ]
19
    }
20
  }
21
]

Get tax zones

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

1
GET https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/tax/zones?id:in=2
2
X-Auth-Token: {{ACCESS_TOKEN}}
3
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.

1
DELETE https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/tax/zones?id:in=3,7
2
X-Auth-Token: {{ACCESS_TOKEN}}
3
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.

1
POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/tax/rates
2
X-Auth-Token: {{ACCESS_TOKEN}}
3
Content-Type: application/json
4
Accept: application/json
5
6
[
7
  {
8
    "class_rates": [
9
      {
10
        "rate": 5,
11
        "tax_class_id": 0
12
      },
13
      {
14
        "rate": 5,
15
        "tax_class_id": 1
16
      }
17
    ],
18
    "enabled": true,
19
    "name": "Sales Tax",
20
    "priority": 1,
21
    "tax_zone_id": 2
22
  }
23
]

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.

1
PUT https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/tax/rates
2
X-Auth-Token: {{ACCESS_TOKEN}}
3
Content-Type: application/json
4
Accept: application/json
5
6
[
7
  {
8
    "class_rates": [
9
      {
10
        "rate": 10,
11
        "tax_class_id": 0
12
      }
13
    ],
14
    "enabled": false,
15
    "id": 3,
16
    "name": "Excise Tax",
17
    "priority": 2,
18
    "tax_zone_id": 4
19
  }
20
]

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.

1
GET https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/tax/rates?tax_zone_id:in=2
2
X-Auth-Token: {{ACCESS_TOKEN}}
3
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.

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

Resources

• Tax Rates and Zones API Reference

Tax Zones reference

• Create tax zones
• Update tax zones
• Get tax zones
• Delete tax zones

Tax Rates reference

• Create tax rates
• Update tax rates
• Get tax rates
• Delete tax rates