Tax attributes

At Taxwire, one of our core values 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. Product attributes describe what is being sold or how the product is used. Customer attributes describe buyer-side exemption status.

Product 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. Some product attributes describe exemption intent. Other product attributes describe facts about the product itself.

Product attribute	Meaning
`_RESALE`	The line item is being purchased for resale. Requires a matching resale customer attribute — see Force resale for the single-sided variant.
`_FORCE_RESALE`	The line item is treated as purchased for resale, with no customer attribute required. See Force resale.
`_DRIVEAWAY`	The vehicle will be titled outside the sale state.
`_NONPROFIT`	The line item is being purchased under nonprofit-qualified treatment.
`_CLEAN_TITLE`	The vehicle has a clean title.
`_SALVAGE_TITLE`	The vehicle has a salvage title.
`_JUNK_TITLE`	The vehicle has a junk title.
`_REBUILT_TITLE`	The vehicle has a rebuilt title.
`_B2C`	The sale is to a consumer rather than a business. Some exemptions apply only to consumer sales — for example New Jersey exempts clothing materials only when sold to a consumer.
`_B2B`	The sale is to a business rather than a consumer.
`_REQUIRED_FOR_DAILY_WORK`	The item is required for the buyer’s occupation. New Jersey exempts occupational clothing such as protective clothing, tool belts and hairnets only when this is set.
`_BABY`	The item is intended for babies. Florida exempts baby and toddler clothing on this basis.
`_TODDLER`	The item is intended for toddlers. Florida exempts baby and toddler clothing on this basis.

Customer attributes

Customer attributes describe buyer-side exemption status, such as a resale certificate, driveaway certificate, or nonprofit status. Customer attributes are passed on the customer.tax_attributes field for a line item. They usually need to be paired with a product attribute because many exemptions depend on both the customer and the item being sold. The examples below are not exhaustive. Resale and driveaway attributes are jurisdiction-specific, and the valid code depends on the customer’s exemption certificate.

Customer attribute examples	Product attribute	Meaning
`RESALE`, `RESALE_USA_TX`, `RESALE_USA_MTC`, `RESALE_USA_SST`, …	`_RESALE`	The customer has a resale certificate and the line item is being purchased for resale.
`DRIVEAWAY_USA_TX`, `DRIVEAWAY_USA_MI`, `DRIVEAWAY_USA_MN`, …	`_DRIVEAWAY`	The customer has a driveaway certificate and the vehicle will be titled outside the sale state.
`NONPROFIT_501_c_3`	`_NONPROFIT`	The customer qualifies as a 501(c)(3) nonprofit and the line item is treated as nonprofit-qualified.

Customer attributes are jurisdiction-specific when the exemption certificate is jurisdiction-specific. For example, use RESALE_USA_TX for a Texas resale certificate and DRIVEAWAY_USA_TX for a Texas driveaway certificate.

Force resale

The standard resale exemption is deliberately double-triggered: it applies only when the customer carries a resale attribute (e.g. RESALE_USA_TX) and the line item carries _RESALE. This is the safe default. A resale certificate on file does not mean every purchase that buyer makes is for resale — a buyer can hold a certificate and still purchase items for their own use, and those sales are taxable. Some catalogs cannot carry product attributes, and some buyers genuinely purchase everything for resale. For those cases, each side of the standard pair has a force variant that triggers on its own:

Attribute	Passed on	Effect
`FORCE_RESALE`	`customer.tax_attributes`	Every line item sold to this customer is treated as purchased for resale.
`_FORCE_RESALE`	`product.tax_attributes`	This line item is treated as purchased for resale, regardless of customer attributes.

Like the standard resale attributes, FORCE_RESALE has jurisdiction-scoped variants (FORCE_RESALE_USA_TX, FORCE_RESALE_USA_MTC, FORCE_RESALE_USA_SST, …). A scoped variant applies only in its own jurisdiction; the unscoped FORCE_RESALE applies in every jurisdiction that has resale rules.

FORCE_RESALE is an unconditional override. Only apply it to customers who never buy for their own use. If a buyer purchases both for resale and for consumption, use the standard RESALE_* + _RESALE pair per line item instead — a force attribute would exempt their retail purchases too.

The same purchase expressed both ways — the standard pair needs a resale attribute on each side, the force variant exempts on the customer attribute alone:

{
    "id": "item_123",
    "quantity": "1",
    "product": {
        "tax_attributes": [
            "TANGIBLE_PERSONAL_PROPERTY._RESALE"
        ]
    },
    "customer": {
        "tax_attributes": [
            "RESALE_USA_TX"
        ]
    },
    "unit_price": "100"
}

{
    "id": "item_123",
    "quantity": "1",
    "product": {
        "tax_attributes": [
            "TANGIBLE_PERSONAL_PROPERTY"
        ]
    },
    "customer": {
        "tax_attributes": [
            "FORCE_RESALE"
        ]
    },
    "unit_price": "100"
}

Resale treatment does not always mean zero tax. In gross-receipts jurisdictions — for example Hawaii’s general excise tax — sales for resale are taxed at a wholesale rate instead of being fully exempt. This applies to both the standard and force variants.

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

For a resale transaction, pass both a product attribute and a customer attribute. The product attribute says this line item is being purchased for resale. The customer attribute says the buyer has a qualifying resale certificate.

{
    "id": "item_123",
    "quantity": "1",
    "product": {
        "tax_attributes": [
            "TANGIBLE_PERSONAL_PROPERTY._RESALE"
        ]
    },
    "customer": {
        "tax_attributes": [
            "RESALE_USA_TX"
        ]
    },
    "unit_price": "100"
}

For a driveaway vehicle transaction, pass _DRIVEAWAY on the product and the matching driveaway customer attribute.

{
    "id": "item_456",
    "quantity": "1",
    "product": {
        "tax_attributes": [
            "MOTOR_VEHICLES.AUTOMOBILES._DRIVEAWAY"
        ]
    },
    "customer": {
        "tax_attributes": [
            "DRIVEAWAY_USA_TX"
        ]
    },
    "unit_price": "2500000"
}

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.

Getting Started

Guides

API details

Calculations

Transactions

Resources

Tax attributes

Tax attributes

Categories

Product attributes

Customer attributes

Force resale

Examples

Marketplace facilitator

Channel sub-attribute

Validation rules

​Tax attributes

​Categories

​Product attributes

​Customer attributes

​Force resale

​Examples

​Marketplace facilitator

​Channel sub-attribute

​Validation rules

Tax attributes

Categories

Product attributes

Customer attributes

Force resale

Examples

Marketplace facilitator

Channel sub-attribute

Validation rules