openapi: 3.2.0
info:
  title: Avalara Batches API
  version: '1.0'
  description: 'Operations tagged Batches across 2 of this provider''s published API definitions: avalara-avatax-rest-openapi.yml, avatax-apis-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://rest.avatax.com
  description: AvaTax Production
- url: https://sandbox-rest.avatax.com
  description: AvaTax Sandbox
- url: http://{{baseurl}}
tags:
- name: Batches
  description: Submit and manage batch transaction processing
paths:
  /api/v2/companies/{companyId}/batches:
    get:
      operationId: listBatches
      summary: Avalara List Batches for a Company
      tags:
      - Batches
      parameters:
      - $ref: '#/components/parameters/companyId'
      - $ref: '#/components/parameters/filter'
      - $ref: '#/components/parameters/top'
      - $ref: '#/components/parameters/skip'
      responses:
        '200':
          description: List of batches
      security:
      - basicAuth: []
      - bearerAuth: []
    post:
      operationId: createBatch
      summary: Avalara Create a New Batch
      tags:
      - Batches
      parameters:
      - $ref: '#/components/parameters/companyId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchModel'
      responses:
        '201':
          description: Batch created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchModel'
      security:
      - basicAuth: []
      - bearerAuth: []
    servers:
    - url: https://rest.avatax.com
      description: AvaTax Production
    - url: https://sandbox-rest.avatax.com
      description: AvaTax Sandbox
  /api/v2/companies/{companyId}/batches/{id}/cancel:
    post:
      tags:
      - Batches
      summary: Avalara CancelBatch
      description: 'Marks the in progress batch identified by this URL as cancelled.


        Only JSON batches can be cancelled. If you attempt to cancel a file batch, you will receive an error message.


        Only in progress batches can be cancelled. If you attempt to cancel a batch that its status is not Waiting or Processing, you will receive an error message.

        Cancelling an in progress batch does not delete any transactions that were created before the cancellation.


        Because the batch system processes with a degree of concurrency, and

        because of batch sizes in the queue vary, AvaTax API is unable to accurately

        predict when a batch will complete. If high performance processing is

        required, please use the

        CreateTransaction API.


        ### Security Policies


        * This API requires one of the following user roles: AccountAdmin, AccountOperator, BatchServiceAdmin, CompanyAdmin, CSPTester, SSTAdmin, SystemAdmin, SystemOperator, TechnicalSupportAdmin.'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example: ''
      parameters:
      - name: X-Avalara-Client
        in: header
        schema:
          type: string
        description: Identifies the software you are using to call this API. For more information on the client header, see [Client Headers](https://developer.avalara.com/avatax/client-headers/).
        example: AvaTax Postman Collection
      - name: companyId
        in: path
        schema:
          type: string
        required: true
      - name: id
        in: path
        schema:
          type: string
        required: true
      responses:
        '200':
          description: Successful response
          content:
            application/json: {}
      security:
      - basicAuth: []
      operationId: postApiV2CompaniesByCompanyIdBatchesByIdCancel
      x-operation-id-source: derived
    servers:
    - url: http://{{baseurl}}
  /api/v2/companies/{companyId}/batches/transactions:
    post:
      tags:
      - Batches
      summary: Avalara CreateTransactionBatch
      description: 'Create a new transaction batch objects attached to this company.


        When a transaction batch is created, it is added to the AvaTax Batch v2 Queue and will be

        processed as quickly as possible in the order it was received. To check the

        status of a batch, fetch the batch and retrieve the results of the batch

        operation.


        Because the batch system processes with a degree of concurrency, and

        because of batch sizes in the queue vary, AvaTax API is unable to accurately

        predict when a batch will complete. If high performance processing is

        required, please use the

        CreateTransaction API.


        The maximum content length of the request body is limited to 28.6 MB. If this limit

        is exceeded, a 404 Not Found status will be returned (possibly with a CORS error if

        the API is called from a browser). In this situation, please split the request into

        smaller batches.


        ### Security Policies


        * This API requires one of the following user roles: AccountAdmin, AccountOperator, BatchServiceAdmin, CompanyAdmin, CSPTester, SSTAdmin, SystemAdmin, SystemOperator, TechnicalSupportAdmin.'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example:
                name: TestBatch-638274861770379744
                transactions:
                - createTransactionModel:
                    code: MyTransaction-638274861770379574
                    lines:
                    - number: '1'
                      quantity: 1
                      amount: 100
                      taxCode: PS081282
                      itemCode: Y0001
                      description: Yarn
                    type: SalesInvoice
                    companyCode: DEFAULT
                    date: '2023-08-13'
                    customerCode: ABC
                    purchaseOrderNo: 2023-08-13-001
                    addresses:
                      singleLocation:
                        line1: 2000 Main Street
                        city: Irvine
                        region: CA
                        country: US
                        postalCode: '92614'
                    commit: true
                    currencyCode: USD
                    description: Yarn
                - adjustTransactionModel:
                    companyCode: DEFAULT
                    transactionCode: MyTransaction-638274861770379574
                    documentType: SalesInvoice
                    adjustmentReason: PriceAdjusted
                    adjustmentDescription: Price drop before shipping
                    newTransaction:
                      code: MyTransaction-638274861770379574
                      lines:
                      - number: '1'
                        quantity: 1
                        amount: 90
                        taxCode: PS081282
                        itemCode: Y0001
                        description: Yarn
                      type: SalesInvoice
                      companyCode: DEFAULT
                      date: '2023-08-13'
                      customerCode: ABC
                      purchaseOrderNo: 2023-08-13-001
                      addresses:
                        singleLocation:
                          line1: 2000 Main Street
                          city: Irvine
                          region: CA
                          country: US
                          postalCode: '92614'
                      commit: true
                      currencyCode: USD
                      description: Yarn
                - createOrAdjustTransactionModel:
                    adjustmentReason: Other
                    adjustmentDescription: Test Description
                    createTransactionModel:
                      code: MyTransaction-638274861770379574
                      lines:
                      - number: '1'
                        quantity: 1
                        amount: 80
                        taxCode: PS081282
                        itemCode: Y0001
                        description: Yarn
                      type: SalesInvoice
                      companyCode: DEFAULT
                      date: '2023-08-13'
                      customerCode: ABC
                      purchaseOrderNo: 2023-08-13-001
                      addresses:
                        singleLocation:
                          line1: 2000 Main Street
                          city: Irvine
                          region: CA
                          country: US
                          postalCode: '92614'
                      commit: true
                      currencyCode: USD
                      description: Yarn
                - voidTransactionModel:
                    companyCode: DEFAULT
                    transactionCode: MyTransaction-638274861770379574
                    documentType: SalesInvoice
                    code: DocVoided
      parameters:
      - name: Content-Type
        in: header
        schema:
          type: string
        example: application/json
      - name: X-Avalara-Client
        in: header
        schema:
          type: string
        description: Identifies the software you are using to call this API. For more information on the client header, see [Client Headers](https://developer.avalara.com/avatax/client-headers/).
        example: AvaTax Postman Collection
      - name: companyId
        in: path
        schema:
          type: string
        required: true
      responses:
        '200':
          description: Successful response
          content:
            application/json: {}
      security:
      - basicAuth: []
      operationId: postApiV2CompaniesByCompanyIdBatchesTransactions
      x-operation-id-source: derived
    servers:
    - url: http://{{baseurl}}
  /api/v2/companies/{companyId}/batches/{id}:
    delete:
      tags:
      - Batches
      summary: Avalara DeleteBatch
      description: 'Marks the batch identified by this URL as deleted.


        If you attempt to delete a batch that is being processed, you will receive an error message.

        Deleting a batch does not delete any transactions that were created by importing the batch.


        Because the batch system processes with a degree of concurrency, and

        because of batch sizes in the queue vary, AvaTax API is unable to accurately

        predict when a batch will complete. If high performance processing is

        required, please use the

        CreateTransaction API.


        ### Security Policies


        * This API requires one of the following user roles: BatchServiceAdmin, CSPAdmin, CSPTester, SSTAdmin, SystemAdmin, SystemOperator, TechnicalSupportAdmin.'
      parameters:
      - name: X-Avalara-Client
        in: header
        schema:
          type: string
        description: Identifies the software you are using to call this API. For more information on the client header, see [Client Headers](https://developer.avalara.com/avatax/client-headers/).
        example: AvaTax Postman Collection
      - name: companyId
        in: path
        schema:
          type: string
        required: true
      - name: id
        in: path
        schema:
          type: string
        required: true
      responses:
        '200':
          description: Successful response
          content:
            application/json: {}
      security:
      - basicAuth: []
      operationId: deleteApiV2CompaniesByCompanyIdBatchesById
      x-operation-id-source: derived
    get:
      tags:
      - Batches
      summary: Avalara GetBatch
      description: 'Get the batch object identified by this URL. A batch object is a large

        collection of API calls stored in a compact file.


        Use this endpoint to retrieve the results or check the status of a batch.


        When a batch is created, it is added to the AvaTax Batch Queue and will be

        processed as quickly as possible in the order it was received. To check the

        status of a batch, fetch the batch and retrieve the results of the batch

        operation.


        Because the batch system processes with a degree of concurrency, and

        because of batch sizes in the queue vary, AvaTax API is unable to accurately

        predict when a batch will complete. If high performance processing is

        required, please use the

        CreateTransaction API.


        ### Security Policies


        * This API requires one of the following user roles: AccountAdmin, AccountOperator, AccountUser, BatchServiceAdmin, CompanyAdmin, CompanyUser, CSPAdmin, CSPTester, SiteAdmin, SSTAdmin, SystemAdmin, SystemOperator, TechnicalSupportAdmin, TechnicalSupportUser.'
      parameters:
      - name: X-Avalara-Client
        in: header
        schema:
          type: string
        description: Identifies the software you are using to call this API. For more information on the client header, see [Client Headers](https://developer.avalara.com/avatax/client-headers/).
        example: AvaTax Postman Collection
      - name: companyId
        in: path
        schema:
          type: string
        required: true
      - name: id
        in: path
        schema:
          type: string
        required: true
      responses:
        '200':
          description: Successful response
          content:
            application/json: {}
      security:
      - basicAuth: []
      operationId: getApiV2CompaniesByCompanyIdBatchesById
      x-operation-id-source: derived
    servers:
    - url: http://{{baseurl}}
  /api/v2/companies/{companyId}/batches/{batchId}/files/{id}/attachment:
    get:
      tags:
      - Batches
      summary: Avalara DownloadBatch
      description: 'Download a single batch file identified by this URL.


        ### Security Policies


        * This API requires one of the following user roles: AccountAdmin, AccountOperator, AccountUser, BatchServiceAdmin, CompanyAdmin, CompanyUser, CSPAdmin, CSPTester, SiteAdmin, SSTAdmin, SystemAdmin, SystemOperator, TechnicalSupportAdmin, TechnicalSupportUser.'
      parameters:
      - name: X-Avalara-Client
        in: header
        schema:
          type: string
        description: Identifies the software you are using to call this API. For more information on the client header, see [Client Headers](https://developer.avalara.com/avatax/client-headers/).
        example: AvaTax Postman Collection
      - name: companyId
        in: path
        schema:
          type: string
        required: true
      - name: batchId
        in: path
        schema:
          type: string
        required: true
      - name: id
        in: path
        schema:
          type: string
        required: true
      responses:
        '200':
          description: Successful response
          content:
            application/json: {}
      security:
      - basicAuth: []
      operationId: getApiV2CompaniesByCompanyIdBatchesByBatchIdFilesByIdAttachment
      x-operation-id-source: derived
    servers:
    - url: http://{{baseurl}}
  /api/v2/batches:
    get:
      tags:
      - Batches
      summary: Avalara QueryBatches
      description: 'Get multiple batch objects across all companies.


        A batch object is a large collection of API calls stored in a compact file.


        Search for specific objects using the criteria in the `$filter` parameter;

        full documentation is available on Filtering in REST .

        Paginate results using the `$top`, `$skip`, and `$orderby` parameters.


        When a batch is created, it is added to the AvaTax Batch Queue and will be

        processed as quickly as possible in the order it was received. To check the

        status of a batch, fetch the batch and retrieve the results of the batch

        operation.


        Because the batch system processes with a degree of concurrency, and

        because of batch sizes in the queue vary, AvaTax API is unable to accurately

        predict when a batch will complete. If high performance processing is

        required, please use the

        CreateTransaction API.


        ### Security Policies


        * This API requires one of the following user roles: AccountAdmin, AccountOperator, AccountUser, BatchServiceAdmin, CompanyAdmin, CompanyUser, CSPAdmin, CSPTester, SiteAdmin, SSTAdmin, SystemAdmin, SystemOperator, TechnicalSupportAdmin, TechnicalSupportUser.'
      parameters:
      - name: X-Avalara-Client
        in: header
        schema:
          type: string
        description: Identifies the software you are using to call this API. For more information on the client header, see [Client Headers](https://developer.avalara.com/avatax/client-headers/).
        example: AvaTax Postman Collection
      responses:
        '200':
          description: Successful response
          content:
            application/json: {}
      security:
      - basicAuth: []
      operationId: getApiV2Batches
      x-operation-id-source: derived
    servers:
    - url: http://{{baseurl}}
components:
  parameters:
    companyId:
      name: companyId
      in: path
      required: true
      schema:
        type: integer
      description: The numeric ID of the company
    top:
      name: $top
      in: query
      schema:
        type: integer
        default: 1000
      description: Maximum number of results to return
    filter:
      name: $filter
      in: query
      schema:
        type: string
      description: OData filter expression for result filtering
    skip:
      name: $skip
      in: query
      schema:
        type: integer
        default: 0
      description: Number of results to skip for pagination
  schemas:
    BatchModel:
      type: object
      properties:
        id:
          type: integer
        companyId:
          type: integer
        name:
          type: string
        type:
          type: string
          enum:
          - AvaCertUpdate
          - AvaCertUpdateAll
          - BatchMaintenance
          - CompanyLocationImport
          - DocumentImport
          - ExemptCertImport
          - ItemImport
          - SalesAuditExport
          - SstpTestDeckImport
          - TaxRuleImport
          - TransactionImport
          - UPCBulkImport
          - UPCBulkDelete
        status:
          type: string
          enum:
          - Waiting
          - SystemErrors
          - Cancelled
          - Completed
          - Creating
          - Deleted
          - Errors
          - Paused
          - Processing
          - ReadyToDelete
        recordCount:
          type: integer
        currentRecord:
          type: integer
        createdDate:
          type: string
          format: date-time
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Use your AvaTax username/password or accountId/licenseKey as basic auth credentials
    bearerAuth:
      type: http
      scheme: bearer
      description: OAuth 2.0 bearer token
externalDocs:
  description: AvaTax REST API v2 Documentation
  url: https://developer.avalara.com/api-reference/avatax/rest/v2/
x-refined-from:
- avalara-avatax-rest-openapi.yml
- avatax-apis-openapi.yml