# Tax

> Configure tax rates and tax codes for invoices and bills.

- **Category:** Guides
- HTML version: https://www.ondayzero.com/docs/guides/tax
- All guides: https://www.ondayzero.com/docs/guides/index.md
- Endpoint catalog: https://www.ondayzero.com/docs/reference/index.md

---

# Tax

DayZero supports configurable **tax rates** (the percentages, by jurisdiction) and **tax codes** (whether a customer, product or line is taxable at all). Both apply to invoices and bills.

## Tax Rates

Tax rates define specific tax percentages by jurisdiction and where the collected tax is posted.

### Create a Tax Rate

```bash
curl -X POST "https://api.ondayzero.com/api/v1/tax/rates" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "California Sales Tax",
    "rate": 0.0725,
    "tax_type": "sales",
    "country": "US",
    "state": "CA",
    "is_default": false
  }'
```

> `rate` is a **decimal fraction**, not a percentage: `0.0725` = 7.25%.

| Field | Type | Description |
|-------|------|-------------|
| `name` | string | Display name (required) |
| `rate` | number | Decimal rate, e.g. `0.0725` (required) |
| `tax_type` | string | `sales` (default), `use`, `vat`, `gst`, `hst`, `pst` |
| `country` / `state` / `county` / `city` | string | Jurisdiction; `country` defaults to `US` |
| `tax_liability_ledger_id` | UUID | Liability ledger the collected tax posts to (a default is used if omitted) |
| `is_default` | boolean | Make this the business default rate |

### List Tax Rates

```bash
curl "https://api.ondayzero.com/api/v1/tax/rates?active_only=true&state=CA" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID"
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `active_only` | boolean | Only return active rates (default: `true`) |
| `country` | string | Filter by country code |
| `state` | string | Filter by state/region |

### Get Default Rate

```bash
curl "https://api.ondayzero.com/api/v1/tax/rates/default" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID"
```

`PUT /api/v1/tax/rates/{rate_id}` updates any field, including `is_active` and `is_default`.

## Tax Codes

Tax codes classify *what* is taxable — `TAXABLE`, `EXEMPT`, `RESALE` — independently of the rate applied. Assign them to customers, products and line items.

### Create a Tax Code

```bash
curl -X POST "https://api.ondayzero.com/api/v1/tax/codes" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "NONPROFIT",
    "name": "Non-profit exempt",
    "description": "501(c)(3) customers with an exemption certificate on file",
    "is_taxable": false
  }'
```

`code` and `name` are required; `is_taxable` defaults to `true`.

### List Tax Codes

```bash
curl "https://api.ondayzero.com/api/v1/tax/codes?active_only=true" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID"
```

### Seed Defaults

Populate the standard codes — `TAXABLE`, `EXEMPT`, `NONTAXABLE`, `RESALE` — if the business has none yet:

```bash
curl -X POST "https://api.ondayzero.com/api/v1/tax/codes/seed-defaults" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID"
```

## AI Rate Suggestions

Get AI-powered tax rate suggestions based on your business location and type:

```bash
curl -X POST "https://api.ondayzero.com/api/v1/tax/suggest-rates" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID"
```

Suggestions are returned for review — nothing is created until you `POST /api/v1/tax/rates` with the ones you want.

## Deleting Rates and Codes

Delete (deactivate) a tax rate or code:

```bash
curl -X DELETE "https://api.ondayzero.com/api/v1/tax/rates/{rate_id}" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID"
```

The same works for `DELETE /api/v1/tax/codes/{code_id}`. This performs a soft deactivation (`is_active: false`) — the rate or code remains in historical records but is no longer offered for new documents. Reactivate with `PUT … {"is_active": true}`.

If an integration import (Shopify, Square, QuickBooks…) created duplicate rates or codes, `POST /api/v1/tax/dedupe-imported` deactivates the duplicates.