> 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 Properties

The Tax Properties API allows merchants to vary the tax information they send to tax providers for tax calculation.

In some jurisdictions, tax rates for products vary by product composition. For example, accurate taxation of alcohol may require information about alcohol percentage. Using product tax properties, providers can return more accurate tax quotes.

Tax calculations can also be affected by customer data that exists outside the standard BigCommerce customer model. For example, a tax provider might apply a tax exemption based on exemption certificates linked to a third-party ERP customer ID. By using customer tax properties, providers can adjust the tax quote accordingly for the customer involved in the transaction.

The examples in this guide expand on these product and customer use cases.

> **Note**
>
> #### Tax properties versus tax codes
>
> A tax code is a single code that tax providers use to invoke specific rules when calculating tax on a product or customer.
> In contrast, tax properties are fields that contain information about product or customer specifics. Tax providers use these fields to factor product or customer specifics into their calculations.

This guide demonstrates how to use the Tax Properties API. For more, see the [Tax Properties API Reference](/developer/api-reference/rest/admin/management/tax/tax-properties) and the [Tax Provider API Reference](/developer/docs/integrations/tax-providers).

## Tax properties

Tax properties rely on `code`s specific to third-party tax providers. Consult a tax provider's documentation to identify supported `code`s. The `code`s used in tax properties are not tax codes. See [Tax properties versus tax codes](#tax-properties-versus-tax-codes).

### Create tax properties

First, use the [Create tax properties](/developer/api-reference/rest/admin/management/tax/tax-properties/create-tax-properties) endpoint to add tax properties to the store. This requires the tax provider's `code` and a `display_name` that shoppers may see, depending on your theme, settings, and jurisdiction.  Optionally, you can add a description.

The response provides an `id` for each tax property. Use the `id` to get, update, or delete a specific tax property.

#### Request

**`Example request: Create tax properties`**

```http title="Example request: Create tax properties"
POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/tax/properties
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json

[
  {
    "code": "alcohol-percentage",
    "display_name": "Alcohol Percentage",
    "description": "Beverage Industry",
    "type": "PRODUCT"
  },
  {
    "code": "erp-external-id",
    "display_name": "ERP Customer ID",
    "description": "External ID used to link customer records with ERP systems",
    "type": "CUSTOMER"
  }
]
```

#### Response

**`Example response: Create tax properties`**

```json title="Example response: Create tax properties"
{
  "data": [
    {
      "id": 1,
      "code": "alcohol-percentage",
      "display_name": "Alcohol Percentage",
      "description": "Beverage Industry",
      "created_at": "2022-05-17T14:25:21+00:00",
      "updated_at": "2022-05-17T14:25:21+00:00",
      "type": "PRODUCT"
    },
    {
      "id": 2,
      "code": "erp-external-id",
      "display_name": "ERP Customer ID",
      "description": "External ID used to link customer records with ERP systems",
      "created_at": "2022-05-17T14:25:21+00:00",
      "updated_at": "2022-05-17T14:25:21+00:00",
      "type": "CUSTOMER"
    }
  ],
  "meta": {}
}
```

### Update tax properties

Send a request to the [Update tax properties](/developer/api-reference/rest/admin/management/tax/tax-properties/update-tax-properties) endpoint to modify a tax property's `code`, `display_name`, or `description`. The request updates only fields that you specify.

#### Request

**`Example request: Update tax properties`**

```http title="Example request: Update tax properties"
PUT https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/tax/properties
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json

[
  {
    "id": 1,
    "description": "Alcohol Industry"
  }
]
```

#### Response

**`Example response: Update tax properties`**

```json title="Example response: Update tax properties"
{
  "data": [
    {
      "id": 1,
      "code": "alcohol-percentage",
      "display_name": "Alcohol Percentage",
      "description": "Alcohol Industry",
      "created_at": "2022-05-17T14:25:21+00:00",
      "updated_at": "2022-05-21T14:25:21+00:00",
      "type": "PRODUCT"
    }
  ],
  "meta": {}
}
```

### Get tax properties

This endpoint supports batch operations. You can get all the tax properties in your store, or only specific tax properties. To get tax properties, send a request to the [Get tax properties](/developer/api-reference/rest/admin/management/tax/tax-properties/get-tax-properties) endpoint. To get only select tax properties, use the `id:in` query parameter.

#### Request

**`Example request: Get tax properties`**

```http title="Example request: Get tax properties"
GET https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/tax/properties?id:in=1,2
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json
```

#### Response

**`Example response: Get tax properties`**

```json title="Example response: Get tax properties"
{
  "data": [
    {
      "id": 1,
      "code": "alcohol-percentage",
      "display_name": "Alcohol Percentage",
      "description": "Alcohol Industry",
      "created_at": "2022-05-17T14:25:21+00:00",
      "updated_at": "2022-05-21T14:25:21+00:00",
      "type": "PRODUCT"
    },
    {
      "id": 2,
      "code": "erp-external-id",
      "display_name": "ERP Customer ID",
      "description": "External ID used to link customer records with ERP systems",
      "created_at": "2022-05-17T14:25:21+00:00",
      "updated_at": "2022-05-17T14:25:21+00:00",
      "type": "CUSTOMER"
    }
  ],
  "meta": {
    "pagination": {
      "total": 2,
      "count": 2,
      "per_page": 50,
      "current_page": 1,
      "total_pages": 1,
      "links": {
        "current": "?page=1&limit=50"
      }
    }
  }
}
```

### Delete tax properties

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

#### Request

**`Example request: Delete tax properties`**

```http title="Example request: Delete tax properties"
DELETE https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/tax/properties?id:in=2
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json
```

#### Response

**`Example response: Delete tax properties`**

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

## Product tax properties

After [creating a tax property](#create-tax-properties), you can attach it to a base product to create a product tax property. To do so, specify the product using its `product_id`. The `product_id` is the `id` from the [Get all products](/developer/api-reference/rest/admin/catalog/products/get-products) endpoint.

You can add multiple tax properties to a single product. The following example shows tax properties attached to alcohol products. In this example, the tax rate of alcohol products varies by both alcohol percentage and net volume.

> **Note**
>
> #### Tax properties aren't product properties
>
> Tax properties are not stored on or retrievable with the product object.

### Update product with tax properties

To attach tax properties to a product, send a request to the [Update product tax properties](/developer/api-reference/rest/admin/management/tax/product-tax-properties/update-product-tax-properties) endpoint. Use the same endpoint to modify a product's existing tax properties.

#### Request

**`Example request: Update product with tax properties`**

```http title="Example request: Update product with tax properties"
PUT https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/tax/products/properties
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json

[
  {
    "product_id": 113,
    "tax_properties": {
      "alcohol-percentage": "4.9",
      "netvolume-milliliters": "400"
    }
  },
  {
    "product_id": 117,
    "tax_properties": {
      "alcohol-percentage": "10",
      "netvolume-milliliters": "200"
    }
  }
]
```

#### Response

**`Example response: Update product with tax properties`**

```json title="Example response: Update product with tax properties"
{
  "data": [
    {
      "product_id": 113,
      "tax_properties": {
        "alcohol-percentage": "4.9",
        "netvolume-milliliters": "400"
      }
    },
    {
      "product_id": 117,
      "tax_properties": {
        "alcohol-percentage": "10",
        "netvolume-milliliters": "200"
      }
    }
  ],
  "meta": {
    "pagination": {
      "total": 2,
      "count": 2,
      "per_page": 50,
      "current_page": 1,
      "total_pages": 1,
      "links": {
        "current": "?page=1&limit=50"
      }
    }
  }
}
```

### Get product tax properties

To get the tax properties attached to a product, send a request to the [Get product tax properties](/developer/api-reference/rest/admin/management/tax/product-tax-properties/get-products-tax-properties) endpoint and use the `product_id:in` query parameter.

#### Request

**`Example request: Get product tax properties`**

```http title="Example request: Get product tax properties"
GET https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/tax/products/properties?product_id:in=113,117
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json
```

#### Response

**`Example response: Get product tax properties`**

```json title="Example response: Get product tax properties"
{
  "data": [
    {
      "product_id": 113,
      "tax_properties": {
        "alcohol-percentage": "4.9",
        "netvolume-milliliters": "400"
      }
    },
    {
      "product_id": 117,
      "tax_properties": {
        "alcohol-percentage": "10",
        "netvolume-milliliters": "200"
      }
    }
  ],
  "meta": {
    "pagination": {
      "total": 2,
      "count": 2,
      "per_page": 50,
      "current_page": 1,
      "total_pages": 1,
      "links": {
        "current": "?product_id%3Ain=113%2C117&page=1&limit=50"
      }
    }
  }
}
```

### Delete product tax properties

> **Note**
>
> #### Batch deletion
>
> This endpoint removes **all** tax properties from a given product.

To remove tax properties from a product, send a request to the [Delete product tax properties](/developer/api-reference/rest/admin/management/tax/product-tax-properties/delete-product-tax-properties) endpoint and use the `product_id:in` query parameter. This disassociates all the tax properties from a product.

#### Request

**`Example request: Delete product tax properties`**

```http title="Example request: Delete product tax properties"
DELETE https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/tax/products/properties?product_id:in=117
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json
```

#### Response

**`Example response: Delete product tax properties`**

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

## Customer tax properties

See the [Tax Customers API](/developer/docs/admin/store-configuration/tax/tax-customers) to attach tax properties to a customer.

## Tax Quotes

BigCommerce sends product and customer tax properties to request [tax estimates](/developer/api-reference/rest/integrations/tax-provider/estimate-taxes) from a provider. The requests include tax properties for each item in a consignment.

The following request uses the Tax Provider API:

**`Example request: Get a tax estimate`**

```http title="Example request: Get a tax estimate" showLineNumbers={false}
POST https://store.example.com/estimate
Authorization: Basic ZGVtbzpwQDU1dzByZA==
Content-Type: application/json
Accept: application/json

{
  "customer": {
    "customer_id": "12345",
    "customer_group_id": "1",
    "taxability_code": "",
    "tax_properties": [
      {
        "code": "tax-exemption-status",
        "value": "exempt"
      },
      {
        "code": "erp-external-id",
        "value": "CUST-001"
      }
    ]
  },
  ...
  "items": [
    {
      "id": "1",
      "price": {
        "amount": 10.0,
        "tax_inclusive": false
      },
      "quantity": 1,
      "tax_class": {
        "code": "custom-tax",
        "class_id": "1",
        "name": "Custom Tax"
      },
      "tax_properties": [
        {
          "code": "alcohol-percentage",
          "value": "4.9"
        },
        {
          "code": "netvolume-milliliters",
          "value": "400"
        }
      ],
      "type": "item",
      "wrapping": null
    }
  ]
  ...
}
```

BigCommerce also sends product tax properties to [commit](/developer/api-reference/rest/integrations/tax-provider/commit-tax-quote) and [adjust tax quotes](/developer/api-reference/rest/integrations/tax-provider/adjust-tax-quote).

## Resources

* [Tax Properties API Reference](/developer/api-reference/rest/admin/management/tax/tax-properties)
* [Tax Provider API Reference](/developer/docs/integrations/tax-providers)

### Tax Properties reference

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

### Product Tax Properties reference

* [Create and update product tax properties](/developer/api-reference/rest/admin/management/tax/product-tax-properties/update-product-tax-properties)
* [Get product tax properties](/developer/api-reference/rest/admin/management/tax/product-tax-properties/get-products-tax-properties)
* [Delete product tax properties](/developer/api-reference/rest/admin/management/tax/product-tax-properties/delete-product-tax-properties)

### Tax Provider reference

* [Create a tax estimate](/developer/api-reference/rest/integrations/tax-provider/estimate-taxes)
* [Create a tax commit](/developer/api-reference/rest/integrations/tax-provider/commit-tax-quote)
* [Create a tax adjustment](/developer/api-reference/rest/integrations/tax-provider/adjust-tax-quote)

### Catalog reference

* [Get all products](/developer/api-reference/rest/admin/catalog/products/get-products)