Connect to the Avalara Managed Returns API

Before you begin integrating with the Avalara Managed Returns API, Avalara will provision your Firm Account, which represents your platform or service. Once provisioned, you’ll receive API credentials to authenticate and begin onboarding your merchant customers (Client Accounts).

API endpoint can be accessed through this URL: https://returns-api.sbx.avalara.com/graphql

The API requires a JWT access token for authentication, where:

client_id = accountId
client_secret = licenseKey

To generate the token

Use the following cURL command to request an access token:

Authentication and credentials

Each account, Firm or Client, receives its own set of credentials:

client_id: The Avalara account ID (accountId)
client_secret: The license key for the account (= licenseKey)

These values are used to generate a JWT access token, which must be included in all authenticated API calls.

Auth SBX can be accessed through this URL: https://ai-sbx.avlr.sh/connect/token

When to use Firm vs Client authentication?

Firm account credentials

Use these credentials to:

Create and provision new Client accounts
Retrieve a list of linked clients
Remove Client account from your Firm

Client account credentials

Use these credentials to:

Link existing Client accounts to your Firm
Create and manage companies
Configure Filing calendars
Retrieve or update Filings, Notices, and other client-specific data

Note

A partner (Firm) must authenticate into the Client’s account using that Client’s credentials to manage filings, returns, calendars, or notices.

As you provision or link client accounts, you are responsible for securely capturing and storing their accountId and licenseKey for future use.

Generate a JWT access token

The API requires a JWT access token for authentication, where:

client_id = accountId
client_secret = licenseKey

To generate the token

Use the following cURL command to request an access token:

View request:

curl --location 'https://ai-sbx.avlr.sh/connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id={accountId}' \
--data-urlencode 'client_secret={licenseKey}'

A successful request returns a JSON response with the access token:

View response:

{
    "access_token": "",
    "expires_in": 3600,
    "token_type": "Bearer",
    "scope": "avatax_api des_api des_monitor"
}

Use the access token

Include the access_token in the Authorization header for API requests.

Ensure you prepend "Bearer" before the token, as shown below:

Authorization: Bearer