​

US VAT & TaxJar Setup

​

Overview

• ✅ 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

• 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

​

Getting Started with TaxJar

​

Prerequisites

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

{
  "gatewayName": "TaxJar",
  "isDefault": true,
  "apiKeys": {
    "apiKey": "your_taxjar_api_key_here"
  }
}

✅ 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

​

Configuration Fields Explained

​

Understanding Key Concepts

​

Tax Codes

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

​

Nexus Addresses

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

​

Address Validation

​

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

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

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

​

Configuration Precedence

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

​

Product-Level Override

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

​

Plan-Level Override

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

​

Configuration Fields

​

Example: Plan with US-Only Restriction

{
  "planId": 456,
  "usVATConfig": {
    "active": true,
    "taxCode": "40030",
    "sellOnUSOnly": true
  }
}

⚠️ 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

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

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

​

US-Only Plans

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

​

Getting Tax Codes

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

​

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

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

​

Case 2: US-Only Plan

• Plan-level override: sellOnUSOnly: true
• Global US VAT: Active

​

Case 3: Multiple Product Types

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

​

Troubleshooting

​

Issue: Tax Not Calculating

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

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

​

Issue: Address Validation Failing

• Invalid ZIP code format
• Incomplete address
• Address doesn’t exist in USPS database

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

​

Issue: Wrong Tax Amount

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

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

​

Related Topics

• Collect Taxes - International VAT setup
• Invoice Computation - Understanding tax in invoices
• TaxJar Documentation - TaxJar API reference