Mapping fields in tax engines

This reference details the mapping of fields in various tax engines, including Vertex, Taxamo, and Avalara, to the Zuora TaxationItem object, highlighting supported fields and field paths.

The following section illustrates what fields can be mapped and their respective mappings in each tax engine.

Note: Zuora only supports field mapping for the Taxation Item object.

Vertex O Series Tax Connector app

The following table lists the fields that can be mapped and specified in Field Name. Information about how to figure out the path to fetch a value fromVertex O Series Tax Connector app (Vertex) is also provided.


	Description
Field name	Field on the Zuora TaxationItem object to store a value. The following fields are supported: name locationCode jurisdiction taxCodeDescription taxRateDescription After activating invoice tax fields through the Zuora UI, you can override the custom fields that are sent in the billing request, in addition to the listed fields. These custom fields will be reflected in the taxation response, ending with suffix __c (double underscore c). For more information about managing custom fields via Zuora UI, see Manage custom fields .
Field path	Path to fetch a value from Vertex's response. Only the fields in the `Taxes`block can be mapped as field path. A typical response from Vertex is in XML format (<Element attribute></Element>). Path to fetch attribute value: `Element, attribute` Path to fetch element value: `Element, __content__`(double underscore) Do not fetch any value: `blank`

A typical response from Vertex is as follows:

<Taxes taxResult="TAXABLE" taxType="SELLER_USE" situs="DESTINATION" taxCollectedFromParty="BUYER" taxStructure="SINGLE_RATE">
    <Jurisdiction jurisdictionLevel="DISTRICT" jurisdictionId="96933"><![CDATA[RETAIL TRANSACTIONS AND USE TAX (SMGT)]]></Jurisdiction>
    <CalculatedTax>10.0</CalculatedTax>
    <EffectiveRate>0.005</EffectiveRate>
    <Taxable>2000.0</Taxable>
    <Imposition impositionId="1">Local Sales and Use Tax</Imposition>
    <ImpositionType impositionTypeId="1">General Sales and Use Tax</ImpositionType>
    <TaxRuleId>496343</TaxRuleId>
</Taxes>

To map Zuora’s name field with Vertex’s impositionId attribute, the field path is Imposition, impositionId , and the value stored is 1
To map Zuora’s name field with Vertex’s Imposition element, the field path is Imposition, __content__ , and the value stored is Local Sales and Use Tax
To store no value on Zuora’s name field, the field path is blank

The following screenshot illustrates how to specify the values for Field Name and Field Path in the Zuora UI:

When the field in the response does not have optional attributes such as <CalculatedTax>10.0</CalculatedTax> :
- Set Field Name to name
- Set Field Path to the name of the field in the Vertex response field, which is CalculatedTax in this case
When the field in the response has optional attributes such as <Imposition impositionId="1">Local Sales and Use Tax</Imposition> :
- Set Field Name to a custom field, which is Imposition__c in this case
- Set Field Path to Imposition, __content__

Note:

The Vertex O Series Tax Connector app also handles flexible fields, mapping fields such as flexible_code_field, flexible_numeric_field, and flexible_date_field into billing responses as custom fields. To know more about the mapping logic, see Map flexible fields from Vertex to billing response.

Vertex Advantage Tax Connector app


	Description
Field name	Field on the Zuora TaxationItem object to store a value. The following fields are supported: name locationCode jurisdiction taxCodeDescription taxRateDescription After activating invoice tax fields through the Zuora UI, you can override the custom fields that are sent in the billing request, in addition to the listed fields. These custom fields will be reflected in the taxation response, ending with suffix __c (double underscore c). For more information about managing custom fields via Zuora UI, see Manage custom fields .
Field path	Path to fetch a value from Taxamo’s response. Only the fields under the `transaction_lines` block can be mapped as field path.

A typical transaction_lines block from the Taxamo vendor response is as follows:

"transaction_lines": [
            {
                "description": "Live - Monthly",
                "amount": 39.0,
                "unit_price": 39.0,
                "custom_fields": [
                    {
                        "key": "invoiceItemId",
                        "value": "8a28b56b8e554f76018e55f3cbaa3030"
                    },
                    {
                        "key": "taxCode",
                        "value": "VAT/GST"
                    },
                    {
                        "key": "taxMode",
                        "value": "0"
                    },
                    {
                        "key": "dbId",
                        "value": "50715533"
                    },
                    {
                        "key": "chargeId",
                        "value": "8a28828d68a2803f0168ab2e14ae1d2d"
                    },
                    {
                        "key": "documentId",
                        "value": "8a28b56b8e554f76018e55f3cb8c302c"
                    },
                    {
                        "key": "documentNumber",
                        "value": "INV01827680"
                    },
                    {
                        "key": "discountAmount",
                        "value": "0"
                    }
                ],
                "tax_amount": 2.57,
                "tax_deducted": false,
                "tax_region": "US",
                "cached_rate": false,
                "tax_rate": 6.5897435898,
                "additional_currencies": {
                    "tax": {
                        "amount": 39.0,
                        "tax_amount": 2.57,
                        "total_amount": 41.57
                    }
                },
                "tax_country_code": "US",
                "line_key": "YIOeJbRhNhOhm1FU",
                "custom_id": "8a28b56b8e554f76018e55f3cbaa3030",
                "tax_name": "Texas Tax",
                "tax_rate_checks": [
                    "CA-GST-enabled",
                    "CA-BC-PST-enabled",
                    "CA-SK-PST-enabled",
                    "CA-QC-QST-enabled"
                ],
                "product_tax_code": "310104",
                "line_num": 1,
                "quantity": 1,
                "total_amount": 41.57,
                "tax_components": [
                    {
                        "revenue": 39.0,
                        "tax_amount": 1.95,
                        "city": "PLANO",
                        "tax_rate": 6.25,
                        "county": "COLLIN",
                        "tax_authority_name": "TEXAS",
                        "tax_authority_id": "35763",
                        "tax_name": "Sales and Use Tax",
                        "revenue_base": 31.2,
                        "calculated_tax_rate_used": true,
                        "percent_taxable": 0.8,
                        "jurisdiction_code": "35763",
                        "calculated_tax_rate": 5,
                        "state_code": "TX"
                    },
                    {
                        "revenue": 39.0,
                        "tax_amount": 0.31,
                        "city": "PLANO",
                        "tax_rate": 1,
                        "county": "COLLIN",
                        "tax_authority_name": "PLANO",
                        "tax_authority_id": "77891",
                        "tax_name": "Local Sales and Use Tax",
                        "revenue_base": 31.2,
                        "calculated_tax_rate_used": true,
                        "percent_taxable": 0.8,
                        "jurisdiction_code": "77891",
                        "calculated_tax_rate": 0.7948717949,
                        "state_code": "TX"
                    },
                    {
                        "revenue": 39.0,
                        "tax_amount": 0.31,
                        "city": "PLANO",
                        "tax_rate": 1,
                        "county": "COLLIN",
                        "tax_authority_name": "DALLAS METROPOLITAN TRANSIT AUTHORITY",
                        "tax_authority_id": "78120",
                        "tax_name": "Local Sales and Use Tax",
                        "revenue_base": 31.2,
                        "calculated_tax_rate_used": true,
                        "percent_taxable": 0.8,
                        "jurisdiction_code": "78120",
                        "calculated_tax_rate": 0.7948717949,
                        "state_code": "TX"
                    }
                ],
                "tax_entity_name": "US",
                "tax_supported": true
            }
        ],

The following screenshot illustrates how to specify the values for Field Name and Field Path in the Zuora UI:

Set Field Name to name , and set Field Path to description
Set Field Name to total_amount__c (custom field), and set Field Path to total_amount

Note that the preceding example is applicable to invoice. The response body of credit memo is different from the response body of invoice. The fields available for Field Path changes, while the format remains the same. See the following example.

{"refund_note_number"=>nil, 
"tax_amount"=>0, 
"total_amount"=>0, 
"refunded_total_amount"=>57.82, 
"refunded_tax_amount"=>8.82, 
"warnings"=>[{"type"=>"refund-amount-too-high", 
"message"=>"Provided amount to be refunded is too high, trimming."}]}

In addition to maintaining the current flexible fields mapping support, our system also offers the capability to map fields within the tax_components section of the vendor response, simplifying access through direct access as shown in the following image:

Note:

To learn more about enhancing flexible access to tax information in billing and refund responses through the mapping of Vertex advantage tax_component fields, refer to Tax component field mapping for Vertex advantage tax connector app.

OneSource Determination app

The following table lists the fields that can be mapped and specified in Field Name. Information about how to figure out the path to fetch a value from OneSource Determination app (Sabrix) is also provided.


	Description
Field name	Field on the Zuora TaxationItem object to store a value. The following fields are supported: name locationCode jurisdiction taxCodeDescription taxRateDescription After activating invoice tax fields through the Zuora UI, you can override the custom fields that are sent in the billing request, in addition to the listed fields. These custom fields will be reflected in the taxation response, ending with suffix __c (double underscore c). For more information about managing custom fields via Zuora UI, see Manage custom fields .
Field path	Path to fetch a value from Sabrix’s response. Only the fields in the `TAX` block can be mapped as field path.

A typical TAX block from the OneSource Determination vendor response is as follows:

<TAX>           
              <RULE_ORDER>9970</RULE_ORDER>
              <TAXABLE_COUNTRY>US</TAXABLE_COUNTRY>
              <TAXABLE_COUNTRY_NAME>UNITED STATES</TAXABLE_COUNTRY_NAME>
              <TAXABLE_STATE>PUERTO RICO</TAXABLE_STATE>
              <TAXABLE_COUNTY>PONCE</TAXABLE_COUNTY>
              <TAXABLE_CITY>PONCE</TAXABLE_CITY>
              <TAXABLE_POSTCODE>00780</TAXABLE_POSTCODE>
              <TAX_RATE_CODE>CU</TAX_RATE_CODE>
              <TAX_TYPE>CU</TAX_TYPE>
              <ZONE_NAME>PUERTO RICO</ZONE_NAME>
              <ZONE_LEVEL>State</ZONE_LEVEL>
              <TAX_RATE>0.105</TAX_RATE>
              <NATURE_OF_TAX>P</NATURE_OF_TAX>
              <EU_TRANSACTION>false</EU_TRANSACTION>
              <AUTHORITY_UUID>fec10be8-57e8-4ce8-81b5-3475f77a3031</AUTHORITY_UUID>
              <AUTHORITY_CURRENCY_CODE>USD</AUTHORITY_CURRENCY_CODE>
              <CURRENCY_CONVERSION>
                <TAX_EXCHANGE_RATE_DATE>2022-08-09</TAX_EXCHANGE_RATE_DATE>
              </CURRENCY_CONVERSION>
              <EXEMPT_AMOUNT>
                <DOCUMENT_AMOUNT>0.00</DOCUMENT_AMOUNT>
                <UNROUNDED_DOCUMENT_AMOUNT>0.0000000000</UNROUNDED_DOCUMENT_AMOUNT>
                <AUTHORITY_AMOUNT>0.00</AUTHORITY_AMOUNT>
                <UNROUNDED_AUTHORITY_AMOUNT>0.0000000000</UNROUNDED_AUTHORITY_AMOUNT>
              </EXEMPT_AMOUNT>
              <GROSS_AMOUNT>
                <AUTHORITY_AMOUNT>120.00</AUTHORITY_AMOUNT>
                <UNROUNDED_AUTHORITY_AMOUNT>120.0000000000</UNROUNDED_AUTHORITY_AMOUNT>
              </GROSS_AMOUNT>
</TAX>

The following screenshot illustrates how to specify the values for Field Name and Field Path in the Zuora UI:

Assume that you want to map the field name with TAXABLE_COUNTRY_NAME and the custom field GrossAmount__c with UNROUNDED_AUTHORITY_AMOUNT , perform the following actions:

Set Field Name to name , and Field Path to TAXABLE_COUNTRY_NAME
Set Field Name to GrossAmount__c , and Field Path to GROSS_AMOUNT, UNROUNDED_AUTHORITY_AMOUNT As UNROUNDED_AUTHORITY_AMOUNT is nested inside GROSS_AMOUNT , we follow the rule <outer element>, <nested element> to set Field Path
Set Field Path to blank to store no value on the name field

Avalara AvaTax for Communication app

The following table lists the fields that can be mapped and specified in Field Name. Information about how to figure out the path to fetch a value from Avalara AvaTax for Communication app (AvalaraTelco) is also provided.


	Description
Field name	Field on the Zuora TaxationItem object to store a value. The following fields are supported: name locationCode jurisdiction taxCodeDescription taxRateDescription After activating invoice tax fields through the Zuora UI, you can override the custom fields that are sent in the billing request, in addition to the listed fields. These custom fields will be reflected in the taxation response, ending with suffix __c (double underscore c). For more information about managing custom fields via Zuora UI, see Manage custom fields .
Field path	Path to fetch a value from AvalaraTelco’s response. Only the fields in the `txs` block can be mapped as field path.

A typical txs block from the AvalaraTelco vendor response is as follows:

{
  "inv": [
    {
      "doc": "CM00098111",
      "itms": [
        {
          "ref": "8a28e9bd7de2b488017de48c907e2bdc",
          "txs": [
            {
              "bill": true,
              "cmpl": true,
              "tm": 41.1,
              "calc": 1,
              "cat": "UTILITY USER TAXES",
              "cid": 8,
              "name": "Utility Users Tax",
              "exm": 0,
              "lns": 0,
              "min": 0,
              "pcd": 383700,
              "rate": 0.04,
              "sur": false,
              "tax": 1.644,
              "lvl": 3,
              "tid": 16
            },
            {
              "bill": true,
              "cmpl": true,
              "tm": 41.1,
              "calc": 1,
              "cat": "EXCISE TAXES",
              "cid": 4,
              "name": "Federal Excise Tax",
              "exm": 0,
              "lns": 0,
              "min": 0,
              "pcd": 0,
              "rate": 0.03,
              "sur": false,
              "tax": 1.233,
              "lvl": 0,
              "tid": 6
            }
          ]
        },
        {
          "ref": "8a28e9bd7de2b488017de48c907d2bd9",
          "txs": [
            {
              "bill": true,
              "cmpl": true,
              "tm": 20.13,
              "calc": 1,
              "cat": "UTILITY USER TAXES",
              "cid": 8,
              "name": "Utility Users Tax",
              "exm": 0,
              "lns": 0,
              "min": 0,
              "pcd": 383700,
              "rate": 0.04,
              "sur": false,
              "tax": -0.8052,
              "lvl": 3,
              "tid": 16
            },
            {
              "bill": true,
              "cmpl": true,
              "tm": 20.13,
              "calc": 1,
              "cat": "EXCISE TAXES",
              "cid": 4,
              "name": "Federal Excise Tax",
              "exm": 0,
              "lns": 0,
              "min": 0,
              "pcd": 0,
              "rate": 0.03,
              "sur": false,
              "tax": -0.6039,
              "lvl": 0,
              "tid": 6
            }
          ]
        }
      ],
      "incrf": {
        "acct": "5408166",
        "ccycd": "USD",
        "ccydesc": "US Dollar"
      }
    }
  ]
}

The following screenshot illustrates how to specify the values for Field Name and Field Path in the Zuora UI:

AvalaraTelco

Set Field Name to name , and set Field Path to cat
Set Field Name to pcd __c (custom field), and set Field Path to pcd

Avalara AvaTax for Salesappand Direct Avalara Integration

Note: These mappings apply equally to both the Avalara AvaTax for Sales app and the Direct Avalara Integration. Ensure your field paths correspond to the structure returned by your selected tax engine.

The following table lists the fields that can be mapped and specified in the Field Name . These mappings apply to both the Avalara AvaTax for Sales app and the Direct Avalara Integration in Zuora:


	Description
Field name	Field on the Zuora TaxationItem object where the value will be stored. The following standard fields are supported: name locationCode jurisdiction taxCodeDescription taxRateDescription After activating invoice tax fields through the Zuora UI, you can override the custom fields that are sent in the billing request, in addition to the listed fields. These custom fields will be reflected in the taxation response, ending with suffix __c (double underscore c). For more information about managing custom fields via Zuora UI, see Manage custom fields .
Field path	The path to extract the value from the tax engine’s response. Only the fields in the `details` block can be mapped as field path. For example, to map the `signatureCode` field from AvaTax, use a field path like `lines[0].details[0].signatureCode` .

A typical details block from the AvaTax vendor response is as follows:

"lines": [
   {
     "id": 85013306890397,
     "transactionId": 85013306890394,
     "lineNumber": "8ad09c4b8282409a01828601458a5bd8",
     "boundaryOverrideId": 0,
     "customerUsageType": "",
     "entityUseCode": "",
     "description": "8ad09c4b8282409a01828601456a5bd7",
     "destinationAddressId": 85013306890395,
     "originAddressId": 85013306890395,
     "discountAmount": 0,
     "discountTypeId": 0,
     "exemptAmount": 0,
     "exemptCertId": 0,
     "exemptNo": "",
     "isItemTaxable": true,
     "isSSTP": false,
     "itemCode": "",
     "lineAmount": 120,
     "quantity": 1,
     "ref1": "",
     "ref2": "",
     "reportingDate": "2022-08-09",
     "revAccount": "",
     "sourcing": "Destination",
     "tax": 13.8,
     "taxableAmount": 120,
     "taxCalculated": 13.8,
     "taxCode": "P0000000",
     "taxCodeId": 8087,
     "taxDate": "2022-08-09",
     "taxEngine": "",
     "taxOverrideType": "None",
     "businessIdentificationNo": "",
     "taxOverrideAmount": 0,
     "taxOverrideReason": "",
     "taxIncluded": false,
     "details": [
       {
         "id": 85013306890400,
         "transactionLineId": 85013306890397,
         "transactionId": 85013306890394,
         "addressId": 85013306890395,
         "country": "US",
         "region": "PR",
         "countyFIPS": "",
         "stateFIPS": "",
         "exemptAmount": 0,
         "exemptReasonId": 4,
         "inState": true,
         "jurisCode": "72",
         "jurisName": "PUERTO RICO",
         "jurisdictionId": 10190241,
         "signatureCode": "CXFO",
         "stateAssignedNo": "",
         "jurisType": "STA",
         "jurisdictionType": "State",
         "nonTaxableAmount": 0,
         "nonTaxableRuleId": 0,
         "nonTaxableType": "RateRule",
         "rate": 0.105,
         "rateRuleId": 1359492,
         "rateSourceId": 3,
         "serCode": "",
         "sourcing": "Destination",
         "tax": 12.6,
         "taxableAmount": 120,
         "taxType": "Sales",
         "taxSubTypeId": "S",
         "taxTypeGroupId": "SalesAndUse",
         "taxName": "PR STATE TAX",
         "taxAuthorityTypeId": 45,
         "taxRegionId": 2131047,
         "taxCalculated": 12.6,
         "taxOverride": 0,
         "rateType": "General",
         "rateTypeCode": "G",
         "taxableUnits": 120,
         "nonTaxableUnits": 0,
         "exemptUnits": 0,
         "unitOfBasis": "PerCurrencyUnit",
         "isNonPassThru": false,
         "isFee": false,
         "reportingTaxableUnits": 120,
         "reportingNonTaxableUnits": 0,
         "reportingExemptUnits": 0,
         "reportingTax": 12.6,
         "reportingTaxCalculated": 12.6,
         "liabilityType": "Seller"
       }
     ],

The following screenshot illustrates how to specify the values for Field Name and Field Path in the Zuora UI:

Set Field Name to name , and set Field Path to transactionLineId
Set Field Name to signature_Code__c (custom field), and set Field Path to signatureCode

CCH SureTax Connector app

The following table lists the fields that can be mapped and specified in Field Name. Information about how to figure out the path to fetch a value from CCH SureTax Connector app (SureTax) is also provided.


	Description
Field name	Field on the Zuora TaxationItem object to store a value. The following fields are supported: name locationCode jurisdiction taxCodeDescription taxRateDescription After activating invoice tax fields through the Zuora UI, you can override the custom fields that are sent in the billing request, in addition to the listed fields. These custom fields will be reflected in the taxation response, ending with suffix __c (double underscore c). For more information about managing custom fields via Zuora UI, see Manage custom fields .
Field path	Path to fetch a value from SureTax’s response. Only the fields in the `TaxList` block can be mapped as field path.

A typical TaxList block from the SureTax vendor response is as follows:

<TaxList>  
    <Tax>
        <TaxTypeCode>051</TaxTypeCode>
        <TaxTypeDesc>VAT</TaxTypeDesc>
        <TaxAmount>20.84</TaxAmount>
        <Revenue>83.36</Revenue>
        <CountyName>UNKNOWN</CountyName><CityName />
        <TaxRate>0.250000000000</TaxRate>
        <PercentTaxable>1.000000</PercentTaxable>
        <FeeRate>0</FeeRate>
        <RevenueBase>83.36</RevenueBase>
        <TaxOnTax>0</TaxOnTax>
        <TaxAuthorityID>99999056</TaxAuthorityID>
        <TaxAuthorityName>DENMARK</TaxAuthorityName><Juriscode />
    </Tax>
</TaxList>

The following screenshot illustrates how to specify the values for Field Name and Field Path in the Zuora UI:

Set Field Name to name , and set Field Path to TaxAuthorityName
Set Field Name to revenue_base__c (custom field), and set Field Path to RevenueBase

Avalara for Brazil App

The following table lists the fields that can be mapped and specified in the Field Name:


Name	Description
Field Name	Field on the Zuora TaxationItem object where the value will be stored. The following standard fields are supported: name locationCode jurisdiction taxCodeDescription taxRateDescription After activating invoice tax fields through the Zuora UI, you can override the custom fields that are sent in the billing request, in addition to the listed fields. These custom fields will be reflected in the taxation response, ending with suffix __c (double underscore c).
Field Path	The path to extract the value from the tax engine's response. Only the fields in the `taxDetails` block including its direct fields and nested fields can be mapped as field paths. For example, to map the `citationId` field from Avalara Brazil, use a field path like `citationId`, map to field name `citation`Id__c.Use a comma (`,`) to separate nested levels. Examples: Field Name: citationId__cField Path: citationId Field Name: financePriceImpact__c Field Path: taxImpact,impactOnFinalPrice Field Name: brazilTaxMode__c Field Path: taxImpact,impactOnNetAmount

A typical response from Avalara is as follows:

"lines":
    [
        {
            "lineCode": 1,
            "operationType": "standardSales",
            "itemCode": "8adca22d98c0054c0198c5a4aa752fce",
            "useType": "use or consumption",
            ...
            "taxDetails":
            [
                {
                    "jurisdictionName": "Brazil",
                    "jurisdictionType": "Country",
                    "taxImpact":
                    {
                        "impactOnFinalPrice": "Informative",
                        "impactOnNetAmount": "Informative",
                        "accounting": "none"
                    },
                    "taxType": "aproxtribFed",
                    "citation": "Trib aprox R$ 13,45 Federal e R$ 18,00 Estadual Fonte: IBPT",
                    "subtotalTaxable": 100,
                    "rate": 13.45,
                    "tax": 13.45,
                    "exemptionCode": "",
                    "isCustomCitation": false
                },
               ...
                {
                    "jurisdictionName": "Brazil",
                    "jurisdictionType": "Country",
                    "taxImpact":
                    {
                        "impactOnFinalPrice": "Included",
                        "impactOnNetAmount": "Included",
                        "accounting": "none"
                    },
                    "taxType": "cofins",
                    "citation": "PIS/COFINS com alíquota zero conforme: \"Lei nº 10.865/2004, Artigo 28, Inciso VI, incluído pela Lei nº 11.033/2004\"",
                    "citationId": "1f0f4a6e-4e31-41b5-9d6a-14f36bf00b34",
                    "subtotalTaxable": 100,
                    "rate": 0,
                    "tax": 0,
                    "exemptionCode": "",
                    "cst": "06",
                    "calcMode": "rate",
                    "isCustomCitation": false
                },
                ...
            ],
            "cfop": 5101,
            "lineAdditionalInfo": "",
            "lineNetFigure": 82
        }    ],

Welcome to Zuora Product Documentation

Explore our rich library of product information

Mapping fields in tax engines

Vertex O Series Tax Connector app

Vertex Advantage Tax Connector app

OneSource Determination app

Avalara AvaTax for Communication app

Avalara AvaTax for Salesappand Direct Avalara Integration

CCH SureTax Connector app

Avalara for Brazil App

zuora-footer