Avalara Managed Returns API

Overview

The Avalara Managed Returns API is designed for partners, such as software platforms or service providers, who want to offer a branded, compliant tax return experience directly within their product. This GraphQL-based solution allows partners to automate their customers’ sales tax preparation, filing, and remittance across U.S. jurisdictions, using Avalara’s infrastructure for compliance, scalability, and accuracy.

In the Avalara Managed Returns API, a partner acts as a Firm, onboarding their merchant customers (Clients) into the Avalara system. Each Client is assigned their own Avalara account, which is linked to the Firm through a firm-client linkage. This linkage enables the partner to manage the returns lifecycle on behalf of each Client. Each Client account may contain one or more Companies, representing the legal entities that require tax filing.

The Avalara Managed Returns API uses 5 key objects to configure and manage the filing process: Account, Firm-Client linkage, Company, Filing calendar, and Filing. Each of these objects contributes to the filing process in a distinct way.

This architecture enables scalable, multitenant onboarding and management, giving partners full control over provisioning and integration workflows for their merchant base.

Account

Avalara Managed Returns, an Account represents a participant in the system, either a partner (Firm) or a merchant (Client). Every participant must have an account to use the Managed Returns functionality.

There are 2 types of accounts:

A Firm Account is created for the partner. This account enables the partner to onboard, provision, and manage multiple merchant customers through a branded, embedded experience.
A Client Account represents the merchant using the partner’s platform. This is the Avalara account that holds all tax configuration, companies, and returns data for that merchant.

An Account serves 2 core purposes:

Billing and usage tracking

Avalara tracks activity and applies billing at the account level. This allows partners to view and manage usage for both their own Firm account and the Client accounts linked to them.
Company relationship management

A Client Account may include one or more Companies, which represent legal entities that are registered to collect and remit tax.

Company

A Company represents a legal business entity and is tied to a single Avalara account. Companies are the anchor point for filing activities and jurisdictional obligations. All filing calendars, return obligations, and jurisdictional requirements are managed at the Company level within the Client’s account. Before Avalara can file returns for your clients, a company must be created for each of them. The company must be set up as a reporting entity with a Taxpayer ID.

Firm-client linkage

The firm-client linkage establishes the relationship between a partner (Firm) and each of its merchant customers (Clients) within the Avalara system. This relationship enables the partner to act on behalf of their Clients for tax returns configuration, management, and submission.

Each Firm has its own Avalara account. Every merchant onboarded through the partner’s platform must also have a separate Avalara account, this is referred to as a Client account. These accounts are connected through the firm-client linkage, allowing the partner to centrally manage filings and compliance for all their Clients.

There are 2 ways to establish a firm-client linkage:

Link to an existing Avalara account: If a merchant already has an Avalara account, the partner can link that existing account to their Firm using the firm-client linkage API.
Provision a new Client account: Partners can programmatically create a new Client account via the API. When doing so, the linkage to the Firm is created automatically as part of the provisioning flow.

Note
Firm-client linkage occurs at the account level, not at the individual Company level. Once linked, the Firm gains visibility into and management access for all Companies under that Client account.

This linkage is required to activate Avalara’s Managed Returns functionality for the Client and supports centralized, scalable returns management across the partner’s customer base.

Filing calendar

The filing calendar defines the tax filing obligations for a specific company within a Client’s account. It determines where and when sales tax returns must be filed, how frequently they’re due, and whether any special registration information is required.

Each filing calendar specifies:

What returns are required: For example, Sales and Use Tax, Seller’s Use Tax, or special district filings.
When filings are due: For example, monthly, quarterly, or semiannual.
Jurisdictional registration details: For example, tax IDs or location codes needed to file.

Partners are responsible for working with their merchants to configure the correct filing calendars for each company. This setup is critical to ensure that Avalara can generate and file returns accurately and on time.

The filing calendar acts as the control mechanism for Avalara’s automated returns engine, ensuring filings are scheduled and generated in accordance with local tax rules.

Note

A company must have an approved filing calendar for each jurisdiction where it needs to file. Avalara can’t process or submit returns for jurisdictions without an active, valid calendar.

Tip

You can use Avalara’s jurisdiction detection and onboarding tools to help merchants identify where filings may be required. Automating this process improves accuracy and reduces merchant onboarding friction.

Filings

A Filing represents the actual sales tax return generated and submitted to a tax jurisdiction on behalf of a Company. Filings are automatically created based on the rules defined in the filing calendar.

Each filing contains:

Transaction activity for the reporting period, including sales, exemptions, and tax collected.
Jurisdiction-specific formatting, such as forms, schedules, or efile data structures.
Filing frequency, which determines how often the returns are generated (monthly, quarterly, annually, and so on).

Filings go through a lifecycle that includes:

Creation: Generated automatically based on the active filing calendar.
Reconciliation: Partners can help merchants review the liability summary and ensure that all transactions have been ingested.
Approval: Avalara locks the filing once finalized and prepares it for submission.
Submission: The return is filed with the jurisdiction by Avalara on the merchant’s behalf.

Note
Partners should ensure that all transactional data for the filing period is imported before the filing deadline to avoid delays or late filings.

This automated filing process ensures timely, compliant submission of returns while reducing the operational burden for both partners and their merchant clients.