Taxes

​

External integration

Let your tax provider handle the complexity of tax logic! We support integrations that allow seamless tax automation.

If you’d like to explore these integrations or be connected to a provider, feel free to contact us.

​

Create taxes at the organization level

Before applying taxes to invoices, you need to create a tax object at the organization level. You can then assign it to billing entities or specific customers.

To create a tax:

# Create a tax object
LAGO_URL="https://api.getlago.com"
API_KEY="__YOUR_API_KEY__"

curl --location --request POST "$LAGO_URL/api/v1/taxes" \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "tax": {
      "name": "French VAT",
      "code": "french_vat",
      "description": "French standard VAT",
      "rate": 20.00
    }
  }'

​

Edit or delete taxes

Taxes can be edited or deleted even if they are already applied to billing entities or customers. However, any change will affect all draft or upcoming invoices linked to that tax.

Available actions:

• Edit: Modify the tax name, code, or rate
• Delete: Remove the tax from your system (irreversible)

​

Apply taxes to objects

When generating invoices, taxes can be applied at various levels and will impact all associated fees (subscriptions, usage-based charges, etc.).

​

At the billing entity level

# Add taxes to a billing entity
curl --location --request PUT "$LAGO_URL/api/v1/billing_entities/{code}" \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "billing_entity": {
      "tax_codes": ["tax_fr", "tax_it"]
    }
  }'

​

At the customer level

# Add taxes to a customer
curl --location --request PUT "$LAGO_URL/api/v1/customers" \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "customer": {
      "code": "acme_inc",
      "tax_codes": ["tax_fr"]
    }
  }'

​

At the plan and charge level

# Add taxes to a plan and its charges
curl --location --request POST "$LAGO_URL/api/v1/plans" \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "plan": {
      "name": "Starter",
      "code": "starter",
      "interval": "monthly",
      "amount_cents": 9900,
      "amount_currency": "USD",
      "tax_codes": ["french_standard_vat"],
      "charges": [
        {
          "billable_metric_code": "user_seat",
          "charge_model": "standard",
          "invoiceable": true,
          "pay_in_advance": false,
          "prorated": false,
          "min_amount_cents": 0,
          "tax_codes": ["french_standard_vat"],
          "properties": {
            "amount": "0.10"
          }
        }
      ]
    }
  }'

​

At the add-on level

# Add tax to an add-on
{
  "add_on": {
    "name": "Setup fee",
    "code": "setup_fee",
    "amount_cents": 100000,
    "amount_currency": "USD",
    "tax_codes": ["french_standard_vat"]
  }
}

​

Tax hierarchy

​

For Subscription Invoices

When generating invoices for subscriptions, taxes are applied in the following order of priority:

1. Billing entity taxes apply to all invoice fees (subscriptions and charges)
2. Customer taxes override billing entity taxes
3. Plan taxes override customer taxes
4. Charge-level taxes override plan taxes, but only affect the specific charge
5. If the customer is linked to a tax provider (e.g., Anrok), the provider’s calculation overrides all other tax levels

​

For one-off invoices

For one-off invoices, the hierarchy is:

1. Organization taxes apply to all fees
2. Customer taxes override organization taxes
3. Add-on taxes override customer taxes for the add-on only
4. Fee-level taxes (set at invoice creation) override add-on-level taxes for the specific fee

​

For prepaid credit invoices

Prepaid credits are considered upfront payments. Therefore, invoices for credit purchases do not include any tax.

​

Auto-detect european taxes with Lago

Lago supports automatic tax detection for European customers.
Refer to our integration guide to set it up.