There are currently some limitations to bear in mind when using the Avalara integration. Some of these are limitations of Avalara's service, some are design choices made by Zuora, and others are features that are currently in development.
This feature is in Limited Availability. If you want to have access to the feature, submit a request at Zuora Global Support.
Avalara service limitations
Tax exemption ignored when using inclusive tax mode
The Avalara integration does not currently account for customers who are tax exempt when generating billing documents (invoices, credit and debit memos) for charges that use the inclusive tax mode. If a taxable product rate plan charge is set to inclusive mode, the tax is still included in the billing documents, regardless of whether they are tax exempt or not.
Maximum of 15,000 invoice items per invoice
A maximum of 15,000 Avalara relevant items is allowed on a billing document. This is an Avalara limitation. If a billing document contains more than 15,000 items and is sent to Avalara, the tax calculation request will fail and an error will be returned.
Submit a request at Zuora Global Support if you require additional assistance.
Invalid addresses in U.S. territories will not return tax details
If an address is passed to Avalara with an invalid address in a U.S. territory, Avalara will not return tax details for the bill run. The error will result in blank cells where there would normally be tax details in the Avalara AvaTax Admin Console.
Zuora recommends correcting all invalid addresses whenever possible, but suggests two alternatives to continue the bill run to completion:
- Remove any invalid street address and only use the city, state, and postal code, or
General Deliveryin the Address 2 field
See Manage Customer Account for more information on how to update contact information.
Taxes calculated for draft and posted billing documents
When creating or posting billing documents, the tax rate on invoice date or memo date is applied to all charges.
Possible inconsistency between tax amounts on draft and posted billing documents
If tax conditions change during the period between the creation of a draft and a posted billing document, the tax amounts on the two documents may be inconsistent. For example, if the SoldTo contact address of an invoice is modified or the tax rules in Avalara are updated after a draft invoice is created and before an invoice is posted, the tax amounts on the two invoices may be different. The same inconsistency may occur when a (negative) credit invoice item is created to return funds to the customer, as the tax conditions may have changed since the original invoice item was created.Avalara are updated after a draft invoice is created and before an invoice is posted, the tax amounts on the two invoices may be different. The same inconsistency may occur when a (negative) credit invoice item is created to return funds to the customer, as the tax conditions may have changed since the original invoice item was created.
Unposting, re-posting and canceling invoices
Cancel posted invoice is not supported
Canceling posted invoices when using the Avalara integration is not officially supported and is not recommended. If you choose to cancel a posted invoice when using the Avalara integration, you can also cancel the corresponding document in Avalara manually. Although Zuora runs a scheduled job to clean up data synchronized between Avalara and Zuora, it does not specifically handle cancelled invoices. In most cases, you need to cancel the document yourself manually in Avalara in order to avoid data inconsistency between Zuora and Avalara.
The only way to conclusively avoid data inconsistencies between Zuora and Avalara is to disable the Cancel Posted Invoices permission. See Configure your Tenant Profile and Permissions for information on how to disable the Cancel Posted Invoices permission.
Re-posted invoices do not have tax recalculated by Avalara
Posting an invoice for the first time stores the calculated tax information on Avalara's servers. If you un-post an invoice that contains an Avalara calculated tax, change the invoice in some way, and then post the invoice again, tax will not be re-calculated by Avalara. The tax calculated for the original posted invoice will remain on Avalara's servers.
For Avalara to calculate the new tax on a re-posted invoice, Zuora recommends that you cancel the posted invoice, cancel the draft invoice, and then regenerate the invoice. By following this procedure, a new invoice number is associated with the re-posted invoice. Avalara will recognize the new invoice number as a new invoice.
Draft amendment previews in Zuora UI
Taxes on previews of draft amendments in the Zuora UI is not yet implemented. The value displayed for Tax is always 0.00. This issue only happens when the draft amendment preview is viewed in the Zuora UI.
Calls using the amend API with the preview option enabled return the correct values.
Draft subscription previews in the Zuora application show incorrect taxes
Previews of draft subscriptions in the Zuora application show incorrect tax values when the following conditions are true:
- The subscription contains at least one taxable rate plan charge that uses the inclusive tax mode.
- The draft subscription preview is viewed in the Zuora application.
Calls to the subscribe API with the preview option enabled return the correct values.