Connect to the Avalara Managed Returns API

Guide: Avalara Managed Returns API (U.S. and Canada)

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

Tip

If you’re building and testing your integration, you can use Dev MCP (Development Model Context Protocol) to assist your development workflow. It allows you to access Managed Returns developer documentation directly from your IDE.

Dev MCP isn’t the standard MCP offering and is intended only for development and testing purposes. It isn’t required to connect to the Avalara Managed Returns API.

For setup instructions and more information, see the Avalara MCP server documentation.

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’re 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

Related resources

The following resources provide additional information on different ways to work with Avalara Managed Returns and related developer tooling:

Avalara intelligent agents and deterministic systems - Learn how AI-powered agents and deterministic systems work together in Avalara solutions.