> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.taxwire.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tax attributes

> Best practices and examples for calculating taxes accurately

## 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](/resources/product-tax-codes/product-hierarchy) 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:

```json theme={null}
// 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.

<Note>
  The API accepts this flag at face value without further validation. Asserting it correctly is the consumer's responsibility — misuse is a compliance issue.
</Note>

```json theme={null}
{
    "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`):

```json theme={null}
{
    "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:

```json theme={null}
{ "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.