# Tax rates

> Create, retrieve, update, and list tax rates for invoices and subscriptions.

A tax rate represents a named percentage applied to invoice line items and subscriptions. You can
attach one or more tax rates to a subscription or invoice item to calculate tax automatically.

> **Illustrative content.** Hand-authored to demonstrate the Standard/Advanced pattern; the production
> page will be generated from the VINR OpenAPI spec (roadmap item #1). Field names are representative.

## The tax rate object

- **id** `string` — Unique identifier for the tax rate, e.g. `txr_4Hm9eLsV`.
- **display\_name** `string` — The name shown to customers on invoices, e.g. `"VAT"`.
- **percentage** `float` — The tax rate as a decimal percentage, e.g. `20.0` for 20%.
- **inclusive** `boolean` — When `true`, the tax is included in the stated price. When `false`, tax is added on top.
  Defaults to `false`.
- **active** `boolean` — Whether this tax rate can be applied to new invoices. Defaults to `true`.
- **country** `string` — Two-letter ISO 3166-1 country code this rate applies to, e.g. `"DE"`. Optional.
- **created** `integer` — Unix timestamp of when the tax rate was created, e.g. `1716300000`.

## Create a tax rate

Pass a `display_name`, `percentage`, and optionally `inclusive` and `country` to create a tax rate.

`POST /v1/tax-rates`

```bash
curl -X POST https://api.vinr.com/v1/tax-rates \
-H "X-Api-Key: $VINR_SECRET_KEY" \
-d display_name=VAT \
-d percentage=20.0 \
-d inclusive=false \
-d country=DE
```

```js
import { Vinr } from '@vinr/sdk';

const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

const taxRate = await vinr.taxRates.create({
display_name: 'VAT',
percentage: 20.0,
inclusive: false,
country: 'DE',
});
```

```python
import vinr

tax_rate = vinr.TaxRate.create(
  display_name="VAT",
  percentage=20.0,
  inclusive=False,
  country="DE",
)
```

```ruby
tax_rate = Vinr::TaxRate.create(
display_name: 'VAT',
percentage: 20.0,
inclusive: false,
country: 'DE',
)
```

```json
{
"id": "txr_4Hm9eLsV",
"display_name": "VAT",
"percentage": 20.0,
"inclusive": false,
"active": true,
"country": "DE",
"created": 1716300000
}
```

## Retrieve a tax rate

`GET /v1/tax-rates/{id}`

```bash
curl https://api.vinr.com/v1/tax-rates/txr_4Hm9eLsV \
-H "X-Api-Key: $VINR_SECRET_KEY"
```

```js
import { Vinr } from '@vinr/sdk';

const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

const taxRate = await vinr.taxRates.retrieve('txr_4Hm9eLsV');
```

```python
import vinr

tax_rate = vinr.TaxRate.retrieve("txr_4Hm9eLsV")
```

```ruby
tax_rate = Vinr::TaxRate.retrieve('txr_4Hm9eLsV')
```

```json
{
"id": "txr_4Hm9eLsV",
"display_name": "VAT",
"percentage": 20.0,
"inclusive": false,
"active": true,
"country": "DE",
"created": 1716300000
}
```

## Update a tax rate

Only `active` can be changed after creation. To correct the percentage or display name, create a
new tax rate and archive the old one.

`POST /v1/tax-rates/{id}`

```bash
curl -X POST https://api.vinr.com/v1/tax-rates/txr_4Hm9eLsV \
-H "X-Api-Key: $VINR_SECRET_KEY" \
-d active=false
```

```js
import { Vinr } from '@vinr/sdk';

const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

const taxRate = await vinr.taxRates.update('txr_4Hm9eLsV', { active: false });
```

```python
import vinr

tax_rate = vinr.TaxRate.modify("txr_4Hm9eLsV", active=False)
```

```ruby
tax_rate = Vinr::TaxRate.update('txr_4Hm9eLsV', active: false)
```

```json
{
"id": "txr_4Hm9eLsV",
"display_name": "VAT",
"percentage": 20.0,
"inclusive": false,
"active": false,
"country": "DE",
"created": 1716300000
}
```

## List tax rates

`GET /v1/tax-rates`

```bash
curl "https://api.vinr.com/v1/tax-rates?active=true&limit=10" \
-H "X-Api-Key: $VINR_SECRET_KEY"
```

```js
import { Vinr } from '@vinr/sdk';

const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

const taxRates = await vinr.taxRates.list({ active: true, limit: 10 });
```

```python
import vinr

tax_rates = vinr.TaxRate.list(active=True, limit=10)
```

```ruby
tax_rates = Vinr::TaxRate.list(active: true, limit: 10)
```

```json
{
"object": "list",
"data": [
  {
    "id": "txr_4Hm9eLsV",
    "display_name": "VAT",
    "percentage": 20.0,
    "inclusive": false,
    "active": true,
    "country": "DE",
    "created": 1716300000
  }
],
"has_more": false
}
```

## Related events

`tax_rate.created` and `tax_rate.updated`. See [Events](/docs/api-reference/events).