openapi: 3.0.1
info:
  title: apaleo Platform Availability Booking API
  description: Unified OpenAPI view of the apaleo API-first hotel property-management system. apaleo exposes its capabilities as a set of versioned REST APIs - Booking, Inventory, Rate Plan, Availability, Finance, and Settings - all served from https://api.apaleo.com and secured with OAuth 2.0 bearer tokens issued by the apaleo identity provider. Real-time events are delivered via the Webhook API at https://webhook.apaleo.com.
  termsOfService: https://apaleo.com/terms
  contact:
    name: apaleo Developer Support
    url: https://apaleo.dev
  version: v1
servers:
- url: https://api.apaleo.com
  description: apaleo Core API (Booking, Inventory, Rate Plan, Availability, Finance, Settings)
security:
- oauth2: []
tags:
- name: Booking
  description: Bookings, reservations, blocks, groups, and offers.
paths:
  /booking/v1/bookings:
    post:
      tags:
      - Booking
      operationId: BookingCreateBooking
      summary: Create a booking with one or more reservations.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBookingModel'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookingCreatedModel'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
    get:
      tags:
      - Booking
      operationId: BookingGetBookings
      summary: Return a list of bookings.
      parameters:
      - name: pageNumber
        in: query
        schema:
          type: integer
          format: int32
      - name: pageSize
        in: query
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
  /booking/v1/bookings/{id}:
    get:
      tags:
      - Booking
      operationId: BookingGetBookingById
      summary: Return a single booking by id.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
        '404':
          description: Not Found
    patch:
      tags:
      - Booking
      operationId: BookingPatchBooking
      summary: Modify the booker and related details of a booking.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: No Content
  /booking/v1/reservations:
    get:
      tags:
      - Booking
      operationId: BookingGetReservations
      summary: Return a list of reservations matching the filter criteria.
      parameters:
      - name: propertyIds
        in: query
        schema:
          type: array
          items:
            type: string
      - name: status
        in: query
        schema:
          type: array
          items:
            type: string
            enum:
            - Confirmed
            - InHouse
            - CheckedOut
            - Canceled
            - NoShow
      - name: from
        in: query
        schema:
          type: string
          format: date-time
      - name: to
        in: query
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: OK
  /booking/v1/reservations/{id}:
    get:
      tags:
      - Booking
      operationId: BookingGetReservationById
      summary: Return a single reservation by id.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReservationItemModel'
        '404':
          description: Not Found
  /booking/v1/reservation-actions/{id}/checkin:
    put:
      tags:
      - Booking
      operationId: BookingCheckinReservation
      summary: Check in a reservation.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: No Content
  /booking/v1/reservation-actions/{id}/checkout:
    put:
      tags:
      - Booking
      operationId: BookingCheckoutReservation
      summary: Check out a reservation.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: No Content
  /booking/v1/blocks:
    post:
      tags:
      - Booking
      operationId: BookingCreateBlock
      summary: Create a block of rooms for a group.
      responses:
        '201':
          description: Created
    get:
      tags:
      - Booking
      operationId: BookingGetBlocks
      summary: Return a list of blocks.
      responses:
        '200':
          description: OK
  /booking/v1/offers:
    get:
      tags:
      - Booking
      operationId: BookingGetOffers
      summary: Return bookable offers for the given property, dates, and occupancy.
      parameters:
      - name: propertyId
        in: query
        required: true
        schema:
          type: string
      - name: arrival
        in: query
        required: true
        schema:
          type: string
          format: date
      - name: departure
        in: query
        required: true
        schema:
          type: string
          format: date
      - name: adults
        in: query
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
components:
  schemas:
    BookingCreatedModel:
      type: object
      properties:
        id:
          type: string
        bookingId:
          type: string
        reservationIds:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
    BookerModel:
      type: object
      properties:
        title:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        email:
          type: string
        phone:
          type: string
        address:
          $ref: '#/components/schemas/AddressModel'
    EmbeddedPropertyModel:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
    CreateBookingModel:
      type: object
      required:
      - reservations
      properties:
        booker:
          $ref: '#/components/schemas/BookerModel'
        paymentAccount:
          type: object
          additionalProperties: true
        reservations:
          type: array
          items:
            $ref: '#/components/schemas/CreateReservationModel'
    MonetaryValueModel:
      type: object
      properties:
        amount:
          type: number
          format: double
        currency:
          type: string
    CreateReservationModel:
      type: object
      required:
      - arrival
      - departure
      - adults
      - ratePlanId
      properties:
        propertyId:
          type: string
        arrival:
          type: string
          format: date-time
        departure:
          type: string
          format: date-time
        adults:
          type: integer
          format: int32
        childrenAges:
          type: array
          items:
            type: integer
            format: int32
        ratePlanId:
          type: string
        guestComment:
          type: string
    ReservationItemModel:
      type: object
      properties:
        id:
          type: string
        bookingId:
          type: string
        status:
          type: string
          enum:
          - Confirmed
          - InHouse
          - CheckedOut
          - Canceled
          - NoShow
        property:
          $ref: '#/components/schemas/EmbeddedPropertyModel'
        ratePlanId:
          type: string
        arrival:
          type: string
          format: date-time
        departure:
          type: string
          format: date-time
        adults:
          type: integer
          format: int32
        totalGrossAmount:
          $ref: '#/components/schemas/MonetaryValueModel'
    AddressModel:
      type: object
      properties:
        addressLine1:
          type: string
        addressLine2:
          type: string
        postalCode:
          type: string
        city:
          type: string
        regionCode:
          type: string
        countryCode:
          type: string
  securitySchemes:
    oauth2:
      type: oauth2
      description: apaleo uses OAuth 2.0. Obtain a bearer access token from the apaleo identity provider and send it in the Authorization header as 'Bearer {token}'. The client-credentials and authorization-code grants are supported.
      flows:
        clientCredentials:
          tokenUrl: https://identity.apaleo.com/connect/token
          scopes:
            reservations.read: Read reservations and bookings
            reservations.manage: Create and manage reservations and bookings
            setup.read: Read inventory and configuration
            setup.manage: Manage inventory and configuration
            rates.read: Read rate plans and rates
            rates.manage: Manage rate plans and rates
            availability.read: Read availability
            availability.manage: Manage availability
            folios.read: Read folios and finance data
            folios.manage: Manage folios, payments, and invoices
        authorizationCode:
          authorizationUrl: https://identity.apaleo.com/connect/authorize
          tokenUrl: https://identity.apaleo.com/connect/token
          scopes:
            reservations.read: Read reservations and bookings
            reservations.manage: Create and manage reservations and bookings
            setup.read: Read inventory and configuration
            setup.manage: Manage inventory and configuration
            rates.read: Read rate plans and rates
            rates.manage: Manage rate plans and rates
            availability.read: Read availability
            availability.manage: Manage availability
            folios.read: Read folios and finance data
            folios.manage: Manage folios, payments, and invoices