Beta » Wallets track balances in tokens, credits, or dollars, automatically as they are used.Learn more
New » Metering turns raw usage events into billable quantities on a subscription.Learn more
/

Help Center › Billing › Taxes › Integrations › TaxJar BETA

TaxJar Troubleshooting and FAQs

Applies to: Advanced Billing · Maxio Core

··View as Markdown·

Last updated on Oct 29, 2026

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.

A Maxio Core invoice shows a tax error for a missing country

If a Maxio Core invoice has no country in the address your tax address setting uses, Maxio can't send that address to TaxJar. When the invoice gets no tax as a result, Maxio saves it with no tax and records a tax sync error: "Tax was not calculated because the invoice address has no country". Maxio doesn't record this error for customers marked Tax Exempt.

You can find these invoices in the following places:

  • The Invoices with tax error count on the Tax health card of the Taxes page, if the card is available on your site.
  • The invoices list, with the Tax Sync filter set to Failed to sync.
  • The invoice page, which shows an alert that the provided address is invalid.

To resolve the error, add the country to the invoice address in Maxio Core and reissue the invoice. Maxio then recalculates tax and removes the error. This works while the invoice is open. On an invoice in a closed accounting period or one that is committed, reissuing doesn't recalculate tax, so contact Support to correct it. See Reissue Invoices to the Billing Portal for when reissue is available.

Maxio reads common spellings of the United States in the country field, such as U.S., USA, and United States of America, as the United States. Any other country text is kept as entered, so use a valid country.

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.

Still need help?
Reach out and our support team will take it from here.

Contact support