AvaTax — Sales Tax Calculation
Scottsdale Mint uses Avalara AvaTax for real-time, address-validated sales tax calculation at checkout. Precious metals have complex tax rules that vary significantly by state — AvaTax handles these automatically.
Why AvaTax for Precious Metals?
Sales tax on precious metals is a complex, state-by-state patchwork:
| State Example | Tax Treatment |
|---|---|
| Arizona | Exempt — bullion above threshold |
| Texas | Exempt — qualified bullion |
| California | Taxable — some exemptions for large purchases |
| New York | Partially exempt (depends on product type) |
Avalara's AvaTax maintains an up-to-date database of tax rules and applies them automatically based on:
- Customer's shipping address
- Product's ItemCode / tax code
- Purchase amount
This eliminates manual maintenance of a 50-state tax table.
Integration Method
The site uses the WooCommerce AvaTax plugin (by Avalara or a compatible connector). The plugin:
- Intercepts WooCommerce's tax calculation
- Calls the AvaTax REST API with order details
- Returns calculated tax amounts
- Stores the tax transaction reference for future auditing
Tax Calculation Flow
Customer changes shipping address at checkout
│
▼
JavaScript triggers AJAX: get_cart_totals or wc_checkout
│
▼
WooCommerce calls AvaTax plugin tax hook
│
▼
AvaTax plugin calls Avalara REST API:
- FROM: Scottsdale Mint address (Phoenix, AZ)
- TO: Customer shipping address
- Lines: Product SKU, quantity, amount, tax code
│
▼
Avalara responds with:
- Tax amount per line
- Jurisdiction codes
- Effective tax rates
│
▼
Displayed to customer on checkout
Product Tax Codes
Products must be assigned Avalara commodity codes to enable precious metals exemptions:
| Commodity | Avalara Tax Code |
|---|---|
| Gold bullion coin/bar | P0000000 (or bullion-specific code) |
| Silver bullion coin/bar | P0000000 |
| Numismatic coins | PS080101 (collectibles) |
| Non-bullion jewelry | Standard tangible goods |
Tax codes are stored in WooCommerce product meta (_avaTax_tax_code) and managed via the plugin's product settings.
Configuration
| ENV Variable | Description |
|---|---|
AVATAX_ACCOUNT_NUMBER | Avalara account number |
AVATAX_LICENSE_KEY | Avalara license key |
AVATAX_COMPANY_CODE | Avalara company code (SCOTTSDALEMINT or similar) |
AVATAX_ENV | sandbox or production |
Dev / Staging Behavior
In development and staging environments, AVATAX_ENV=sandbox must be set. The sandbox does not bill real tax transactions but may return slightly different tax amounts than production.
If AvaTax sandbox calls fail in development (no network access):
- The AvaTax plugin falls back to WooCommerce's built-in tax rates (stored in the DB)
- Enable fallback in plugin settings: WooCommerce → AvaTax → Fallback to WooCommerce rates
Tax-Exempt Customers
Some customers qualify for sales tax exemption certificates:
- Registered dealers
- Businesses purchasing for resale
- State-specific exemptions
These customers have an exemption certificate stored in their Avalara account. The WooCommerce AvaTax plugin checks the customer's avatax_exempt_code user meta and passes it in API calls to zero out tax.
Transaction Commits
AvaTax transactions are committed when an order is placed. Each order generates a Document Code in Avalara equal to the WooCommerce order number. This document code is stored on the order for audit retrieval.
Admin Retrieval
Admins can view tax calculations for each order:
- WooCommerce → Orders → [Order]
- Scroll to AvaTax metabox
- View Avalara Document Code, jurisdiction, and tax breakdown
Troubleshooting
| Issue | Action |
|---|---|
| Tax not calculating at checkout | Check AVATAX_ACCOUNT_NUMBER and AVATAX_LICENSE_KEY are set; check Avalara sandbox vs prod |
| Tax showing as 0 for all states | Product tax code may be exempt — check product's _avaTax_tax_code |
| AvaTax timeout errors | Avalara API may be down; check Avalara status page; ensure Lambda has internet access |
| Tax showing incorrectly on staging | Verify AVATAX_ENV=sandbox; sandbox may have slightly different rates than production |