Skip to main content

​
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

​
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: 
{
  "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