Skip to main content
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

FieldTypeRequiredDescription
tax_rate_codestringYesThe code of the tax rate to link
entity_typestringNotenant, customer, subscription, or invoice
entity_idstringNoID of the entity to link
external_customer_idstringNoYour own customer ID, usable instead of entity_id for customer-level associations
auto_applyboolNoSet to true to apply this tax automatically on every new invoice
priorityintNoLower number fires first. Default: 0
currencystringNoScopes this association to a specific currency, e.g. "USD"
start_datetimestampNoWhen the association becomes active. Defaults to now.
end_datetimestampNoWhen 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://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://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://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
FieldTypeRequiredDescription
tax_rate_codestringYesThe code of the tax rate to link
currencystringYesISO currency code, e.g. "USD"
auto_applyboolNoDefaults to true
priorityintNoLower number fires first. Default: 0
metadataobjectNoKey-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://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://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://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

FieldTypeRequiredDescription
actionstringYesadd or remove
tax_rate_idstringWhen action=addID of the tax rate to attach
tax_association_idstringWhen action=removeID of the tax association to detach
effective_datetimestampNoWhen 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://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,stateat6100, state at 6% adds 6 and federal at 2% adds 2foratotaltaxof2 for a total tax of 8. They do not compound.

​
List associations

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