How Numeral Calculates Tax in Maxio

After setup is complete, Maxio uses Numeral in the background to calculate sales tax for eligible taxable charges. This article explains what Maxio sends to Numeral and how tax appears in Maxio.

Important: Numeral tax calculation depends on a complete Maxio tax origin address, a usable customer destination address, taxable products or components, and valid Numeral credentials.

How calculation works

When a taxable charge is previewed or billed, Maxio builds a Numeral tax request using your site origin address, the customer's selected destination address, and each taxable line item's amount and product tax code. A taxable shipping charge is sent as its own line item, the same way as any other taxable amount. Numeral returns the amount to collect and jurisdiction details. Maxio then creates tax line items on the invoice.

Calculation stages

Tax calculation happens across catalog setup, customer setup, previews, invoice generation, and post-billing actions. Each stage depends on accurate tax data from Maxio and valid calculation results from Numeral.

1. Catalog setup: You maintain products and components in Maxio. If a Numeral product tax code is present on a taxable product or component, Maxio sends it as the product tax code for the line item.
2. Customer and subscription setup: Customer shipping and billing addresses are captured in Maxio. Your tax address option determines which address is sent to Numeral.
3. Tax calculation: During previews and invoice generation, Maxio sends Numeral the origin address, destination address, and each taxable line item's amount and product tax code.
4. Invoice enrichment: Maxio records Numeral tax amounts as tax line items and stores available jurisdiction breakdowns for invoice tax display.
5. Post-billing actions: For invoice-centric billing sites, invoice, void, and refund events enqueue background jobs that export corresponding transaction activity to Numeral.

What Maxio sends to Numeral

Maxio sends Numeral the transaction and address details needed to calculate tax. The request can include origin, destination, tax ID, and line item information.

For tax calculation, Maxio can send Numeral the following details:

• Origin address fields, including country, postal code, state, city, and street.
• Destination address fields, including country, postal code, state, city, and street.
• The customer's tax ID and a business customer type, when a VAT number or similar tax ID is on file.
• Each taxable line item's amount and product tax code, when available. A taxable shipping charge is sent as its own line item the same way.

Preview and invoice behavior

Maxio requests a soft tax quote during previews and commits the tax transaction when an invoice is finalized. This helps the tax shown during preview match the tax recorded on the invoice.

• Previews: When a user previews an upcoming charge, Maxio calls Numeral for a soft quote so the preview reflects real-time tax.
• Invoice creation: When an invoice is finalized, Maxio commits the transaction with Numeral, persisting the tax record for reporting and filing.
• Failures: If a Numeral call fails, such as from an invalid product code, bad address, or credential issue, Maxio logs the error and surfaces the setup or configuration issue in the UI rather than billing an incorrect amount.

Tax-inclusive pricing

For a tax-inclusive charge, Maxio extracts the tax from the gross price instead of adding tax on top of it. Maxio tells Numeral which charges are tax-inclusive so Numeral can calculate the tax portion already included in the price.

A subscription can mix tax-inclusive and tax-exclusive charges in the same billing period. Maxio calculates each type correctly and combines the results on the invoice.

Tax display in Maxio

When Numeral returns tax to collect, Maxio creates a tax charge with a memo built from the returned jurisdiction's tax authority and tax type, such as California Sales Tax (8.25%), where the percentage is the combined rate across all jurisdictions that applied. Maxio can also store available state, county, city, and special district breakdowns for invoice tax presentation.