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.
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.
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.
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/jsonDelete 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.
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/jsonProduct 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.
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.
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.
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/jsonDelete product tax properties
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.
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/jsonTax 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:
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.