Skip to main content

Avalara taxes in API calls and bill runs


Avalara taxes in API calls and bill runs

This article explains how taxes are calculated with Avalara when generating and posting billing documents (invoices, credit and debit memos) with API calls and bill runs.

Avalara taxes in API calls

This feature is in Limited Availability. If you want to have access to the feature, submit a request at Zuora Global Support

Tax rates for billing documents created through calls to the Zuora SOAP and REST APIs can be calculated in real-time using the Avalara API.

API-generated billing documents have two possible states: Draft and Posted:

  1. Draft: Billing documents in this state have had charges calculated by the Zuora Rating and Billing Engine (RBE), and tax values have been calculated by Avalara, but no transaction data has been stored on Avalara's servers. Only the Invoice.create() and Invoice.generate() SOAP API calls can produce draft invoices. For credit and debit memos, you can use POST REST API calls to create draft memos.
  2. Posted: Billing documents in this state have been posted to end customers, and transaction data has been stored on Avalara's servers for reporting purposes. Draft invoices are posted with the update() SOAP API call. The subscribe() and amend() SOAP API calls can only produce posted invoices. For credit and debit memos, you can use POST REST API calls to post draft memos. 

There is no canceled state for billing documents generated by calls to the Zuora APIs. If the tax calculation with Avalara fails, the entire Zuora API call is considered to have failed, and all changes are rolled back to the state before the call was made.

Preview modes for subscriptions and amendments are supported too, allowing you to view real-time tax values before committing to a billing document.

See Generating an Invoice and Generating an Invoice - API Reference for more information. 

API calls that generate billing documents with Avalara relevant taxes can suffer a small reduction in performance, due to the extra time it takes to communicate with the Avalara servers, and for Avalara to process the request.

If you unpost a posted invoice, the related tax document on the Avalara servers isn't removed immediately. The same is true for when a subscribe call fails, but has created a document on Avalara. In order to maintain data consistency between Zuora and Avalara these orphaned documents are removed from Avalara as part of a scheduled job, which runs daily at 3:30 AM.

Avalara taxes in bill runs

This feature is in Limited Availability. If you want to have access to the feature, submit a request at Zuora Global Support

Tax rates for billing documents created through bill runs are calculated asynchronously in batches, and have four possible states; draft, pending for tax, posted, and canceled:

  • Pending for Tax: Charges have been calculated by the Zuora Rating and Billing Engine ( RBE) and a request has been sent to Avalara for tax rates to be calculated. If the request succeeds, the billing document will go into Draft state. If it fails, it goes into the Canceled state.
  • Draft: Tax values have been calculated by Avalara, but no transaction data has been stored on Avalara's servers.
  • Posted: The Billing document has been posted to the end customer, and transaction data has been stored on Avalara's servers for reporting purposes.
  • Canceled: The billing document was not generated by the bill run. This may be because you canceled a Pending for Tax invoice in order to make invoice item adjustments, or may be due to a problem calculating tax rates. 

Bill runs use Avalara's batch call mechanism, where up to 50,000 billing document items are sent to Avalara in a single batch call. If a bill run contains more than 50,000 items, then Zuora makes a series of batch calls to Avalara. There is no maximum limit to the number of invoice items a bill run can process.

Draft invoices are canceled if subsequent bill runs fail. Suppose an account has a draft invoice that contains Avalara tax items in the period 4/1/2014 - 4/30/2014, then you create a bill run for the same account with a target date in a new period, 5/1/2014 . If the bill run fails, the draft invoice will be canceled. This is an Avalara specific issue, and his only occurs when using Avalara as the selected tax engine for invoice items, not when using Zuora Tax.

Billing Documents in Pending for Tax State

Billing documents in the Pending for Tax state are held in a queue in Avalara, waiting to for tax rates to be calculated. Often these requests are processed immediately, but if Avalara receives an unusually large number of requests from its other customers, your request can remain in the 'Waiting' state for some time before it is processed. If you are waiting a long time for billing documents to be processed by Avalara, you can check the status by logging in to the AvaTax Admin Console and going to Tools > View Imported File Status. You will see the status of each request received from Zuora; Waiting, Processing, Completed, Error.

  • Waiting: The request is in a queue, waiting for Avalara to calculate taxes. Check the Import Time column to see how long it has been in the queue for.
  • Processing: The request is currently being processed by Avalara, and the tax calculations will be returned to Zuora soon.
  • Completed: The taxes have been calculated, stored in Avalara, and returned to Zuora.
  • Error: There was a problem calculating the tax rates. An error message will be returned to Zuora, and the invoice, credit memo, or debit memo will go into the canceled state.


How to cancel a Pending for Tax invoice

Invoices in the Pending for Tax state can be manually canceled. This may be necessary in order to make adjustments on the invoice, for example, you want to update the target date of the invoice, or if you simply do not want to wait for Avalara to calculate the taxes.

To cancel a Pending for Tax invoice, log in to the Zuora application and go to Billing Operations > Invoices, click on the invoice name, then click the cancel the invoice button.

Invoices in canceled state

In addition to manually canceling an invoice in the Pending for Tax state, invoices can also enter the canceled state if a bill run cannot successfully calculate tax rates through Avalara.

When an invoice fails to generate for any reason, its account and subscription are listed on the bill run detail page, along with a description of the failure reason. From this description, you can determine whether the failure was due to a problem with the Avalara tax calculation, or something else.

Go to Billing > Bill Runs, click into a specific bill run and scroll down to the Failed Accounts and Subscriptions tab. This tab is only visible when invoices have failed to generate.

Each failed invoice has a failure reason displayed. Avalara tax calculations may fail in one of two ways;

  • There is a problem with the calculation of taxes for a particular invoice causing that invoice to fail. For example, the address of the customer on the invoice may be incorrect or not in a format accepted by Avalara
  • There is a problem with the batch call to Avalara, in which case all invoices in the bill run fail. If a large number of invoices all fail for the same reason, then it is likely that the batch call to Avalara failed.  This may be because your Avalara connection credentials are invalid / have expired, or the Company Code is incorrect. It is also possible that the Avalara service has a problem, or that your server has internet connectivity issues preventing it from communicating with Avalara

If you cannot identify the reason for a canceled invoice, contact Zuora Global Support.