Select regions and forms to file returns

Determine where to file returns

In this step, partners guide the merchant in identifying the regions (states or jurisdictions) where tax returns should be filed. This can be done either by using Avalara’s automated recommendations based on historical transaction data or by manually selecting from a list of supported forms per jurisdiction.

Partners have 2 supported options for enabling merchants to choose return forms:

Recommended approach

Option 1: Use suggested Returns based on transaction history

If historical transaction data has been imported for the client (via the onboarding transaction import process), Avalara will analyze this data and provide automated return form suggestions.

These suggestions are available via the suggestedTaxForms field of the companies GraphQL query. Each suggestion includes:

The region and country
A list of return forms applicable to that region
The tax authority name and form description

View respect:

query Companies {
    companies(id: 123456) {
        value {
            suggestedTaxForms {
                country
                region
                suggestedReturns {
                    description
                    taxAuthorityId
                    taxAuthorityName
                    taxFormCode
                    taxFormName
                    taxTypes
                }
                answeredQuestions {
                    accountId
                    answerId
                    companyId
                    country
                    onboardingQuestionAnswerId
                    questionId
                    region
                }
                onboardingQuestions {
                    allowMultiSelect
                    country
                    dataType
                    helpText
                    question
                    questionId
                    region
                    sequence
                    standard
                    answers {
                        answer
                        answerHelpText
                        leadingQuestionAnswerId
                        nextQuestionId
                        taxFormCode
                    }
                }
            }
        }
    }
}

View response:

{
  "data": {
    "companies": {
      "value": [
        {
          "suggestedTaxForms": [
            {
              "country": "US",
              "region": "NC",
              "suggestedReturns": [
                {
                  "description": "Sales and Use Tax Return",
                  "taxAuthorityId": 123,
                  "taxAuthorityName": "NORTH CAROLINA",
                  "taxFormCode": "ABCDE",
                  "taxFormName": "ABCDE",
                  "taxTypes": [
                    "Sales Tax",
                    "Sellers Use",
                    "Consumer Use"
                  ]
                }
              ],
              "answeredQuestions": [],
              "onboardingQuestions": [
                {
                  "allowMultiSelect": false,
                  "country": "US",
                  "dataType": "",
                  "helpText": "",
                  "question": "",
                  "questionId": 12,
                  "region": "NC",
                  "sequence": 1,
                  "standard": false,
                  "answers": [
                    {
                      "answer": "",
                      "answerHelpText": "",
                      "leadingQuestionAnswerId": 123,
                      "nextQuestionId": null,
                      "taxFormCode": "[\"ABCDE\"]"
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  }
}

Note

Avalara’s suggested forms rely on recent transaction data. For the best experience, partners should upload at least 12 months of historical data before initiating this step.

Option 2: Manual form selection

If the merchant wants to add additional regions not covered by past sales or business address, partners can use the taxForms query to retrieve a list of all supported returns forms by region.

This allows the partner to present an interface where the merchant can select a region (state or jurisdiction) and view the forms that Avalara supports for that region.

Note

This approach is ideal when no transaction history is available, or when the merchant wants to proactively register in new jurisdictions.

View request:

query TaxForms {
  definitions(input: {country: "US", region: "AR"}) {
    value {
      taxForms {
        authorityName
        country
        displayName
        taxFormCode
        taxFormName
        taxAuthority
        shortCode
        revision
        region
        purpose
        minor
        legacyReturnName
      }
    }
  }
}

View response:

{
  "data": {
    "definitions": {
      "value": {
        "taxForms": [
          {
            "authorityName": "MIDWEST TAX AGENCY",
            "country": "US",
            "displayName": "US-AR Sales Tax Form A",
            "taxFormCode": "FORM-US-AR-001",
            "taxFormName": "Arkansas Sales and Use Form A",
            "taxAuthority": "ARKANSAS DOR",
            "shortCode": "AR001",
            "revision": 19,
            "region": "AR",
            "purpose": null,
            "minor": 0,
            "legacyReturnName": null
          },
          {
            "authorityName": "MIDWEST TAX AGENCY",
            "country": "US",
            "displayName": "US-AR Sales Tax Form B",
            "taxFormCode": "FORM-US-AR-002",
            "taxFormName": "Arkansas Sales and Use Form B",
            "taxAuthority": "ARKANSAS DOR",
            "shortCode": "AR002",
            "revision": 5,
            "region": "AR",
            "purpose": null,
            "minor": 0,
            "legacyReturnName": null
          }
        ]
      }
    }
  }
}

Return form setup isn’t a one-time activity. Merchants may expand into new jurisdictions over time, requiring additional filing calendars and forms. Partners should design their onboarding and settings UI to allow merchants to:

Review configured return forms
Add new regions and forms at any time
Update jurisdictional details (for example, filing frequency, registration numbers)

Next step

Once the merchant has selected their returns forms, either from Avalara’s suggestions or by browsing supported forms, the partner proceeds to configure filing calendars and gather any additional jurisdiction-specific information.