How TaxJar Calculates Tax in Maxio

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

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

How calculation works

When a taxable charge is previewed or billed, Maxio builds a TaxJar tax request using your site origin address, the customer's selected destination address, taxable line items, shipping amount, and product tax codes. Discounts are already reflected in each line's taxable amount before the request is built, so they don't need to be sent separately. TaxJar 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 TaxJar.

1. Catalog setup: You maintain products and components in Maxio. If a TaxJar 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 TaxJar.
3. Tax calculation: During previews and invoice generation, Maxio sends TaxJar the origin address, destination address, taxable amount, shipping amount, and taxable line items.
4. Invoice enrichment: Maxio records TaxJar tax amounts as tax line items and stores available jurisdiction breakdowns for invoice tax display.
5. Post-billing actions: Maxio enqueues background jobs for invoice, void, refund, and credit note events that export corresponding transaction activity to TaxJar.

What Maxio sends to TaxJar

Maxio sends TaxJar the transaction and address details needed to calculate tax. The request can include origin, destination, line item, shipping, and product tax code information.

For tax calculation, Maxio can send TaxJar 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.
• Taxable transaction amount.
• Shipping amount when a shipping charge is present.
• Taxable line items with quantity, a unit price that already reflects any discount, and product tax code when available.
• A Maxio Payments surcharge, as its own line item tagged with your site's surcharge tax code, when surcharging is enabled and a surcharge tax code is configured.

How surcharge tax is reported

If your site has Maxio Payments credit card surcharging enabled and a surcharge tax code configured, Maxio sends the surcharge to TaxJar as its own line item, separate from your product and component line items, tagged with that surcharge tax code. The tax TaxJar calculates on the surcharge is included in the invoice's total TaxJar tax, alongside tax on the rest of the invoice.

Because of this, an invoice can get a TaxJar transaction even when every product or component line item on it is untaxed, as long as the surcharge itself is taxed. A surcharge is sometimes added to an invoice after it's already been sent to TaxJar, so Maxio also re-checks affected invoices shortly after payment and updates the TaxJar transaction if a taxed surcharge was added late.

If no surcharge tax code is configured, Maxio sends no surcharge line to TaxJar and the surcharge itself is not taxed. See Credit Card Surcharging FAQ for how the surcharge tax code is set.

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 TaxJar for a soft quote so the preview reflects real-time tax.
• Invoice creation: When an invoice is finalized, Maxio commits the transaction with TaxJar, persisting the tax record for reporting and filing.
• Failures: If a TaxJar 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 display in Maxio

When TaxJar returns tax to collect, Maxio creates a tax charge with a memo based on the TaxJar jurisdiction and tax rate, such as State, County, City (8.25%) when jurisdiction data is available. Maxio can also store available state, county, city, and special district breakdowns for invoice tax presentation.