# Avalara Managed Returns API (EMEA)

Source: https://developer.avalara.com/products/returns/integration-guides/managed-returns-emea/gas7739501601007/

Guide: Avalara Managed Returns API (EMEA)

# Avalara Managed Returns API (EMEA)

Learn how the Avalara Managed Returns API enables VAT return preparation, filing, and remittance across EMEA jurisdictions.

Understand how the Avalara Managed Returns API supports VAT return preparation, filing, and remittance across EMEA jurisdictions.

## Overview

The Avalara Managed Returns API is designed for partners such as software platforms and service providers who want to deliver a branded, compliant VAT return experience directly within their products.

This GraphQL-based solution enables partners to automate their customers’ tax preparation, filing, and remittance across UK jurisdictions, while using Avalara’s infrastructure for compliance, scalability, and accuracy.

In the Managed Returns API, the partner operates as a Firm (or marketplace) and onboards merchant customers, referred to as Clients, into the Avalara system. Each Client is assigned a dedicated Avalara account that is linked to the Firm. This linkage allows the partner to manage the full returns lifecycle on behalf of the Client.

![End-to-end filing workflows](https://knowledge-be.avalara.com/bundle/aot2888389596944_aot2888389596944/page/dij6839615325083.image?_LANG=enus)

The API is structured around 5 key objects that support configuration and end-to-end filing workflows:

-   Account

-   Company

-   Registration

-   Return obligation

-   Return period

Each object represents a distinct component of the returns process, and they work together to enable accurate, timely VAT filings.

This architecture supports scalable, multitenant onboarding and centralized management. This gives partners full control over provisioning, configuration, and integration workflows across their entire merchant base.

## Account

An Account represents a participant in the system, either:

-   A partner called a Firm or marketplace
-   A merchant called a Client

Every participant must have an Account to use Managed Returns.

There are 2 types of accounts:

-   **Firm Account**: Created for the partner. This account allows the partner to onboard, provision, and manage multiple merchant customers through a branded, embedded experience.

-   **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 Firm account and the Client accounts linked to them.

-   **Company relationship management**: A Client Account includes 1 Company, which represents the legal entity that is registered to collect and remit tax. All filing activities roll up through this Company under the Client Account.

## Company

A Company represents a legal business entity and is tied to a single Avalara Account (typically a Client Account).

Companies are the anchor point for filing activities and jurisdictional obligations.

The following are managed at the Company level for a Client account:

-   VAT registrations
-   Return obligations
-   Jurisdictional requirements and obligations
-   Return periods and filings

Before Avalara can file returns for your clients, you must create a Company for each client and configure it.

## Registration

A **Registration** represents a single VAT Registration for a legal entity in a specific country, identified by a VAT number and registration type or scheme.

For example, VAT Registration for the UK.

Each registration:

-   Ties to a specific Client or Company and country
-   Stores the VAT number
-   Includes effective start and end dates

Registrations are created as part of onboarding once the merchant’s VAT number or registration application is available.

## Return obligation

A Return obligation describes the type of return that you must file for a given Registration and how often you must file it.

Each Return obligation:

-   Belongs to a single Registration
-   Specifies the return type
-   Specifies the filing frequency
-   Includes effective start and end dates

A single Registration can have multiple Return obligations, typically one per return type and frequency combination.

For example, for GB registration GB123456789:

-   VAT Return – Monthly
-   EC Sales List – Monthly

Each Return obligation belongs to exactly 1 Registration (for example, GB VAT Registration).

A single Registration can have multiple obligations, typically one per return type and frequency combination (for example, VAT Return – Monthly, EC Sales List – Monthly, Intrastat – Monthly).

Each Return obligation specifies:

-   Return type (for example, VAT Return, EC Sales List, IOSS, Union OSS)
-   Frequency (for example, Monthly, Quarterly, Annual, Special)
-   Effective start and end dates, which drive how Return periods are generated

The Return obligation acts as the return period row for that registration and return type:

-   Determines which forms or reports exist for that registration
-   Drives automatic Return period creation based on the defined frequency and effective date range

## Return period

A Return period is a single filing period under a specific Return obligation.

Each Return period represents a specific instance in time for a return, such as a monthly or quarterly reporting period.

For example:

-   Q1 2026 VAT Return for a quarterly GB VAT Return obligation (start month = 1, end month = 3, year = 2026)
-   April 2024 for a monthly EC Sales List obligation (start month = 4, end month = 4, year = 2024)

Each Return period includes:

-   Parent-Child relationship:
    -   Each Return Period belongs to exactly one Return Obligation (for example, via `returnObligationId` or `filingCalendarId`)
    -   A single Return Obligation typically has a sequence of periods (for example, monthly periods for 2024, quarterly periods for 2025)
-   Time window:
    -   Start month
    -   End month
    -   Year
    -   Start date and end date
-   Filing deadline
-   Links to:
    -   Status
    -   Nil flag
    -   Amounts (liability)
    -   Documents and artifacts, such as drafts, confirmations, and payment data
-   Lifecycle:
    -   Return Periods are typically autogenerated from the Return Obligation’s frequency and effective date range (for example, created every month or quarter while the obligation is active)
    -   A Return Period serves as the anchor for:
        -   Draft generation and client approvals
        -   Submission and payment
        -   Correctives and retroactives (other periods or flags linked back to the original period)

## Filing

A Filing is the concrete VAT return instance generated and submitted for a particular Return period and Return obligation.

A Filing includes:

-   The calculated VAT position and line-level or box-level data
-   The official return payload (PDF, XML, portal copy, and other formats)
-   The submission and payment status with the tax authority

Each Filing follows a repeatable workflow from data ingestion through submission and settlement.

This workflow includes:

-   Ingest transaction data:
    -   At the start of each filing cycle, transaction data for the merchant is imported via API into Avalara
    -   This includes taxable and exempt sales, purchases, and other activity relevant to the Return period
    -   Data can be ingested from the partner’s platform, data lake, or other upstream systems
    -   Both domestic and cross-border transactions are included, along with adjustments, credit notes, and corrections where applicable
    -   Once ingested, the data is normalized and mapped to the appropriate Registration, Return obligation, and Return period
-   Reconcile liability summary:
    -   Avalara generates a liability summary for the period using the ingested data
    -   This includes:
        -   Total taxable and exempt sales
        -   Tax collected and recoverable input tax
        -   Allocation of liability by jurisdiction or tax type
        -   Prepayments, carry-forward credits, or prior-period adjustments where applicable
    -   Partners or merchants can review this liability summary in their own portal or via API before the return is locked and submitted
-   Submit the return:
    -   After the return is locked, Avalara submits the Filing to the appropriate tax authority using the method defined during setup (for example, e-filing via API, web portal upload, or other electronic channels)
    -   The correct Filing format (PDF, XML, portal form, and other formats) is generated from the locked data
    -   Submission responses from the authority, such as acknowledgment IDs, timestamps, or confirmation numbers, are captured and stored against the Filing
    -   Once submission is successful, the merchant or partner can download submission receipts and confirmations for their records