TaxJar Troubleshooting and FAQs

Use this article to resolve common TaxJar setup, connection, and calculation issues, and to answer common questions about the integration.

Troubleshooting

The TaxJar card is not visible

Confirm the TaxJar integration feature is enabled for your site by Maxio Support or your CSM.

The connection test fails

Confirm the API token is valid for the selected Sandbox or Production environment.

Maxio validates the key format and attempts a live call to TaxJar when you use Test Connection. If the test fails, review the error message, confirm the key, and confirm that the key belongs to the intended environment.

Taxes are not calculated

Confirm the tax origin address is complete, the customer destination address is available, and the subscription has taxable products or components.

Tax doesn't calculate on Maxio Core Contracts

Confirm Invoicing Suite and Billing Portal is enabled for your Maxio Core account by Maxio Support, and that AvaTax isn't also active on the same account — TaxJar can't estimate Contract tax through Advanced Billing while AvaTax is enabled.

The tax category is unexpected

Confirm the product or component tax code in Maxio matches the TaxJar product tax code you want to use.

Tax calculation fails

Maxio logs TaxJar errors and displays setup or calculation issues where applicable. Common causes include:

• Invalid credentials.
• Missing tax origin address.
• Missing customer address.
• Unsupported or malformed address data.
• Invalid product codes.
• TaxJar service timeout.

Void or refund activity is missing in TaxJar

Confirm the original invoice included TaxJar tax and that the invoice activity is supported by the TaxJar sync workflow. See Maxio Invoice and TaxJar Transaction Sync for which invoice activity exports and how Maxio identifies each transaction.

Frequently asked questions

Does Maxio maintain tax rates?

No. TaxJar calculates rates dynamically based on invoice line items, product tax codes, and address data Maxio sends. You should still maintain taxable flags, tax codes, customer addresses, and origin address settings in Maxio.

Can I test before going live?

Yes. Connect a Maxio test site to a TaxJar Sandbox account using a Sandbox API key. Run test subscriptions or invoice previews and confirm expected taxes. Before going live, update the integration to Production and test the connection again.

What invoice activity is exported to TaxJar?

Invoices, invoice voids, refunds, and credit note activity are exported with transaction metadata used for reconciliation. See Maxio Invoice and TaxJar Transaction Sync for the exact transaction ID formats.

Do customers still manage taxability settings?

Yes. Product taxability, product tax codes, customer address collection, tax origin configuration, nexus, and filing setup remain customer-managed.

Can I use TaxJar alongside Avalara, Anrok, Numeral, or Sphere?

No. Only one tax provider can be active per site at a time.

Will exempt customers be respected?

Yes. Exemption status set in TaxJar is honored on Maxio invoices. TaxJar can override an applied exemption in certain scenarios, such as when a customer is exempt in one region but taxable in another.

What happens if I delete or void an invoice in Maxio?

The void or refund is synchronized to TaxJar so reporting stays accurate when the invoice includes TaxJar tax and the workflow supports transaction export. See Maxio Invoice and TaxJar Transaction Sync for full and partial void behavior.

Best practices

• Use Sandbox for implementation testing.
• Use Production only when ready to calculate live taxes.
• Keep the tax origin address complete and current.
• Require the customer address type used by your tax address setting.
• Mark taxable products and components as subject to tax.
• Use TaxJar product tax codes when a product or component needs a special tax category.
• On Maxio Core, confirm Invoicing Suite and Billing Portal is enabled before relying on TaxJar for Contract tax.
• Review invoices after launch to confirm TaxJar tax lines and jurisdiction breakdowns appear as expected.