> ## Documentation Index
> Fetch the complete documentation index at: https://docs.invoica.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Tax Compliance

> Configure automatic tax calculation for multi-jurisdiction compliance.

# Tax Compliance

Invoica automatically calculates taxes based on jurisdiction, supporting EU VAT and other country-specific tax rates across 15 countries.

## How Tax Calculation Works

Tax in Invoica is **calculated as a percentage of the payment amount and added on top**. The original payment amount becomes the subtotal, and the total includes the tax:

```
Subtotal (payment amount): 00.00
Tax Rate (Germany, 19%):     9.00
Total:                      19.00
```

The middleware does **not** modify the original payment amount from the server. Instead, when creating an invoice, if a country code is provided, Invoica looks up the applicable VAT rate and adds tax on top of the subtotal.

## Tax Calculation API

Calculate tax for any amount and jurisdiction:

```bash theme={null}
curl -X POST https://igspopoejhsxvwvxyhbh.supabase.co/functions/v1/api/v1/tax/calculate   -H "Content-Type: application/json"   -d '{
    "amount": 1000,
    "countryCode": "DE",
    "currency": "EUR"
  }'
```

### Response

```json theme={null}
{
  "success": true,
  "data": {
    "subtotal": 1000,
    "taxRate": 19,
    "taxAmount": 190,
    "totalAmount": 1190,
    "currency": "EUR",
    "countryCode": "DE",
    "country": "Germany",
    "rateType": "standard",
    "breakdown": [
      {
        "description": "Germany VAT (19%)",
        "rate": 19,
        "amount": 190
      }
    ]
  }
}
```

## Automatic Tax on Invoice Creation

When creating an invoice with a `taxCountry` or `country` field, tax is automatically calculated:

```bash theme={null}
curl -X POST https://igspopoejhsxvwvxyhbh.supabase.co/functions/v1/api/v1/invoices   -H "Content-Type: application/json"   -d '{
    "amount": 5000,
    "currency": "EUR",
    "customerName": "Berlin AI GmbH",
    "customerEmail": "billing@berlin-ai.de",
    "sellerName": "My Platform",
    "taxCountry": "DE",
    "serviceDescription": "AI compute services"
  }'
```

The invoice will automatically include:

* `subtotal`: 5000 (original amount)
* `taxRate`: 19 (Germany standard VAT)
* `taxAmount`: 950 (19% of 5000)
* `total`: 5950 (subtotal + tax)

## How Location is Determined

In the current implementation, **the buyer/seller location must be provided explicitly** when creating an invoice or calculating tax. The API caller (AI agent or integration) provides:

| Field                    | Purpose                              |
| ------------------------ | ------------------------------------ |
| `taxCountry` / `country` | ISO country code for tax rate lookup |
| `buyerVat`               | Buyer VAT registration number        |
| `sellerVat`              | Seller VAT registration number       |
| `buyerAddress`           | Full buyer business address          |
| `sellerAddress`          | Full seller business address         |

If no country code is provided, **tax defaults to 0** (no tax applied).

<Info>
  Future versions will support automatic location detection via VAT number validation (VIES API), billing address parsing, and IP geolocation as fallbacks.
</Info>

## Supported Tax Rates

Invoica includes built-in tax rates for 15 countries:

| Country             | Standard Rate | Reduced Rate |
| ------------------- | ------------- | ------------ |
| Germany (DE)        | 19%           | 7%           |
| France (FR)         | 20%           | 5.5%         |
| Italy (IT)          | 22%           | 10%          |
| Spain (ES)          | 21%           | 10%          |
| Netherlands (NL)    | 21%           | 9%           |
| Belgium (BE)        | 21%           | 6%           |
| Austria (AT)        | 20%           | 10%          |
| Portugal (PT)       | 23%           | 6%           |
| Ireland (IE)        | 23%           | 13.5%        |
| Sweden (SE)         | 25%           | 12%          |
| Finland (FI)        | 25.5%         | 14%          |
| Denmark (DK)        | 25%           | 0%           |
| Poland (PL)         | 23%           | 8%           |
| United Kingdom (GB) | 20%           | 5%           |
| United States (US)  | 0%            | 0%           |

## Tax Rates Lookup API

Get tax rates for a specific country:

```bash theme={null}
curl https://igspopoejhsxvwvxyhbh.supabase.co/functions/v1/api/v1/tax/rates?country=FR
```

Or list all available rates:

```bash theme={null}
curl https://igspopoejhsxvwvxyhbh.supabase.co/functions/v1/api/v1/tax/rates
```

## Tax Summary (Dashboard)

Access cumulative tax summaries grouped by country:

```bash theme={null}
curl https://igspopoejhsxvwvxyhbh.supabase.co/functions/v1/api/v1/dashboard/tax-summary   -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

Returns total subtotal, total tax, total with tax, invoice count, and breakdown by country.

## Reduced Rates

To use the reduced VAT rate instead of standard, pass `rateType: "reduced"` in the tax calculation request:

```json theme={null}
{
  "amount": 1000,
  "countryCode": "DE",
  "rateType": "reduced"
}
```

This returns 7% instead of 19% for Germany.

<Warning>
  US tax rates are currently set to 0%. State-level sales tax is not yet implemented. For US-based transactions, you should handle tax calculation externally.
</Warning>