Skip to main content

Flexible Tax Mapping

Zuora

Flexible Tax Mapping

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 field mapping rule. With Flexible Tax Mapping, you can override the mapping rule to select and store the data that best suits your business needs.

Customize field mappings

Prerequisite: Before customizing the field mappings, you need to 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 the field mapping, navigate to ENGINE SETTING > Field Mappings. Click ADD MAPPING and provide the Field Name and Field Path for each pair.

Mapping fields in each tax engine

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 Taxation Item. 

Vertex O Series Tax Connector app

The following table lists the descriptions of supported field names and field paths in Vertex O Series Tax Connector app (Vertex).

  Description
Field name

Field on the Zuora TaxationItem object to store a value. 

The following fields are supported:

  • name
  • locationCode
  • jurisdiction
  • taxCodeDescription
  • taxRateDescription

Apart from the listed fields, you can override the custom fields that are sent in the billing request after activating invoice tax fields in custom fields via Zuora UI. 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 graph illustrates what you can do via Zuora UI:

Vertex.png

  • When the field in the response does not have optional attributes like <CalculatedTax>10.0</CalculatedTax>:
    • Set the field name as "name."
    • Set the field path as 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 like <Imposition impositionId="1">Local Sales and Use Tax</Imposition>:
    • Set the field name as a custom field, which is "Imposition__c" in this case.
    • Set the field path as "Imposition, __content__."

Vertex Advantage Tax Connector app

The following table lists the descriptions of supported field names and field paths in Vertex Advantage Tax Connector app (Taxamo).

  Description
Field name

Field on the Zuora TaxationItem object to store a value. 

The following fields are supported:

  • name
  • locationCode
  • jurisdiction
  • taxCodeDescription
  • taxRateDescription

Apart from the listed fields, you can override the custom fields that are sent in the billing request after activating invoice tax fields in custom fields via Zuora UI. 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 - Desktop & Mobile - Monthly",
        "amount": 49,
        "unit_price": 49,
        "custom_fields": [
          {
            "key": "invoiceItemId",
            "value": "8a2889ea7dc30040017dc79f614b00ab"
          },
          {
            "key": "taxCode",
            "value": "VAT/GST"
          },
          {
            "key": "taxMode",
            "value": "0"
          },
          {
            "key": "dbId",
            "value": "433"
          },
          {
            "key": "chargeId",
            "value": "8a28f83d7cff2177017d2c3eae16057f"
          },
          {
            "key": "documentId",
            "value": "8a2889ea7dc30040017dc79f613100a2"
          },
          {
            "key": "documentNumber",
            "value": "INV01015740"
          },
          {
            "key": "discountAmount",
            "value": "0"
          }
        ],
        "tax_amount": 8.82,
        "tax_deducted": false,
        "tax_region": "IN",
        "tax_rate": 18,
        "tax_country_code": "IN",
        "line_key": "XLjltJUtjYsMruPs",
        "custom_id": "8a2889ea7dc30040017dc79f614b00ab",
        "tax_name": "GST",
        "tax_rate_checks": [
          "CA-BC-PST-enabled",
          "CA-SK-PST-enabled",
          "CA-QC-QST-enabled"
        ],
        "product_tax_code": "310104",
        "tax_number_service": "self-declaration",
        "line_num": 1,
        "deducted_tax_amount": 0,
        "quantity": 1,
        "total_amount": 57.82,
        "deducted_tax_rate": 0,
        "tax_entity_name": "India",
        "tax_supported": true
      }
    ],

The following graph illustrates what you can do via Zuora UI:

Taxamo.png

  • Set the field name as "name," and set the field path as "description."
  • Set the field name as "total_amount__c" (custom field), and set the field path as "total_amount."

Note that 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."}]}

OneSource Determination app

The following table lists the descriptions of supported field names and field paths in OneSource Determination app (Sabrix).

  Description
Field name

Field on the Zuora TaxationItem object to store a value. 

The following fields are supported:

  • name
  • locationCode
  • jurisdiction
  • taxCodeDescription
  • taxRateDescription

Apart from the listed fields, you can override the custom fields that are sent in the billing request after activating invoice tax fields in custom fields via Zuora UI. 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 transaction_lines 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 graph illustrates what you can do via 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 the field name as "name," and the field path as "TAXABLE_COUNTRY_NAME."
  • Set the name of the custom field as "GrossAmount__c," and the field path as "GROSS_AMOUNT, UNROUNDED_AUTHORITY_AMOUNT." 
    As "UNROUNDED_AUTHORITY_AMOUNT" is nested inside "GROSS_AMOUNT," so we follow the rule <outer element>, <nested element> to set the field path.
  • Set the field path as "blank" to store no value on the "name" field.

Avalara AvaTax for Communication app

The following table lists the descriptions of supported field names and field paths in Avalara AvaTax for Communication app (AvalaraTelco).

  Description
Field name

Field on the Zuora TaxationItem object to store a value. 

The following fields are supported:

  • name
  • locationCode
  • jurisdiction
  • taxCodeDescription
  • taxRateDescription

Apart from the listed fields, you can override the custom fields that are sent in the billing request after activating invoice tax fields in custom fields via Zuora UI. 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 graph illustrates what you can do via Zuora UI:

AvalaraTelco.png

  • Set the field name as "name," and set the field path as "cat."
  • Set the field name as "pcd__c" (custom field), and set the field path as "pcd."

Avalara AvaTax for Sales app

The following table lists the descriptions of supported field names and field paths in Avalara AvaTax for Sales app (AvaTax).

  Description
Field name

Field on the Zuora TaxationItem object to store a value. 

The following fields are supported:

  • name
  • locationCode
  • jurisdiction
  • taxCodeDescription
  • taxRateDescription

Apart from the listed fields, you can override the custom fields that are sent in the billing request after activating invoice tax fields in custom fields via Zuora UI. 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 graph illustrates what you can do via Zuora UI:

AvaTax.png

  • Set the field name as "name," and set the field path as "transactionLineId."
  • Set the field name as "signature_Code__c" (custom field), and set the field path as "signatureCode."

CCH SureTax Connector app

The following table lists the descriptions of supported field names and field paths in CCH SureTax Connector app (SureTax).

  Description
Field name

Field on the Zuora TaxationItem object to store a value. 

The following fields are supported:

  • name
  • locationCode
  • jurisdiction
  • taxCodeDescription
  • taxRateDescription

Apart from the listed fields, you can override the custom fields that are sent in the billing request after activating invoice tax fields in custom fields via Zuora UI. 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 graph illustrates what you can do via Zuora UI:

SureTax.png

  • Set the field name as "name," and set the field path as "TaxAuthorityName."
  • Set the field name as "revenue_base__c" (custom field), and set the field path as "RevenueBase."