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

# Apply Tax to Customers and Subscriptions

> Link tax rates to tenants, customers and subscriptions, and choose whether each is added to the price or included in it

A **tax association** is what makes a tax rate collect: it associates the rate with an entity, and carries the two decisions that matter, which rate applies and whether that rate is added on top of your price (`exclusive`) or already inside it (`inclusive`). Tirdad supports associations at three scopes: tenant (default for all customers), customer (overrides tenant for that customer), and subscription (overrides customer for that subscription's invoices).

| Level | Use it when |
| - | - |
| Tenant | Every customer you bill pays this tax by default |
| Customer | This customer pays a tax the rest do not, or is in a different jurisdiction |
| Subscription | One subscription needs different tax treatment from the rest of the customer's |

## Association fields

| Field | Type | Required | Description |
| - | - | - | - |
| `tax_rate_code` | string | Yes | The `code` of the tax rate to link |
| `entity_type` | string | No | `tenant`, `customer`, `subscription`, or `invoice` |
| `entity_id` | string | No | ID of the entity to link |
| `external_customer_id` | string | No | Your own customer ID, usable instead of `entity_id` for customer-level associations |
| `auto_apply` | bool | No | Set to `true` to apply this tax automatically on every new invoice |
| `tax_behavior` | string | No | `inclusive` or `exclusive`. Resolved from the subscription's currency if omitted. |
| `priority` | int | No | Lower number fires first. Default: `0` |
| `currency` | string | No | Scopes this association to a specific currency, e.g. `"USD"` |
| `start_date` | timestamp | No | When the association becomes active. Defaults to now. |
| `end_date` | timestamp | No | When the association expires. Omit for indefinite. |

## Apply to a tenant (default for all customers)

A tenant-level association acts as the default tax for every customer that has no association of its own.

```bash theme={null}
curl -X POST https://api.tirdad.ai/v1/taxes/associations \
  -H "x-api-key: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "tax_rate_code": "TAX_US_CA",
    "entity_type": "tenant",
    "entity_id": "<your_tenant_id>",
    "auto_apply": true,
    "currency": "USD",
    "tax_behavior": "inclusive",
    "priority": 0
  }'
```

**Response**

```json theme={null}
{
  "id": "txa_01abc123",
  "tax_rate_id": "txr_01abc456",
  "entity_type": "tenant",
  "entity_id": "<your_tenant_id>",
  "auto_apply": true,
  "currency": "USD",
  "tax_behavior": "inclusive",
  "priority": 0
}
```

## Apply to a specific customer

Customer-level associations override tenant-level ones for that customer only.

```bash theme={null}
curl -X POST https://api.tirdad.ai/v1/taxes/associations \
  -H "x-api-key: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "tax_rate_code": "TAX_EU_VAT",
    "entity_type": "customer",
    "external_customer_id": "your-customer-id",
    "auto_apply": true,
    "currency": "EUR",
    "tax_behavior": "exclusive",
    "priority": 0
  }'
```

## Apply at subscription creation

Pass `tax_rate_overrides` in the create subscription request to link rates directly to that subscription. These override any customer or tenant associations for that subscription's invoices.

```bash theme={null}
curl -X POST https://api.tirdad.ai/v1/subscriptions \
  -H "x-api-key: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "<customer_id>",
    "plan_id": "<plan_id>",
    "start_date": "2025-01-01T00:00:00Z",
    "tax_rate_overrides": [
      {
        "tax_rate_code": "TAX_US_CA",
        "currency": "USD",
        "tax_behavior": "exclusive"
      }
    ]
  }'
```

> [!NOTE]
>
> When `tax_rate_overrides` is set, tirdad uses only those rates for the
> subscription's invoices. Customer and tenant associations are not inherited.
> Omit `tax_rate_overrides` entirely to inherit from the customer.

**`tax_rate_overrides` fields**

| Field | Type | Required | Description |
| - | - | - | - |
| `tax_rate_code` | string | Yes | The `code` of the tax rate to link |
| `currency` | string | Yes | ISO currency code, e.g. `"USD"` |
| `tax_behavior` | string | No | `inclusive` or `exclusive`. Resolved from the subscription's currency if omitted. |
| `auto_apply` | bool | No | Defaults to `true` |
| `priority` | int | No | Lower number fires first. Default: `0` |
| `metadata` | object | No | Key-value pairs for your own tracking |

## Add or remove tax after subscription creation

Use the subscription modification API with `type: "tax"`.

### Add a tax rate

```bash theme={null}
curl -X POST https://api.tirdad.ai/v1/subscriptions/<subscription_id>/modify/execute \
  -H "x-api-key: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "tax",
    "tax_params": {
      "action": "add",
      "tax_rate_id": "<tax_rate_id>",
      "effective_date": "2025-06-01T00:00:00Z"
    }
  }'
```

`effective_date` is optional. Omit it to apply the change immediately.

### Remove a tax rate

```bash theme={null}
curl -X POST https://api.tirdad.ai/v1/subscriptions/<subscription_id>/modify/execute \
  -H "x-api-key: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "tax",
    "tax_params": {
      "action": "remove",
      "tax_association_id": "<tax_association_id>"
    }
  }'
```

Get the `tax_association_id` from `GET /v1/taxes/associations?entity_type=subscription&entity_id=<subscription_id>`.

Removing a tax association affects only invoices generated after the change. Previously issued invoices are not changed.

### Preview before executing

Swap `/modify/execute` for `/modify/preview` to see the effect without committing:

```bash theme={null}
curl -X POST https://api.tirdad.ai/v1/subscriptions/<subscription_id>/modify/preview \
  -H "x-api-key: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "tax",
    "tax_params": {
      "action": "add",
      "tax_rate_id": "<tax_rate_id>"
    }
  }'
```

## tax\_params fields

| Field | Type | Required | Description |
| - | - | - | - |
| `action` | string | Yes | `add` or `remove` |
| `tax_rate_id` | string | When `action=add` | ID of the tax rate to attach |
| `tax_association_id` | string | When `action=remove` | ID of the tax association to detach |
| `effective_date` | timestamp | No | When the change takes effect. Defaults to now. |

## Multiple tax rates on the same entity

Create one association per rate. Each rate is applied independently to the same taxable base and does not compound.

```bash theme={null}
# State tax (higher priority)
curl -X POST https://api.tirdad.ai/v1/taxes/associations \
  -H "x-api-key: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "tax_rate_code": "TAX_STATE",
    "entity_type": "customer",
    "entity_id": "<customer_id>",
    "auto_apply": true,
    "currency": "USD",
    "priority": 0
  }'

# Federal tax (lower priority)
curl -X POST https://api.tirdad.ai/v1/taxes/associations \
  -H "x-api-key: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "tax_rate_code": "TAX_FEDERAL",
    "entity_type": "customer",
    "entity_id": "<customer_id>",
    "auto_apply": true,
    "currency": "USD",
    "priority": 1
  }'
```

If the taxable amount is \$100, state at 6% adds \$6 and federal at 2% adds \$2 for a total tax of \$8. They do not compound.

## List associations

```bash theme={null}
curl "https://api.tirdad.ai/v1/taxes/associations?entity_type=customer&entity_id=<customer_id>" \
  -H "x-api-key: <API_KEY>"
```

## Update an association

You can update `priority`, `auto_apply`, `tax_behavior`, and `metadata` without deleting and recreating.

```bash theme={null}
curl -X PUT https://api.tirdad.ai/v1/taxes/associations/<tax_association_id> \
  -H "x-api-key: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "auto_apply": false
  }'
```

Setting `auto_apply: false` pauses the tax without removing the record. Set it back to `true` to re-enable.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.