Calculations
A tax calculation quotes the tax for a checkout before you charge the buyer. You display the returned amounts, pass taxCalculationId through your PSP, then commit the transaction after payment succeeds. See Integration for the full sequence.
The response returns a single aggregate taxAmount - per-component breakdown is not on the public API today.
What you pass
- Customer identity and billing address (and shipping when physical goods matter)
- Line items with product codes, prices, and quantities
- Tax identifiers when the jurisdiction requires them (jurisdiction-prefixed types such as EU_VAT)
- Evidence of customer location when required (billing country, IP, payment method country)
API map
Request and response schemas live in the API reference - link from here, don't re-implement them on this page.
Region specific
Some jurisdictions add request requirements beyond the common calculation shape. Rules for each region live here - not in the sections above.
Brazil
BrazilBrazil NFS-e calculations have stricter request requirements than EU/US quotes. Request and response examples live in the API reference. End-to-end walkthrough: collect payments and stay tax-compliant.
- Currency must be BRL for Brazil NFS-e calculations
- B2C: customer first and last name, plus exactly one BR_CPF tax identifier
- B2B: BR_CNPJ, with buyerTaxRegime (SIMPLES_NACIONAL, LUCRO_PRESUMIDO, or LUCRO_REAL)
- taxBehavior INCLUSIVE - the submitted line amount stays the service value / ISS tax base, and ISS is reported separately, not backed out of the total
- Evidence is optional for Brazil - if provided, billingCountry must be BR
- CPF/CNPJ checks are format and check-digit only - a format-valid ID can still fail at NFS-e issuance
NFS-e vs NFCom: regular (non-telecom) services use NFS-e / ISS. Telecom or communication services (for example eSIM) need NFCom / ICMS instead - do not run them through the NFS-e path.
In sandbox, always send a valid-format BR_CPF or BR_CNPJ. Omitting the identifier can silently return zero tax.