Review open returns

Avalara automatically generates return filings for each active filing calendar that has a return due in a given cycle. These filings are created based on the return frequency specified in the merchant’s filing calendar (for example, monthly, quarterly, or annual).

Filing cycle overview

Each return follows the cadence established by its filing calendar:

Monthly returns are generated every month.
Quarterly and annual returns are generated at the start of each corresponding filing period.

Once generated, these returns are placed in a READYFORREVIEW state, giving the partner (acting as the Firm) and the merchant an opportunity to validate the data.

Review and approval window

Between the 1st and 10th of each month, merchants are encouraged to:

Review their open returns.
Approve them for filing.

This review step helps ensure accuracy but isn’t mandatory.

Automatic approval

To prevent late filings, Avalara automatically approves all open returns at 5:00 p.m. PT on the 10th of each month. This ensures returns are submitted on time, even if the merchant hasn’t manually approved them.

Query returns statuses

Partners can use the filings query to retrieve all generated returns that are pending approval for a specific merchant:

View request:

query Filings {
  filings(input: {companyId: 123456}) {
    recordsetCount
    value {
      companyId
      id
      month
      type
      year
      filingRegions {
        returns {
          formCode
          formName
          filingType
          filingFrequency
          filingCalendarId
          filedDate
          id
          returnTaxDetails {
            nonTaxableAmount
            numberOfNights
            salesAmount
            taxAmount
            taxType
          }
          returnTaxSummary {
            collectAmount
            nonTaxableAccrualAmount
            nonTaxableAmount
            remittanceAmount
            reportableNonTaxableAmount
            reportableSalesAmount
            reportableTaxAmount
            reportableTaxableAmount
            salesAccrualAmount
            salesAmount
            taxAccrualAmount
            taxAmount
            taxableAccrualAmount
            taxableAmount
          }
          status
          startPeriod
          taxAuthorityId
          totalAdjustments
          totalAugmentations
          totalPayments
        }
      }
    }
  }
}

View response:

{
  "data": {
    "filings": {
      "recordsetCount": 1,
      "value": [
        {
          "companyId": 123456,
          "id": 112233,
          "month": 3,
          "type": "ORIGINAL",
          "year": 2025,
          "filingRegions": [
            {
              "returns": [
                {
                  "formCode": "ARET1",
                  "formName": "AR ET1",
                  "filingType": "ELECTRONICRETURN",
                  "filingFrequency": "MONTHLY",
                  "filingCalendarId": 1166792,
                  "filedDate": null,
                  "id": 1233444,
                  "returnTaxDetails": [
                    {
                      "nonTaxableAmount": 0,
                      "numberOfNights": null,
                      "salesAmount": 0,
                      "taxAmount": 0,
                      "taxType": "Sales Tax"
                    },
                    {
                      "nonTaxableAmount": 0,
                      "numberOfNights": null,
                      "salesAmount": 0,
                      "taxAmount": 0,
                      "taxType": "Consumer Use"
                    }
                  ],
                  "returnTaxSummary": {
                    "collectAmount": 0,
                    "nonTaxableAccrualAmount": 0,
                    "nonTaxableAmount": 0,
                    "remittanceAmount": 0,
                    "reportableNonTaxableAmount": 0,
                    "reportableSalesAmount": 0,
                    "reportableTaxAmount": 0,
                    "reportableTaxableAmount": 0,
                    "salesAccrualAmount": 0,
                    "salesAmount": 0,
                    "taxAccrualAmount": 0,
                    "taxAmount": 0,
                    "taxableAccrualAmount": 0,
                    "taxableAmount": 0
                  },
                  "status": "READYFORREVIEW",
                  "startPeriod": "2025-03-01T00:00:00",
                  "taxAuthorityId": 277,
                  "totalAdjustments": 0,
                  "totalAugmentations": 0,
                  "totalPayments": 0
                }
              ]
            },
            {
              "returns": []
            }
          ]
        }
      ]
    }
  }
}

Important

If a return is modified through adjustments or new transaction imports, Avalara will regenerate the return and update it in the filings list.
Partners may also want to track whether a particular filing calendar is currently being updated or is in the READYFORREVIEW state.

Filing return status

These are the possible statuses:

READYFORREVIEW: Ready for review by merchant
REFRESHINGNUMBERS: Currently refreshing tax numbers
PREPARINGTOFILE: In the process of preparing to file
FILED: Return has been filed