Taxes

Bilteo applies taxes per line, not per invoice. Each line references up to three taxes from the tenant catalogue. The backend calculates bases, amounts, and breakdowns; you choose which taxes apply to each line.

Catalogue: GET /taxes

Taxes are tenant entities. Read active sales taxes with taxes:read:

curl "https://api.test.bilteo.com/api/v1/taxes?tax_use=sale&is_active=true" \
  -H "Authorization: Bearer bk_live_xxx"

Field	Purpose
id	Value sent as main_tax_id and related fields.
type	Tax family: sujeto, exento, retencion, recargo…
amount / amount_type	Rate and calculation method.
tax_use	sale, purchase, or none.
tax_scope	service or consu.
exempt_reason	Exemption cause.
label / invoice_label	Display and print labels.

Three tax slots per line

{
  "description": "Professional service",
  "quantity": "1",
  "unit_price": "1000.00",
  "main_tax_id": "…",
  "retention_tax_id": "…",
  "surcharge_tax_id": "…"
}

Field	Accepted types	Effect
main_tax_id	sujeto, sujeto_isp, sujeto_agri, exento, no_sujeto, no_sujeto_loc, no_deducible, dua	Main tax, usually VAT.
retention_tax_id	retencion	Personal-income-tax withholding; subtracts from the amount due.
surcharge_tax_id	recargo	Equivalence surcharge; adds to the base.

If main_tax_id is omitted from a normal sales line, the tenant's default main tax applies. A line with product_id inherits the product taxes unless you override them.

Tax families

• sujeto: taxable, non-exempt operation.
• exento: taxable but exempt, with exempt_reason and zero tax.
• no_sujeto / no_sujeto_loc: not subject, including place-of-supply rules.
• sujeto_isp: reverse charge; the recipient accounts for VAT.
• retencion: withholding, used in retention_tax_id.
• recargo: equivalence surcharge, used in surcharge_tax_id.

The territory—VAT, IGIC, or IPSI—is determined by the selected catalogue tax, not by a separate field.

Disbursements

For an expense paid on behalf of the customer without taxes, use line_type: "sup"; the default is "pos". Invoice totals are:

Total	Meaning
base	Tax bases from pos lines.
tax_amount	Total tax amount.
total	base + tax_amount.
total_suplidos	Sum of sup lines.
total_payable	Customer amount due, including disbursements and withholdings.

Breakdown

GET /invoices/{id} includes tax_breakdown, aggregated by tax. This is what appears in the PDF and is submitted to the AEAT.

"tax_breakdown": [
  { "tax_id": "…", "tax_rate": "21", "base": "1000.00", "tax_amount": "210.00" }
]

See full examples in the Cookbook.