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.
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 and the Tax Provider API Reference.
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.
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.
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.
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.
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.
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 are not stored on or retrievable with the product object.
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.
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.
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.
See the Tax Customers API to attach tax properties to a customer.
BigCommerce sends product and customer 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:
BigCommerce also sends product tax properties to commit and adjust tax quotes.