Skip to main content

Flexible Tax Mapping

Zuora

Flexible Tax Mapping

  1. Last updated
  2. Save as PDF

When supported tax apps and vendors complete tax calculations and send back the results, Zuora stores the returned values in the database with a built-in rule for mapping fields. With Flexible Tax Mapping, you can override the built-in mapping rule to select and store the data that best suits your business needs.

Customize field mappings

Before customizing field mappings, purchase the tax app you want to use from the Marketplace, install it, and access it in your Zuora tenant. See Configurable tax app for information about purchasing an app, installing it, and accessing it in Zuora Billing.

To customize field mappings, navigate to Engine Setting > Field Mappings. Click Add Mapping and specify values for Field Name and Field Path.

Mapping fields in tax engines

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

Note that we only support 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 from Vertex 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

Example

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:

Vertex.png

  • 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__

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

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 Vertex Advantage Tax Connector app (Taxamo) 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 Taxamo’s response. 

Only the fields under the transaction_lines block can be mapped as field path.

Example

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:

Taxamo.png

  • 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:

clipboard_e2a2f778c90591e269057307e24ea7599.png

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.

Example

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:

OneSource.png

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.

Example

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.png

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

Avalara AvaTax for Sales 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 Sales app (AvaTax) 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 AvaTax’s response. 

Only the fields in the details block can be mapped as field path. For example, the following signatureCode field is in the details block under lines, so the signatureCode field can be mapped as field path.

Example

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:

AvaTax.png

  • 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.

Example

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:

SureTax.png

  • 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