openapi: 3.1.0
info:
  title: Avalara MyLodgeTax API
  description: >-
    The MyLodgeTax API provides sales and lodging tax compliance for short-term
    property rentals. It offers partners access to summarized tax responsibilities
    for property owners by marketplace, including direct listings and marketplace
    bookings, with tax rate lookups and filing obligation information.
  version: '1.0'
  contact:
    name: Avalara Developer Relations
    url: https://developer.avalara.com/
    email: developer.relations@avalara.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  termsOfService: https://legal.avalara.com/#siteterms
externalDocs:
  description: MyLodgeTax API Documentation
  url: https://developer.avalara.com/api-reference/myLodgeAPI/tax/
servers:
- url: https://api.avalara.com/mylodgetax/v1
  description: MyLodgeTax API Production
tags:
- name: Obligations
  description: View filing obligations and tax responsibilities
- name: Properties
  description: Manage rental property registrations
- name: Tax Rates
  description: Look up lodging tax rates by location
security:
- bearerAuth: []
paths:
  /tax-rates:
    get:
      operationId: getLodgingTaxRates
      summary: Avalara Get Lodging Tax Rates
      description: >-
        Returns applicable lodging and short-term rental tax rates for a
        given property location, broken down by jurisdiction.
      tags:
      - Tax Rates
      parameters:
      - name: line1
        in: query
        required: true
        schema:
          type: string
        description: Street address
      - name: city
        in: query
        schema:
          type: string
      - name: region
        in: query
        required: true
        schema:
          type: string
        description: State or province
      - name: postalCode
        in: query
        required: true
        schema:
          type: string
      - name: country
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Lodging tax rates
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LodgingTaxRateResponse'
  /properties:
    get:
      operationId: listProperties
      summary: Avalara List Registered Properties
      tags:
      - Properties
      responses:
        '200':
          description: List of properties
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RentalProperty'
    post:
      operationId: registerProperty
      summary: Avalara Register a Rental Property
      tags:
      - Properties
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RentalProperty'
      responses:
        '201':
          description: Property registered
  /properties/{propertyId}/obligations:
    get:
      operationId: getPropertyObligations
      summary: Avalara Get Filing Obligations for a Property
      description: >-
        Returns a summary of tax filing obligations for a registered
        property, including which taxes apply and filing frequencies.
      tags:
      - Obligations
      parameters:
      - name: propertyId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Filing obligations
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FilingObligation'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  schemas:
    LodgingTaxRateResponse:
      type: object
      properties:
        totalRate:
          type: number
          format: double
          description: Total combined lodging tax rate
        rates:
          type: array
          items:
            type: object
            properties:
              jurisdiction:
                type: string
              jurisdictionType:
                type: string
                enum:
                - State
                - County
                - City
                - District
              taxName:
                type: string
              rate:
                type: number
                format: double
    RentalProperty:
      type: object
      properties:
        propertyId:
          type: string
        propertyName:
          type: string
        address:
          type: object
          properties:
            line1:
              type: string
            city:
              type: string
            region:
              type: string
            postalCode:
              type: string
            country:
              type: string
        listingPlatforms:
          type: array
          items:
            type: string
          description: Platforms where the property is listed (e.g., Airbnb, VRBO)
        propertyType:
          type: string
          enum:
          - House
          - Apartment
          - Condo
          - Room
          - Other
    FilingObligation:
      type: object
      properties:
        jurisdiction:
          type: string
        taxType:
          type: string
        filingFrequency:
          type: string
          enum:
          - Monthly
          - Quarterly
          - Annual
        nextDueDate:
          type: string
          format: date
        registrationRequired:
          type: boolean
        registrationUrl:
          type: string