openapi: 3.2.0
info:
  title: Avalara Tax Rules API
  version: '1.0'
  description: 'Operations tagged TaxRules 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: Tax Rules
  description: Manage tax rules and overrides for companies
paths:
  /api/v2/companies/{companyId}/taxrules:
    get:
      operationId: listTaxRules
      summary: Avalara List Tax Rules for a Company
      tags:
      - Tax Rules
      parameters:
      - $ref: '#/components/parameters/companyId'
      - $ref: '#/components/parameters/filter'
      - $ref: '#/components/parameters/top'
      - $ref: '#/components/parameters/skip'
      responses:
        '200':
          description: List of tax rules
      security:
      - basicAuth: []
      - bearerAuth: []
    post:
      operationId: createTaxRules
      summary: Avalara Create Tax Rules for a Company
      tags:
      - Tax Rules
      parameters:
      - $ref: '#/components/parameters/companyId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/TaxRuleModel'
      responses:
        '201':
          description: Tax rules created
      security:
      - basicAuth: []
      - bearerAuth: []
    servers:
    - url: https://rest.avatax.com
      description: AvaTax Production
    - url: https://sandbox-rest.avatax.com
      description: AvaTax Sandbox
  /api/v2/countryCoefficients:
    put:
      tags:
      - Tax Rules
      summary: Avalara CreateCountryCoefficients
      description: 'Create one or more Country Coefficients for particular country.


        We would like to use country coefficients during Cross-Border calculations to slightly increase or decrease

        a calculation for a line based on the tax-subtype and Country of destination for a transaction.


        This will allow AvaTax to minimize the variance caused between actual transaction taken place on ground Vs Tax

        Calculated by AvaTax.


        Make sure to use the same API to update the country coefficients that is already present in the database.

        This will make existing entry for specific country as ineffective for that date. And new entry created will get applicable

        to the newer transactions.'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example:
                accountId: 0
                coefficientDetails:
                - companyCode: ''
                  country: ''
                  coefficient: 0
                  taxSubTypeId: ''
                  currencyCode: USD
                  unitOfBasisId: 0
                  isApplicable: false
                  startDate: '2023-08-13'
                  endDate: '9999-12-31'
      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
      responses:
        '200':
          description: Successful response
          content:
            application/json: {}
      security:
      - basicAuth: []
      operationId: putApiV2CountryCoefficients
      x-operation-id-source: derived
    servers:
    - url: http://{{baseurl}}
  /api/v2/companies/{companyId}/taxrules/{id}:
    delete:
      tags:
      - Tax Rules
      summary: Avalara DeleteTaxRule
      description: 'Mark the custom tax rule identified by this URL as deleted.


        A tax rule represents a rule that changes the default AvaTax behavior for a product or jurisdiction. Custom tax rules

        can be used to change the taxability of an item, to change the tax base of an item, or to change the tax rate

        charged when selling an item. Tax rules can also change tax behavior depending on the `entityUseCode` value submitted

        with the transaction.


        You can create custom tax rules to customize the behavior of AvaTax to match specific rules that are custom to your

        business. If you have obtained a ruling from a tax auditor that requires custom tax calculations, you can use

        custom tax rules to redefine the behavior for your company or item.


        Please use custom tax rules carefully and ensure that these tax rules match the behavior agreed upon with your

        auditor, legal representative, and accounting team.


        ### Security Policies


        * This API requires one of the following user roles: AccountAdmin, BatchServiceAdmin, CompanyAdmin, CSPTester, SSTAdmin, 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: deleteApiV2CompaniesByCompanyIdTaxrulesById
      x-operation-id-source: derived
    get:
      tags:
      - Tax Rules
      summary: Avalara GetTaxRule
      description: 'Get the taxrule object identified by this URL.


        A tax rule represents a rule that changes the default AvaTax behavior for a product or jurisdiction. Custom tax rules

        can be used to change the taxability of an item, to change the tax base of an item, or to change the tax rate

        charged when selling an item. Tax rules can also change tax behavior depending on the `entityUseCode` value submitted

        with the transaction.


        You can create custom tax rules to customize the behavior of AvaTax to match specific rules that are custom to your

        business. If you have obtained a ruling from a tax auditor that requires custom tax calculations, you can use

        custom tax rules to redefine the behavior for your company or item.


        Please use custom tax rules carefully and ensure that these tax rules match the behavior agreed upon with your

        auditor, legal representative, and accounting team.


        ### Security Policies


        * This API requires one of the following user roles: AccountAdmin, AccountUser, BatchServiceAdmin, CompanyAdmin, CompanyUser, CSPAdmin, CSPTester, SiteAdmin, SSTAdmin, SystemAdmin, 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: getApiV2CompaniesByCompanyIdTaxrulesById
      x-operation-id-source: derived
    put:
      tags:
      - Tax Rules
      summary: Avalara UpdateTaxRule
      description: 'Replace the existing custom tax rule object at this URL with an updated object.


        A tax rule represents a rule that changes the default AvaTax behavior for a product or jurisdiction. Custom tax rules

        can be used to change the taxability of an item, to change the tax base of an item, or to change the tax rate

        charged when selling an item. Tax rules can also change tax behavior depending on the `entityUseCode` value submitted

        with the transaction.


        You can create custom tax rules to customize the behavior of AvaTax to match specific rules that are custom to your

        business. If you have obtained a ruling from a tax auditor that requires custom tax calculations, you can use

        custom tax rules to redefine the behavior for your company or item.


        Please use custom tax rules carefully and ensure that these tax rules match the behavior agreed upon with your

        auditor, legal representative, and accounting team.


        ### Security Policies


        * This API requires one of the following user roles: AccountAdmin, BatchServiceAdmin, CompanyAdmin, CSPTester, SSTAdmin, TechnicalSupportAdmin.'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example:
                id: 56789
                companyId: 12345
                taxCode: FR020800
                stateFIPS: '04'
                jurisName: MARICOPA
                jurisCode: '013'
                jurisTypeId: 0
                jurisdictionTypeId: County
                taxTypeId: BothSalesAndUseTax
                taxTypeCode: ALL
                taxRuleTypeId: ProductTaxabilityRule
                isAllJuris: false
                value: 0
                cap: 0
                threshold: 0
                effectiveDate: '2023-08-13'
                description: Freight
                countyFIPS: '013'
                country: US
                region: AZ
                taxTypeGroup: SalesAndUse
                taxSubType: ALL
      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
      - name: id
        in: path
        schema:
          type: string
        required: true
      responses:
        '200':
          description: Successful response
          content:
            application/json: {}
      security:
      - basicAuth: []
      operationId: putApiV2CompaniesByCompanyIdTaxrulesById
      x-operation-id-source: derived
    servers:
    - url: http://{{baseurl}}
  /api/v2/{country}/CountryCoefficients:
    get:
      tags:
      - Tax Rules
      summary: Avalara ListCountryCoefficients
      description: 'Retrieve all or any specific records of Country Coefficients based on the filters(optional) for specific country.


        Search for specific objects using the criteria in the `$filter` parameter; full documentation is available on Filtering in REST .

        Paginate your results using the `$top`, `$skip`, and `$orderby` parameters.'
      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: country
        in: path
        schema:
          type: string
        required: true
      responses:
        '200':
          description: Successful response
          content:
            application/json: {}
      security:
      - basicAuth: []
      operationId: getApiV2ByCountryCountryCoefficients
      x-operation-id-source: derived
    servers:
    - url: http://{{baseurl}}
  /api/v2/taxrules:
    get:
      tags:
      - Tax Rules
      summary: Avalara QueryTaxRules
      description: 'Get multiple taxrule objects across all companies.


        A tax rule represents a rule that changes the default AvaTax behavior for a product or jurisdiction. Custom tax rules

        can be used to change the taxability of an item, to change the tax base of an item, or to change the tax rate

        charged when selling an item. Tax rules can also change tax behavior depending on the `entityUseCode` value submitted

        with the transaction.


        You can create custom tax rules to customize the behavior of AvaTax to match specific rules that are custom to your

        business. If you have obtained a ruling from a tax auditor that requires custom tax calculations, you can use

        custom tax rules to redefine the behavior for your company or item.


        Please use custom tax rules carefully and ensure that these tax rules match the behavior agreed upon with your

        auditor, legal representative, and accounting team.


        Search for specific objects using the criteria in the `$filter` parameter; full documentation is available on Filtering in REST .

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


        ### Security Policies


        * This API requires one of the following user roles: AccountAdmin, AccountUser, BatchServiceAdmin, CompanyAdmin, CompanyUser, CSPAdmin, CSPTester, SiteAdmin, SSTAdmin, SystemAdmin, 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: getApiV2Taxrules
      x-operation-id-source: derived
    servers:
    - url: http://{{baseurl}}
components:
  parameters:
    top:
      name: $top
      in: query
      schema:
        type: integer
        default: 1000
      description: Maximum number of results to return
    companyId:
      name: companyId
      in: path
      required: true
      schema:
        type: integer
      description: The numeric ID of the company
    skip:
      name: $skip
      in: query
      schema:
        type: integer
        default: 0
      description: Number of results to skip for pagination
    filter:
      name: $filter
      in: query
      schema:
        type: string
      description: OData filter expression for result filtering
  schemas:
    TaxRuleModel:
      type: object
      properties:
        id:
          type: integer
        companyId:
          type: integer
        taxCodeId:
          type: integer
        taxCode:
          type: string
        stateFIPS:
          type: string
        jurisName:
          type: string
        jurisCode:
          type: string
        jurisTypeId:
          type: string
        rateTypeId:
          type: string
        ruleTypeId:
          type: string
        isAllJuris:
          type: boolean
  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