apaleo Finance API

openapi: 3.0.1
info:
  title: apaleo Platform 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.
  - name: Inventory
    description: Properties, units, unit groups, and unit attributes.
  - name: Rate Plan
    description: Rate plans, rates, services, and policies.
  - name: Availability
    description: Real-time availability for units, unit groups, and services.
  - name: Finance
    description: Folios, payments, refunds, invoices, and accounts.
  - name: Settings
    description: Account- and property-level configuration.
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
  /inventory/v1/properties:
    get:
      tags: [Inventory]
      operationId: InventoryGetProperties
      summary: Return a list of properties.
      responses:
        '200':
          description: OK
    post:
      tags: [Inventory]
      operationId: InventoryCreateProperty
      summary: Create a property.
      responses:
        '201':
          description: Created
  /inventory/v1/properties/{id}:
    get:
      tags: [Inventory]
      operationId: InventoryGetPropertyById
      summary: Return a single property by id.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PropertyModel'
  /inventory/v1/units:
    get:
      tags: [Inventory]
      operationId: InventoryGetUnits
      summary: Return a list of units.
      parameters:
        - name: propertyId
          in: query
          schema:
            type: string
      responses:
        '200':
          description: OK
    post:
      tags: [Inventory]
      operationId: InventoryCreateUnit
      summary: Create a unit.
      responses:
        '201':
          description: Created
  /inventory/v1/unit-groups:
    get:
      tags: [Inventory]
      operationId: InventoryGetUnitGroups
      summary: Return a list of unit groups.
      responses:
        '200':
          description: OK
    post:
      tags: [Inventory]
      operationId: InventoryCreateUnitGroup
      summary: Create a unit group.
      responses:
        '201':
          description: Created
  /rateplan/v1/rate-plans:
    get:
      tags: [Rate Plan]
      operationId: RateplanGetRatePlans
      summary: Return a list of rate plans.
      parameters:
        - name: propertyId
          in: query
          schema:
            type: string
      responses:
        '200':
          description: OK
    post:
      tags: [Rate Plan]
      operationId: RateplanCreateRatePlan
      summary: Create a rate plan.
      responses:
        '201':
          description: Created
  /rateplan/v1/rate-plans/{id}:
    get:
      tags: [Rate Plan]
      operationId: RateplanGetRatePlanById
      summary: Return a single rate plan by id.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RatePlanModel'
  /rateplan/v1/rate-plans/{id}/rates:
    get:
      tags: [Rate Plan]
      operationId: RateplanGetRates
      summary: Return the rates of a rate plan.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: from
          in: query
          schema:
            type: string
            format: date
        - name: to
          in: query
          schema:
            type: string
            format: date
      responses:
        '200':
          description: OK
    patch:
      tags: [Rate Plan]
      operationId: RateplanUpdateRates
      summary: Update the rates of a rate plan.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: No Content
  /rateplan/v1/services:
    get:
      tags: [Rate Plan]
      operationId: RateplanGetServices
      summary: Return a list of services.
      responses:
        '200':
          description: OK
    post:
      tags: [Rate Plan]
      operationId: RateplanCreateService
      summary: Create a service.
      responses:
        '201':
          description: Created
  /availability/v1/units:
    get:
      tags: [Availability]
      operationId: AvailabilityGetUnits
      summary: Return unit availability for a property and date range.
      parameters:
        - name: propertyId
          in: query
          required: true
          schema:
            type: string
        - name: from
          in: query
          required: true
          schema:
            type: string
            format: date-time
        - name: to
          in: query
          required: true
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: OK
  /availability/v1/unit-groups:
    get:
      tags: [Availability]
      operationId: AvailabilityGetUnitGroups
      summary: Return unit-group availability for a property and date range.
      parameters:
        - name: propertyId
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
  /availability/v1/services:
    get:
      tags: [Availability]
      operationId: AvailabilityGetServices
      summary: Return service availability for a property and date range.
      responses:
        '200':
          description: OK
  /finance/v1/folios:
    get:
      tags: [Finance]
      operationId: FinanceGetFolios
      summary: Return a list of folios.
      parameters:
        - name: reservationId
          in: query
          schema:
            type: string
      responses:
        '200':
          description: OK
    post:
      tags: [Finance]
      operationId: FinanceCreateFolio
      summary: Create a folio.
      responses:
        '201':
          description: Created
  /finance/v1/folios/{id}:
    get:
      tags: [Finance]
      operationId: FinanceGetFolioById
      summary: Return a single folio by id.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FolioModel'
  /finance/v1/folio-actions/{folioId}/charges:
    post:
      tags: [Finance]
      operationId: FinancePostCharge
      summary: Post a charge to a folio.
      parameters:
        - name: folioId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
  /finance/v1/folios/{folioId}/payments:
    get:
      tags: [Finance]
      operationId: FinanceGetPayments
      summary: Return the payments of a folio.
      parameters:
        - name: folioId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
    post:
      tags: [Finance]
      operationId: FinanceCreatePayment
      summary: Add a payment to a folio.
      parameters:
        - name: folioId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
  /finance/v1/invoices:
    get:
      tags: [Finance]
      operationId: FinanceGetInvoices
      summary: Return a list of invoices.
      responses:
        '200':
          description: OK
    post:
      tags: [Finance]
      operationId: FinanceCreateInvoice
      summary: Create an invoice from a folio.
      responses:
        '201':
          description: Created
  /settings/v1/city-tax:
    get:
      tags: [Settings]
      operationId: SettingsGetCityTaxes
      summary: Return the configured city taxes.
      responses:
        '200':
          description: OK
    post:
      tags: [Settings]
      operationId: SettingsCreateCityTax
      summary: Create a city tax configuration.
      responses:
        '201':
          description: Created
  /settings/v1/market-segments:
    get:
      tags: [Settings]
      operationId: SettingsGetMarketSegments
      summary: Return a list of market segments.
      responses:
        '200':
          description: OK
    post:
      tags: [Settings]
      operationId: SettingsCreateMarketSegment
      summary: Create a market segment.
      responses:
        '201':
          description: Created
  /settings/v1/languages:
    get:
      tags: [Settings]
      operationId: SettingsGetLanguages
      summary: Return the enabled languages of the account.
      responses:
        '200':
          description: OK
components:
  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
  schemas:
    CreateBookingModel:
      type: object
      required:
        - reservations
      properties:
        booker:
          $ref: '#/components/schemas/BookerModel'
        paymentAccount:
          type: object
          additionalProperties: true
        reservations:
          type: array
          items:
            $ref: '#/components/schemas/CreateReservationModel'
    BookerModel:
      type: object
      properties:
        title:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        email:
          type: string
        phone:
          type: string
        address:
          $ref: '#/components/schemas/AddressModel'
    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
    BookingCreatedModel:
      type: object
      properties:
        id:
          type: string
        bookingId:
          type: string
        reservationIds:
          type: array
          items:
            type: object
            properties:
              id:
                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'
    EmbeddedPropertyModel:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
    PropertyModel:
      type: object
      properties:
        id:
          type: string
        code:
          type: string
        name:
          type: string
        description:
          type: string
        timeZone:
          type: string
        currencyCode:
          type: string
        status:
          type: string
          enum: [Test, Live, Archived]
        location:
          $ref: '#/components/schemas/AddressModel'
    RatePlanModel:
      type: object
      properties:
        id:
          type: string
        code:
          type: string
        name:
          type: string
        description:
          type: string
        isSubjectToCityTax:
          type: boolean
        propertyId:
          type: string
        unitGroupId:
          type: string
        cancellationPolicyId:
          type: string
        noShowPolicyId:
          type: string
    FolioModel:
      type: object
      properties:
        id:
          type: string
        reservationId:
          type: string
        propertyId:
          type: string
        type:
          type: string
          enum: [Guest, External, House]
        status:
          type: string
          enum: [Open, Closed]
        balance:
          $ref: '#/components/schemas/MonetaryValueModel'
        charges:
          type: array
          items:
            type: object
            additionalProperties: true
        payments:
          type: array
          items:
            type: object
            additionalProperties: true
    AddressModel:
      type: object
      properties:
        addressLine1:
          type: string
        addressLine2:
          type: string
        postalCode:
          type: string
        city:
          type: string
        regionCode:
          type: string
        countryCode:
          type: string
    MonetaryValueModel:
      type: object
      properties:
        amount:
          type: number
          format: double
        currency:
          type: string