Skip to main content
Avalara Help Center

AvaTax for Communications Zuora connector user manual

A warning icon

This user manual refers to a legacy product that is no longer available.

There is a newer AvaTax for Communications connector available for Zuora. Contact your Customer Account Manager or our sales team if you're interested in purchasing the connector.

Overview

The AvaTax for Communications (AFC) Zuora connector is a cloud-based service which allows integration of Avalara’s AFC engine and Zuora in order to perform tax calculations on invoices and invoice item adjustments. The connector performs its work automatically by scanning the Zuora tenant at regular time intervals in order to determine if there are any invoices or invoice item adjustments that require taxation. In addition, a callout notification may be configured within Zuora in order to send a notification to the connector when a bill run is executed to begin the tax calculation process immediately.

After the scan or receiving a bill run notification, the connector will begin the tax calculation process for the completed bill run by querying the invoice and invoice line item data out of Zuora. The connector then calculates taxes on each line item within the invoice using Avalara’s AFC engine, logs the input and output in a backend database, and returns the tax calculation results to Zuora. Tax calculation results are displayed within each invoice in Zuora as TaxationItem objects. Compliance reports are generated on a monthly basis using the tax data contained in the database log.

Figure 1 - Zuora Connector Process

Image_ZuoraConnectorProcess.png

Zuora Tenant Configuration

The following setup is required within the Zuora tenant to enable the connector to perform tax calculations.

Zuora Tenant Permissions

Contact your Zuora representative to request the following permissions within your Zuora tenant:

Table 1 - Permissions

Permission

Enable/Disable

Purpose

Taxation

Enable

Allows the connector to perform tax calculations on invoices and invoice item adjustments.

Callout for Notification

Enable

Enables callout notifications from Zuora to inform the connector that a bill run has completed.

Tax Details API for Draft Invoices

Enable

Enables the tax connector to use the Zuora API to perform tax calculations on draft invoices.

Full Data Source Access

Enable

Allows the connector to access all required data sources to obtain bill run and invoice data.

Expose TaxMode in TaxationItem

Enable

Allows the connector to determine if tax calculations should be performed using Tax Inclusive or Tax Exclusive mode.

Custom Field

Enable

Allows users to create custom fields in Zuora tenant.

Edit Invoices

Enable

Allows the connector to modify the invoices’ status after performing tax calculations.

Auto-Post Invoices on Bill Run

Disable

Prevent invoices from being posted automatically during a bill run to allow the connector to process tax calculations before being posted.

Cancel Posted Invoices

Enable

Allow invoices to be canceled. The connector will back out the taxes on any canceled invoices.

Delete Posted Invoices

Disable

Prevent invoices from being deleted, which would cause a discrepancy between the taxes saved in Zuora and the taxes logged in the AFC Zuora connector’s database. Canceled invoices should remain in Zuora until the taxes are backed out by the connector.

API User Role

If an API user role has not been created in your Zuora tenant, please follow the instructions provided below for creating this role.

Step

Action

1

Select Setting > Administration in the upper right corner.

NOTE: The Administration Settings page opens.

2

Click the Manage User Roles option. (See Figure 1 for screenshot.)

NOTE: The Manage Roles page opens.

3

Click the Add New Role button.

NOTE: The New Role page opens.

4

Enter a name in the Role Name field which clearly identifies this role, e.g., "API User". (See Figure 2 for screenshot.)

5

Click the API Write Access box, but leave the UI Access box unchecked. This gives the role the ability to create, update, and delete data in the SOAP and REST APIs, but not to log in to the UI.

6

Click the Save button.

NOTE: The Manage Roles page displays the API user role.

Figure 2 - Administration Settings for User Roles

image

 

Figure 3 - Naming New User Roles

image

API User Account

Create an API user account in your Zuora tenant if you don’t already have one. Please follow the steps provided below.

Step

Action

1

Select the Setting > Administration Setting menu item.

2

Select Manage Users on the Administration Settings page.

3

Click the Add Single User button.

4

Complete the fields with the appropriate information for the user account and make sure to select API User as the Zuora Platform Role. (See Figure 3 screenshot.)

5

Click the Save button.

NOTE: An email from Zuora into the email account provided for the API user account is automatically generated.

6

Follow the instructions provided in the email invitation to activate the account.

NOTE: You will need to provide the credentials for the API user account to the connector using the AFC Zuora Portal (see AFC Zuora Configuration Page).

Figure 4 - Defining New User Account Details

image

Custom Fields

The following custom fields must be created in your Zuora Tenant for use by the connector. Please follow the steps provided below to create a custom field:

Step

Action

1

Select the Settings > Z-Billing Settings menu item.

2

Click Manage Custom Fields on the Z-Billing Settings page. (See Figure 4 screenshot.)

3

Select the desired object.

4

Select the Add New Field button on the Fields page for the object. (See examples within Figures 5, 6, and 7 screenshots.)

5

Enter the new custom field information as indicated below.

6

Click the Save button.

Figure 5 - Managing and Adding Custom Fields

image

 

Figure 6 - Account Custom Fields

image

 

Figure 7 - Product Rate Plan Charge Custom Fields

image

 

Figure 8 - Invoice Item Adjustment Custom Fields

image

 

Figure 9 - Invoice Custom Fields

image

 

Figure 10 - Subscription Custom Fields

image

 

Figure 11 - Subscription Rate Plan Charge Custom Fields

image

These steps must be repeated for each custom field identified in the Custom Fields table provided below. Please note the following when creating the custom fields:

  • Zuora will append “ c” to the API Name of each custom field after it is created. (This is normal.)
  • Values entered into the Picklist Values must be entered exactly as shown.
  • You may choose to specify a different Field Label for each custom field as desired.
  • The order of Picklist Values entered is important to enable the desired default value to be selected. You may change the order of the Picklist Values to best suit your needs.

Table 2 - Custom Fields

 

Object

Field

Field Setup

Account

Lifeline

Field Type

Picklist

Field Label

Lifeline

API Name

BillSoft_Lifeline

Picklist Values

No

Yes

Description

Indicates if account’s subscriber is a lifeline participant.

Required

Yes

Incorporated

Field Type

Picklist

Field Label

Incorporated

API Name

BillSoft_Incorporated

Picklist Values

Yes

No

Description

Indicates if client’s Sold-To contact address is inside or outside the city limits.

Required

Yes

Customer Type

Field Type

Picklist

Field Label

Customer Type

API Name

BillSoft_CustomerType

Picklist Values

Business

Industrial

Residential

Senior Citizen

Description

Specifies the type of customer for the subscriber’s account.

Required

Yes

Jurisdiction PCode

Field Type

Text

Field Length

10

Field Label

Jurisdiction Pcode

API Name

BillSoft_JurisdictionPCode

Description

Pcode used for determining taxing jurisdiction for account.

Required

No

Taxation System

Field Type

Picklist

Field Label

Taxation System

API Name

BillSoft_TaxationSystem

Picklist Values

EZTax

(enter any other taxation systems as desired)

Description

Indicates which tax engine should be used for performing tax calculations.

Required

Yes

Wholesaler

Field Type

Picklist

Field Label

Wholesaler

API Name

BillSoft_Wholesaler

Picklist Values

No

Yes

Description

Indicates if customer is a wholesaler.

Required

Yes

Product Rate Plan Charge

 

Discount Type

Field Type

Picklist

Field Label

Discount Type

API Name

BillSoft_DiscountType

Picklist Values

No Discount

Account Level

Goodwill

Manufacturer Product

Retail Product

Subsidized

Description

Indicates the type of discount being applied for discounts within a rate plan charge.

Required

Yes

Service Type

Field Type

Text

Field Length

5

Field Label

Service Type

API Name

BillSoft_ServiceType

Description

AFC Service Type ID used in combination with the Transaction Type to specify the type of product or service being sold.

Required

Yes

Transaction Type

Field Type

Text

Field Length

5

Field Label

Transaction Type

API Name

BillSoft_TransactionType

Description

AFC Transaction Type ID used in combination with the Service Type to specify the type of product or service being sold.

Required

Yes

Invoice

Tax Status

Field Type

Text

Field Length

11

Field Label

Tax Status

API Name

BillSoft_TaxStatus

Default

“Pending” or leave blank.

Description

Field used by the connector to determine if the appropriate tax calculations or adjustments have been processed for the invoice.

Required

No

Invoice Item Adjustment

Tax Status

Field Type

Text

Field Length

255

Field Label

Tax Status

API Name

BillSoft_TaxStatus

Description

Indicates the status of tax calculations for the invoice item adjustment. This field should only be edited by the connector.

Required

No

Discount Type

Field Type

Picklist

Field Label

Discount Type

API Name

BillSoft_DiscountType

Picklist Values

No Discount

Account Level

Goodwill

Manufacturer Product

Retail Product

Subsidized

Description

Indicates the type of discount being applied for an invoice item adjustment.

Required

Yes

Tax Level

Field Type

Text

Field Length

1

Field Label

Tax Level

API Name

BillSoft_TaxLevel

Description

Tax Level ID for taxes generated by AFC

Required

No

Tax Type

Field Type

Text

Field Length

5

Field Label

Tax Type

API Name

BillSoft_TaxType

Description

Tax Type ID for taxes generated by AFC

Required

No

Subscription

Jurisdiction Code

Field Type

Text

Field Length

10

Field Label

Jurisdiction PCode

API Name

BillSoft_JurisdictionPCode

Description

PCode used for determining taxing jurisdiction for order.

Required

No

Subscription Rate Plan Charge

Jurisdiction PCode

Field Type

Text

Field Length

10

Field Label

Jurisdiction Code

API Name

BillSoft_JurisdictionPCode

Description

Taxing jurisdiction for charge.

Field Type

Text

Required

No

Taxation Codes

The AFC Zuora connector requires a single Tax Code to be created and activated in your Zuora tenant. Please follow the instructions provided below to setup this Tax Code.

Step

Action

1

Select the Settings > Z-Billing Settings menu option.

2

Click Setup Taxation Codes on the Z-Billing Settings page.

3

Click the Add New Tax Code button on the Tax Codes page.

4

Enter EZTax for the Tax Code.

5

Enter the desired accounting code.

6

Click the Save button.

 

After creating the EZTax Tax Code, you must import an empty tax rate file in order to activate it. Please follow the steps provided below for activating the Tax Code.

Step

Action

1

Click the link provided to download a template tax rate import file (see screenshot below) and save it on your computer.

2

Select the Choose File button to finish the process and activate the Tax Code.

3

Click the Import Tax Rates button to finish the process and activate the Tax Code.

Figure 12 - Tax Code Setup

image

The EZTax Tax Code must be selected within each Rate Plan Charge for which you wish to use the connector to perform tax calculations.

Step

Action

1

When editing a Product Rate Plan Charge, check the Taxable checkbox under Taxation.

2

Select EZTax from the Tax Code list.

Note: The screenshot below provides an example.

Figure 13 - Enabling Taxation on Rate Plan Charge

image

AFC Zuora Portal

The AFC Zuora Portal is a web application which allows you to setup the configuration for your AFC Zuora connector as well as review the activity performed by connector. The address for this portal is https://zuora.billsoft.com/ZuoraConnector.

Log in with the User ID and password provided to you by Avalara. You will receive two sets of credentials: one for use within Zuora’s live environment (http://www.zuora.com) and one for use within Zuora’s sandbox environment (http://apisandbox.zuora.com). If you need assistance,  submit a support case.

AFC Zuora Activity Home Page

The Activity page, which is also considered the AFC Zuora Home page, displays a list of the most recent activity performed by the Tax Connector indicating the date when a tax calculation process is executed, the number of invoices processed and the number of invoices which failed, if any.

Figure 14 - AFC Zuora Activity Home Page

image

AFC Submit Bill Run Page

The Submit Bill Run page allows the user to submit a bill run ID. If the bill run ID was not previously submitted to the AFC Zuora Connector by any means, the bill run ID can now be added to the list and be processed by the connector. If the bill run ID was previously submitted and processed by the connector, the status of the bill run is changed to Pending and the connector re-processes the bill run. When reprocessing a bill run, only invoices with a Draft status in Zuora are picked up by the connector and processed. Posted invoices are not re-processed.

This is helpful in times when the connector might have processed a bill run, but did not pick up certain invoices due to invalid parameters (e.g. wrong Taxation System custom field value in the Account, or incorrect Tax Code in Product Rate Plan Charge). This feature can also be used to submit a bill run immediately when call out notifications are disabled and it is not desired to wait until the next 15-minute scan performed by the connector in order for the bill run to be submitted.

Figure 15- AFC Zuora Submit Bill Run Page

cid:image001.png@01D330A5.0BC2CFD0

AFC Zuora Configuration Page

The Configuration page allows you to modify the settings for your AFC Zuora connector. The following settings must be specified for the connector to successfully process tax calculations on Zuora invoices.

Figure 16 - AFC Zuora Configuration Page

image

Table 3 – AFC Zuora Connector Configuration

Setting

Description

API User Name

User ID of the API User account which you have created in your Zuora tenant (see API User Account). This user account will be used by the connector to connect to your Zuora tenant to extract invoice information and submit tax calculation results.

Password

Password for Zuora API user account.

Zuora Connector Token

Unique identifier assigned to your organization. This token is used when setting up Bill Run Completed notifications on your Zuora tenant (see Bill Run Notifications).

Business Class

Indicates if your organization is an Incumbent Local Exchange Carrier (ILEC) or a Competitive Local Exchange Carrier (CLEC).

Service Class

Defines the primary activity of your organization as either Primary Long Distance or Primary Local.

Regulated

Indicates if your organization and its services are regulated by the regulatory commission in the state of service.

Franchise

Indicates if the company provides services sold pursuant to a franchise agreement between the carrier and jurisdiction.

Facilities

Specifies if tangible facilities are used by the company to deliver the service.

Enable Customer Mode

Customer Mode in AFC allows brackets and limits to be applied on an invoice basis rather than on each individual line item. Enable customer mode in order to

Adjustment Method

Preferred adjustment method to be used when processing adjustments for bracket determination. In relation to taxes with multiple brackets, it specifies which brackets should be applied. The Default option indicates that brackets should be applied in the order specified by each bracket’s maximum base. The Least Favorable Rate option indicates that the tax engine should use the brackets that yield the least amount of tax to be returned (lowest tax rate). The Most Favorable Rate option indicates that the tax engine should use the brackets that yield the greatest amount of tax to be returned (highest tax rate).

Post Invoices

Specifies whether invoices processed by the Zuora Connector should be automatically posted in Zuora.

Bill Run Notifications

The AFC Zuora connector regularly scans the Zuora tenant to determine if any invoices or invoice item adjustments have been created in order to process tax calculations on them. However, you may setup a bill run notification to inform the connector as soon as a bill run has been completed. Please follow the steps provided below to configure the notification.

Step

Action

1

Click the Settings -> Z-Billing Settings menu option.

2

Click on Setup Profiles, Notifications and Email Templates on the Z-Billing Settings page.

3

If an event for Bill Run Completion | Completed Status already exists, click the Edit link next to it.  Otherwise, click the Add New Notification button.

4

Enter the settings specified in the table below and click the Add New Notification button.

 

Table 4 - Bill Run Notification Setup

Bill Run Setting

Value

Event Category

Bill Run Completion

Event Name

Bill Run Notification for AFC Zuora

Description

Notify Avalara’s AFC Zuora connector when a bill run has been completed in order to process tax calculations on the invoices generated.

Active

Checked

Bill Run Status

Completed

Email

Unchecked

Callout

Checked

Base URL

https://zuora.billsoft.com/ZuoraConn...?token=[token]

NOTE: Replace [token] with your Zuora Connector Token (see Zuora Connector Token).

Parameters

BillRun.ID

BillRun.ExecutedOn

Http Method

GET

Sandbox Account

Log into the AFC Zuora Portal using your sandbox account credentials in order to setup the configuration for your sandbox account. When logged into your sandbox account, the portal’s header displays AFC Zuora Sandbox to indicate that you are logged into your sandbox account.

Figure 17 - Sandbox Account in Portal

image

The configuration for your sandbox and production accounts are separate. The sandbox account connects to http://apisandbox.zuora.com for use with the Zuora sandbox environment. Please follow the same steps to configure your sandbox account as your production account. It is strongly recommended that you use different API User account credentials than in your production environment.

Transactions processed using your sandbox account will not be included in any compliance reports generated by the system at the end of the month.

Tax Calculation Process

AFC Zuora Connector Execution

There are two main events which may trigger the tax calculation process performed by the connector:

  • A bill run completed notification is received.
  • The connector’s scan process is executed.

See the Bill Run Notifications section for an explanation on setting up the bill run notifications. The AFC Zuora connector’s scan process is executed within a 15-minute time interval. The scan process determines if any invoices or invoice item adjustments have been created. The tax calculation process begins immediately after detecting any items which require taxation.

Taxable Items

The following are the different types of items in Zuora that are processed by the AFC Zuora connector:

  • Invoices created through a bill run. The bill run must be in Complete status.
  • Invoices in Draft status created through an external system using Zuora’s API.
  • Invoice Item Adjustments created for Invoice Items for where the custom Tax Status field is blank.

The following conditions must be met for any invoices to be processed by the AFC Zuora connector:

  • The product rate plan charge must have a Tax Code of EZTax
  • The account’s Taxation System custom field must have a value of EZTax
  • For Invoices, the invoice must be in Draft status and have a Tax Status of Pending or blank in order to process tax calculations.

Status Codes

The Tax Status custom field within the Invoice and Invoice Item Adjustment objects is used to determine the action that will be or has been taken by the connector on that particular object. The following actions will be performed by the connector based on the combination of the Status and Tax Status fields:

  • Invoices in Draft status with a blank or “Pending” Tax Status will be processed by the connector. If the tax calculation succeeds, the connector will update the invoice’s status to Posted and the Tax Status to Taxed. If the tax calculation results in an error, the connector will set the invoice’s status to Canceled and the Tax Status to Tax Error.
  • Invoices in Canceled Status with a Tax Status of Taxed will be picked up by the connector in order to cancel out the taxes for that invoice. If the cancelation of the taxes succeeds, the invoice’s Tax Status will be updated to Canceled. If the cancelation results in an error, the Tax Status will be set to Cancel Error.
  • Invoice Item Adjustments in Processed status with a blank or “Pending” Tax Status will be processed by the connector. If the tax calculation succeeds, the Tax Status will be set to Taxed.
  • Invoice Item Adjustments in Canceled status with a Tax Status of Taxed will be canceled out by the connector. If the cancelation succeeds, the tax status will be set to Canceled and if it failed, the tax status will be set to Cancel Error.

Transaction Input Fields

The table below indicates the data fields that are used for tax calculations by the connector. These fields are mapped to an AFC Transaction structure in order to be processed by the AFC engine.

Table 5 - AFC Transaction Input

AFC Transaction Input Field

Data Field

Jurisdiction Determination

Bill-To Address

Account’s Sold-To contact information.

Origination Address

Same as bill to address

Termination Address

Same as bill to address

Incorporated

Account’s incorporated custom field value.

Invoice Information

Date

Invoice’s created date

Charge

Invoice detail charge amount

Lines

Invoice detail quantity (for per-line transaction/service types)

Locations

N/A.

Minutes

N/A.

Adjustment Method

Adjustment Method specified in AFC Zuora Portal.

Discount Type

Product rate plan charge’s Discount Type custom field value.

Product Information

Transaction Type

Product rate plan charge’s Transaction Type custom field value.

Service Type

Product rate plan charge’s Service Type custom field value.

Sale

Default to True (assumes all transactions are retail rather than wholesale)

Debit

Default to false (Prepaid card transactions not available using the AFC Zuora connector).

Customer Information

Customer Type

Account’s customer type custom field value.

Lifeline

Account’s lifeline custom field value.

Company Information

Business Class

Business Class specified in AFC Zuora Portal.

Service Class

Service Class specified in AFC Zuora Portal.

Company Identifier

Assigned by Avalara

Facilities

Facilities value specified in AFC Zuora Portal.

Franchise

Franchise value specified in AFC Zuora Portal.

Regulated

Regulated specified in AFC Zuora Portal.

Exemption Data

Federal Exempt

Account’s tax exempt status.

State Exempt

Account’s tax exempt status.

County Exempt

Account’s tax exempt status.

Local Exempt

Account’s tax exempt status.

Federal PCode

Account’s sold-to contact information.

State PCode

Account’s sold-to contact information.

AFC Transaction Input Field

Data Field

County PCode

Account’s sold-to contact information.

Local PCode

Account’s sold-to contact information.

Exemptions

N/A (specific tax exemptions not available using the AFC Zuora connector).

Tax Jurisdiction Determination

The AFC Zuora connector may use either of the following information in order to determine the taxing jurisdiction for a transaction in the order listed below:

  1. Product Rate Plan Charge Jurisdiction Code
  2. Subscription Jurisdiction PCode
  3. Account Jurisdiction PCode
  4. Account’s Sold-To Contact

If a subscription’s jurisdiction PCode custom field value has been left blank, the connector will use the account’s jurisdiction PCode custom field value. If no value has been specified for this field either, then the account’s sold-to contact information will be used.

When using the sold-to contact information, the following information is required to be populated in each sold-to contact in order for the connector to successfully resolve the taxing jurisdiction:

  • Country
  • State
  • County (optional, but recommended)
  • City
  • Postal Code

For U.S. locations, the postal code must contain at least a valid 5-digit zip code, although it is recommended to enter the zip+4 zip code extension if available. For locations in Canada, a 6-character postal code is required.

The Incorporated custom field in the account is also used to determine if local taxes are to be applied to the invoice’s tax calculations. Default the Incorporated custom field value to Yes, unless a customer indicates otherwise or if you are using a geocoding software to determine if the customer’s address is inside or outside the city limits.

Per-Line Charges and Taxes

Several types of transactions are taxed on a per-line basis. In order to setup these per-line charges, enter the appropriate AFC transaction/service type into the product rate plan charge (e.g. 19/21 for VoIP/Lines). The Charge Model must be set to Per Unit Pricing and UOM to Each. The connector will use the Quantity in the subscription to determine the number of lines to use for tax calculations.

Figure 18 - Per-Line Charge Example

image

Per-Minute Charges and Taxes

Similarly, taxes may be applied on a per-minute basis. To specify per-minute charges, set the Charge Model to Per Unit Pricing and UOM to Minutes.

Figure 19 - Per Minute Example

image

Exemptions

A customer may be exempt from taxation by setting the Tax Exempt status on the customer’s account to Yes in the customer account information. The connector will apply exemptions on all Federal, State, County, and Local taxes on the Sold-To contact’s taxing jurisdiction. Modifying the value of the Issuing Jurisdiction for the exemption in the account information will have no effect within the connector.

NOTE: Certain taxes are not allowed to be exempted by the taxing jurisdiction or regulatory agency. Therefore, the connector will apply those taxes even if the account is tax exempt. This behavior can be overridden by creating an override file for the AFC engine using Avalara’s RLM (Rate and Logic Modifier) tool.

Discounts

Discount types are used by the AFC engine to determine the appropriate applicability of taxes when processing tax calculations on discounts. When creating a Product Rate Plan Charge with a Discount Charge Model in Zuora, select the appropriate value for the Discount Type custom field. Otherwise, leave as No Discount for any other type of regular charges.

The AFC Zuora connector supports tax calculations on discounts created using Zuora’s discount charge models. A discount in Zuora is a separate Invoice Item that is associated to another charge Invoice Item within an invoice through the Applied-To Invoice Item ID field. The following differences apply to discount processing:

  • The Transaction Type and Service Type in the discount’s Product Rate Plan Charge are ignored; however, a value is required and must be entered in these fields. It is recommended to set both the Transaction Type and Service Type fields to 0.
  • The connector will use the Transaction Type and Service Type from the Applied-To Invoice Item’s Product Rate Plan Charge when processing the discount. This ensures that the discount has the same tax applicability as the charge that it is associated with, thereby adjusting the appropriate taxes.
  • The discount will be processed using the same Tax Mode as the Applied-To Invoice Item ID (Tax Inclusive or Tax Exclusive).

Tax Inclusive and Tax Exclusive Calculations

When setting up charges for your products’ rate plans, you may indicate if the specified charge amount is tax inclusive or tax exclusive. When selecting Tax Exclusive, taxes will be calculated using the full charge amount as the sale amount and the taxes generated will be additional charges which are added to the customer’s invoice.

When selecting Tax Inclusive, the connector will determine what the appropriate base sale amount should be so that the base sale amount plus the total tax amount calculated equal the charge amount specified. For invoices, the charge amount on each line item will be updated in order to reflect the base sale amount calculated by AFC. For invoice item adjustments, the original adjustment’s charge will be updated to reflect the base sale amount calculated by AFC, and a new invoice item adjustment will be created for each tax that was generated.

Tax Output for Invoices

When taxes are calculated successfully for an invoice, a Taxation Item object will be created for each tax generated for each invoice line item and the invoice’s status will be set to Posted by the connector. The following table indicates how the tax data output for each tax generated by the AFC engine is copied into each Taxation Item object.

Table 6 - Taxation Item Output

Zuora Taxation Item Field

Value

Accounting Code

Accounting code selected when creating AFC.

Exempt Amount

Exempt sale amount calculated by AFC.

Invoice ID

Invoice ID.

Invoice Item ID

ID of Invoice Detail (line item) that the tax belongs to.

Jurisdiction

Taxing jurisdiction name.

Location Code

Avalara’s PCode for taxing jurisdiction.

Name

Tax type description.

Tax Amount

Tax amount calculated by AFC.

Tax Code

Tax code used by the AFC Zuora connector (“EZTax”).

Tax Code Description

String value containing Avalara tax level ID and tax type ID separated by a forward slash (e.g. 2/10 for tax level 2 and tax type 10 for County/E911 tax.) If the invoice resulted in an error, this field will contain an error code that corresponds to the error message included in the Name field (e.g. “Error Code: -2000).”

Tax Date

Date and time when the tax calculation was processed.

Tax Mode

Tax mode selected in product’s rate plan charge (tax inclusive or tax exclusive).

Tax Rate

Tax rate.

Tax Rate Description

Calculation type used by AFC to determine tax amount (Rate, Per Line, Fixed Rate).

Tax Rate Type

“Rate” or “Flat Fee”.

Customizing Tax Names

The tax type description that is placed in the Name field of the Taxation Item may be customized by creating a CSV file that specifies the name to be displayed for a specific tax type. The CSV file must contain the following columns:

Table 7 – Tax Names CSV File Columns

Column Header

Field Description

TaxLevelID

AFC tax level ID. Value must be numeric. Possible values are:

  1. – Federal

  2. – State

  3. – County

  4. – City

  5. – Unincorporated

TaxTypeID

AFC tax type ID. Value must be numeric.

TaxName

Name for tax as it should appear in TaxationItem object on Zuora Invoice. You may include a description for the tax level if desired. E.g. “Federal Universal Service Fee”. The maximum length for the tax name is 50 characters.

The first row of the CSV file must contain the column headers as indicated in the table above. The file must be named portalUserID-TaxNames.csv where portalUserID is replaced with the user ID used to log in to the AFC Zuora Connector Portal for the tenant that these name changes should be applied to.

This file must be submitted via a support case for installation on your AFC Zuora Connector account. When tax calculations are performed, the connector will apply the TaxName as specified in the CSV file to any taxes with a matching tax level and tax type IDs.

Invalid entries in the CSV file (such as non-numeric tax level or tax type IDs) may cause a failure which will prevent the connector from processing any invoices on the Zuora tenant that the CSV file is being applied to. Any invalid entries will need to be corrected to allow the connector to apply the tax name customizations and continue processing tax calculations on Zuora invoices.

Tax Output for Invoice Item Adjustments

When taxes are calculated for an invoice item adjustment, a new invoice item adjustment will be created in Zuora for each tax generated. The following table indicates how the tax data for each tax generated by the AFC engine is copied into each invoice item adjustment created by the connector.

Table 8 - Invoice Item Adjustment Tax Output

Invoice Item Adjustment Field

Value

Adjustment Date

Date when the adjustment was processed by the connector.

Accounting Code

None.

Amount

Tax amount calculated by AFC.

Discount Type Custom Field

Same value as original invoice item adjustment.

Tax Status Custom Field

“Processed”.

Comment

Description indicating the tax type, rate and jurisdiction for the tax. For example:

“Tax adjustment for State - Sales Tax with a rate of 0.0615 in OVERLAND PARK, KS”

Reason Code

Same value as original invoice item adjustment.

Type

Value indicating if this is a credit or refund.

Tax Type Custom Field

Avalara tax type ID.

Tax Level Custom Field

Avalara tax level ID.

Non-Billable Taxes

Certain taxes are not allowed to be passed on to the customer. However, your organization is responsible for paying the tax liability to the taxing jurisdiction. Non-billable taxes are not submitted to Zuora to avoid these taxes from showing up in customer invoices. The charges are logged in Avalara’s database and will be shown in the compliance reports generated by Avalara at the end of the month.

Error Handling on Invoices

Errors may occur during taxation if the taxing jurisdiction is not found, or if the transaction/service type indicated in the product rate plan charge are not valid, or some other type of input is missing. If tax calculations fail for any line item within an invoice, the connector will set the invoice’s status to Cancelled.

Figure 20 - Failed Invoice Status

image

In addition, an error message will appear within the tax details for the invoice indicating the reason why taxes failed to be calculated on the invoice.

Figure 21 - Failed Invoice Error Message

image

After correcting the errors that caused the taxation to fail, a new bill run must be generated in order to reprocess the invoice.

Error Handling on Invoice Item Adjustments

If an error occurs during taxation for an invoice item adjustment, the connector will update the custom Tax Status field with an error message.

Figure 22 - Failed Invoice Item Adjustment Tax Status

image

Any errors that caused the taxation on the invoice item adjustment to fail must be corrected. The connector will continue trying to reprocess tax calculations on the item adjustment until it is able to process it successfully. Upon success, the connector will set the Tax Status to “Processed.”

Tax Logs and Compliance Reports

Transaction input and tax calculation results are logged in Avalara’s database in addition to being submitted to your Zuora tenant. The invoice date is used to determine the month for the compliance report in which the taxes for the invoice will show up in. For example, if an invoice is generated on February 28, 2014 the taxes for the invoice will show up in the February 2014 compliance reports which will be generated on March 1st, 2014.

If using AFC SaaS Pro outside of the AFC Zuora connector for additional tax calculations that are required to be reported for compliance purposes, it will be required to enter the month for compliance into the Optional10 field of the AFC transaction structure in yyyyMM format (e.g. 201402 for February 2014) so that these taxes are included along with the taxes calculated by the AFC Zuora connector in the compliance reports.

AFC Connector Setup Checklist

Please use the following checklist to validate your initial setup for using the AFC Zuora connector.

  • Create custom fields specified in the Custom Field table.
  • Create EZTax Tax Code in your Zuora tenant (see Taxation Codes).
  • Create an API user account in your Zuora tenant (see API User Account).
  • Log in to the AFC Zuora Portal to provide the credentials for your API user account and to set the configuration for your connector (see AFC Zuora Portal).
  • Setup a bill run notification for the AFC Zuora connector (see Bill Run Notifications).
  • Set the value for the Lifeline, Incorporated, and Customer Type custom fields on each customer account as appropriate.
  • Set the value for the Discount Type, Transaction Type, and Service Type custom field on each product rate plan charge as appropriate. Make sure to enter a valid transaction/service combination.
  • Was this article helpful?