# Tax Rates

A tax rate's name and percentage can't be changed once created. The API
only applies default tax rates to an invoice, subscription, or sales
page when you send `include_default_tax_rates: true`; otherwise you get
exactly the `tax_rates` you send.

To find a tax rate's `id`, use the one returned when you create it, or
read it from an invoice's `tax_rates`.

## The tax rate object

- `id` (string): Example: `0abcDEF1234567890xyzAB`.
- `name` (string)
- `percentage` (string): Percentage as a decimal string, without trailing zeros.
- `is_default` (boolean)
- `created_at` (timestamp): Date and time in UTC. Example: `2024-06-15T12:00:00.000000Z`.
- `updated_at` (timestamp): Date and time in UTC. Example: `2024-06-15T12:00:00.000000Z`.
- `is_deleted` (boolean)

```json
{
  "id": "0abcDEF1234567890xyzAB",
  "name": "QST",
  "percentage": "9.975",
  "is_default": true,
  "created_at": "2024-06-15T12:00:00.000000Z",
  "updated_at": "2024-06-15T12:00:00.000000Z",
  "is_deleted": false
}
```

## Create a tax rate

`POST /tax-rates`

### Request body

- `name` (string, required): Max length 255.
- `percentage` (number, required): Up to 4 decimals. Example: `9.975`. Min 0. Max 100.
- `is_default` (boolean, required)

### Response

- `201`: Created tax rate. Returns a [tax rate object](#the-tax-rate-object).

### Errors

- `400` `request_failed`: Your request could not be processed.
- `400` `api_version_unsupported`: The requested API version is not supported. Current version: 2026-08-21
- `401` `api_key_missing`: The API key is missing.
- `401` `api_key_invalid`: The API key is invalid or has been revoked.
- `403` `api_key_read_only`: This API key is read-only and cannot make write requests.
- `422`: The request body or query parameters are invalid.
- `429`: Too many requests. The limit is 300 requests per 5 minutes.

### Example request

```bash
curl -X POST https://api.tallymark.com/tax-rates \
  -H "Authorization: Bearer $TALLYMARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "QST",
  "percentage": 9.975,
  "is_default": true
}'
```

### Example response

```json
{
  "id": "0abcDEF1234567890xyzAB",
  "name": "QST",
  "percentage": "9.975",
  "is_default": true,
  "created_at": "2024-06-15T12:00:00.000000Z",
  "updated_at": "2024-06-15T12:00:00.000000Z",
  "is_deleted": false
}
```

## Set or unset a tax rate as default

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

Only `is_default` can be changed. A tax rate's name and percentage are
fixed once it's created.

### Path parameters

- `id` (string, required): The tax rate ID. Example: `0abcDEF1234567890xyzAB`.

### Request body

- `is_default` (boolean, required)

### Response

- `200`: Updated tax rate. Returns a [tax rate object](#the-tax-rate-object).

### Errors

- `400` `request_failed`: Your request could not be processed.
- `400` `api_version_unsupported`: The requested API version is not supported. Current version: 2026-08-21
- `401` `api_key_missing`: The API key is missing.
- `401` `api_key_invalid`: The API key is invalid or has been revoked.
- `403` `api_key_read_only`: This API key is read-only and cannot make write requests.
- `404`: The record doesn't exist or was deleted.
- `422`: The request body or query parameters are invalid.
- `429`: Too many requests. The limit is 300 requests per 5 minutes.

### Example request

```bash
curl -X POST https://api.tallymark.com/tax-rates/0abcDEF1234567890xyzAB/update \
  -H "Authorization: Bearer $TALLYMARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "is_default": false
}'
```

### Example response

```json
{
  "id": "0abcDEF1234567890xyzAB",
  "name": "QST",
  "percentage": "9.975",
  "is_default": true,
  "created_at": "2024-06-15T12:00:00.000000Z",
  "updated_at": "2024-06-15T12:00:00.000000Z",
  "is_deleted": false
}
```

## Delete a tax rate

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

Deletes the tax rate. It can no longer be added to invoices,
subscriptions, or sales pages, but those that already use it keep it.
A deleted default tax rate keeps `is_default` but is no longer added
by `include_default_tax_rates`.

### Path parameters

- `id` (string, required): The tax rate ID. Example: `0abcDEF1234567890xyzAB`.

### Response

- `200`: Deleted tax rate (`is_deleted` true). Returns a [tax rate object](#the-tax-rate-object).

### Errors

- `400` `request_failed`: Your request could not be processed.
- `400` `api_version_unsupported`: The requested API version is not supported. Current version: 2026-08-21
- `401` `api_key_missing`: The API key is missing.
- `401` `api_key_invalid`: The API key is invalid or has been revoked.
- `403` `api_key_read_only`: This API key is read-only and cannot make write requests.
- `404`: The record doesn't exist or was deleted.
- `429`: Too many requests. The limit is 300 requests per 5 minutes.

### Example request

```bash
curl -X POST https://api.tallymark.com/tax-rates/0abcDEF1234567890xyzAB/delete \
  -H "Authorization: Bearer $TALLYMARK_API_KEY"
```

### Example response

```json
{
  "id": "0abcDEF1234567890xyzAB",
  "name": "QST",
  "percentage": "9.975",
  "is_default": true,
  "created_at": "2024-06-15T12:00:00.000000Z",
  "updated_at": "2024-06-15T12:00:00.000000Z",
  "is_deleted": false
}
```