> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flexprice.io/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. Manage post-creation changes via the subscription modification API.

A **tax association** is the link between a tax rate and an entity. flexprice 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).

## 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                  |
| `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.flexprice.io/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",
    "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",
  "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.flexprice.io/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",
    "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.flexprice.io/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"
      }
    ]
  }'
```

<Info>
  When `tax_rate_overrides` is set, flexprice 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.
</Info>

**`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"`        |
| `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.flexprice.io/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.flexprice.io/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.flexprice.io/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.flexprice.io/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.flexprice.io/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.flexprice.io/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`, and `metadata` without deleting and recreating.

```bash theme={null}
curl -X PUT https://api.flexprice.io/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.

## Common patterns

**Exempt a specific customer from tax**
Create no customer-level associations and ensure no tenant associations set to auto-apply are inherited. Customers with no resolvable active association generate invoices with zero tax.

**Give one subscription different tax treatment**
Use `tax_rate_overrides` at subscription creation. The customer's associations remain unchanged for their other subscriptions.

**Stop a tax mid-lifecycle**
Use the modification API with `action: "remove"`. Pass the `tax_association_id` from listing the subscription's associations.