Avalara Developer Network Developer communications

Chapter 4.1 - Client Profiles

What is a client profile?

Client profiles provide a way to customize how the AFC tax engine interprets a transaction request and returns the tax results. There can be multiple client profiles associated to a client. These customizations include overrides, bundles, exclusions, exemptions, and a few configurations for how tax data is returned.

Why use client profile?

There are a few reasons to use client profiles:

  • Profiles are cached - this speeds up the response times on requests
  • The use of profiles eliminates the need to apply the same override, exclusion, exemption, etc. with each request. Some of the customizations contained within a client profile, such as an override, can be done within an individual transaction request. However, instead of adding the same override, exclusion, or exemption to each line, a customization file can be added to your client ID as a profile. When the profile is specified in the header with client_profile_id, the overrides, exclusions, exemptions, and bundles are automatically be applied to all transactions run using that header.
  • Multiple profiles can be created for your client ID, meaning that multiple scenarios can be created and utilized. Examples uses for multiple profiles include:
    • Separate configurations for different aspects of your business
    • Separate configurations for sub companies
    • Testing proposed configurations
  • How to apply a client profile to a session

    When authenticating to REST v2, pass the desired client profile ID in the client_profile_id header field.

    Postman example

    Add the following headers to your request:
    • api_key
    • client_id
    • Content-Type: application/json
    • client_profile_id

    How to run transactions without a profile

    If a profile is not specified, REST v2 uses the System Default configuration. There are two ways to send send a transaction to AFC Rest v2 without a client profile applied:
    • Do not include client_profile_id from the header. client_profile_id is an optional header field
    • Set client_profile_id to 0 in the header

    How to request a new client profile or changes to an existing client profile

    Contact CommunicationSupport@avalara.com to request a new client profile for your account.
    • Request the configuration changes required and any overrides, exclusions, exemptions, or bundles needed. If you already have customization files, attach those files to the email.
    • Include instructions as to whether the files should be applied to the Sandbox, Production, or both environments.
    • If changes are needed to an existing client profile, include the client_profile_id to be updated.
    • Once applied, the account could take up to 24 hours to refresh with the new changes.


    Client profiles are numbered in sequential order, starting with client_profile_id "1". By default, the System Default profile is "0".