Import transactions during onboarding

Importing historical transaction data is a key first step when setting up a client for returns filing. This process allows Avalara to evaluate past activity and provide suggested returns forms for the jurisdictions where the client has likely tax obligations.

There are 2 primary uses of transaction imports:

During onboarding: To recommend jurisdictions and return forms based on past transactions.
During return preparation: To populate return liabilities and generate the actual filing data.

Prepare transaction data for import

To begin onboarding, the firm must submit historical transaction data via API on behalf of the client.

Note

Typically, 12 months of transaction history is sufficient to provide accurate recommendations across applicable jurisdictions.

Avalara supports 2 separate APIs depending on the amount of detail:

Transaction-level data

Submit detailed records using the createTransaction mutation.

Each transaction record should include the following fields:
- transactionCode (unique ID)
- transactionDate
- grossAmount, taxAmount, and optionally taxableAmount
- Location details: region, country, and preferably a full address for best jurisdiction mapping
- taxRate, taxLevel, and taxType
Each record must include a transactionCode, that is, the field that allows for retrying failed submissions later.
Summary-level data

Submit aggregate tax data using the createTransactionSummary mutation.

Submit transactions

Transactions are submitted in batches. Upon submission, you’ll receive a transactionBatchId, which is used to:

Check the status of the import
Identify and correct errors
Resubmit failed transactions

API reference

For Transaction-level data:

View request:

mutation CreateTransaction {
  createTransaction(
    input: [
      {
        transactionDate: "2025-01-03"
        country: "US"
        region: "AR"
        addressLine1: "151 Polk Road 72"
        county: null
        city: "Mena"
        postalCode: "71953-8186"
        taxType: "Sellers Use"
        taxLevel: "State"
        taxRate: 0.085
        grossAmount: 19.66
        exemptAmount: 0
        taxableAmount: 19.66
        taxAmount: 1.67
        transactionCode: "1234657"
      }
      {
        transactionDate: "2025-01-03"
        country: "US"
        region: "TX"
        addressLine1: "1006 Harrison Ave"
        county: null
        city: "Arlington"
        postalCode: "76011-7361"
        taxType: "Sales"
        taxLevel: "State"
        taxRate: 0.0825
        grossAmount: 85.68
        exemptAmount: 0
        taxableAmount: 85.68
        taxAmount: 7.07
        transactionCode: "12346570"
      }
    ]
    companyId: 9276620
  ) {
    errorMessage
    status
    transactionBatchId
  }
}

View response:

{
    "data": {
        "createTransaction": {
            "status": "SUBMITTED",
            "transactionBatchId": 49, #This Id will be used to check the status
            "errorMessage": null
        }
    }
}

For Summary-level data:

View request:

mutation CreateTransactionsSummary {
  createTransactionsSummary(
    companyId: 123456
    input: [
      {
        year: 2025
        month: 3
        country: "US"
        region: "TX"
        city: "Arlington"
        postalCode: "76011-7361"
        taxType: "Sellers Use"
        grossAmount: 2343
        exemptAmount: 0.0000
        taxableAmount: 300
        taxAmount: 23
      }
    ]
  ) {
    status
    transactionBatchId
    errorMessage
  }
}

View response:

{
  "data": {
    "createTransactionsSummary": {
      "status": "SUBMITTED",
      "transactionBatchId": 1234567, #This Id will be used to check the status
      "errorMessage": null
    }
  }
}

Monitor import status

After submission, the partner must periodically poll the batch status using the transactions query:

View request:

query Transactions {
    transactions(companyId: 123456, batchId: 123456) {
        value {
            batchStatus {
                transactionBatchId
                status
                errorMessages
                hasErrorFile
                fileName
                importType
                createdDate
            }
            batchErrors {
                companyId
                companyName
                status
                errors {
                errorType
                transaction {
                    addressLine1
                    city
                    country
                    county
                    exemptAmount
                    grossAmount
                    postalCode
                    region
                    taxableAmount
                    taxAmount
                    taxLevel
                    taxRate
                    taxType
                    transactionDate
                    transactionCode #This property can be used to identify the transaction
                }
                }
            }
            importHistory {
                value {
                    transactionBatchId
                    status
                    errorMessages
                    hasErrorFile
                    fileName
                    importType
                }
            }
        }
    }
}

Success example

View response:

{
    "data": {
        "transactions": {
            "value": {
                "batchStatus": {
                    "hasErrorFile": false,
                    "status": "COMPLETED",
                    "transactionBatchId": 49
                }
            }
        }
    }
}

Error example

View response:

{
  "data": {
    "transactions": {
      "value": {
        "batchStatus": {
          "transactionBatchId": 12345,
          "status": "COMPLETED",
          "errorMessages": null,
          "hasErrorFile": true,
          "fileName": null,
          "importType": "D",
          "createdDate": "2025-05-27T12:12:39.809153"
        },
        "batchErrors": { # These are batch errors
          "companyId": 456777,
          "companyName": "CRR Onboarding Test V2 33",
          "status": "COMPLETED",
          "errors": [
            {
              "errorType": "INVALIDTAXTYPE", # These are example errors
              "transaction": {
                "addressLine1": "ABC",
                "city": "ABC",
                "country": "AB",
                "county": "",
                "exemptAmount": 0,
                "grossAmount": 1.4,
                "postalCode": "123",
                "region": "XX",
                "taxableAmount": 1.5,
                "taxAmount": 1.5,
                "taxLevel": "State",
                "taxRate": 1.5,
                "taxType": "Sellers Use",
                "transactionDate": "2025-01-04T00:00:00",
                "transactionCode": "123456QWERA" # Error transaction code
              }
            }
          ]
        },
        "importHistory": { # This is import history
          "value": [
            {
              "transactionBatchId": 123456,
              "status": "DELETED",
              "errorMessages": null,
              "hasErrorFile": false,
              "fileName": "CRROnboardingTestV233_202504.csv",
              "importType": "D"
            },
            {
              "transactionBatchId": 123457,
              "status": "DELETED",
              "errorMessages": null,
              "hasErrorFile": false,
              "fileName": "CRROnboardingTestV233_202504.csv",
              "importType": "D"
            }
          ]
        }
      }
    }
  }
}

Handling errors

When errors are present:

Locate the transactions by transactionCode.
Correct the data.
Resubmit using the same transactionCode (this will overwrite the original record).

Note

If the full address isn’t available, Avalara will use fallback logic (ZIP, city+county) to assign tax jurisdictions. However, the best results come from full address data.

Next step

Once historical transactions are successfully submitted and processed:

Avalara will analyze the data to recommend appropriate return forms based on where the tax was collected.
If no transaction data is available, present a list of supported forms by region.