openapi: 3.0.1
info:
  title: Lodgify Public Availability Bookings API
  description: The Lodgify Public API is a REST interface for the Lodgify vacation rental platform. It exposes properties and room types, availability calendars, daily rates, rate settings, priced quotes, the full booking and reservation lifecycle, guest messaging threads, and webhook subscriptions. The API spans two versions (v1 and v2) under the host https://api.lodgify.com and is authenticated with an X-ApiKey request header.
  termsOfService: https://www.lodgify.com/legal-stuff/
  contact:
    name: Lodgify Support
    url: https://docs.lodgify.com
  version: '2.0'
servers:
- url: https://api.lodgify.com
  description: Lodgify Public API (v1 and v2 paths)
security:
- ApiKeyAuth: []
tags:
- name: Bookings
  description: Booking and reservation lifecycle management.
paths:
  /v2/reservations/bookings:
    get:
      operationId: listBookings
      tags:
      - Bookings
      summary: List bookings
      description: Returns a paged list of bookings filtered by status, date, and channel.
      parameters:
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/Size'
      - name: stayFilter
        in: query
        schema:
          type: string
          enum:
          - Upcoming
          - Current
          - Historic
          - All
      responses:
        '200':
          description: A paged list of bookings.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookingList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createBooking
      tags:
      - Bookings
      summary: Create a booking
      description: Creates a new booking, optionally upgrading an existing enquiry.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BookingCreate'
      responses:
        '201':
          description: The created booking.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Booking'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/reservations/bookings/{id}:
    get:
      operationId: getBooking
      tags:
      - Bookings
      summary: Get a booking
      description: Returns the details of a single booking by its identifier.
      parameters:
      - $ref: '#/components/parameters/BookingId'
      responses:
        '200':
          description: The requested booking.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Booking'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateBooking
      tags:
      - Bookings
      summary: Update a booking
      description: Updates an existing booking.
      parameters:
      - $ref: '#/components/parameters/BookingId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BookingCreate'
      responses:
        '200':
          description: The updated booking.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Booking'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteBooking
      tags:
      - Bookings
      summary: Delete a booking
      description: Deletes a booking.
      parameters:
      - $ref: '#/components/parameters/BookingId'
      responses:
        '204':
          description: Booking deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/reservations/bookings/{id}/quote/paymentLink:
    get:
      operationId: getBookingPaymentLink
      tags:
      - Bookings
      summary: Get a booking payment link
      description: Returns the current payment link for a booking.
      parameters:
      - $ref: '#/components/parameters/BookingId'
      responses:
        '200':
          description: The payment link.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentLink'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createBookingPaymentLink
      tags:
      - Bookings
      summary: Create a booking payment link
      description: Creates a payment link for a booking.
      parameters:
      - $ref: '#/components/parameters/BookingId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentLinkCreate'
      responses:
        '201':
          description: The created payment link.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentLink'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/reservations/bookings/{id}/keyCodes:
    put:
      operationId: updateKeyCodes
      tags:
      - Bookings
      summary: Update key codes
      description: Sets or updates the key codes associated with a booking.
      parameters:
      - $ref: '#/components/parameters/BookingId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KeyCodes'
      responses:
        '200':
          description: Key codes updated.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/reservations/bookings/{id}/checkin:
    put:
      operationId: checkinBooking
      tags:
      - Bookings
      summary: Check in a booking
      description: Marks a booking as checked in.
      parameters:
      - $ref: '#/components/parameters/BookingId'
      responses:
        '200':
          description: Booking checked in.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/reservations/bookings/{id}/checkout:
    put:
      operationId: checkoutBooking
      tags:
      - Bookings
      summary: Check out a booking
      description: Marks a booking as checked out.
      parameters:
      - $ref: '#/components/parameters/BookingId'
      responses:
        '200':
          description: Booking checked out.
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    Booking:
      type: object
      properties:
        id:
          type: integer
          format: int32
        property_id:
          type: integer
          format: int32
        status:
          type: string
          enum:
          - Open
          - Booked
          - Tentative
          - Declined
        arrival:
          type: string
          format: date
        departure:
          type: string
          format: date
        guest:
          $ref: '#/components/schemas/Guest'
        total_amount:
          type: number
          format: double
        currency_code:
          type: string
        source:
          type: string
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
    KeyCodes:
      type: object
      properties:
        key_codes:
          type: array
          items:
            type: string
    BookingCreate:
      type: object
      required:
      - property_id
      - arrival
      - departure
      properties:
        property_id:
          type: integer
          format: int32
        room_types:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
                format: int32
              people:
                type: integer
                format: int32
        arrival:
          type: string
          format: date
        departure:
          type: string
          format: date
        guest:
          $ref: '#/components/schemas/Guest'
        status:
          type: string
          enum:
          - Open
          - Booked
          - Tentative
    BookingList:
      type: object
      properties:
        count:
          type: integer
          format: int32
        items:
          type: array
          items:
            $ref: '#/components/schemas/Booking'
    PaymentLinkCreate:
      type: object
      properties:
        amount:
          type: number
          format: double
        currency:
          type: string
        description:
          type: string
    PaymentLink:
      type: object
      properties:
        url:
          type: string
          format: uri
        amount:
          type: number
          format: double
        currency:
          type: string
    Guest:
      type: object
      properties:
        name:
          type: string
        email:
          type: string
          format: email
        phone:
          type: string
        country_code:
          type: string
  responses:
    Unauthorized:
      description: Missing or invalid X-ApiKey.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    BookingId:
      name: id
      in: path
      required: true
      schema:
        type: integer
        format: int32
      description: Booking identifier.
    Page:
      name: page
      in: query
      schema:
        type: integer
        format: int32
        default: 1
      description: 1-based page number.
    Size:
      name: size
      in: query
      schema:
        type: integer
        format: int32
        default: 50
      description: Number of items per page.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-ApiKey
      description: Account API key passed in the X-ApiKey request header.