End-to-end reservation lifecycle - create bookings and reservations, fetch offers, manage groups and blocks, and run reservation actions such as check-in, check-out, amend, assign-unit, and cancel.
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