Tax Engine Settings

Parameter table

Property Name	Type	Description
name	string	The tax engine name.
isTestEnvironment	boolean	Indicates if the tax engine is in a test environment.
useAdvanceSettings	boolean	Determines whether advanced settings are applied. Default is false. If false, all advanced settings are ignored.
vendor	enum	The tax vendor name. The supported values are: Z-Tax Avalara ONESOURCE VertexAdvancedTax
authenticationType	enum	The authentication method. The supported values are: BasicAuth OAuth2 PrivateToken
username	string	Username for accessing the tax URL and tax void URL. Required if authenticationType is BasicAuth.
password	string	Password for accessing the tax URL and tax void URL. Required if authenticationType is BasicAuth.
securityToken	string	Password for accessing the tax vendor. Required if authenticationType is PrivateToken.
accessTokenUrl	string	Access token URL. Required if authenticationType is OAuth2 for on-premise tax vendors.
clientId	string	ClientId. Required if authenticationType is OAuth2.
clientSecret	string	ClientSecret. Required if authenticationType is OAuth2.
networkOpenTimeoutInSeconds	number	Network timeout (in seconds) for establishing a connection.
networkReadTimeoutInSeconds	number	Network Timeout (in seconds) for reading a response.
requestTemplate	string	The request template for tax calculation. If not provided, the system default template is used. This field is required when advanced settings are enabled. Note: When providing the request template as a JSON string, escape special characters to ensure the string can be safely included without breaking the JSON structure.
voidTemplate	string	The request template for voiding tax. Defaults to the system template if not provided. You must provide the void request template when you use advanced settings. Note: When providing the request template as a JSON string, escape special characters to ensure the string can be safely included without breaking the JSON structure.
customFieldMetas	Array of objects	Defines whether to use the latest value of custom fields. Example: "customFieldMetas": {     "useLatestValue" : true,     "customFieldName" : "PicklistCustom__c",     "customFieldObjectType" : "Account"   }
requestHeaders	map	HTTP request headers in key-value pairs. Example:  "requestHeaders": {      "Accept-encoding" : "gzip, deflate, br" }
responseMappings	map	Custom mappings for interpreting the tax engine response.
jsonFields**	map	JSON fields configuration.

HTTP request:

POST https://rest.zuora.com/apps/settings/tax-engines/

Request body:

curl --location 'https://rest.zuora.com/apps/settings/tax-engines/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <oauth token>' \
--data '{
    "name": "My Direct Avalara",
    "isTestEnvironment": true,
    "vendor": "Avalara",
    "authenticationType": "BasicAuth",
    "username": "username",  // Avalara accountNumber
    "password": "password",  // Avalara licenseKey
    "useAdvancedSettings": false
}'

Response body:

{
    "id": "402833ec850fae4a01850fb5d039132d",
    "name": "My Direct Avalara",
    "vendor": "Avalara",
    "isTestEnvironment": true,
    "authenticationType": "BasicAuth",
    "username": "username",
    "useAdvancedSettings": false,
    "success": true
}

Request body - Advanced mode:

curl --location 'https://rest.zuora.com/apps/settings/tax-engines/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <oauth token>' \
--data '{
    "name": "My Direct Avalara",
    "vendor": "Avalara",
    "isTestEnvironment": true,
    "authenticationType": "BasicAuth",
    "username": "username",
    "password": "password",
    "useAdvancedSettings": true,
    "networkOpenTimeoutInSeconds": 60,
    "networkReadTimeoutInSeconds": 60,
    "requestTemplate": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "voidTemplate": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "requestHeaders": { "content-type": "application/json" },
    "responseMappings": { "TextCustom__c": "abc" },
    "customFieldMetas": [
        {
            "useLatestValue": true,
            "customFieldName": "Entity__c",
            "customFieldObjectType": "Account"
        }
    ]
}'

Response body - Advanced mode:

{
    "id": "402833ec850fae4a01850fb5d039132d",
    "name": "My Direct Avalara",
    "vendor": "Avalara",
    "isTestEnvironment": true,
    "authenticationType": "BasicAuth",
    "username": "username",
    "useAdvancedSettings": true,
    "networkOpenTimeoutInSeconds": 60,
    "networkReadTimeoutInSeconds": 60,
    "requestTemplate": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "voidTemplate": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "requestHeaders": { "content-type": "application/json" },
    "responseMappings": { "TextCustom__c": "abc" },
    "customFieldMetas": [
        {
            "useLatestValue": true,
            "customFieldName": "Entity__c",
            "customFieldObjectType": "Account"
        }
    ],
    "success": true
}

Create a Tax Engine for ONESOURCE

For details on the parameter fields, see Parameter Table.

Request body:

{
    "name": "My ONESOURCE",
    "isTestEnvironment": true,
    "vendor": "ONESOURCE",
    "authenticationType": "OAuth2",
    "clientId": "abc",
    "clientSecret": "123",
    "useAdvancedSettings": false
}

Response body:

{
   "success": true,
   "id": "8ad08595987feb1c019891bc109d21ef",
   "name": "My ONESOURCE",
   "isTestEnvironment": true,
   "vendor": "ONESOURCE",
   "authenticationType": "OAuth2",
   "clientId": "abc",
   "useAdvancedSettings": false
}

Create a Tax Engine for VertexAdvancedTax

For details on the parameter fields, see Parameter Table.

Request body:

{
    "name": "My VertexAdvancedTax",
    "isTestEnvironment": true,
    "vendor": "VertexAdvancedTax",
    "authenticationType": "PrivateToken",
    "accessTokenUrl": "abc",
    "useAdvancedSettings": false
}

Response body:

{
   "success": true,
   "id": "8ad08288987feb25019891cb02c92a32",
   "name": "My VertexAdvancedTax",
   "isTestEnvironment": true,
   "vendor": "VertexAdvancedTax",
   "authenticationType": "PrivateToken",
   "useAdvancedSettings": false
}