VAT GraphQL API

Provides VAT GraphQL operations, including fileUploadStatus (query) and vatUploadTransactions (mutation), along with their input and result types.

API Endpoints

Production GraphQL endpoint

Queries

`fileUploadStatus`

Description

Get file upload status.

Retrieves the processing status of a previously uploaded file.

The id argument must match a fileId returned by vatUploadTransactions. If the identifier is invalid (empty, longer than 256 characters, or contains characters outside [A-Za-z0-9_-]), the API returns status as "Error" with a descriptive message.

Returns

Returns the processing status and related details for the specified file.

Example

query {
  fileUploadStatus(id: "f47ac10b-58cc-4372-a567-0e02b2c3d479") {
    id
    status
    fileName
    error
    message
    transactionId
    info
  }
}

Response

Returns a FileUploadStatusResult

Arguments

Name	Description
`id` - `String!`	Unique file ID returned by `vatUploadTransactions` as `FileUploadResult.fileId`. Required. Must contain only letters, numbers, hyphens, and underscores, and be at most 256 characters.

Example

Query

query fileUploadStatus($id: String!) {
  fileUploadStatus(id: $id) {
    status
    id
    fileName
    error
    message
    transactionId
    info
  }
}

Variables

{"id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"}

Response

{
  "data": {
    "fileUploadStatus": {
      "status": "Completed",
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "fileName": "vat-report-2026-Q1.xlsx",
      "error": "xyz789",
      "message": "File processed successfully",
      "transactionId": "txn_9f3d2c1a4b5e6f7",
      "info": "xyz789"
    }
  }
}

Mutations

`vatUploadTransactions`

Description

Upload VAT transactions file.

Uploads a VAT reporting file for processing. The API accepts Excel, CSV, JSON, or plain-text payloads as base64-encoded content. The API returns a FileUploadResult with a success flag and message.

Supported file types

Excel: .xlsx, .xls
CSV: .csv
Text: .txt
JSON: .json

Constraints

Maximum decoded file size: 50 MB.
fileName, content, contentType and template are all required.
The request requires a valid JWT in the Authorization header.

Returns

Returns the result of the upload, including success status, message, and file details when successful.

Example usage

mutation {
  vatUploadTransactions(input: {
    fileName: "vat-report-2026-Q1.xlsx"
    content: "UEsDBBQAAAAIAA..."
    contentType: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
    template: "Your-Template-Name"
  }) {
    success
    message
    fileId
    fileName
  }
}

Example successful response

{
  "data": {
    "vatUploadTransactions": {
      "success": true,
      "message": "File uploaded successfully",
      "fileId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "fileName": "vat-report-2026-Q1.xlsx"
    }
  }
}

Response

Returns a FileUploadResult

Arguments

Name	Description
`input` - `FileUploadInput!`	Upload payload containing file details and content. See `FileUploadInput` for required fields, size limits, and supported MIME types and templates.

Example

Query

mutation vatUploadTransactions($input: FileUploadInput!) {
  vatUploadTransactions(input: $input) {
    success
    message
    fileId
    fileName
  }
}

Variables

{
  "input": {
    "fileName": "vat-report-2026-Q1.xlsx",
    "content": "UEsDBBQAAAAIAA...",
    "contentType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
    "template": "Your-Template-Name"
  }
}

Response

{
  "data": {
    "vatUploadTransactions": {
      "success": true,
      "message": "File uploaded successfully",
      "fileId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "fileName": "vat-report-2026-Q1.xlsx"
    }
  }
}

Types

Boolean

Description

Represents a boolean value: true or false.

Types

FileUploadInput

Description

Defines the input parameters for vatUploadTransactions. The schema marks contentType and template as nullable for backward compatibility. New integrations should supply both.

Fields

Input Field	Description
`fileName` - `String!`	Name of the file being uploaded, including its extension. Required. Used for downstream file identification and validation.
`content` - `String!`	Base64-encoded file content. Required. Must decode to a non-empty buffer. Maximum decoded size is 50 MB (52,428,800 bytes). Larger payloads are rejected with `success` set to `false` and an error message.
`contentType` - `String`	MIME type of the file. Required for new integrations. Common values Excel 2007+ (`.xlsx`): `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` Excel 97–2003 (`.xls`): `application/vnd.ms-excel` CSV (`.csv`): `text/csv` JSON (`.json`): `application/json` Plain text (`.txt`): `text/plain`
`template` - `String`	Template that defines how the file is parsed, validated, and mapped. Required for new integrations. Available templates `Avalara VAT Reporting Clearing Template` – Avalara Standard Template. `Avalara VAT Reporting Generic Template` – Avalara Standard Template. `Avalara VAT Reporting GL Template` – Avalara Standard Template. `Your Custom Template`

Example

{
  "fileName": "vat-report-2026-Q1.xlsx",
  "content": "UEsDBBQAAAAIAA...",
  "contentType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
  "template": "Your-Template-Name"
}

Types

FileUploadResult

Description

Returns the result of the upload, including success status, message, and file details when successful.

Always includes a boolean success flag and a human-readable message so callers can handle the response consistently. The remaining fields are populated only on successful uploads.

Fields

Field Name	Description
`success` - `Boolean!`	Indicates whether the upload was accepted for processing. `true`: File was accepted and processing continues asynchronously. Use `fileUploadStatus` to track outcome. `false`: Upload was rejected. Inspect `message` for details.
`message` - `String`	Human-readable summary of the upload outcome. Always populated. On success, returns `"File uploaded successfully"`. On failure, returns a descriptive error message.
`fileId` - `String`	Unique ID assigned to the file. Use this value as the `id` argument to `fileUploadStatus` to poll for the processing outcome. Populated only when `success` is `true`. Format: opaque string of letters, numbers, hyphens and underscores (max 256 characters), e.g. `"f47ac10b-58cc-4372-a567-0e02b2c3d479"`. The value is case-sensitive and must not be modified before reuse.
`fileName` - `String`	Original name of the uploaded file, echoed back from the `FileUploadInput.fileName` argument unchanged. Includes the file extension (e.g. `"vat-report.xlsx"`). Populated only on success.

Example

{
  "success": true,
  "message": "File uploaded successfully",
  "fileId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "fileName": "vat-report-2026-Q1.xlsx"
}

Types

FileUploadStatusResult

Description

Represents the processing status of a previously uploaded file returned by fileUploadStatus.

The API populates only the fields that are available when partial information exists.

Fields

Field Name	Description
`status` - `String`	Current processing state of the file. Includes lifecycle states (`Pending`, `Processing`, `Completed`, `Failed`) and diagnostic states (`Error`, `Unknown`). Lifecycle values `Pending`: Upload has been accepted but processing has not yet started. `Processing`: File is currently being parsed and validated. `Completed`: Processing finished successfully. `Failed`: Processing failed; see `error` or `message`. Diagnostic values `Error`: Validation or transport failure (e.g. invalid file ID, or the upload service could not be reached). `message` will explain the cause; other fields may be `null`. `Unknown`: Status was retrieved but the response could not be interpreted. The first 500 bytes of the raw payload are surfaced in `info` for diagnostics.
`id` - `String`	ID of the file whose status is being reported. Echoes the `id` argument supplied to `fileUploadStatus`. Format matches `FileUploadResult.fileId`: an opaque string of letters, numbers, hyphens and underscores, max 256 characters (e.g. `"f47ac10b-58cc-4372-a567-0e02b2c3d479"`). May be `null` if validation failed before the file could be looked up.
`fileName` - `String`	Original file name, as recorded for the upload. Includes the file extension when present (e.g. `"vat-report-2026-Q1.xlsx"`). Not guaranteed to be populated for every status value.
`error` - `String`	Detailed error description when processing fails. Typically `null` while the file is `Pending` or `Processing`.
`message` - `String`	Human-readable note about the current status. On failure, returns a description of the issue.
`transactionId` - `String`	Correlation ID for the processing run. Use this value when reporting issues to support log tracing.
`info` - `String`	Free-form diagnostic payload populated only when the response cannot be interpreted. Contains up to the first 500 characters of the raw payload. Null under normal operation.

Example

{
  "status": "Completed",
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "fileName": "vat-report-2026-Q1.xlsx",
  "error": "abc123",
  "message": "File processed successfully",
  "transactionId": "txn_9f3d2c1a4b5e6f7",
  "info": "abc123"
}

Types

String

Description

Represents textual data encoded as UTF-8 character sequences. Commonly used for human-readable text.

Example

"abc123"