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

# Tax and VAT Codes

> Retrieve tax codes and apply them to invoice line items

Use structured tax codes instead of free-text VAT names. Friday validates the code against the business's chart of accounts, calculates line tax when an amount is not supplied, and stores the code on the invoice line item for auditability.

## Fetch Available Codes

Fetch the active codes for the business before creating taxable invoices:

```bash theme={null}
GET https://sandbox.thredfi.com/v1/platform/businesses/{business_id}/tax-codes/
Authorization: Bearer {business_token}
```

Example response:

```json theme={null}
{
  "business_id": "964f4325-3efb-400d-a1bd-8b1f29e828cf",
  "count": 3,
  "tax_codes": [
    {
      "code": "BTW_21",
      "name": "VAT 21% (Standard)",
      "rate": 0.21,
      "purchase_account": "1520",
      "sales_account": "2100",
      "effective_from": "2024-01-01",
      "is_active": true
    },
    {
      "code": "EXEMPT",
      "name": "VAT Exempt",
      "rate": 0,
      "purchase_account": null,
      "sales_account": null,
      "effective_from": "2024-01-01",
      "is_active": true
    }
  ]
}
```

## Create Invoices With Tax Codes

Pass the code on each invoice line item:

```json theme={null}
{
  "external_id": "invoice-2026-001",
  "customer_id": "customer-uuid",
  "invoice_number": "INV-2026-001",
  "sent_at": "2026-06-11T10:00:00Z",
  "due_at": "2026-07-11T10:00:00Z",
  "line_items": [
    {
      "external_id": "line-001",
      "description": "Consulting services",
      "quantity": 1,
      "unit_price": 10000,
      "tax_code": "BTW_21"
    }
  ]
}
```

When `tax_code` is valid and no explicit tax amount is supplied, Friday calculates the tax from the configured rate and persists the code on the line item. The same `tax_code` field is returned in invoice line-item responses.

## sales\_taxes Compatibility

If your system already sends structured tax lines, include `sales_taxes[].code`:

```json theme={null}
{
  "description": "Consulting services",
  "quantity": 1,
  "unit_price": 10000,
  "sales_taxes": [
    {
      "code": "BTW_21",
      "name": "VAT 21% (Standard)",
      "amount": 2100
    }
  ]
}
```

`sales_taxes.name` is accepted only when a `code` is also present. The code is the canonical value used for validation and audit.

## Validation Rules

* Unknown or inactive tax codes return a 4xx validation error.
* Conflicting line-level codes, such as `tax_code: "BTW_21"` plus `sales_taxes[].code: "EXEMPT"`, return a validation error.
* If you provide both a tax code and explicit `sales_taxes[].amount`, the amount must match the configured tax-code rate within rounding tolerance.
* Customers marked `tax_exempt: true` reject taxable invoice line items. Use `EXEMPT` or another zero-rated code.
* Tax-exempt errors identify the customer and the offending `line_items[index]`.

<Note>
  Do not infer VAT treatment from the tax name alone. Always fetch and send a valid `code`.
</Note>