> ## 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.

# US VAT & TaxJar Setup

> Learn how to set up US sales tax collection with TaxJar integration in UniBee

# US VAT & TaxJar Setup

UniBee supports automated US sales tax calculation and compliance through TaxJar integration. This system automatically calculates state, city, and county-level taxes based on precise address information.

## Overview

UniBee's US VAT system is powered by TaxJar and provides:

* ✅ **Automatic Tax Calculation**: Real-time sales tax calculation based on customer address
* ✅ **Address Validation**: Ensures accurate tax calculation through address verification
* ✅ **Multi-Level Taxation**: Handles state, city, and county taxes automatically
* ✅ **Transaction Upload**: Automatically uploads transactions to TaxJar for tax filing
* ✅ **Product Tax Codes**: Supports different tax codes for different product types
* ✅ **Nexus Management**: Only collects tax in states where you have a business presence

### Why US VAT is Different

US sales tax differs from international VAT in several ways:

* **Multi-level taxes**: State, city, and county taxes can stack
* **Address precision**: Requires exact street address for accurate calculation
* **Nexus concept**: Only collect tax in states where you have business presence
* **Product tax codes**: Different products have different tax rules
* **Compliance reporting**: Transactions must be uploaded for tax filing

Use this guide when you need to collect US sales tax, submit transactions to TaxJar, or keep checkout behavior compliant for US buyers.

***

## Getting Started with TaxJar

### Prerequisites

Before setting up TaxJar integration, you'll need:

1. **TaxJar Account**: Sign up at [taxjar.com](https://www.taxjar.com)
2. **API Key**: Get your API key from TaxJar dashboard
   * **Production**: Use for live transactions
   * **Sandbox**: Use for testing (free)

> 💡 **Tip**: Start with Sandbox API key for testing, then switch to Production when ready.

***

## Step 1: Set Up TaxJar Gateway

### Option A: Admin Portal Setup

1. Go to **Settings** page in UniBee Admin Portal
2. Navigate to **VAT & Tax** → **US VAT Gateways**
3. Click **Add Gateway**
4. Select **TaxJar**
5. Paste your TaxJar API key
6. Check **Set as default** if this is your primary gateway
7. Click **Save**

### Option B: API Setup

You can also set up TaxJar via API:

**Endpoint**: `POST /api/merchant/vat/setup_us_vat_gateway`

**Request**:

```json theme={null}
{
  "gatewayName": "TaxJar",
  "isDefault": true,
  "apiKeys": {
    "apiKey": "your_taxjar_api_key_here"
  }
}
```

**Response**: Gateway connection confirmed

> ✅ **Verify Setup**: After setup, you can verify the connection by checking your merchant profile. The system will show your configured US VAT gateways.

***

## Step 2: Configure Global US VAT Settings

After setting up TaxJar, configure your global US VAT defaults. These settings apply to all products and plans unless overridden.

### Configuration Fields Explained

| Field                         | Required    | What It Does                                                                 |
| ----------------------------- | ----------- | ---------------------------------------------------------------------------- |
| **Active**                    | ✅ Yes       | Master switch to enable/disable US VAT globally                              |
| **Default Gateway**           | ✅ Yes       | Select TaxJar (or other enabled gateway)                                     |
| **Tax Code**                  | ✅ Yes       | Product tax code (e.g., "40030" for SaaS, "31000" for Clothing)              |
| **From Address**              | ✅ Yes       | Your business origin address (where goods/services ship from)                |
| **To Address**                | ⚠️ Optional | Default destination (usually left empty to use customer address)             |
| **Nexus Addresses**           | ⚠️ Optional | States/cities where you have business presence (required for tax collection) |
| **Check Address Via Gateway** | ⚠️ Optional | Validate all US addresses through TaxJar (recommended for accuracy)          |
| **Upload Invoice To Gateway** | ⚠️ Optional | Automatically upload transactions to TaxJar for tax filing (recommended)     |

### Understanding Key Concepts

#### Tax Codes

Different products have different tax rates. Common tax codes include:

* **40030**: Software as a Service (SaaS)
* **31000**: Clothing
* **20010**: Digital Goods
* **00000**: Fully Taxable (general products)

#### Nexus Addresses

Nexus is your business presence in a state. You only need to collect tax in states where you have nexus. Common nexus triggers:

* Physical location (office, warehouse)
* Employees working in the state
* Significant sales volume

#### Address Validation

Enabling address validation ensures accurate tax calculation by verifying customer addresses against official USPS databases.

### Configuration Example

#### Admin Portal Configuration

1. Go to **Settings** → **VAT & Tax** → **US VAT Configuration**
2. Enable **Active** toggle
3. Fill in the required fields:
   * **From Address**: Your business location
   * **Tax Code**: Select appropriate code for your products
   * **Nexus Addresses**: Add states where you have business presence
4. Enable **Check Address Via Gateway** (recommended)
5. Enable **Upload Invoice To Gateway** (for tax filing)
6. Save configuration

#### API Configuration

**Endpoint**: `POST /api/merchant/vat/setup_global_us_vat_config`

**Example Request**:

```json theme={null}
{
  "global_us_vat_config": {
    "active": true,
    "defaultGatewayName": "TaxJar",
    "taxCode": "40030",
    "fromAddress": {
      "countryCode": "US",
      "zipCode": "10001",
      "state": "NY",
      "city": "New York",
      "address": "123 Business St"
    },
    "nexusAddresses": [
      {
        "countryCode": "US",
        "zipCode": "10001",
        "state": "NY",
        "city": "New York",
        "address": ""
      }
    ],
    "checkAddressViaGateway": true,
    "uploadInvoiceToGateway": true
  }
}
```

### Important Notes

* **Address Required**: Once US VAT is active, US customers must provide a complete address for accurate tax calculation
* **Tax Recalculation**: After address changes, tax amounts are automatically recalculated
* **Tax Code List**: Fetch available tax codes using the category list API
* **Transaction Upload**: Enabled transactions are automatically uploaded to TaxJar for compliance reporting

***

## Step 3: Product & Plan-Level Configuration (Optional)

You can override global US VAT settings for specific products or plans. This is useful when:

* Different products have different tax codes
* Products ship from different locations
* Some plans are US-only

### Configuration Precedence

Settings are applied in this order (highest to lowest priority):

1. **Plan-level** configuration
2. **Product-level** configuration
3. **Global** configuration

### Product-Level Override

Override global settings for specific products:

**When to Use**:

* Product has different tax code
* Product ships from different location
* Product-specific tax rules

### Plan-Level Override

Override global settings for specific plans:

**When to Use**:

* Plan is US-only (set `sellOnUSOnly: true`)
* Plan has different shipping address
* Plan-specific tax requirements

### Configuration Fields

| Field               | Required                | Description                                          |
| ------------------- | ----------------------- | ---------------------------------------------------- |
| **Active**          | ✅ Yes                   | Enable this override (must be `true` to take effect) |
| **Tax Code**        | ⚠️ Optional             | Override tax code for this product/plan              |
| **From Address**    | ⚠️ Optional             | Override shipping origin address                     |
| **To Address**      | ⚠️ Optional             | Override destination address                         |
| **Nexus Addresses** | ⚠️ Optional             | Override nexus addresses                             |
| **Sell On US Only** | ⚠️ Optional (Plan only) | Hide plan unless buyer is in US                      |

### Example: Plan with US-Only Restriction

```json theme={null}
{
  "planId": 456,
  "usVATConfig": {
    "active": true,
    "taxCode": "40030",
    "sellOnUSOnly": true
  }
}
```

This plan will only be visible to US customers.

> ⚠️ **Important**: Set `active: true` for the override to work. Without it, global settings will be used instead.

***

## How US VAT Works in Practice

### During Checkout

When US VAT is active and a customer selects the United States:

1. **Address Collection Required**: Customer must provide complete US address
   * Street address
   * City
   * State (2-letter code)
   * ZIP code (5-digit or ZIP+4)

2. **Address Validation** (if enabled):
   * Address is validated against USPS database
   * System may suggest corrected/normalized addresses
   * Customer can choose from validated options

3. **Tax Calculation**:
   * Tax calculated based on exact address
   * Includes state, city, and county taxes
   * Tax amount shown before payment

4. **Tax Updates**:
   * Tax recalculates automatically when address changes
   * Preview APIs reflect updated tax amounts

### Automatic Transaction Upload

When enabled, UniBee automatically:

* ✅ Uploads paid invoices to TaxJar
* ✅ Creates refund records for refunds
* ✅ Maintains transaction history for tax filing

This ensures your TaxJar account stays synchronized for tax reporting.

### US-Only Plans

Plans with `sellOnUSOnly: true`:

* Only visible to US customers
* Hidden from international customers
* Useful for location-restricted services

### Getting Tax Codes

Use the TaxJar category list API to:

* View all available product tax codes
* Find the right tax code for your products
* Update tax codes when gateway changes

**API**: `GET /api/merchant/vat/us_vat_category_list`

***

## Best Practices

### Setup Recommendations

1. **Start with Sandbox**: Test with TaxJar Sandbox API key before going live
2. **Enable Address Validation**: Ensures accurate tax calculation
3. **Upload Transactions**: Enable automatic upload for tax filing compliance
4. **Configure Nexus Properly**: Only add states where you have business presence

### Address Management

1. **Collect Complete Addresses**: Always require full US address for accurate taxes
2. **Validate Addresses**: Use address validation to catch errors early
3. **Handle Address Changes**: Recalculate tax when customers update addresses
4. **Display Normalized Addresses**: Show TaxJar's normalized addresses for confirmation

### Tax Code Selection

1. **Choose Correct Code**: Select tax code matching your product type
2. **Review Tax Codes**: Check TaxJar documentation for appropriate codes
3. **Update When Needed**: Tax codes can change - review periodically

### Compliance

1. **Monitor Transactions**: Check transaction upload status regularly
2. **Keep Records**: All tax calculations are logged for audit
3. **Review Tax Amounts**: Verify calculated taxes match expectations
4. **Handle Refunds**: Refunds automatically use original tax rates

***

## Common Use Cases

### Case 1: SaaS Product for US Market

**Setup**:

* Tax Code: `40030` (Software as a Service)
* From Address: Your business location
* Nexus: States where you have employees/office
* Upload: Enabled for tax filing

**Result**: Automatic sales tax calculation based on customer location

### Case 2: US-Only Plan

**Setup**:

* Plan-level override: `sellOnUSOnly: true`
* Global US VAT: Active

**Result**: Plan only visible to US customers, taxes calculated automatically

### Case 3: Multiple Product Types

**Setup**:

* Global Tax Code: Default code (e.g., `00000`)
* Product A: Override with `31000` (Clothing)
* Product B: Override with `20010` (Digital Goods)

**Result**: Each product uses appropriate tax code

***

## Troubleshooting

### Issue: Tax Not Calculating

**Possible Causes**:

* US VAT not enabled globally
* Customer address incomplete or invalid
* No nexus configured for customer's state

**Solution**:

* Check global configuration is active
* Verify customer provided complete US address
* Ensure nexus addresses include customer's state

### Issue: Address Validation Failing

**Possible Causes**:

* Invalid ZIP code format
* Incomplete address
* Address doesn't exist in USPS database

**Solution**:

* Verify ZIP code (5-digit or ZIP+4)
* Ensure all required fields provided
* Try alternative address formats

### Issue: Wrong Tax Amount

**Possible Causes**:

* Wrong tax code selected
* Outdated nexus configuration
* Address not validated

**Solution**:

* Review tax code matches product type
* Update nexus addresses if business expanded
* Enable address validation for accuracy

***

## Related Topics

* [Collect Taxes](./collect-tax) - International VAT setup
* [Invoice Computation](../invoices/invoice-computation) - Understanding tax in invoices
* [TaxJar Documentation](https://developers.taxjar.com/) - TaxJar API reference

***

By following this guide, you can successfully set up US sales tax collection with TaxJar, ensure checkout compliance, and maintain accurate tax records for filing.