> This page is for Developer.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.bigcommerce.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server.

# Tax Rates and Tax Zones

[Tax rates](https://support.bigcommerce.com/s/article/Manual-Tax-Setup?language=en_US#tax-rate) are percentages a store uses to calculate taxes due for products and services. Tax zones are geographic regions defined in a store. [Tax zones](https://support.bigcommerce.com/s/article/Manual-Tax-Setup?language=en_US#tax-zone) 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](https://support.bigcommerce.com/s/article/Manual-Tax-Setup?language=en_US) for a store. For more information, see the [Tax Rates and Zones API Reference](/developer/api-reference/rest/admin/management/tax/tax-rates).

## 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.

> **Note**
>
> #### 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](/developer/api-reference/rest/admin/management/tax/tax-zones/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.

#### Request

**`Example request: Create tax zones`**

```http title="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
      ]
    }
  }
]
```

#### Response

**`Example response: Create tax zones`**

```json title="Example response: Create tax zones"
{
  "data": [
    {
      "id": 2,
      "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"
            ],
            "postal_codes": []
          },
          {
            "country_code": "AU",
            "subdivision_codes": [
              "WA",
              "VIC"
            ],
            "postal_codes": []
          }
        ],
        "customer_groups": [
          0
        ]
      }
    }
  ],
  "meta": {}
}
```

### Update tax zones

To modify a tax zone, send a request to the [Update tax zones](/developer/api-reference/rest/admin/management/tax/tax-zones/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.

#### Request

**`Example request: Update tax zones`**

```http title="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
      ]
    }
  }
]
```

#### Response

**`Example response: Update tax zones`**

```json title="Example response: Update tax zones"
{
  "data": [
    {
      "id": 2,
      "name": "example zone",
      "enabled": false,
      "price_display_settings": {
        "show_inclusive": false,
        "show_both_on_detail_view": false,
        "show_both_on_list_view": false
      },
      "shopper_target_settings": {
        "locations": [
          {
            "country_code": "AR",
            "subdivision_codes": [
              "T",
              "V"
            ],
            "postal_codes": []
          },
          {
            "country_code": "AU",
            "subdivision_codes": [
              "WA",
              "VIC"
            ],
            "postal_codes": []
          }
        ],
        "customer_groups": [
          2
        ]
      }
    }
  ],
  "meta": {}
}
```

> **Note**
>
> #### 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](/developer/api-reference/rest/admin/management/tax/tax-zones/get-tax-zones) returns all tax zones by default. To return select tax zones, include the `id:in` query parameter.

#### Request

**`Example request: Get tax zones`**

```http title="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
```

#### Response

**`Example response: Get tax zones`**

```json title="Example response: Get tax zones"
{
  "data": [
    {
      "id": 2,
      "name": "example zone",
      "enabled": false,
      "price_display_settings": {
        "show_inclusive": false,
        "show_both_on_detail_view": false,
        "show_both_on_list_view": false
      },
      "shopper_target_settings": {
        "locations": [
          {
            "country_code": "AR",
            "subdivision_codes": [
              "T",
              "V"
            ],
            "postal_codes": []
          },
          {
            "country_code": "AU",
            "subdivision_codes": [
              "WA",
              "VIC"
            ],
            "postal_codes": []
          }
        ],
        "customer_groups": [
          2
        ]
      }
    }
  ],
  "meta": {}
}
```

### Delete tax zones

To delete tax zones, send a request to the [Delete tax zones](/developer/api-reference/rest/admin/management/tax/tax-zones/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.

#### Request

**`Example request: Delete tax zones`**

```http title="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
```

#### Response

**`Example response: Delete tax zones`**

```http title="Example response: Delete tax zones"
HTTP 204 No content
```

## 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](/developer/api-reference/rest/admin/management/tax/tax-rates/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](/developer/api-reference/rest/admin/management/tax/tax-zones/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.

#### Request

**`Example request: Create tax rates`**

```http title="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
  }
]
```

#### Response

**`Example response: Create tax rates`**

```json title="Example response: Create tax rates"
{
  "data": [
    {
      "class_rates": [
        {
          "rate": 5,
          "tax_class_id": 0
        },
        {
          "rate": 5,
          "tax_class_id": 1
        }
      ],
      "enabled": true,
      "id": 3,
      "name": "Sales Tax",
      "priority": 1,
      "tax_zone_id": 2
    }
  ]
}
```

### Update tax rates

To update tax rates, send a request to the [Update tax rates](/developer/api-reference/rest/admin/management/tax/tax-rates/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](/developer/api-reference/rest/admin/management/tax/tax-zones/get-tax-zones) endpoint.

#### Request

**`Example request: Update tax rates`**

```http title="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
  }
]
```

#### Response

**`Example response: Update tax rates`**

```json title="Example response: Update tax rates"
{
  "data": [
    {
      "class_rates": [
        {
          "rate": 10,
          "tax_class_id": 0
        },
        {
          "rate": 5,
          "tax_class_id": 1
        }
      ],
      "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](/developer/api-reference/rest/admin/management/tax/tax-rates/get-tax-rates) endpoint. To get the tax rates for a subset of zones, pass a comma-separated string of the tax zone `id`s using the `tax_zone_id:in` query parameter.

#### Request

**`Example request: Get tax rates`**

```http title="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
```

#### Response

**`Example response: Get tax rates`**

```json title="Example response: Get tax rates"
{
  "data": [
    {
      "class_rates": [
        {
          "rate": 10,
          "tax_class_id": 0
        },
        {
          "rate": 5,
          "tax_class_id": 1
        }
      ],
      "enabled": false,
      "id": 3,
      "name": "Excise Tax",
      "priority": 2,
      "tax_zone_id": 4
    }
  ]
}
```

### Delete tax rates

To delete tax rates, send a request to the [Delete tax rates](/developer/api-reference/rest/admin/management/tax/tax-rates/delete-tax-rates) endpoint. Use the `id:in` query parameter to specify the tax rates you want to delete.

#### Request

**`Example request: Delete tax rates`**

```http title="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
```

#### Response

**`Example response: Delete tax rates`**

```http title="Example response: Delete tax rates"
HTTP 204 No content
```

## Resources

* [Tax Rates and Zones API Reference](/developer/api-reference/rest/admin/management/tax/tax-rates)

### Tax Zones reference

* [Create tax zones](/developer/api-reference/rest/admin/management/tax/tax-zones/create-tax-zones)
* [Update tax zones](/developer/api-reference/rest/admin/management/tax/tax-zones/update-tax-zones)
* [Get tax zones](/developer/api-reference/rest/admin/management/tax/tax-zones/get-tax-zones)
* [Delete tax zones](/developer/api-reference/rest/admin/management/tax/tax-zones/delete-tax-zones)

### Tax Rates reference

* [Create tax rates](/developer/api-reference/rest/admin/management/tax/tax-rates/create-tax-rates)
* [Update tax rates](/developer/api-reference/rest/admin/management/tax/tax-rates/update-tax-rates)
* [Get tax rates](/developer/api-reference/rest/admin/management/tax/tax-rates/get-tax-rates)
* [Delete tax rates](/developer/api-reference/rest/admin/management/tax/tax-rates/delete-tax-rates)