Alguna Tax

Alguna Tax is the built-in tax engine. You create tax rules — a country, optionally a state or province, a rate, a tax type, and a taxability reason — under each legal entity, and Alguna applies the most specific matching rule to every invoice line based on the customer’s billing address. Use it when your tax obligations are simple enough to express as a short list of jurisdictions and rates, and you would rather own the rules than pay for an engine. Alguna Tax does not use tax codes and does not vary tax by product. If you need per-product taxability, nexus tracking, or rates kept current for you, connect an external tax provider instead. The choice is per legal entity; see the Tax overview for what both engines put on an invoice and for the POST /tax/calculations API, which uses whichever engine the entity has.

---

​

Create a tax rule

Rules belong to a legal entity and are managed in the dashboard under Tax → Tax Rates. There is no public API for rules.

1. Open Tax → Tax Rates and click Create Rule.
2. Configure it:
   • Country — required.
   • State — a state or province, for jurisdictions that tax below country level. Leave empty for a country-wide rule.
   • Tax rate — the percentage to apply.
   • Tax type — vat, gst, hst, pst, qst, igst, jct, sales_tax, service_tax, or lease_tax. Printed on the invoice and used for reporting.
   • Taxability reason — how the line should be treated (below).
3. Save.

​

Rule matching

A rule is matched on the customer’s billing address, from most specific to least: a rule with matching country and state wins over a country-only rule for the same country. If nothing matches, no tax is applied. Because rules are keyed on jurisdiction, every line on an invoice to a given customer gets the same treatment.

​

Taxability reasons

The reason records why a line was taxed as it was. It appears on the invoice and on each line’s tax_reason in the API.

---

​

Common setups

​

Standard rate

Create a rule for the country (and state, where relevant) at the applicable rate with reason standard_rated. Repeat for each jurisdiction where you are registered. Rates change; review them periodically — Alguna does not update them for you.

​

Reverse charge (EU B2B)

Reverse charge is applied by a rule, not detected automatically:

1. Create a rule for the customer’s country at 0%.
2. Set the taxability reason to reverse_charge.
3. Record the customer’s VAT ID in tax_id on their tax settings so the treatment is defensible. See Customer Tax Settings.

The conditions that make reverse charge correct — the customer being VAT-registered in a different member state from the supplying entity — are yours to establish. The invoice shows 0% VAT with a reverse-charge note.

​

Zero-rated

Create a rule for the jurisdiction at 0% with reason zero_rated.

​

Exempt customer

There is no exemption toggle. A customer who should not be charged tax has their own tax settings set to a 0% tax_rate with tax_reason customer_exempt, and their tax_id recorded so the treatment can be justified. Invoice lines for that customer then carry customer_exempt. See Customer Tax Settings.

---

​

Customer tax settings

Each customer carries its own tax fields, set in the dashboard under the customer’s Tax settings and returned on GET /customers/{id}: tax_country (ISO 3166-1 alpha-2), tax_id, tax_rate (a decimal fraction, 0.20 = 20%), tax_reason, tax_type, and tax_status. They are not writable through POST or PATCH /customers. When they are set they take precedence over the entity’s rules for that customer; leave tax_rate at zero and the reason unset to let the rules decide. See Customer Tax Settings.

---

​

How tax is calculated on an invoice

1. Location — the customer’s tax_country (falling back to the billing address) gives country and state.
2. Customer settings — if the customer has a tax_rate and tax_reason of their own, those apply to every line.
3. Rule — otherwise, the most specific matching rule for the legal entity issuing the invoice.
4. Amount — tax_amount = amount_excluding_tax × rate per line; the invoice tax is the sum.

The same calculation runs for POST /tax/calculations, where the address and tax IDs come from the request instead of the customer record, and tax_behavior: "inclusive" backs the tax out of amounts that already include it. See the Tax overview.

---

​

Multiple legal entities

Each legal entity has its own rule set, so a US entity can carry state-by-state sales tax while an EU entity carries VAT rules. Customers are assigned to a legal entity; the invoice is issued — and taxed — by that entity. Legal entities are managed in the dashboard.

---

​

Reporting

Every invoice line records its rate, amount, type, and reason. To reconcile what you collected:

• Tax → Transactions in the dashboard lists taxed documents by period and jurisdiction.
• GET /tax/calculations lists API-driven calculations with tax_date filters; GET /invoices with date filters plus each invoice’s line_items[].tax_rate / tax_amount covers subscription invoices. See Data Exports.

---

​

Best practices