Taxation limitations
This section describes known limitations and configuration considerations when working with taxation in Zuora Billing.
Limitations when using multiple tax engines in a single billing document
Avoid using multiple tax engines within the same billing document for tax calculation. Using multiple tax engines in a single billing document may block downstream operations such as creating credit memos, debit memos, or writing off invoices.
Invoices, credit memos, and debit memos that contain items taxed by multiple tax engines are not supported by standard reversal and write-off flows.
If an invoice uses more than one tax engine, the reverse invoice operation may fail with an error.
When you create a credit memo from an invoice that used more than one tax engine and Tax Auto Calculation is enabled, the operation may fail with an error.
Limitations of the tax engine mapping formula (Multiple Tax Engines)
The tax engine mapping formula supports only standard fields and custom fields on the Account and SoldToContact objects. Fields from Subscription, Rate Plan, and Rate Plan Charge objects are not supported.
When using Orders preview with previewAccountInfo, mapping logic that depends on account-level custom fields works only if you reference an existing accountNumber or include the relevant custom field values directly in previewAccountInfo. If a synthetic preview account is passed without these fields, the mapping formula cannot evaluate the conditions correctly and may route the request to the default tax engine.
The mapping formula is designed to route transactions between tax engines and cannot be used to disable taxation. If a charge is marked as Taxable and has a tax code, the mapping formula must resolve to a tax engine. Leaving the formula empty for certain cases is not supported and may result in an error. To prevent tax calculation, configure the charge as non-taxable or remove the tax code from the charge.
Zuora Tax rate file and Settings API limitations
The Zuora Tax rate CSV file supports only the documented columns. Additional or custom columns are not supported. Use existing fields such as Tax Jurisdiction, Tax Location Code, and Tax Rate Description for segmentation or reporting.
The Zuora Tax Settings APIs, which manage tax rate periods and tax rates, are subject to Zuora's standard API rate limits and concurrent request limits. Large or frequent bulk uploads should be designed with these limits in mind.
Multiple Tax Engines with Zuora Tax
When a Multiple Tax Engines tax code routes to Zuora Tax, the underlying Zuora Tax code must have valid tax rates configured for the applicable jurisdictions. If no rates are available, Zuora Tax is selected but no tax is calculated.
Only the fields documented for the Tax engine mapping formula are supported, including standard and custom fields on the Account and SoldToContact objects. Using undocumented fields or fields from other objects may lead to unexpected routing to the default tax engine.