Apply Tax to Customers and Subscriptions

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.

curl -X POST https://us.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

{
  "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.

curl -X POST https://us.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.

curl -X POST https://us.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"
      }
    ]
  }'

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.

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

curl -X POST https://us.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

curl -X POST https://us.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:

curl -X POST https://us.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.

# State tax (higher priority)
curl -X POST https://us.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://us.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

curl "https://us.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.

curl -X PUT https://us.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.

Introduction

Getting Started

Connect

Event Ingestion

Product Catalogue

Scenarios

Customers

Checkout

Subscriptions

Wallet

Invoices

Webhooks

Settings

Collectors

Data Exports

RBAC

Cookbooks

AI Cost Tracking

Contributing Guide

Exportable UI

Apply Tax to Customers and Subscriptions

Association fields

Apply to a tenant (default for all customers)

Apply to a specific customer

Apply at subscription creation

Add or remove tax after subscription creation

Add a tax rate

Remove a tax rate

Preview before executing

tax_params fields

Multiple tax rates on the same entity

List associations

Update an association

Common patterns

​Association fields

​Apply to a tenant (default for all customers)

​Apply to a specific customer

​Apply at subscription creation

​Add or remove tax after subscription creation

​Add a tax rate

​Remove a tax rate

​Preview before executing

​tax_params fields

​Multiple tax rates on the same entity

​List associations

​Update an association

​Common patterns

Association fields

Apply to a tenant (default for all customers)

Apply to a specific customer

Apply at subscription creation

Add or remove tax after subscription creation

Add a tax rate

Remove a tax rate

Preview before executing

tax_params fields

Multiple tax rates on the same entity

List associations

Update an association

Common patterns