Link an existing Client Account

If a merchant already has an Avalara account, you can connect their existing account to your Firm using the firm-client linkage mutation. This establishes a formal relationship between your Firm and the Client within the Avalara system.

Once linked, your platform will be able to:

View and manage the client’s returns configuration
Submit and track filings
Access and monitor tax notices

Requirements for linking an existing Client account:

Authenticate using the client account credentials (that is, the merchant’s accountId and licenseKey).
The client must provide their Avalara account ID and license key so that the linkage can be authorized.
The Firm is responsible for storing the Client credentials securely and using them for any API requests related to the Client’s filings, calendars, or transactions.

Note

Once the linkage is established, all operations that affect a specific client (for example, setting up filing calendars, submitting transactions, or viewing filings) must be performed using the Client’s API credentials, not the Firm’s.

Use the Firm credentials to manage linkages.
Use the Client credentials for day-to-day returns operations.

Use the following mutation to create a linkage between the client account and a firm account:

View request:

mutation CreateFirmClientLinkage {
    createFirmClientLinkage(
        input: { firmAccountId: 12345, firmAccountName: "anonymous" }
    ) {
        clientAccountId
        clientAccountName
        firmAccountId
        firmAccountName
        firmContactEmail
        firmContactName
        id
        isDeleted
        status
        company {
            companyId
            accountId
            name
            isDefault
            isActive
            hasProfile
            isReportingEntity
            companyCode
            isTest
        }
    }
}

View response:

{
  "data": {
    "createFirmClientLinkage": {
      "clientAccountId": 12345,
      "clientAccountName": "anonymous",
      "firmAccountId": 2091022162,
      "firmAccountName": "ABCDE",
      "firmContactEmail": "",
      "firmContactName": "anonymous ",
      "id": 340444,
      "isDeleted": false,
      "status": "APPROVED",
      "company": null,
      "licenseKey": null
    }
  }
}