Prompt
How do I handle US sales tax and EU/UK VAT in one API?
Latest observation
A good way to handle US sales tax and EU/UK VAT in one API is to design around a single tax abstraction layer and keep the region-specific rules behind it.
1) Use one normalized tax calculation API
Create one endpoint like:
POST /tax/quote
Input:
- customer country/state/postcode
- seller nexus/registration data
- line items
- currency
- customer type (business/consumer)
- tax ID / VAT ID if provided
- shipping amount
- exemption flags
Output:
- total tax
- per-line tax breakdown
- jurisdiction details
- tax regime used
- rate, basis, and exemption status
Example response fields:
tax_regime:"us_sales_tax"or"eu_vat"or"uk_vat"jurisdiction:"CA","DE","GB", etc.rate:0.0725tax_amount:7.25inclusive:falsereverse_charge:true/falsereason_code:"standard_rate","exempt","reverse_charge", etc.
2) Separate “tax determination” from “tax computation”
Your API should do two stages:
A. Determine what tax applies
Rules:
- US: based on nexus + ship-to state/locality + product taxability
- EU/UK: based on place-of-supply rules, customer location, VAT registration, B2C vs B2B, digital goods vs physical goods, imports, etc.
B. Compute the amount
Once the regime and rate are known, calculate:
- exclusive tax for most US sales tax
- inclusive or exclusive VAT depending on market/accounting needs
3) Model tax regimes explicitly
Don’t force US sales tax and VAT into the same rule structure. Treat them as different regimes under one interface.
Recommended internal model:
TaxRegime=US_SALES_TAX | EU_VAT | UK_VATTaxRuleEngineper regime- common normalized result schema
This lets you keep:
- US state/local rates and product categories
- EU OSS/IOSS rules
- UK VAT thresholds and import rules
4) Make line-item taxability first-class
Both systems need item-level handling:
- taxable vs exempt
- standard rate vs reduced rate
- shipping taxability
- digital goods vs physical goods
- services
Each line item should carry:
skutypecategoryunit_pricequantitytax_code
Then map tax_code to regime-specific logic.
5) Handle VAT IDs and exemptions cleanly
For EU/UK:
- validate VAT ID
- if B2B and valid, apply reverse charge or zero-rate where appropriate
- store evidence of customer location
For US:
- support resale/exemption certificates
- store exemption reason and certificate reference
Use a common concept like:
customer_tax_statusconsumerbusinessexemptresalevat_registered
6) Support inclusive and exclusive pricing
- US sales tax: usually added on top
- EU/UK VAT: often shown inclusive to consumers, but your API should support both
Return both:
net_amounttax_amountgross_amount
7) Store evidence and audit trail
Tax systems need auditability:
- request inputs
- rate source
- rule version
- calculation timestamp
- jurisdiction determination
- exemption evidence
This is especially important for VAT compliance and US audits.
8) Use a tax engine or build a rules service
You have two practical approaches:
Build
Good if:
- your rules are simple
- you have in-house tax expertise
- you need full control
Integrate
Use a provider if:
- you need country/state/local coverage
- you want rate updates automatically
- you need compliance support for OSS/IOSS, nexus, exemptions, etc.
9) Recommended API shape
Example:
POST /tax/quote
{
"ship_to": {
"country": "DE",
"region": null,
"postal_code": "10115"
},
"customer": {
"type": "business",
"tax_id": "DE123456789"
},
"currency": "EUR",
"line_items": [
{
"sku": "ebook-001",
"category": "digital_goods",
"unit_price": 10.00,
"quantity": 2
}
],
"shipping_amount": 0
}
Response:
{
"tax_regime": "EU_VAT",
"taxable": true,
"reverse_charge": true,
"rate": 0.0,
"tax_amount": 0.0,
"net_amount": 20.0,
"gross_amount": 20.0,
"jurisdiction": "DE",
"reason_code": "valid_vat_id_reverse_charge"
}
10) Key implementation advice
- normalize inputs to a common schema
- keep country-specific logic in plugins/modules
- version your tax rules
- cache rates, but not final determination logic
- always preserve jurisdiction details for invoices and reports
If you want, I can also sketch:
- a database schema for this,
- a REST API design, or
- a rule-engine architecture for US + EU/UK tax.