Taxes

Overview

Taxes in BoxBilling define rate configurations that can be applied to various entities — customers, subscriptions, plans, and charges. When applied, taxes are automatically calculated and included on invoices. Tax rates are identified by unique codes, making them easy to reference and reuse across your billing setup.

How taxes work

Define tax rate (code + rate)
        │
        ▼
Apply tax to entities ──► customer, subscription,
        │                  plan, charge, or add-on
        ▼
Invoice generation ──► Tax calculated on line items
        │
        ▼
Invoice displays tax breakdown
(taxes_amount_cents on each fee)

Tax properties

Field	Type	Description
id	uuid	Unique tax identifier
code	string	Unique tax code (max 255 chars)
name	string	Display name (max 255 chars)
rate	number	Tax rate as a percentage (e.g., 20.0 for 20%)
description	string?	Optional description
category	string?	Optional category for grouping (max 100 chars)
applied_to_organization	boolean	Whether this tax applies at the organization level (default: false)
created_at	datetime	Creation timestamp
updated_at	datetime	Last update timestamp

Create a tax rate

curl -X POST /v1/taxes/ \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "vat_20",
    "name": "VAT 20%",
    "rate": 20.0,
    "description": "Standard UK VAT rate",
    "category": "vat",
    "applied_to_organization": false
  }'

Response (201):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "code": "vat_20",
  "name": "VAT 20%",
  "rate": "20.0",
  "description": "Standard UK VAT rate",
  "category": "vat",
  "applied_to_organization": false,
  "created_at": "2026-03-08T10:00:00Z",
  "updated_at": "2026-03-08T10:00:00Z"
}

The code must be unique across all taxes. Use descriptive codes like vat_20, gst_10, or sales_tax_ca to make them easy to reference.

Update a tax rate

curl -X PUT /v1/taxes/vat_20 \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "VAT 20% (Standard)",
    "description": "Standard UK VAT rate — updated April 2026"
  }'

All fields are optional — only the fields you include are modified. Taxes are referenced by code in the URL path.

Get a tax rate

curl /v1/taxes/vat_20 \
  -H "Authorization: Bearer $API_KEY"

Delete a tax rate

curl -X DELETE /v1/taxes/vat_20 \
  -H "Authorization: Bearer $API_KEY"

Returns 204 No Content on success. Deleting a tax does not retroactively affect invoices that have already been generated with that tax applied.

List tax rates

curl /v1/taxes/ \
  -H "Authorization: Bearer $API_KEY"

Supports pagination with skip and limit query parameters (default: 100 items, max: 1000). Use order_by to sort results.

Apply a tax to an entity

Taxes are applied to entities — customers, subscriptions, plans, charges, or add-ons — using the taxable_type and taxable_id fields. When a tax is applied to an entity, it is automatically calculated during invoice generation.

curl -X POST /v1/taxes/apply \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tax_code": "vat_20",
    "taxable_type": "customer",
    "taxable_id": "customer-uuid"
  }'

Response (201):

{
  "id": "660e8400-e29b-41d4-a716-446655440000",
  "tax_id": "550e8400-e29b-41d4-a716-446655440000",
  "taxable_type": "customer",
  "taxable_id": "customer-uuid",
  "tax_rate": "20.0",
  "tax_amount_cents": 0,
  "tax_name": "VAT 20%",
  "tax_code": "vat_20",
  "created_at": "2026-03-08T11:00:00Z"
}

Taxable types

Taxes can be applied to different entity levels, and BoxBilling resolves them during invoicing:

Taxable type	Description
customer	Tax applies to all charges for the customer
subscription	Tax applies to all charges within the subscription
plan	Tax applies to all subscriptions using the plan
charge	Tax applies to a specific charge
add_on	Tax applies to a specific add-on

When multiple taxes apply (e.g., a tax on the customer and a tax on the charge), BoxBilling combines them on the resulting invoice line items.

List applied taxes

Retrieve all taxes applied to a specific entity.

# List taxes applied to a customer
curl "/v1/taxes/applied?taxable_type=customer&taxable_id=customer-uuid" \
  -H "Authorization: Bearer $API_KEY"

Both taxable_type and taxable_id are required query parameters.

Remove an applied tax

curl -X DELETE /v1/taxes/applied/{applied_tax_id} \
  -H "Authorization: Bearer $API_KEY"

Returns 204 No Content on success. Removing an applied tax stops it from being calculated on future invoices but does not affect invoices already generated.

Tax application counts

Get a summary of how many entities each tax is applied to.

curl /v1/taxes/application_counts \
  -H "Authorization: Bearer $API_KEY"

Response:

{
  "counts": {
    "vat_20": 45,
    "gst_10": 12,
    "sales_tax_ca": 8
  }
}

Applied entities for a tax

View all entities that a specific tax is applied to.

curl /v1/taxes/vat_20/applied_entities \
  -H "Authorization: Bearer $API_KEY"

Response:

{
  "tax_id": "550e8400-e29b-41d4-a716-446655440000",
  "tax_code": "vat_20",
  "entities": [
    {"taxable_type": "customer", "taxable_id": "customer-uuid-1"},
    {"taxable_type": "subscription", "taxable_id": "subscription-uuid-1"}
  ]
}

Tax-inclusive vs tax-exclusive pricing

How taxes appear on invoices depends on whether charges use tax-inclusive or tax-exclusive pricing:

Mode	Behavior	Example (20% tax on $100 charge)
Tax-exclusive	Tax is added on top of the charge amount	Subtotal: $100 + Tax: $20 = Total: $120
Tax-inclusive	Tax is already included in the charge amount	Subtotal: $83.33 + Tax: $16.67 = Total: $100

Tax-inclusive or tax-exclusive behavior is configured at the charge or plan level. The taxes_amount_cents field on invoices and fees always reflects the calculated tax amount regardless of mode.

How taxes interact with invoices

During invoice generation, BoxBilling resolves all applicable taxes for each line item:

1. Collects taxes applied to the customer, subscription, plan, and individual charges
2. Calculates the tax amount for each fee based on the combined rates
3. Records taxes_amount_cents on each fee and on the invoice total
4. Displays the tax breakdown on the invoice PDF

The taxes_amount_cents field appears on invoices, fees, and credit notes, giving you a consistent view of tax amounts across all billing documents.

Entity relationships

• Invoices — taxes are calculated and recorded as taxes_amount_cents on each fee and the invoice total
• Customers — taxes applied to a customer affect all their charges
• Subscriptions — taxes applied to a subscription affect all charges within it
• Plans — taxes applied to a plan affect all subscriptions using that plan
• Charges — taxes can target individual charges for granular control
• Credit notes — include taxes_amount_cents to reflect the tax portion of credits or refunds

API endpoints

Method	Path	Description
POST	/v1/taxes/	Create a tax rate
GET	/v1/taxes/	List tax rates
GET	/v1/taxes/{code}	Get a tax rate by code
PUT	/v1/taxes/{code}	Update a tax rate
DELETE	/v1/taxes/{code}	Delete a tax rate
POST	/v1/taxes/apply	Apply a tax to an entity
GET	/v1/taxes/applied	List applied taxes for an entity
DELETE	/v1/taxes/applied/{applied_tax_id}	Remove an applied tax
GET	/v1/taxes/application_counts	Get tax application counts
GET	/v1/taxes/{code}/applied_entities	Get entities a tax is applied to