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

# Collect taxes

> Learn how to collect taxes with UniBee using VAT gateways and automatic tax calculation

# Collect Taxes with UniBee

UniBee provides comprehensive tax collection capabilities for both international (VAT) and US (Sales Tax) customers. The system automatically calculates taxes based on customer location, validates VAT numbers, and ensures compliance with tax regulations.

## Overview

UniBee supports two main tax systems:

* **VAT (Value Added Tax)**: For EU and international customers
* **US Sales Tax**: For US customers via TaxJar integration

Taxes are automatically calculated during checkout and applied to all invoices, ensuring your business stays compliant with tax regulations worldwide.

***

## VAT Tax System (EU/International)

### Available VAT Gateways

UniBee supports multiple VAT gateway options to suit different business needs:

#### 1. Default Gateway (Built-in)

**Best for**: Small businesses or businesses that need basic VAT calculation

**Features**:

* ✅ Built-in VAT rate database
* ✅ No API key required
* ✅ Free to use
* ✅ Supports most EU and international countries
* ✅ Based on official EU tax rates

**Setup**: Automatically available - no configuration needed

#### 2. VATSense Gateway

**Best for**: Businesses that need professional VAT validation and real-time rate updates

**Features**:

* ✅ Real-time VAT number validation
* ✅ Automatic weekly rate updates
* ✅ EORI number validation support
* ✅ Professional VAT service provider

**Setup**: Requires VATSense API key

#### 3. VATStack Gateway

**Best for**: Alternative professional VAT service

**Features**:

* ✅ VAT number validation
* ✅ Country tax rate queries
* ✅ Webhook support for async validation

**Setup**: Requires VATStack API key

#### 4. Github VIES Gateway

**Best for**: EU-only businesses looking for a free VAT validation solution

**Features**:

* ✅ Free service
* ✅ EU VAT number validation via VIES system
* ✅ Format and entity validation

**Setup**: No API key required (free service)

### Setting Up a VAT Gateway

1. Go to **Settings** page in UniBee Admin Portal
2. Navigate to **Configuration** → **Integrates** tab
3. Select your preferred VAT gateway
4. Enter API key (if required)
5. Save the configuration

> 💡 **Which gateway should I choose?**
>
> * Start with **Default Gateway** if you need basic VAT calculation
> * Use **VATSense** or **VATStack** if you need VAT number validation
> * Choose **Github VIES** for free EU-only VAT validation

### How VAT Calculation Works

UniBee automatically calculates VAT based on:

1. **Customer's country**: Tax rates vary by country
2. **VAT number**: Valid VAT numbers result in 0% tax (business-to-business)
3. **Product type**: Some products may have different tax rates
4. **Payment gateway rules**: You can configure custom rates per gateway

**Tax Calculation Flow**:

```
Customer makes purchase
  ↓
System checks customer's country
  ↓
Retrieves applicable tax rate
  ↓
Checks if customer has valid VAT number
  ├─ Yes → 0% tax (B2B transaction)
  └─ No → Apply standard tax rate
  ↓
Tax added to invoice
```

### VAT Number Validation

When customers provide a VAT number, UniBee automatically validates it:

* **Real-time validation**: VAT numbers are checked against official databases
* **Automatic exemption**: Valid VAT numbers result in 0% tax
* **Validation history**: All validations are recorded for your records

**How it works**:

1. Customer enters VAT number during checkout
2. UniBee validates the number format
3. System checks validation history (cached results)
4. If not cached, calls VAT gateway for real-time validation
5. Valid VAT number = 0% tax applied automatically

> ⚠️ **Important**: VAT validation only confirms the number is valid. You may still need to verify the customer's name and address matches the VAT registration after purchase.

### Changing Customer Tax for Recurring Payments

When you change a customer's country, the tax rate will automatically update:

1. Go to **Customers** → **User List**
2. Select the customer
3. Edit their country information
4. The next invoice will use the new tax rate (if changed before the next billing cycle)

**Note**: For recurring subscriptions, the tax rate is retrieved from the customer's data and calculated based on the current tax rate at invoice generation time.

***

## Custom Tax Rates via API

You can also manage taxes within your own system and pass custom tax rates via UniBee API. Custom rates take precedence over gateway-provided rates.

### APIs Supporting Custom Tax Rates

* [Subscription Create Preview](/api-reference/subscription/create-subscription-preview)
* [Subscription Create Submit](/api-reference/subscription/create-subscription)
* [Subscription Update Preview](/api-reference/subscription-update/update-subscription-preview)
* [Subscription Update Submit](/api-reference/subscription-update/update-subscription)
* [Subscription Renew](/api-reference/subscription-update/renew-subscription)

### Fields to Use

When calling these APIs, you can specify:

* `taxPercentage`: Custom tax rate (in basis points, e.g., 1900 = 19%)
* `vatNumber`: Customer's VAT number
* `vatCountryCode`: Customer's country code

**Example**:

```json theme={null}
{
  "taxPercentage": 2000,  // 20% tax
  "vatNumber": "GB123456789",
  "vatCountryCode": "GB"
}
```

> 💡 **Priority**: Custom tax rates specified via API take precedence over rates provided by VAT gateways.

***

## Tax on Refunds

When processing refunds, UniBee automatically:

* ✅ Uses the original invoice's tax rate
* ✅ Calculates refund tax accurately
* ✅ Maintains tax compliance for refunds

The system ensures that refund taxes match the original purchase taxes for proper accounting.

***

## Best Practices

### For VAT Setup

1. **Choose the right gateway**:
   * Start with Default Gateway for basic needs
   * Upgrade to VATSense/VATStack if you need validation
   * Use Github VIES for free EU-only validation

2. **Enable VAT number validation**:
   * Allows B2B customers to provide VAT numbers
   * Automatically exempts valid VAT numbers from tax

3. **Keep rates updated**:
   * Default Gateway uses built-in rates
   * VATSense/VATStack update weekly automatically
   * Verify rates periodically for accuracy

### For Tax Compliance

1. **Verify VAT numbers**: Even though UniBee validates VAT numbers, verify customer details match registration
2. **Keep records**: All tax calculations and VAT validations are logged for audit purposes
3. **Monitor changes**: Tax rates can change - ensure your gateway stays updated

***

## Related Topics

* [US VAT & TaxJar Setup](./us-vat-and-taxjar) - For US sales tax collection
* [Invoice Computation](../invoices/invoice-computation) - Understanding tax in invoices