# Avalara Managed Returns API (U.S. and Canada) Source: https://developer.avalara.com/products/returns/integration-guides/managed-returns/qae5286130571702/ Guide: Avalara Managed Returns API (U.S. and Canada) # Avalara Managed Returns API (U.S. and Canada) Use the Avalara Managed Returns API to embed a branded, compliant sales tax return experience in your platform, and automate preparation, filing, and remittance across U.S. jurisdictions. ## Overview The Avalara Managed Returns API is for partners, such as software platforms or service providers, who want to offer a branded, compliant tax return experience directly in their product. This GraphQL-based solution lets partners automate their customers’ sales tax preparation, filing, and remittance across U.S. jurisdictions. It uses Avalara infrastructure for compliance, scalability, and accuracy. In the Avalara Managed Returns API, a partner acts as a **Firm** and onboards their merchant customers, called **Clients**, into the Avalara system. Each Client has its own Avalara account, which is linked to the Firm through a firm-client linkage. This linkage lets the partner manage the returns lifecycle for each Client. Each Client account can contain 1 or more Companies, which represent 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 object supports a specific part of the filing process. This architecture supports scalable, multitenant onboarding and management. It gives partners control over provisioning and integration workflows for their merchant base. ![](https://knowledge-be.avalara.com/bundle/qfq5499557990815_qfq5499557990815/page/lga0057197107111.image?_LANG=enus) ## Account In Avalara Managed Returns, an **Account** represents a participant in the system, either a partner, called a Firm, or a merchant, called a Client. Every participant must have an account to use Managed Returns. There are 2 types of accounts: - A **Firm Account** is created for the partner. This account lets the partner onboard, provision, and manage multiple merchant customers through a branded, embedded experience. - A **Client Account** represents the merchant using the partner’s platform. This Avalara account 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 lets partners view and manage usage for both their own Firm account and the Client accounts linked to them. - **Company relationship management** A Client Account can include 1 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 account. Before Avalara can file returns for your clients, you must create a company for each client. Set up the company as a **reporting entity** with a **Taxpayer ID**. ## Firm-client linkage The **firm-client linkage** defines the relationship between a partner, called a Firm, and each of its merchant customers, called Clients, in the Avalara system. This relationship lets the partner 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, called a **Client account**. These accounts are connected through the firm-client linkage, which lets the partner 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 by using the firm-client linkage API. - **Provision a new Client account**: Partners can programmatically create a new Client account by using the API. When they do this, 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 gets visibility into and management access for all Companies under that Client account. This linkage is required to activate Avalara Managed Returns for the Client. It 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 account. It determines where and when sales tax returns must be filed, how often they’re due, and whether any special registration information is required. Each filing calendar specifies: - **What returns are required**, such as Sales and Use Tax, Seller’s Use Tax, or special district filings. - **When filings are due**, such as monthly, quarterly, or semiannual. - **Jurisdictional registration details**, such as 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 make sure Avalara can generate and file returns accurately and on time. The filing calendar acts as the control mechanism for Avalara’s automated returns engine. It makes sure that filings are scheduled and generated in line 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 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 sales tax return that Avalara generates and submits to a tax jurisdiction on behalf of a Company. Filings are created automatically 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 e-file data structures. - **Filing frequency**, which determines how often the returns are generated, such as monthly, quarterly, or annually. Filings go through this lifecycle: 1. **Creation**: Generated automatically based on the active filing calendar. 2. **Reconciliation**: Partners can help merchants review the liability summary and confirm that all transactions have been ingested. 3. **Approval**: Avalara locks the filing once it’s finalized and prepares it for submission. 4. **Submission**: Avalara files the return with the jurisdiction on the merchant’s behalf. Note Partners should make sure that all transactional data for the filing period is imported before the filing deadline to avoid delays or late filings. This automated filing process supports timely, compliant submission of returns and reduces the operational burden for both partners and their merchant clients.