openapi: 3.2.0
info:
  title: Avalara Locations API
  version: '1.0'
  description: 'Operations tagged Locations across 3 of this provider''s published API definitions: avalara-avatax-rest-openapi.yml, avalara-excise-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: https://exciseapi.avalara.com/api/v1
  description: Excise API Production
- url: http://{{baseurl}}
tags:
- name: Locations
  description: Manage company locations and jurisdictions
paths:
  /api/v2/companies/{companyId}/locations:
    get:
      operationId: queryLocations
      summary: Avalara List Locations for a Company
      tags:
      - Locations
      parameters:
      - $ref: '#/components/parameters/companyId'
      - $ref: '#/components/parameters/filter'
      - $ref: '#/components/parameters/top'
      - $ref: '#/components/parameters/skip'
      responses:
        '200':
          description: List of locations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FetchResult_LocationModel'
      security:
      - basicAuth: []
      - bearerAuth: []
    post:
      operationId: createLocations
      summary: Avalara Create Locations for a Company
      tags:
      - Locations
      parameters:
      - $ref: '#/components/parameters/companyId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/LocationModel'
      responses:
        '201':
          description: Locations created
      security:
      - basicAuth: []
      - bearerAuth: []
    servers:
    - url: https://rest.avatax.com
      description: AvaTax Production
    - url: https://sandbox-rest.avatax.com
      description: AvaTax Sandbox
  /Locations:
    get:
      operationId: listLocations
      summary: Avalara List Locations
      tags:
      - Locations
      responses:
        '200':
          description: List of locations
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ExciseLocation'
      security:
      - bearerAuth: []
    post:
      operationId: createLocation
      summary: Avalara Create a Location
      tags:
      - Locations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExciseLocation'
      responses:
        '201':
          description: Location created
      security:
      - bearerAuth: []
    servers:
    - url: https://exciseapi.avalara.com/api/v1
      description: Excise API Production
  /api/v2/companies/{companyId}/locations/{locationId}/parameters:
    post:
      tags:
      - Locations
      summary: Avalara CreateLocationParameters
      description: 'Add parameters to a location.


        Some locations can be taxed differently depending on the properties of that location. In AvaTax, these tax-affecting properties are called "parameters".


        A parameter added to a location will be used by default in tax calculation but will not show on the transaction line referencing the location.


        A parameter specified on a transaction line will override a location parameter if they share the same parameter name.


        To see available parameters for this location, call `/api/v2/definitions/parameters?$filter=attributeType eq Company`


        Some parameters are only available for use if you have subscribed to specific AvaTax services. To see which parameters you are able to use, add the query parameter "$showSubscribed=true" to the parameter definition call above.


        ### Security Policies


        * This API requires one of the following user roles: AccountAdmin, BatchServiceAdmin, CompanyAdmin, CSPAdmin, CSPTester, FirmAdmin, SiteAdmin, SSTAdmin, SystemAdmin, TechnicalSupportAdmin.'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example:
                id: 0
                name: NumberOfUnitsForRent
                unit: Count
                value: '10'
                locationId: 12345
      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: locationId
        in: path
        schema:
          type: string
        required: true
      responses:
        '200':
          description: Successful response
          content:
            application/json: {}
      security:
      - basicAuth: []
      operationId: postApiV2CompaniesByCompanyIdLocationsByLocationIdParameters
      x-operation-id-source: derived
    get:
      tags:
      - Locations
      summary: Avalara ListLocationParameters
      description: 'List parameters for a location.


        Some locations can be taxed differently depending on the properties of that location. In AvaTax, these tax-affecting properties are called "parameters".


        A parameter added to a location will be used by default in tax calculation but will not show on the transaction line referencing the location.


        A parameter specified on a transaction line will override a location parameter if they share the same parameter name.


        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, ECMAccountUser, ECMCompanyUser, FirmAdmin, FirmUser, SiteAdmin, SSTAdmin, SystemAdmin, TechnicalSupportAdmin, TechnicalSupportUser, TreasuryAdmin, TreasuryUser.'
      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: locationId
        in: path
        schema:
          type: string
        required: true
      responses:
        '200':
          description: Successful response
          content:
            application/json: {}
      security:
      - basicAuth: []
      operationId: getApiV2CompaniesByCompanyIdLocationsByLocationIdParameters
      x-operation-id-source: derived
    servers:
    - url: http://{{baseurl}}
  /api/v2/companies/{companyId}/locations/{id}:
    delete:
      tags:
      - Locations
      summary: Avalara DeleteLocation
      description: 'Mark the location object at this URL as deleted.


        ### Security Policies


        * This API requires one of the following user roles: AccountAdmin, BatchServiceAdmin, CompanyAdmin, CSPAdmin, CSPTester, FirmAdmin, SiteAdmin, SSTAdmin, SystemAdmin, 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: deleteApiV2CompaniesByCompanyIdLocationsById
      x-operation-id-source: derived
    get:
      tags:
      - Locations
      summary: Avalara GetLocation
      description: 'Get the location object identified by this URL.

        An ''Location'' represents a physical address where a company does business.

        Many taxing authorities require that you define a list of all locations where your company does business.

        These locations may require additional custom configuration or tax registration with these authorities.

        For more information on metadata requirements, see the ''/api/v2/definitions/locationquestions'' API.


        You may specify one or more of the following values in the `$include` parameter to fetch additional nested data, using commas to separate multiple values:


        * LocationSettings

        * parameters


        ### Security Policies


        * This API requires one of the following user roles: AccountAdmin, AccountUser, BatchServiceAdmin, CompanyAdmin, CompanyUser, CSPAdmin, CSPTester, ECMAccountUser, ECMCompanyUser, FirmAdmin, FirmUser, SiteAdmin, SSTAdmin, SystemAdmin, TechnicalSupportAdmin, TechnicalSupportUser, TreasuryAdmin, TreasuryUser.'
      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: getApiV2CompaniesByCompanyIdLocationsById
      x-operation-id-source: derived
    put:
      tags:
      - Locations
      summary: Avalara UpdateLocation
      description: 'Replace the existing location object at this URL with an updated object.

        All data from the existing object will be replaced with data in the object you PUT.

        To set a field''s value to null, you may either set its value to null or omit that field from the object you post.


        ### Security Policies


        * This API requires one of the following user roles: AccountAdmin, BatchServiceAdmin, CompanyAdmin, CSPAdmin, CSPTester, FirmAdmin, SiteAdmin, SSTAdmin, SystemAdmin, TechnicalSupportAdmin.'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example:
                id: 56789
                companyId: 12345
                locationCode: DEFAULT
                description: Bob's Artisan Pottery
                addressTypeId: Location
                addressCategoryId: MainOffice
                isMarketplaceOutsideUsa: false
                line1: 2000 Main Street
                city: Irvine
                county: Orange
                region: CA
                postalCode: '92614'
                country: US
                isDefault: true
                isRegistered: true
                dbaName: Bob's Artisan Pottery
                outletName: Main Office
                registeredDate: '2015-01-01T00:00:00'
                settings:
                - questionId: 17
                  value: abcdefghij
      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: putApiV2CompaniesByCompanyIdLocationsById
      x-operation-id-source: derived
    servers:
    - url: http://{{baseurl}}
  /api/v2/companies/{companyId}/locations/{locationId}/parameters/{id}:
    delete:
      tags:
      - Locations
      summary: Avalara DeleteLocationParameter
      description: 'Delete a single location parameter.


        Some locations can be taxed differently depending on the properties of that location. In AvaTax, these tax-affecting properties are called "parameters".


        A parameter added to a location will be used by default in tax calculation but will not show on the transaction line referencing the location.


        A parameter specified on a transaction line will override a location parameter if they share the same parameter name.


        ### Security Policies


        * This API requires one of the following user roles: AccountAdmin, BatchServiceAdmin, CompanyAdmin, CSPAdmin, CSPTester, FirmAdmin, SiteAdmin, SSTAdmin, SystemAdmin, 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: locationId
        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: deleteApiV2CompaniesByCompanyIdLocationsByLocationIdParametersById
      x-operation-id-source: derived
    get:
      tags:
      - Locations
      summary: Avalara GetLocationParameter
      description: 'Retrieve a single location parameter.


        Some locations can be taxed differently depending on the properties of that location. In AvaTax, these tax-affecting properties are called "parameters".


        A parameter added to a location will be used by default in tax calculation but will not show on the transaction line referencing the location.


        A parameter specified on a transaction line will override a location parameter if they share the same parameter name.


        ### Security Policies


        * This API requires one of the following user roles: AccountAdmin, AccountUser, BatchServiceAdmin, CompanyAdmin, CompanyUser, CSPAdmin, CSPTester, ECMAccountUser, ECMCompanyUser, FirmAdmin, FirmUser, SiteAdmin, SSTAdmin, SystemAdmin, TechnicalSupportAdmin, TechnicalSupportUser, TreasuryAdmin, TreasuryUser.'
      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: locationId
        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: getApiV2CompaniesByCompanyIdLocationsByLocationIdParametersById
      x-operation-id-source: derived
    put:
      tags:
      - Locations
      summary: Avalara UpdateLocationParameter
      description: 'Update a location parameter.


        Some locations can be taxed differently depending on the properties of that location. In AvaTax, these tax-affecting properties are called "parameters".


        A parameter added to a location will be used by default in tax calculation but will not show on the transaction line referencing the location.


        A parameter specified on a transaction line will override a location parameter if they share the same parameter name.


        ### Security Policies


        * This API requires one of the following user roles: AccountAdmin, BatchServiceAdmin, CompanyAdmin, CSPAdmin, CSPTester, FirmAdmin, SiteAdmin, SSTAdmin, SystemAdmin, TechnicalSupportAdmin.'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example:
                id: 0
                name: NumberOfUnitsForRent
                unit: Count
                value: '10'
                locationId: 12345
      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: locationId
        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: putApiV2CompaniesByCompanyIdLocationsByLocationIdParametersById
      x-operation-id-source: derived
    servers:
    - url: http://{{baseurl}}
  /api/v2/locations:
    get:
      tags:
      - Locations
      summary: Avalara QueryLocations
      description: 'Get multiple location objects across all companies.

        An ''Location'' represents a physical address where a company does business.

        Many taxing authorities require that you define a list of all locations where your company does business.

        These locations may require additional custom configuration or tax registration with these authorities.

        For more information on metadata requirements, see the ''/api/v2/definitions/locationquestions'' API.


        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.


        You may specify one or more of the following values in the `$include` parameter to fetch additional nested data, using commas to separate multiple values:


        * LocationSettings

        * parameters


        ### Security Policies


        * This API requires one of the following user roles: AccountAdmin, AccountUser, BatchServiceAdmin, CompanyAdmin, CompanyUser, CSPAdmin, CSPTester, ECMAccountUser, ECMCompanyUser, FirmAdmin, FirmUser, SiteAdmin, SSTAdmin, SystemAdmin, TechnicalSupportAdmin, TechnicalSupportUser, TreasuryAdmin, TreasuryUser.'
      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: getApiV2Locations
      x-operation-id-source: derived
    servers:
    - url: http://{{baseurl}}
  /api/v2/companies/{companyId}/locations/{id}/validate:
    get:
      tags:
      - Locations
      summary: Avalara ValidateLocation
      description: 'Returns validation information for this location.

        This API call is intended to compare this location against the currently known taxing authority rules and regulations,

        and provide information about what additional work is required to completely setup this location.


        ### Security Policies


        * This API requires one of the following user roles: AccountAdmin, AccountUser, BatchServiceAdmin, CompanyAdmin, CompanyUser, CSPAdmin, CSPTester, ECMAccountUser, ECMCompanyUser, FirmAdmin, FirmUser, SiteAdmin, SSTAdmin, SystemAdmin, TechnicalSupportAdmin, TechnicalSupportUser, TreasuryAdmin, TreasuryUser.'
      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: getApiV2CompaniesByCompanyIdLocationsByIdValidate
      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:
    LocationModel:
      type: object
      properties:
        id:
          type: integer
        companyId:
          type: integer
        locationCode:
          type: string
        description:
          type: string
        addressTypeId:
          type: string
          enum:
          - Firm
          - Location
          - Salesperson
        addressCategoryId:
          type: string
          enum:
          - Storefront
          - MainOffice
          - Warehouse
          - Salesperson
          - Other
        line1:
          type: string
        city:
          type: string
        region:
          type: string
        postalCode:
          type: string
        country:
          type: string
    FetchResult_LocationModel:
      type: object
      properties:
        '@recordsetCount':
          type: integer
        value:
          type: array
          items:
            $ref: '#/components/schemas/LocationModel'
    ExciseLocation:
      type: object
      properties:
        locationId:
          type: string
        locationName:
          type: string
        locationType:
          type: string
          enum:
          - Terminal
          - Warehouse
          - BulkPlant
          - Retail
          - Blender
          - Refinery
        address:
          $ref: '#/components/schemas/ExciseAddress'
        irsTerminalCode:
          type: string
    ExciseAddress:
      type: object
      properties:
        line1:
          type: string
        line2:
          type: string
        city:
          type: string
        region:
          type: string
          description: State or province code
        postalCode:
          type: string
        country:
          type: string
          description: ISO 3166 country code
  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
x-refined-from:
- avalara-avatax-rest-openapi.yml
- avalara-excise-openapi.yml
- avatax-apis-openapi.yml