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:

TaxJar Account: Sign up at taxjar.com
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

Go to Settings page in UniBee Admin Portal
Navigate to VAT & Tax → US VAT Gateways
Click Add Gateway
Select TaxJar
Paste your TaxJar API key
Check Set as default if this is your primary gateway
Click Save

Option B: API Setup

You can also set up TaxJar via API: Endpoint: POST /api/merchant/vat/setup_us_vat_gateway Request:

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

Go to Settings → VAT & Tax → US VAT Configuration
Enable Active toggle
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
Enable Check Address Via Gateway (recommended)
Enable Upload Invoice To Gateway (for tax filing)
Save configuration

API Configuration

Endpoint: POST /api/merchant/vat/setup_global_us_vat_config Example Request:

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

Plan-level configuration
Product-level configuration
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

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

Address Collection Required: Customer must provide complete US address
- Street address
- City
- State (2-letter code)
- ZIP code (5-digit or ZIP+4)
Address Validation (if enabled):
- Address is validated against USPS database
- System may suggest corrected/normalized addresses
- Customer can choose from validated options
Tax Calculation:
- Tax calculated based on exact address
- Includes state, city, and county taxes
- Tax amount shown before payment
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

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

Address Management

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

Tax Code Selection

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

Compliance

Monitor Transactions: Check transaction upload status regularly
Keep Records: All tax calculations are logged for audit
Review Tax Amounts: Verify calculated taxes match expectations
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

Collect Taxes - International VAT setup
Invoice Computation - Understanding tax in invoices
TaxJar Documentation - 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.

​US VAT & TaxJar Setup

​Overview

​Why US VAT is Different

​Getting Started with TaxJar

​Prerequisites

​Step 1: Set Up TaxJar Gateway

​Option A: Admin Portal Setup

​Option B: API Setup

​Step 2: Configure Global US VAT Settings

​Configuration Fields Explained

​Understanding Key Concepts

​Tax Codes

​Nexus Addresses

​Address Validation

​Configuration Example

​Admin Portal Configuration

​API Configuration

​Important Notes

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

​Configuration Precedence

​Product-Level Override

​Plan-Level Override

​Configuration Fields

​Example: Plan with US-Only Restriction

​How US VAT Works in Practice

​During Checkout

​Automatic Transaction Upload

​US-Only Plans

​Getting Tax Codes

​Best Practices

​Setup Recommendations

​Address Management

​Tax Code Selection

​Compliance

​Common Use Cases

​Case 1: SaaS Product for US Market

​Case 2: US-Only Plan

​Case 3: Multiple Product Types

​Troubleshooting

​Issue: Tax Not Calculating

​Issue: Address Validation Failing

​Issue: Wrong Tax Amount

​Related Topics

US VAT & TaxJar Setup

Overview

Why US VAT is Different

Getting Started with TaxJar

Prerequisites

Step 1: Set Up TaxJar Gateway

Option A: Admin Portal Setup

Option B: API Setup

Step 2: Configure Global US VAT Settings

Configuration Fields Explained

Understanding Key Concepts

Tax Codes

Nexus Addresses

Address Validation

Configuration Example

Admin Portal Configuration

API Configuration

Important Notes

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

Configuration Precedence

Product-Level Override

Plan-Level Override

Configuration Fields

Example: Plan with US-Only Restriction

How US VAT Works in Practice

During Checkout

Automatic Transaction Upload

US-Only Plans

Getting Tax Codes

Best Practices

Setup Recommendations

Address Management

Tax Code Selection

Compliance

Common Use Cases

Case 1: SaaS Product for US Market

Case 2: US-Only Plan

Case 3: Multiple Product Types

Troubleshooting

Issue: Tax Not Calculating

Issue: Address Validation Failing

Issue: Wrong Tax Amount

Related Topics