Numeral Troubleshooting and FAQs

Use this article to resolve common Numeral setup, connection, and calculation issues in Maxio, and to find answers to frequently asked questions and best practices for keeping tax calculation working after setup.

Troubleshooting common issues

The Numeral card is not visible

Confirm the Numeral 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 Test or Production environment.

Maxio validates the key format and attempts a live call to Numeral 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.

The tax category is unexpected

Confirm the Numeral Product Category value set on the product or component in Maxio matches the category you intend Numeral to use.

Tax calculation fails

Maxio logs Numeral 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.
• Numeral service timeout.
• Numeral rate limit exceeded.

Void or refund activity is missing in Numeral

Confirm the original invoice included Numeral tax and that the invoice activity is supported by the Numeral sync workflow. For invoice-centric billing sites, invoice, void, and refund events enqueue background jobs that export corresponding transaction activity to Numeral.

FAQs and best practices

Does Maxio maintain tax rates?

No. Numeral 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 Numeral using a Test API key. Run test subscriptions or invoice previews and confirm expected taxes. Before going live, switch to a Production API key and test the connection again.

What invoice activity is exported to Numeral?

Invoices, invoice voids, refunds, and supported credit note activity are exported with transaction metadata used for reconciliation.

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 Numeral alongside Avalara, Anrok, TaxJar, 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 Numeral is honored on Maxio invoices. Numeral 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?

A deleted invoice is skipped entirely by every export path. Maxio doesn't create a new export for it, and doesn't update, void, or refund any export that already existed before it was deleted. Voiding or refunding an already-exported invoice is different: the void or refund is synchronized to Numeral so reporting stays accurate, as long as the invoice included Numeral tax and the activity is supported by the Numeral sync workflow.

What are the recommended best practices?

Follow these best practices to keep the Numeral integration accurate and reliable after setup. Review these items before testing, going live, or making changes to tax-related settings.

• Use a Test key for implementation testing.
• Use a Production key 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 Numeral product tax codes when a product or component needs a special tax category.
• Review invoices after launch to confirm Numeral tax lines and jurisdiction breakdowns appear as expected.