Tax Providers

Spark CRM integrates with TaxJar and Avalara to calculate sales tax in real time during checkout and report finalized transactions (charges, refunds, and voids) back to the provider for remittance reporting.

Navigation: Settings > Tax Providers

Overview

With a tax provider configured, Spark CRM will:

• Calculate the correct sales tax at checkout based on the customer’s shipping address.
• Charge the customer that tax amount as part of their order total.
• Report every approved payment transaction — the base charge, each upsell, and each subscription rebill — to your provider as its own record, so the provider dashboard reflects what you collected. Posting happens when the charge is approved, not when the order reaches Completed.
• Report refunds and post-capture voids so remittance stays in sync when money is returned to the customer.

You can have multiple tax providers per team and designate one as primary. Primary is the fallback used by any campaign that doesn’t explicitly choose a provider.

Before You Start

You’ll need:

1. An account with one of the supported providers:
   • TaxJar — an API token. Generate one in your TaxJar dashboard under Account > SmartCalcs API.
   • Avalara — your AvaTax account ID, license key, and company code.
2. At least one nexus state configured with your provider. Nexus tells the provider which states you’re obligated to collect tax in. In TaxJar, configure nexus in the dashboard under Account > State Nexus Settings.
3. Your origin address — the location goods ship from. This determines origin-based tax rules.

Adding a Tax Provider

Who can access this page: Account Owners, Account Admins and Account Managers. Viewing the list needs the tax:view_any permission, with tax:create / tax:update / tax:delete for the matching actions. Everyone else sees an Access Restricted card instead of the provider list, and the Add Provider button is hidden. Outside of team owners and Account Admins, the permission only applies on Account-type teams — and editing, testing, disabling or deleting a provider requires an Account-type team for everyone, owners and Account Admins included.

Step 1: Navigate to Tax Providers

1. Go to Settings in the sidebar
2. Click Tax Providers in the left menu

Step 2: Add Provider

1. Click Add Provider
2. Select TaxJar or Avalara as the provider type
3. Fill in the form:

Product tax codes are provider-specific — TaxJar uses its SmartCalcs category codes, Avalara uses AvaTax tax codes. The list shown in the product form comes from whichever provider is flagged primary.

Step 3: Origin Address

Select your country and state from the dropdowns, then fill in ZIP, city, and street. If your country isn’t one of the 20 we ship state/province lists for (US, CA, AU, GB, NZ, IN, BR, DE, FR, JP, HK, CN, MX, ZA, IT, ES, RU, NG, AR, CH), the State / Province field becomes a free-form text box for a region code.

The origin address is optional but strongly recommended. Without it, your provider falls back to your account’s default nexus settings, which may not reflect where this particular team actually ships from.

Step 4: Test the Connection

From the provider’s row menu (three dots), click Test Connection. Spark CRM calls your provider’s API to verify the credentials — TaxJar’s categories endpoint, Avalara’s ping endpoint. On success, the provider status flips to Active; on failure it flips to Connection Error.

Step 5: Set as Primary (Optional)

Only one provider per team can be primary. If you check this on a second provider, the previous primary is automatically unset.

Campaign Configuration

Tax collection is controlled at the campaign level.

Navigation: Campaigns > your campaign > Settings > Tax Settings

How It Chooses a Provider

1. If the campaign has an explicit Tax Provider selected and that provider is not Inactive → use it. This includes providers still in Pending Verification or Connection Error — only a provider explicitly disabled (Inactive) is skipped.
2. If the campaign’s Tax Provider is set but Inactive → no tax is applied, to avoid silently switching to a different provider account.
3. If the campaign has no provider selected → fall back to the team’s primary tax provider, as long as one exists and it is not Inactive.
4. If none of the above → no tax applied; tax_amount comes through as 0.

When a new campaign is created, the team’s primary tax provider is pre-selected automatically.

Product Tax Codes

Tax providers categorize products so jurisdictions can apply different rates (clothing, groceries, prescription drugs, SaaS, etc.). Products with a tax code assigned will be taxed according to that category’s rules. The codes are provider-specific — the examples below are TaxJar’s.

Navigation: CRM > Products > edit a product

• Optional. Leaving it blank means the product is fully taxable, which is the default treatment.
• Start typing in the searchable dropdown to find a category (e.g. “Clothing”, “Food”).
• The code plus category name is shown, for example: 20010 — Clothing.

Examples of When It Matters

• Clothing (20010) is exempt from sales tax in Pennsylvania, exempt under $110 in New York, but fully taxable in California.
• Food & Groceries (40030) is exempt or reduced-rate in most states.
• Prescription drugs (51020) are exempt in nearly every US state.

If you sell only fully-taxable items, you don’t need to set any tax codes — the default treats everything as taxable unless told otherwise.

The full category list is loaded from your provider automatically and cached for 24 hours. Only shown in the product form when the team has a primary tax provider whose category list loads successfully — if no provider is flagged primary, or the category fetch fails (bad credentials, provider outage), the Tax Code field is hidden entirely.

How Tax Flows Through an Order

1. Checkout tax preview — Your checkout form can call POST /checkout/tax to get a real-time tax quote for a cart + shipping address. The returned tax_amount is what you display to the customer.
2. Order creation — When the order is created, the tax amount is locked in. Either:
   • The caller passes tax_amount in the order request (matching what the customer saw).
   • Or the server auto-calculates at save time against the provider’s API.
3. Payment — The customer is charged the total including tax.
4. Provider reporting — As soon as a payment transaction is approved, it’s queued for posting to the provider’s Transactions endpoint as its own record. The base charge, each upsell and each subscription rebill post separately, so one order can produce several provider records; the order does not have to reach Completed first. You’ll see a system note on the order: “Transaction reported to TaxJar (production) — transaction_number: TXN-…, sales_tax: Y.” Orders flagged as test orders are skipped by default; check Report test orders on the provider to opt in.
5. Refunds and voids — If the order is later refunded or voided, a matching refund transaction is sent to the provider so your reporting stays accurate. Partial refunds are prorated; full refunds and voids send the entire tax amount back.

Charge vs. Report Are Separate

If a campaign has tax calculation disabled but the order comes in with a tax_amount (typically from an external checkout system), Spark CRM still charges the customer that amount — but it won’t be reported to your tax provider. No provider is stamped on the order, so nothing is ever posted for it.

This is intentional: it supports clients who handle remittance externally or don’t use a tax provider at all, while still being able to bill the correct total.

Sales Tax Report

Navigation: Reports > Sales Tax

The Sales Tax report summarizes tax collected and refunded per day, per jurisdiction (country and state).

Columns:

• Collected — gross tax on orders
• Refunded — tax on refund transactions posted to your provider
• Net Tax — collected minus refunded (what you actually owe)
• Revenue — total order revenue in that bucket

Use the date range picker and country/state filters to drill into a specific period for remittance.

The report counts only orders in Completed, Refunded or Partially Refunded status. Reporting to your provider has no such filter, so an order that was posted to the provider can still be missing from this report.

Best Practices

Setup

• Always verify your nexus configuration matches your provider’s dashboard before going live.
• Use sandbox mode during testing — sandbox credentials don’t submit to your real tax books.
• Set an origin address even if your provider account has one configured. It makes the integration self-contained and resilient.
• Run Test Connection after saving. A provider left in Pending Verification still calculates tax, so a bad credential won’t announce itself.

Campaigns

• Let campaigns inherit the team primary unless you have a reason to override (multi-brand, different provider accounts).
• If a campaign should NEVER collect tax, uncheck “Enable tax calculation” explicitly rather than removing the provider.

Products

• Only assign tax codes to items that are genuinely in a special tax category. Over-assigning can cause under-collection.
• Review product tax codes annually — provider taxonomies occasionally update.

Troubleshooting

“Connection Failed” when testing a provider

Check:

• Credentials are correct and not expired (TaxJar API key, or Avalara account ID / license key / company code)
• Sandbox toggle matches the credential type (sandbox credentials won’t work against the production API and vice versa)
• Your provider account is active

Orders are showing $0 tax when they shouldn’t

Check:

• Campaign has “Enable tax calculation” checked
• Campaign has a provider selected, OR the team has a primary
• Provider status is not Inactive. (Providers in Pending Verification or Connection Error still calculate tax — only Inactive, set from the row menu’s Disable action, stops it.)
• Customer’s shipping state matches a state in your provider’s nexus configuration
• Shipping address is complete (country, zip, state are all required for calculation)

Orders are being charged tax but not showing in your tax provider

Check:

• A payment transaction on the order was actually approved. Posting is per approved transaction, not per completed order — order status plays no part in reporting. (The Sales Tax report is different: it only counts orders in Completed / Refunded / Partially Refunded, so an order that was posted to your provider can still be missing from the report.)
• The order has a tax provider stamped on it (tax_provider_id). There is no field for this on the order page — the only visible signal is a “… reported to TaxJar …” system note after a successful post, so its absence is the symptom rather than the diagnosis. If tax was charged from a tax_amount supplied on the order request while the campaign had tax calculation off, no provider was stamped and nothing will ever be reported.
• The campaign has “Enable tax calculation” on — if off, tax is charged but not reported, by design
• The order is not flagged as a test order — test orders are skipped unless Report test orders is enabled on the provider
• The provider didn’t reject the post — look for a system note starting with the provider’s name, e.g. “TaxJar rejected transaction TXN-…”, on the order. These appear when the provider refuses the payload (e.g. zip/state mismatch, malformed address). The job does not retry these — a provider validation rejection is swallowed once the note is written, while network and 5xx failures do retry (3 attempts, 60s backoff). Correcting the address fixes future orders, but the already-rejected transaction is never re-posted automatically; enter it in the provider dashboard manually.

Refunds aren’t updating your tax provider

Check:

• The original transaction was posted to the provider in the first place (look for the “Transaction reported to …” system note)
• The refund transaction has a negative amount
• The refund completed without error — look at the order’s notes for a “Refund reported to …” confirmation

Wrong tax rate for a specific product

Check:

• Product has a tax code assigned (or doesn’t — depending on what you intended)
• Tax code matches your provider’s current catalog
• The product’s jurisdiction actually treats that category specially

Related Topics

• Coupons - Discount configuration (applied before tax)
• Campaigns - Campaign-level settings
• API Tokens - Grant the api:tax.calculate ability to tokens that need to call the checkout tax endpoint. In the token form it appears as Tax - Calculate under the Tax group. Tokens holding the legacy api:view_any ability are also accepted.