Getting Started with Aeion Tax

Start with the jurisdictions where you have tax nexus (physical presence or economic nexus).

Nexus = Where you must collect tax:

Physical nexus: Warehouse in Texas, office in California, store in New York Economic nexus: $500K+ revenue in a state (most US states as of 2023) Voluntary nexus: You chose to register in a state

Add your first rate:

Admin → Tax → Rates → Add Rate

typescript // US State Tax Example — California { name: "California State Tax", country: "US", state: "CA", postalCodeType: "any", // Applies to all ZIPs in CA rate: 7.25, // CA base state rate taxType: "sales", isCompound: false, // State tax only (no tax-on-tax) taxShipping: true, // Shipping is taxable in CA appliesToAllProducts: true, // Default: all products taxed isActive: true, priority: 1, // Lower = higher priority }

Add a county tax (compound):

typescript // Los Angeles County — compounds on state { name: "LA County Tax", country: "US", state: "CA", county: "Los Angeles", postalCodeType: "any", rate: 2.25, taxType: "sales", isCompound: true, // ← COMPOUND: calculates on (subtotal + state tax) taxShipping: true, appliesToAllProducts: true, isActive: true, priority: 2, // After state (priority 1) }

Add a city tax:

```typescript // Los Angeles City — compounds on county (and therefore on state) { name: "Los Angeles City Tax", country: "US", state: "CA", county: "Los Angeles", city: "Los Angeles", postalCodeType: "any", rate: 1.50, taxType: "sales", isCompound: true, // ← TAX-ON-TAX: applied to subtotal + state + county taxShipping: true, appliesToAllProducts: true, isActive: true, priority: 3, }

// Result for $100 in LA City: // State: $100 × 7.25% = $7.25 // County: ($100 + $7.25) × 2.25% = $2.41 // City: ($100 + $7.25 + $2.41) × 1.50% = $1.64 // Total: $11.30 (effective rate: 11.30%) ```

Postal code targeting (NYC example):

```typescript // NYC has different rates by borough { name: "NYC City Tax (Manhattan)", country: "US", state: "NY", city: "New York", postalCodeType: "prefix", postalCodePrefix: "100", // Manhattan ZIPs start with 100, 101 rate: 4.875, taxType: "sales", isCompound: true, // On state + MTA appliesToAllProducts: true, isActive: true, }

{ name: "NYC City Tax (Brooklyn)", country: "US", state: "NY", city: "New York", postalCodeType: "prefix", postalCodePrefix: "112", // Brooklyn rate: 4.875, // ... }

// City → "New York" matches all NYC boroughs // Prefix → narrows to specific borough ```

Bulk import from CSV:

``` Admin → Tax → Rates → Import CSV

CSV format: name, country, state, county, city, postalCodeType, postalCode, rate, taxType, isCompound, taxShipping, isActive

California,US,CA,,,,7.25,sales,false,true,true LA County,US,CA,Los Angeles,,any,,2.25,sales,true,true Los Angeles City,US,CA,Los Angeles,Los Angeles,any,,1.50,sales,true,true NYC State,US,NY,,,,8.00,sales,false,true,true NYC City,US,NY,New York,,prefix,100,4.875,sales,true,true

Data sources: your accountant, Zip2Tax, TaxJar (export), Vertex ```

Tax classes let products be taxed differently based on type (clothing vs digital vs groceries).

Default tax classes (ready out of the box):

```typescript // Taxable Goods { code: "taxable", name: "Standard Taxable", defaultTreatment: "taxable" }

// Clothing and footwear { code: "clothing", name: "Clothing and Footwear", jurisdictionRules: [ { state: "TX", treatment: "exempt" }, // TX: clothing exempt { state: "NY", treatment: "reduced", rate: 4.0 }, // NY: reduced clothing rate ] }

// Groceries { code: "groceries", name: "Food and Groceries", jurisdictionRules: [ { state: "TX", treatment: "exempt" }, // TX: groceries exempt { state: "CA", treatment: "reduced", rate: 0 }, // CA: SNAP-exempt { state: "VA", treatment: "reduced", rate: 1.5 }, // VA: reduced rate ] }

// Prescription medicine { code: "prescription", name: "Prescription Medicine", jurisdictionRules: [ { country: "US", treatment: "exempt" }, // Federal: Rx exempt ] } ```

Create a new class:

```typescript // Admin → Tax → Classes → Add Class

{ code: "digital-downloads", name: "Digital Products and Downloads", defaultTreatment: "taxable", // Default: taxable unless jurisdiction overrides

jurisdictionRules: [ // EU: digital services taxed at customer's country (VAT MOSS) { country: "EU", treatment: "reduced", rate: 20 }, { country: "GB", treatment: "reduced", rate: 20 }, { country: "AU", treatment: "reduced", rate: 10 },

// Some US states tax digital differently { state: "NY", treatment: "taxable" }, // NY taxes digital { state: "FL", treatment: "exempt" }, // FL exempts digital ], } ```

Assign classes to products in Commerce:

```typescript // Admin → Commerce → Products → [Product] → Tax Settings { name: "E-Book: Complete Guide to SEO", sku: "EBOOK-SEO-001", price: 1999, // $19.99 in cents type: "digital", taxClass: "digital-downloads", // Also works for physical products: // taxClass: "clothing", "groceries", "prescription", etc. }

// At checkout: // NY customer → digital-downloads → NY rate applied // FL customer → exempt → $0 tax // UK customer → digital-downloads → UK VAT rate applied ```

Override rate in class rule:

typescript // Some states have special digital rates { code: "digital-downloads", name: "Digital Products", jurisdictionRules: [ { state: "HI", treatment: "reduced", rate: 4.0 }, // HI: special digital rate { state: "SD", treatment: "exempt" }, // SD: exempts digital ] }

B2B customers (resellers, nonprofits, governments) often have tax exemptions.

Add an exemption:

```typescript // Admin → Tax → Exemptions → Add Exemption // OR: Customer profile → Tax Exemptions → Add

{ customerId: "cust_acme_wholesale", customerName: "Acme Wholesale LLC",

exemptionType: "resale", exemptionReason: "Valid Resale Certificate",

// Geographic scope — states where exemption applies scopeType: "specific_states", exemptStates: ["TX", "FL", "NV", "WA"], // OR: scopeType: "all" → exempt in all states

// Product scope — what can be purchased tax-exempt appliesToAllProducts: true, // OR: appliesToAllProducts: false // exemptProductClasses: ["clothing", "electronics"],

// Exemption type exemptFromAll: true, // Full exemption → $0 tax // OR: isPartialExemption: true, exemptionPercentage: 75, // 75% exempt, 25% taxed // OR: isPartialExemption: true, maxExemptAmount: 100000, // First $1,000 exempt

// Certificate details certificateNumber: "RESALE-TX-2026-001234", documentUrl: "https://...", // Uploaded PDF of certificate issuedBy: "Texas Comptroller",

// Validity neverExpires: false, expiresAt: "2027-05-11", // Annual renewal status: "active", } ```

Exemption flow at checkout:

Before tax is calculated, Aeion checks the customer's active exemption certificates:

1. Certificate belongs to this customer
2. Certificate status is active
3. Certificate hasn't expired (or is marked as never expiring)
4. Certificate's geographic scope covers the shipping address (e.g., Texas is in the exempt-states list)
5. Certificate's product scope covers the items in the cart

If every check passes, the exemption is applied — fully or partially, per the certificate's configuration.

Exemption shown in cart: 🏢 Tax-Exempt (Resale Certificate TX-2026-001234) Subtotal: $1,000.00 Tax: $0.00 ← Exempt Total: $1,000.00

Renewal reminders:

```typescript // Call this endpoint to get certificates expiring soon (admin-only): POST /api/tax/exemptions/check-expiring { "daysAhead": 30 }

// Response: { "expiringCount": 3, "exemptions": [ { "id": "...", "name": "Acme Wholesale LLC", "customerId": "...", "expiresAt": "2027-06-01" } ] } ```

This is an on-demand endpoint, not an automatic cron job — call it from your own scheduled Blueprint workflow (or any external scheduler) to notify finance before certificates lapse.

Many states have annual sales tax holidays (back-to-school, hurricane supplies, energy-efficient products).

Add a seasonal holiday:

```typescript // Admin → Tax → Rates → Add Rate

{ name: "Texas Back-to-School Tax Holiday 2026", country: "US", state: "TX", postalCodeType: "any", rate: 0, // ← 0% during holiday taxType: "sales",

isActive: true, seasonalConfig: { isSeasonal: true, startMonth: 8, // August startDay: 1, endMonth: 8, // August 31 endDay: 31, },

appliesToAllProducts: false, productTaxClassIds: ["clothing", "footwear", "school-supplies"],

priority: 0, // High priority override }

// After August 31: // → the seasonal date check no longer matches // → rate not matched // → Standard TX rates apply ```

Holiday year-by-year (use effective dates):

```typescript // 2026 holiday { name: "TX Back-to-School Holiday 2026", effectiveFrom: "2026-08-01", effectiveUntil: "2026-08-31", // ... }

// 2027 holiday (update before August 2027) { name: "TX Back-to-School Holiday 2027", effectiveFrom: "2027-08-01", effectiveUntil: "2027-08-31", // ... } ```

Florida Hurricane Preparedness Holiday:

typescript { name: "FL Hurricane Preparedness Holiday", country: "US", state: "FL", rate: 0, seasonalConfig: { isSeasonal: true, startMonth: 6, startDay: 1, endMonth: 8, endDay: 31, }, appliesToAllProducts: false, productTaxClassIds: ["emergency-supplies", "generators", "batteries"], }

Track where you're generating revenue so you know when you're approaching economic nexus in a new state.

Running totals update automatically:

Every tax calculation updates the running totals for the rate(s) it applied — how many times that rate has fired, and how much tax it has collected.

Pull jurisdiction totals:

GET /api/tax/analytics/by-jurisdiction

json // Response — sorted by tax collected, descending { "data": [ { "jurisdiction": "US-CA", "taxCollected": 41234000, "transactionCount": 1842 }, { "jurisdiction": "US-TX", "taxCollected": 23410000, "transactionCount": 967 }, { "jurisdiction": "US-NY", "taxCollected": 8920000, "transactionCount": 412 } ] }

Compare against your own thresholds:

Aeion Tax doesn't ship pre-built economic-nexus thresholds or automatic threshold-crossing alerts — every state's rule (revenue vs. transaction count, $100K vs. $500K, look-back period) changes too often to hardcode reliably. Keep your thresholds wherever you track compliance today, and check /tax/analytics/by-jurisdiction periodically (e.g., monthly, or from your own scheduled Blueprint workflow) against them. When you're closing in on a threshold in a new state, that's your cue to talk to your accountant about registering.

Aeion Tax automatically intercepts commerce checkouts and billing subscription renewals.

Commerce checkout integration:

``` Tax calculation runs automatically at checkout — no manual wiring required.

→ Every order is routed through the tax engine → Results attach to the checkout session → Tax is shown in cart, calculated before payment ```

Manual calculation (for invoices, back-office):

```typescript // API call to calculate tax: POST /api/tax/calculate { "items": [ { "id": "item_1", "amount": 4999, "quantity": 2, "taxClassId": "clothing" }, { "id": "item_2", "amount": 2999, "quantity": 1, "taxClassId": "digital" } ], "shippingAddress": { "country": "US", "state": "TX", "postalCode": "78701" }, "customerId": "cust_123", "shippingAmount": 599 }

// Response: { "adjustments": [ { "label": "TX State", "amount": 832, "rate": 7.25, "jurisdiction": "TX USA" }, { "label": "TX Clothing (Exempt)", "amount": 0, "rate": 0, "jurisdiction": "TX USA" } ], "totalTax": 832, "shippingTax": 0, "summary": { "subtotal": 12997, "totalTax": 832, "total": 13829, "effectiveRate": 6.40 }, "exemptionsApplied": [] } ```

Override at product level:

typescript // Product-level tax override (for bundles, special deals) POST /api/tax/calculate { "items": [ { "id": "bundle", "amount": 7999, "quantity": 1, "taxClassId": "taxable" } ], "shippingAddress": { "country": "US", "state": "CA" }, "overrides": [ { "itemId": "bundle", "effectiveRate": 5.0 } // Override CA rate with 5% ] }