Skip to main content

Set up connections to Avalara

Zuora

Set up connections to Avalara

  1. Last updated
  2. Save as PDF

This article describes how to set up connections from Zuora to Avalara.

Prerequisites

Before you begin the setup process, you should have the following information:

  • Avalara Account Number: This is a 10-digit number used to authenticate the API call to Avalara. It is not the Avatax Admin Console user name. You can find your Account Number at the top right of the window when you log in to the AvaTax Admin Console.
  • Avalara License Key: This is a 13-character or 16-character string used to authenticate the API call to Avalara. If you ever reset your license key, you must update it in Zuora too, or else calls to Avalara will fail. See License keys for more information on how to find or reset your license key.
  • Avalara User Name and Password: These are the credentials you use to log in to the AvaTax Admin Console. This user must have the correct permissions required, for example, Account Admin, in order for the Zuora/Avalara integration to function correctly. See the Avalara documentation for detailed information on user permissions.

    To avoid duplicate records in Avalara, you must use different Avalara credentials for your Zuora Production and API Sandbox environments. For instance, invoices with the same invoice number in Zuora Production and API Sandbox map to the same document in Avalara.

  • Company Code: This is a unique code that identifies the company in the AvaTax account where the document should be posted. The maximum length allowed is 50 characters. You must have at least one of these for calls to Avalara to succeed. While the majority of users only need one Company Code, you can use multiple Company Codes in Zuora. Currently, up to 40 Company Codes defined in Avalara can be used for integration between Zuora and Avalara. Every Company Code defined in Avalara and used to post billing documents (invoices, credit, and debit memos) must be configured in Zuora.  See the Company Code Identification for more information.

If an account has a Tax Company Code, that company code will be sent to Avalara instead of the one configured in the Tax Engine, potentially resulting in an error such as: The Zuora GetTax call to Avalara returned the following error(s): Company not found. Verify the CompanyCode.
For example, if the company code in the Avalara tax engine is DEFAULT and the account's Tax Company Code is ABCD, then ABCD will be sent to Avalara instead of DEFAULT.

You must ensure that the account’s Company Code matches the one configured in the tax engine to avoid such errors. 

  • Company Id: This is a unique identifier for the company in the Avalara database. It is a 6-digit number in Avalara production but could be a 7-digit number in the Avalara sandbox. To find your company ID, log in to the AvaTax Admin Console. Within your AvaTax account, click the Settings tab and select Company details. The Company ID can be found in the URL. You can confirm your Company ID with Avalara Support before reaching out to the Zuora team.

Set up a connection to Avalara

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

You can only create an Avalara tax engine from the Zuora UI. There is no API support for creating tax engines or modifying connection details. To set up Avalara as a new tax engine in Zuora, perform the following steps:

  1. Click your user name at the top right and navigate to Settings > Billing.
  2. Click Setup Tax Engine and Tax Date.
  3. If you have not set up Avalara, select Avalara from the drop-down list, and click setup new tax engine. 
  4. If you have already set up Avalara, click Edit.
  5. Specify the basic information for the new tax engine:
    1. Enter a name for your new tax engine in the Name field.
    2. If you would like to connect to the Avalara test environment for testing purposes, select the Use Test Environment check box. Clear this check box to connect to the live production system.

      The Avalara test and production environments are two separate environments, each with its own admin console and API URL. For more information, see Sandbox vs Production environments.

    3. Enter your Avalara Account Number.
    4. Enter your Avalara License Key.
    5. Enter your Avalara User Name and Password. 
      Note that this step applies only to Sandbox environment.
    6. Click the test connection button to confirm your credentials.
    7. Click save.
  6. Specify the company information:
    1. Click add company. 
    2. Enter a Company Code and Company Id.
    3. (Optional) Enter the origin address information related to the Company Code. If left blank, the address in your tenant profile will be used.
    4. Click save.