BigCommerce
Store Operations
Tax
Tax Properties

Tax Properties for Products

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 tax properties, providers can return more accurate tax quotes. The examples in this guide expand on this use case.

Tax providers may sometimes need multiple inputs that can vary between different types of product. For example, for products with alcohol, the alcohol percentage and the volume sold affect alcohol taxes. As shown in this guide, merchants can provide both pieces of information to tax providers.

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. In contrast, tax properties are fields that contain information about product specifics. Tax providers use these fields to factor product specifics into their calculations.

This guide demonstrates how to use the Tax Properties API. For more, see the Tax Properties API Reference and the Tax Provider API Reference.

Tax properties

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

Create tax properties

First, use the 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.

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"
  },
  {
    "code": "fuel-type",
    "display_name": "Fuel Type",
    "description": "Oil and Natural Gas Industry"
  }  
]

Update tax properties

Send a request to the Update tax properties endpoint to modify a tax property's code, display_name, or description. The request updates only fields that you specify.

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"
  }  
]

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 endpoint. To get only select tax properties, use the id:in query parameter.

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

Delete tax properties

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

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

Product tax properties

After creating a tax property, 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 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.

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 endpoint. Use the same endpoint to modify a product's existing tax properties.

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"
    }
  }
]

Get product tax properties

To get the tax properties attached to a product, send a request to the Get product tax properties endpoint and use the product_id:in query parameter.

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

Delete product tax properties

⚠️

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 endpoint and use the product_id:in query parameter. This disassociates all the tax properties from a product.

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

Tax Quotes

BigCommerce sends product tax properties to request tax estimates 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
POST https://store.example.com/estimate
Authorization: Basic ZGVtbzpwQDU1dzByZA==
Content-Type: application/json
Accept: application/json
 
{
  ...
  "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 and adjust tax quotes.

Resources

Tax Properties reference

Product Tax Properties reference

Tax Provider reference

Catalog reference

Did you find what you were looking for?