Client Headers

The AvaTax REST V2 API uses the X-Avalara-Client request header to identify the application making each request. As a tax provider, Avalara records information about every call made to the AvaTax API. This information contains information about errors, system performance, and characteristics of usage.

The client header will help you identify information about which version of software was used to make an API call. If you identify something concerning in your data or your system, the client header contains a “Fingerprint” that can help figure out which software version or library may be affected by the problem. It is required for all integrations.

The header includes a unique identifier (for example, a0o5a000007T8dRAA1). This unique identifier will be provided by Avalara. It is not intended to replace your app name or version, but rather to augment the client header for internal tracking purposes.

Note

  • For Technology Partners: You will receive a unique client identifier from Avalara.
  • For Customers using API: It is recommended to self-define a meaningful client value (e.g., integration or platform version) to aid support log identification.

Avalara uses this identifier to:

  • Monitor API usage across specific integrations and partner applications
  • Support troubleshooting and performance analysis

How to include it

Use the X-Avalara-Client header in standard semicolon-delimited format: AppName; AppVersion; AdapterName; AdapterVersion; MachineName. For connectors, include the Avalara-provided unique identifier in AppVersion only, not appended to Connector Name.

The structure of the client header is:

X-Avalara-Client: (AppName); (AppVersion); (AdapterName); (AdapterVersion); (MachineName)

Let’s look at what these fields are and how they are useful:

Field Description Example Required
AppName The name of your application or integration. Choose a value that clearly identifies your software MyERPSystem Yes
AppVersion For Technology Partners: A unique identifier string provided by Avalara (e.g., a0o5a000007T8dRAA1). For API Customers: The version number of your application or integration. a0o5a000007T8dRAA1 Yes
AdapterName If you are using a client library to connect to AvaTax, this should be the name of the client library. AvaTax-Java-SDK Suggested
AdapterVersion The release version of the library or SDK your application uses to communicate with AvaTax. Update this only when the library itself is released with a new version. 17.12.0.147 Suggested
MachineName The name or identifier of the machine making the request. This can help distinguish requests originating from different hosts. LAPTOP-W601 Optional

Providing accurate client header information ensures:

  • The application name is clearly identifiable
  • Version details remain accurate and up to date
  • The Avalara-provided unique identifier is preserved for tracking
  • The SDKs provided by Avalara generates a properly formatted X-Avalara-Client header

Implementation

If your integration already uses REST API v2 but Avalara is not receiving client headers, verify your implementation using the guidance below.

1. Using a Custom HTTP Client

If you are not using an Avalara SDK, manually include the X-Avalara-Client header with every REST API request.

Example:

POST /api/v2/transactions/create
X-Avalara-Client: MyStore;2.4.1;Custom Client;1.0;Server01
Authorization: Basic xxxxxxxxx
Content-Type: application/json

2. Using an Avalara SDK

Avalara provides SDKs for several programming languages that simplify working with REST API v2.

Depending on the SDK, portions of the client header may be generated automatically. However, you are responsible for ensuring that your application information is provided where required.

See the AvaTax SDK documentation for language-specific implementation details.

SDK Examples

Refer to the SDK documentation or GitHub repositories for language-specific examples. Supported SDKs include:

1. JavaScript

Example:

const config = {
  appName: 'Aptech-PMS',        // your app/system name -> becomes part of the client header
  appVersion: '1.0',            // your app version -> becomes part of the client header
  environment: 'sandbox',       // 'sandbox' or 'production'
  machineName: 'app-server-01', // optional, but recommended for tracing calls
  timeout: 5000,                // optional, ms; default is 20 min
};
2. C#

Example:

var Client = new AvaTaxClient("Aptech-PMS", "1.0", Environment.MachineName, AvaTaxEnvironment.Sandbox)
    .WithSecurity("MyUsername", "MyPassword");
3. Java

Example:

AvaTaxClient client = new AvaTaxClient("Aptech-PMS", "1.0", "app-server-01", AvaTaxEnvironment.Sandbox)
                .withSecurity("MyUsername", "MyPassword");
4. PHP

Example:

$client = new Avalara\AvaTaxClient('phpTestApp', '1.0', 'localhost', 'sandbox');
$client->withSecurity('myUsername', 'myPassword');
5. Python

Example:

client = AvataxClient('Aptech-PMS',
                       '1.0',
                       'app-server-01',
                       'sandbox')
# Add credentials (Account ID / License Key)
client = client.add_credentials('MyUsername', 'MyPassword')
6. Ruby

Example:

@client = AvaTax::Client.new({
  :app_name       => 'Aptech-PMS',
  :app_version    => '1.0',
  :machine_name   => 'app-server-01',
  :environment    => 'sandbox',
  :username       => 'MyUsername',
  :password       => 'MyPassword',
  :logger         => true,
  :log_request_and_response_info => true
})

Migrating to REST API v2

Client headers are supported only by the AvaTax REST API v2. If your integration currently uses SOAP or REST API v1, you must migrate to REST API v2 before implementing client headers.

Migrating from SOAP

SOAP implementations do not support transmitting the X-Avalara-Client HTTP header. To use client headers, migrate your integration to REST API v2.

This limitation is specific to the legacy SOAP API and does not apply to the AvaTax REST API v2. To implement functionality that depends on client headers, you will need to refactor your integration to AvaTax REST API v2.

Migrating from REST API v1

REST API v1 integration should migrate to REST API v2 to take advantage of current platform capabilities, including client header support.

For detailed migration instructions, see: REST API v1 to REST API v2 Refactor Guide

Troubleshooting

Client Header Not Received

Possible causes include:

Issue Resolution
Using SOAP Migrate to REST API v2. SOAP does not support client headers. See Migrating from SOAP above
Using REST API v1 Upgrade to REST API v2. See Migrating From Rest API V1 above
Header not included Add the X-Avalara-Client header to every request
Incorrect header format Verify that fields are separated by semicolons
Outdated SDK Upgrade to the latest supported SDK version

Frequently Asked Questions

1. Do client headers affect tax calculations?

No. Client headers are informational only. They do not affect tax calculations or AvaTax API behavior.

2. Does SOAP support client headers?

No. SOAP implementations do not transmit the X-Avalara-Client HTTP header. To use client headers, you must migrate to REST API v2. See Migrating from SOAP for the full list of migration steps and links to detailed guides.

3. I am using REST API v1. Do I need to migrate?

Yes. Client headers are only supported in REST API v2. REST API v1 customers must upgrade to take advantage of client header support and other current platform capabilities. See Migrating from REST API v1 for migration steps and a link to the detailed refactor guide.

4. Do I have to use an Avalara SDK?

No. You can use any HTTP client capable of sending custom HTTP headers.

5. Can I customize the client header?

Yes. You should populate each field with information that accurately identifies your application and version, while following the documented semicolon-delimited format.