Skip to main content

​
Tax attributes

At Taxwire, one of our core value is simplicity. We developed a taxonomy of product categories that is easy to understand and use while offering the ability to express complex tax rules. There are several types of tax attributes that can be used to calculate taxes.

​
Categories

Categories like the product categories, often referred to as product tax codes are used to generally identify the type of product being sold. Categories are hierarchical. A category can only be expressed in its valid form. For example, you can use DIGITAL_PROPERTY.DIGITAL_SOFTWARE but not DIGITAL_SOFTWARE. You can see the full list of categories in the Product categories section.

​
Attributes

On top of the product categories, we have product attributes that can be used to further refine the tax calculation. Attributes are additive. For example, if you sell a piece of software, you can use the _DOWNLOADED attribute to indicate that the product is downloaded, as opposed to being shipped on a CD or USB stick, which would be the _LOAD_AND_LEAVE attribute. This can materially affect the tax calculation, as the taxability of the product is different for these two attributes in certain jurisdictions. Attributes can be used in any order at the end of a category or by themselves. For example, DIGITAL_PROPERTY.DIGITAL_SOFTWARE._DOWNLOADED is valid but DIGITAL_PROPERTY._DOWNLOADED.DIGITAL_SOFTWARE is not. There is no implied hierarchy or order of importance between attributes, only for categories.

​
Examples

Let’s take the concrete example of a digital software product sold to a customer physically. For example, a video game, sold as a Nintendo Switch cartridge. The category is DIGITAL_PROPERTY.DIGITAL_SOFTWARE and the attribute is _LOAD_AND_LEAVE. So the full expression is DIGITAL_PROPERTY.DIGITAL_SOFTWARE._LOAD_AND_LEAVE. The calculation or transaction API call would include the following line item: 
// Contents of a line item object
{
    "id": "item_123",
    "quantity": "1",
    "product": {
        "tax_attributes": [
            "DIGITAL_PROPERTY.DIGITAL_SOFTWARE._LOAD_AND_LEAVE"
        ]
    },
    "unit_price": "100"
}
🏗️ Coming soon 🏗️ Similarly, you might want to add tax qualifiers to customers of your products. For example, you might want to add a tax qualifier to a customer who is a reseller. You can do this by adding the RESELLER attribute to the customer. 

{
    "id": "item_123",
    "quantity": "1",
    "customer": {
        "tax_attributes": ["RESELLER"]
    },
    "unit_price": "100"
}