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

​
Marketplace facilitator

When a sale is facilitated by a marketplace (e.g. Amazon, Etsy, Walmart, Faire, TikTok Shop, Mercado Libre, Rakuten), the marketplace is responsible for collecting and remitting tax — not the seller. This applies across jurisdictions: US sales tax under marketplace-facilitator laws, EU VAT under the deemed-supplier rule, UK VAT, AU/NZ GST, and similar regimes worldwide. Mark such lines by adding the MARKETPLACE attribute to line_item.fulfillment.tax_attributes. MARKETPLACE lines:
  • produce zero seller-side tax, and
  • are excluded from registration thresholds (economic nexus in the US, VAT/GST registration thresholds elsewhere) in jurisdictions that exclude marketplace-facilitated sales from the seller’s own threshold.
The API accepts this flag at face value without further validation. Asserting it correctly is the consumer’s responsibility — misuse is a compliance issue.
{
    "id": "item_123",
    "quantity": "1",
    "fulfillment": {
        "tax_attributes": ["MARKETPLACE"]
    },
    "unit_price": "100"
}

​
Channel sub-attribute

To record the specific marketplace channel (for reporting and filing), append a channel sub-attribute label using the underscore-prefix convention (same shape as DIGITAL_PROPERTY.DIGITAL_SOFTWARE._DOWNLOADED): 
{
    "id": "item_123",
    "quantity": "1",
    "fulfillment": {
        "tax_attributes": ["MARKETPLACE", "_ETSY"]
    },
    "unit_price": "100"
}
Channel labels must be alphanumeric and underscore only ([A-Za-z0-9_]+). Pick any label that matches this charset — there is no fixed enum.

​
Validation rules

The same validation applies to every tax_attributes field on a line item — product.tax_attributes, customer.tax_attributes, seller.tax_attributes, and fulfillment.tax_attributes. Each entry in the list must match ^[A-Za-z0-9_]+(\.[A-Za-z0-9_]+)*$:
  • single node: MARKETPLACE, B2B, _ETSY
  • dotted path of any depth: MARKETPLACE._ETSY, DIGITAL_PROPERTY.DIGITAL_SOFTWARE._DOWNLOADED, DIGITAL_PROPERTY.DIGITAL_SOFTWARE._DOWNLOADED._FROM_CLOUD
The two list shapes below are equivalent — entries are joined with . into a single ltree path before rule matching: 
{ "tax_attributes": ["MARKETPLACE", "_ETSY"] }
{ "tax_attributes": ["MARKETPLACE._ETSY"] }
Rejected at ingest (HTTP 422):
  • empty strings ("")
  • dashes, spaces, or other characters outside [A-Za-z0-9_]
  • leading dot (.LEADING), trailing dot (TRAILING.), or consecutive dots (DOUBLE..DOT)
  • control characters (e.g. null bytes, newlines)
Each tax_attributes list is capped at 20 entries.