Skip to content
HotelPlatform.io

HotelAPI 2.2.0-alpha.1

HotelApi

Manage the entire reservation cycle through a single API. The amount of details can vary from setup to setup as the system relies on the data provided by the PMS. The API is designed to be flexible and to allow different setups to be integrated.

Servers: https://hotelplatform.io/api/v2http://localhost:{port}/api/v2

Availability

Beta only

Availability for the unit types and units of the property.

List Availability

GET /availability/unit-types

List the available unit types.

The longest allowed period in one single request is 365 days.

Filter example:

?filter[startDate]=2023-06-28&filter[endDate]=2023-06-29

Filter for one specific unit type

?filter[startDate]=2023-06-28&filter[endDate]=2023-06-29&filter[unitTypeId]=497f6eca-6276-4993-bfeb-53cbbbba6f08

  • $ref: '#/components/parameters/filter'

Parameters

  • filter (query, object)

    Filter results using field/operator pairs. The format is filter[field][operator]=value.

    Supported operators: eq, ne, gt, gte, lt, lte, like.

    Multiple filters are combined with AND.

Responses

  • 200

    OK

  • 400

    The server could not understand the request due to invalid syntax.

  • 500

    An unexpected error occurred on the server.

Update UnitType Availability

PATCH /availability/unit-types/{unitTypeId}

Update the availability in the given time period. Provide only unitType's in a period which change. This endpoints manages time periods with a start and end date / time and does not work with resource ids!

It's not allowed to update the availability of a unitType in a contiguous period with the same quantity.

Consider sorting the by startDate in an ascending manner.

Parameters

  • unitTypeId (path, string, required)

Request body

application/vnd.api+json · UnitTypeBaseAvailability[]

Takes an array of periods of a unitType availability. Each item in the array represents an available period and the number of units (count) it has available. The next available period of the same unit must have a different count.

  • startDate (string (date)) – First available date
  • startTime (string (time)) – First available time
  • endDate (string (date)) – Last available date
  • endTime (string (time)) – Last available time
  • quantity (number, required) – number of available units of this unitType

Responses

  • 204

    No Content

List Unit Availability

GET /availability/units

list available untis

Parameters

  • filter (query, object)

    Filter results using field/operator pairs. The format is filter[field][operator]=value.

    Supported operators: eq, ne, gt, gte, lt, lte, like.

    Multiple filters are combined with AND.

Responses

  • 200

    Quantity is always 1.

  • 400

    The server could not understand the request due to invalid syntax.

  • 500

    An unexpected error occurred on the server.

Update Unit Availability

PATCH /availability/units/{unitId}

Update the unit available in the provided period. Multiple periods (array items) can be provided in the same request.

Parameters

  • unitId (path, string, required)

Request body

application/vnd.api+json · UnitBaseAvailability[]

Takes an array of periods of a units availability.

  • startDate (string (date), required) – The start date
  • startTime (string (time)) – The start time
  • endDate (string (date), required) – The end date
  • quantity (number enum, required) – 0 or 1 depending of weather the unit is available

Responses

  • 204

    No Content

List Reservation Availability

GET /availability/reservations/{reservationId}/units

Get available units which can be assigned to one of the stays of a reservation. This will return units for any of the stays of your reservation which do not have a unit assigned. If the reservation has stays for multiple different unitType's, one must filter the result for the specific stay or use getAvailableReservationStayUnits for every single stay.

One would typically call this before assigning a unit to a stay.

Parameters

  • reservationId (path, string, required)
  • filter (query, object)

    Filter results using field/operator pairs. The format is filter[field][operator]=value.

    Supported operators: eq, ne, gt, gte, lt, lte, like.

    Multiple filters are combined with AND.

Responses

  • 200

    Quantity is always 1.

  • 400

    The server could not understand the request due to invalid syntax.

  • 404

    The requested resource could not be found.

  • 500

    An unexpected error occurred on the server.

Get Unit Stay Availability

GET /availability/reservations/{reservationId}/stays/{stayId}/units

Returns available and assignable units for an individual stay.

One would typically call this before assigning a unit to a stay.

Parameters

  • reservationId (path, string, required)
  • stayId (path, string, required)
  • filter (query, object)

    Filter results using field/operator pairs. The format is filter[field][operator]=value.

    Supported operators: eq, ne, gt, gte, lt, lte, like.

    Multiple filters are combined with AND.

Responses

  • 200

    Quantity is always 1.

  • 400

    The server could not understand the request due to invalid syntax.

  • 404

    The requested resource could not be found.

  • 500

    An unexpected error occurred on the server.

Extensions

Extensions to the base API.
These extensions are intended for internal use, may change and are not officially supported.

Invoke PMS Extension (read)

GET /pms/providers/{configurationId}/extensions/{extensionName}

Generic dispatcher for a read-style PMS extension. Query parameters are forwarded to the adapter verbatim. Returns the adapter's response under data; 404 when the extension is unknown or the configured adapter does not support it.

Parameters

  • configurationId (path, string, required)

    Uuid of the PMS configuration

  • extensionName (path, string, required)

    Name of the extension to invoke. The set of supported extensions is owned by the configured PMS adapter and is discoverable via the capabilities endpoint — for example sync, payment-methods, inventory-units, webhooks, unit-types, units. Each extension's HTTP method, query parameters, request body and response shape are adapter- and extension-specific; property-api forwards the query string and request body verbatim and returns the adapter's response under data. Examples: POST .../extensions/sync?startDate=&endDate=, GET .../extensions/payment-methods, POST / DELETE .../extensions/webhooks with optional { "callbackUrl": "..." }.

Responses

  • 200

    OK — adapter- and extension-specific payload, returned verbatim under data.

  • default

    The requested extension is not implemented for this integration

Invoke PMS Extension (write)

POST /pms/providers/{configurationId}/extensions/{extensionName}

Generic dispatcher for a write-style PMS extension (e.g. sync, inventory-units, webhooks). The query string and request body are forwarded to the adapter verbatim. Returns the adapter's response under data; 404 when the extension is unknown or the configured adapter does not support it.

Parameters

  • configurationId (path, string, required)

    Uuid of the PMS configuration

  • extensionName (path, string, required)

    Name of the extension to invoke. The set of supported extensions is owned by the configured PMS adapter and is discoverable via the capabilities endpoint — for example sync, payment-methods, inventory-units, webhooks, unit-types, units. Each extension's HTTP method, query parameters, request body and response shape are adapter- and extension-specific; property-api forwards the query string and request body verbatim and returns the adapter's response under data. Examples: POST .../extensions/sync?startDate=&endDate=, GET .../extensions/payment-methods, POST / DELETE .../extensions/webhooks with optional { "callbackUrl": "..." }.

Request body

application/vnd.api+json · object

Responses

  • 200

    OK — adapter- and extension-specific payload, returned verbatim under data.

  • default

    The requested extension is not implemented for this integration

Invoke PMS Extension (remove)

DELETE /pms/providers/{configurationId}/extensions/{extensionName}

Generic dispatcher for the removal side of a PMS extension (e.g. webhooks). The query string and request body are forwarded to the adapter verbatim. Returns the adapter's response under data; 404 when the extension is unknown or the configured adapter does not support it.

Parameters

  • configurationId (path, string, required)

    Uuid of the PMS configuration

  • extensionName (path, string, required)

    Name of the extension to invoke. The set of supported extensions is owned by the configured PMS adapter and is discoverable via the capabilities endpoint — for example sync, payment-methods, inventory-units, webhooks, unit-types, units. Each extension's HTTP method, query parameters, request body and response shape are adapter- and extension-specific; property-api forwards the query string and request body verbatim and returns the adapter's response under data. Examples: POST .../extensions/sync?startDate=&endDate=, GET .../extensions/payment-methods, POST / DELETE .../extensions/webhooks with optional { "callbackUrl": "..." }.

Request body

application/vnd.api+json · object

Responses

  • 200

    OK — adapter- and extension-specific payload, returned verbatim under data.

  • default

    The requested extension is not implemented for this integration

Get PMS Capabilities

GET /pms/providers/{configurationId}/capabilities

Returns the feature-flag set declared by the configured PMS adapter for this configuration. Resolved by sending a pms.capabilities.requested CloudEvent to the adapter on the bus and waiting for the reply. The property-api caches each adapter's response for 30 minutes; the first call after a cold start (or cache eviction) pays the bus round-trip, subsequent calls are local.

Parameters

  • configurationId (path, string, required)

    Uuid of the PMS configuration

Responses

  • 200

    OK

  • default

    The requested extension is not implemented for this integration

Payments

Payments are financial transactions done by the customer or guest.

Add payment to stay

POST /reservations/{reservationId}/stays/{stayId}/actions/record-payment

Add a payment to an existing stay.
Stay payments can be partial and do not have to cover the full outstanding due amount.
Payments can only be recorded but are not trackked with the upstream PMS system.

Parameters

  • reservationId (path, string, required)

    The uuid of a reservation

  • stayId (path, string, required)

    The uuid of the stay

Request body

application/vnd.api+json · StayPayment

  • currency (Iso4217CurrencyCode, required) – Three alphabetic caracters representing the currency according to the [Iso4217 standards](https://www.iso.org/standard/64758.html).
  • amount (PaymentAmount, required) – The amount of the payment in lowest currency unit, ex 100 (for 1.00 CHF/EUR). The amount of the intent can only be overwritten in very special cases. You usually want to omit this to use the intent amount.
  • brand (brand, required) – The payment method or brand used to make this payment.
  • customerReceipt (customerReceipt) – The customer receipt
  • merchantReceipt (merchantReceipt) – The merchant receipt
  • id (string (uuid), required) – The generated UUID
  • createdAt (string (date-time), required) – Time of creation
  • updatedAt (string (date-time), required) – Time of last update

Responses

  • 201

    Created

  • 400

    The server could not understand the request due to invalid syntax.

  • 422

    The request body failed validation.

  • 500

    An unexpected error occurred on the server.

Add payment to reservation

POST /reservations/{reservationId}/actions/record-payment

Add a payment to an existing reservation.
Reservation payments must be of the full outstanding due amount for the entire reservation.
Partial payments are only possible on stays.
Payment records are not tracked with the upstream PMS system.

Parameters

  • reservationId (path, string, required)

    The uuid of a reservation

Request body

application/vnd.api+json · StayPayment

  • currency (Iso4217CurrencyCode, required) – Three alphabetic caracters representing the currency according to the [Iso4217 standards](https://www.iso.org/standard/64758.html).
  • amount (PaymentAmount, required) – The amount of the payment in lowest currency unit, ex 100 (for 1.00 CHF/EUR). The amount of the intent can only be overwritten in very special cases. You usually want to omit this to use the intent amount.
  • brand (brand, required) – The payment method or brand used to make this payment.
  • customerReceipt (customerReceipt) – The customer receipt
  • merchantReceipt (merchantReceipt) – The merchant receipt
  • id (string (uuid), required) – The generated UUID
  • createdAt (string (date-time), required) – Time of creation
  • updatedAt (string (date-time), required) – Time of last update

Responses

  • 201

    Created

  • 400

    The server could not understand the request due to invalid syntax.

  • 422

    The request body failed validation.

  • 500

    An unexpected error occurred on the server.

List reservation payments

GET /payments

List all payments associated with a reservation or a stay.

Payments added outside of the HotelApi will not be tracked here!

Responses

  • 200

    OK

  • 400

    The server could not understand the request due to invalid syntax.

  • 500

    An unexpected error occurred on the server.

Show payment

GET /payments/{paymentId}

Get a specific payment

Parameters

  • paymentId (path, string, required)

    Uuid of the payment

Responses

  • 200

    OK

  • 404

    The requested resource could not be found.

  • 500

    An unexpected error occurred on the server.

Delete payment

DELETE /payments/{paymentId}

Delete a payment

Parameters

  • paymentId (path, string, required)

    Uuid of the payment

Responses

  • 204

    No Content

Profiles

Profiles for customers and guests.

A person should only have one profile of type Private but can have more profiles of type Company.

List Profiles

GET /profiles

Returns all profiles in the system

Parameters

  • filter (query, object)

    Filter results using field/operator pairs. The format is filter[field][operator]=value.

    Supported operators: eq, ne, gt, gte, lt, lte, like.

    Multiple filters are combined with AND.

  • page (query, object)

    Cursor-based pagination. Use page[after] or page[before] with a resource id to navigate pages.

Responses

  • 200

    OK

  • 400

    The server could not understand the request due to invalid syntax.

  • 401

    Authentication is required and has not been provided or has failed.

  • 403

    The server understood the request but refuses to authorize it.

  • 404

    The requested resource could not be found.

  • 422

    The request body failed validation.

  • 429

    The client has sent too many requests in a given amount of time.

  • 500

    An unexpected error occurred on the server.

Create Profile

POST /profiles

Create new profiles for guests or visitors.

Request body

application/vnd.api+json · Profile

The profile to create a new or update existing profile.

  • firstName (string, required)
  • middleName (string)
  • lastName (string, required) – surname
  • nationality (string) – 2 Alpha ISO code
  • companyName (string)
  • profileType (ProfileType) – List of supported profile types
  • title (string)
  • languageCode (string) – 2 alpha code ISO
  • birthDate (string (date))
  • gender (Gender) – List of genders
  • addresses (Address[])
  • emails (Email[])
  • phoneNumbers (PhoneNumber[])
  • number (string) – profile id, usually from a 3rd party system (PMS)
  • type (string)
  • externalId (externalId) – external identifier of 3rd party system

Responses

  • 201

    Profile response

  • 400

    The server could not understand the request due to invalid syntax.

  • 422

    The request body failed validation.

  • 500

    An unexpected error occurred on the server.

Show profile

GET /profiles/{profileId}

Get a specific profile by its id

Parameters

  • profileId (path, string, required)

    Uuid of the profile

Responses

  • 200

    Profile response

  • 404

    The requested resource could not be found.

  • 500

    An unexpected error occurred on the server.

Update profile

PUT /profiles/{profileId}

Overwrite profile

Parameters

  • profileId (path, string, required)

    Uuid of the profile

Request body

application/vnd.api+json · Profile

The profile to create a new or update existing profile.

  • firstName (string, required)
  • middleName (string)
  • lastName (string, required) – surname
  • nationality (string) – 2 Alpha ISO code
  • companyName (string)
  • profileType (ProfileType) – List of supported profile types
  • title (string)
  • languageCode (string) – 2 alpha code ISO
  • birthDate (string (date))
  • gender (Gender) – List of genders
  • addresses (Address[])
  • emails (Email[])
  • phoneNumbers (PhoneNumber[])
  • number (string) – profile id, usually from a 3rd party system (PMS)
  • type (string)
  • externalId (externalId) – external identifier of 3rd party system

Responses

  • 204

    No Content

Modify Profile

PATCH /profiles/{profileId}Deprecated

update any of the profile fields

Parameters

  • profileId (path, string, required)

    Uuid of the profile

Request body

application/vnd.api+json · object

Accepts any fields of the profile object.

Responses

  • 204

    No Content

Delete Profile

DELETE /profiles/{profileId}

Deletes a profile. Profile can only be delete if no reservation is associated with it.

Parameters

  • profileId (path, string, required)

    Uuid of the profile

Responses

  • 204

    No Content

  • 409

    The resource cannot be deleted because it is still referenced by other resources.

Properties

Information about the properties.

Where is this property located with some additional information.

List all properties

GET /properties

List all available properties with address

Parameters

  • filter (query, object)

    Filter results using field/operator pairs. The format is filter[field][operator]=value.

    Supported operators: eq, ne, gt, gte, lt, lte, like.

    Multiple filters are combined with AND.

  • page (query, object)

    Cursor-based pagination. Use page[after] or page[before] with a resource id to navigate pages.

Responses

  • 200

    OK

  • 400

    The server could not understand the request due to invalid syntax.

  • 500

    An unexpected error occurred on the server.

Create Property

POST /properties

Create a new property
One instance should usually only handle one property. If you have multiple properties, create multiple instances.

Request body

application/vnd.api+json · Property

Create or update property

  • name (string, required)
  • description (string)
  • enabled (boolean, required)
  • address (Address, required) – The structure to create a new address. Country must be an ISO 3166-1 alpha-2 code (two upper-case letters, e.g. "CH").
  • code (string)
  • id (string (uuid), required) – The generated UUID
  • createdAt (string (date-time), required) – Time of creation
  • updatedAt (string (date-time), required) – Time of last update

Responses

  • 201

    Property response

  • 400

    The server could not understand the request due to invalid syntax.

  • 422

    The request body failed validation.

  • 500

    An unexpected error occurred on the server.

Show property

GET /properties/{propertyId}

Show a property by its uuid

Parameters

  • propertyId (path, string, required)

    Uuid of the property

Responses

  • 200

    Property response

  • 404

    The requested resource could not be found.

  • 500

    An unexpected error occurred on the server.

Update Property

PUT /properties/{propertyId}

Overwrite property information

Parameters

  • propertyId (path, string, required)

    Uuid of the property

Request body

application/vnd.api+json · Property

Create or update property

  • name (string, required)
  • description (string)
  • enabled (boolean, required)
  • address (Address, required) – The structure to create a new address. Country must be an ISO 3166-1 alpha-2 code (two upper-case letters, e.g. "CH").
  • code (string)
  • id (string (uuid), required) – The generated UUID
  • createdAt (string (date-time), required) – Time of creation
  • updatedAt (string (date-time), required) – Time of last update

Responses

  • 204

    No Content

Delete Property

DELETE /properties/{propertyId}

Delete a property

Parameters

  • propertyId (path, string, required)

    Uuid of the property

Responses

  • 204

    No Content

RatePlans

Beta only

Rate plans are rules which are applied for reservations (stays and services).

A rate plan is responsible for applying

  • the correct rate to a stay or service considering the duration (per night), the count (persons, items), time of booking etc.
  • the tax rates
  • policies such as cancellation possibilities

List rate plans

GET /rate-plans

List all existing rate plans

Parameters

  • filter (query, object)

    Filter results using field/operator pairs. The format is filter[field][operator]=value.

    Supported operators: eq, ne, gt, gte, lt, lte, like.

    Multiple filters are combined with AND.

  • page (query, object)

    Cursor-based pagination. Use page[after] or page[before] with a resource id to navigate pages.

Responses

  • 200

    OK

  • 400

    The server could not understand the request due to invalid syntax.

  • 500

    An unexpected error occurred on the server.

Create Rate Plan

POST /rate-plans

create a new rate plan

Request body

application/vnd.api+json · RatePlan

  • active (boolean) – If the rate is enabled or not
  • parentId (string (uuid))
  • code (string, required) – A short human readable code to identify the rate in an ui
  • name (string, required) – The full name of the rate according to the `code`
  • description (string) – Some information when the rate should apply and what it covers
  • startDate (string (date), required) – First available date
  • startTime (string (time)) – First available time
  • endDate (string (date), required) – Last available date
  • endTime (string (time)) – Last available time
  • mealPlan (MealPlan) – Meal-plan inclusion of a rate plan. Maps to OTA `MealPlanIndicator` / `MealPlanCodes`. | Value | Description | | :------------ | :---------- | | RoomOnly | No meals included | | Breakfast | Breakfast included | | HalfBoard | Breakfast + one additional meal | | FullBoard | Breakfast + lunch + dinner | | AllInclusive | All meals and typically drinks included |
  • currency (Iso4217CurrencyCode) – Three alphabetic caracters representing the currency according to the [Iso4217 standards](https://www.iso.org/standard/64758.html).
  • guaranteeType (GuaranteeType) – What payment the booking channel collects or requires at booking. Maps to OTA `GuaranteeType`. | Value | Description | | :--------- | :---------- | | None | No guarantee required | | CcRequired | A credit card is required to hold the booking but is not charged | | Deposit | A specific amount or percentage is pre-charged or due at booking | | Prepay | Full prepayment required at booking |
  • cancellationPolicyId (string (uuid)) – Reference to the `CancellationPolicy` applied by default for bookings under this rate plan. Each `ReservationStay` snapshots the policy at booking time.
  • derivedAdjustment (DerivedAdjustment) – Defines how a derived rate plan (one with `parentId` set) adjusts off its parent. Without this, `parentId` alone cannot drive a derived amount.

Responses

  • 201

    Created

  • 400

    The server could not understand the request due to invalid syntax.

  • 422

    The request body failed validation.

  • 500

    An unexpected error occurred on the server.

Show rate plan

GET /rate-plans/{ratePlanId}

Show an existing rate plan by id (uuid)

Parameters

  • ratePlanId (path, string, required)

    Uuid of the rate plan

Responses

  • 200

    OK

  • 404

    The requested resource could not be found.

  • 500

    An unexpected error occurred on the server.

Update Rate Plan

PUT /rate-plans/{ratePlanId}

Overwrite rate plan

Parameters

  • ratePlanId (path, string, required)

    Uuid of the rate plan

Request body

application/vnd.api+json · RatePlan

  • active (boolean) – If the rate is enabled or not
  • parentId (string (uuid))
  • code (string, required) – A short human readable code to identify the rate in an ui
  • name (string, required) – The full name of the rate according to the `code`
  • description (string) – Some information when the rate should apply and what it covers
  • startDate (string (date), required) – First available date
  • startTime (string (time)) – First available time
  • endDate (string (date), required) – Last available date
  • endTime (string (time)) – Last available time
  • mealPlan (MealPlan) – Meal-plan inclusion of a rate plan. Maps to OTA `MealPlanIndicator` / `MealPlanCodes`. | Value | Description | | :------------ | :---------- | | RoomOnly | No meals included | | Breakfast | Breakfast included | | HalfBoard | Breakfast + one additional meal | | FullBoard | Breakfast + lunch + dinner | | AllInclusive | All meals and typically drinks included |
  • currency (Iso4217CurrencyCode) – Three alphabetic caracters representing the currency according to the [Iso4217 standards](https://www.iso.org/standard/64758.html).
  • guaranteeType (GuaranteeType) – What payment the booking channel collects or requires at booking. Maps to OTA `GuaranteeType`. | Value | Description | | :--------- | :---------- | | None | No guarantee required | | CcRequired | A credit card is required to hold the booking but is not charged | | Deposit | A specific amount or percentage is pre-charged or due at booking | | Prepay | Full prepayment required at booking |
  • cancellationPolicyId (string (uuid)) – Reference to the `CancellationPolicy` applied by default for bookings under this rate plan. Each `ReservationStay` snapshots the policy at booking time.
  • derivedAdjustment (DerivedAdjustment) – Defines how a derived rate plan (one with `parentId` set) adjusts off its parent. Without this, `parentId` alone cannot drive a derived amount.

Responses

  • 204

    No Content

Delete Rate Plan

DELETE /rate-plans/{ratePlanId}

Delete a rate plan

Parameters

  • ratePlanId (path, string, required)

    Uuid of the rate plan

Responses

  • 204

    No Content

Reservations

Reservations are bookings of with stay information including additional services.

If a reservation has multiple stay elements it can be considered a group reservation.

A reservation is made for a duration, typically a night for a specified unitType (room category). It holds the reservation holder (profile) and additional services it is booked with.

List reservations

GET /reservations

List all reservations

Parameters

  • filter (query, object)

    Filter results using field/operator pairs. The format is filter[field][operator]=value.

    Supported operators: eq, ne, gt, gte, lt, lte, like.

    Multiple filters are combined with AND.

  • page (query, object)

    Cursor-based pagination. Use page[after] or page[before] with a resource id to navigate pages.

Responses

  • 200

    OK

  • 400

    The server could not understand the request due to invalid syntax.

  • 500

    An unexpected error occurred on the server.

Create Reservation

POST /reservations

Create a new reservation.
To create a reservation for a known profile, pass an object with the profile id in the profiles array. To create a new profile along with the reservation, pass a full profile instead.
If an id property is present in the profile object, it will be prioritized over the profile object. Do not pass an empty id property.

Request body

application/vnd.api+json · object

Create or update a reservation

  • externalId (externalId) – external identifier of 3rd party system
  • stays (ReservationStayRequest[]) – list of stays

Responses

  • 201

    Reservation response

  • 400

    The server could not understand the request due to invalid syntax.

  • 422

    The request body failed validation.

  • 500

    An unexpected error occurred on the server.

Show reservation

GET /reservations/{reservationId}

Get an existing reservation by its id

Parameters

  • reservationId (path, string, required)

    The uuid of a reservation

Responses

  • 200

    Reservation response

  • 404

    The requested resource could not be found.

  • 500

    An unexpected error occurred on the server.

Update Reservation

PUT /reservations/{reservationId}

Update a reservation

Parameters

  • reservationId (path, string, required)

    The uuid of a reservation

Request body

application/vnd.api+json · object

Create or update a reservation

  • externalId (externalId) – external identifier of 3rd party system
  • stays (ReservationStayRequest[]) – list of stays

Responses

  • 204

    No Content

Modify Reservation

PATCH /reservations/{reservationId}Deprecated

Update any reservation field

Parameters

  • reservationId (path, string, required)

    The uuid of a reservation

Request body

application/vnd.api+json · object

Accepts any field of the reservation object

Responses

  • 204

    No Content

Delete Reservation

DELETE /reservations/{reservationId}

deletes a reservation

Parameters

  • reservationId (path, string, required)

    The uuid of a reservation

Responses

  • 204

    No Content

Services

Services are products that can be booked with a reservation.

Service pricing is calculated with a rate (see rate plan) and a "service pricing type" which can be

  • per stay
  • per night
  • per person
  • per use (item)
  • per person and night

List services

GET /services

List all existing services

Parameters

  • filter (query, object)

    Filter results using field/operator pairs. The format is filter[field][operator]=value.

    Supported operators: eq, ne, gt, gte, lt, lte, like.

    Multiple filters are combined with AND.

  • page (query, object)

    Cursor-based pagination. Use page[after] or page[before] with a resource id to navigate pages.

Responses

  • 200

    OK

  • 400

    The server could not understand the request due to invalid syntax.

  • 500

    An unexpected error occurred on the server.

Create Service

POST /services

Create a new service which can then be used for reservations.

Request body

application/vnd.api+json · Service

Create or update a service

  • code (string, required)
  • name (string, required)
  • description (string)
  • currencyCode (Iso4217CurrencyCode, required) – Three alphabetic caracters representing the currency according to the [Iso4217 standards](https://www.iso.org/standard/64758.html).
  • amountWithTax (number (float), required)
  • amountWithoutTax (number (float), required)
  • pricingType (PricingType, required) – List of supported pricing types | Code | Code Name | Description | | :--- | :---------- | ------------------------ | | 12 | Stay | per stay | | 19 | Night | per night | | 20 | Person | per person per stay | | 21 | PersonNight | per person and per night | | 24 | Item | per item |
  • count (integer, required) – Multiplier for items, 1 for other pricing type.

Responses

  • 201

    Created

  • 400

    The server could not understand the request due to invalid syntax.

  • 422

    The request body failed validation.

  • 500

    An unexpected error occurred on the server.

Show service

GET /services/{serviceId}

Get a service by its id

Parameters

  • serviceId (path, string, required)

    Uuid of the service

Responses

  • 200

    OK

  • 404

    The requested resource could not be found.

  • 500

    An unexpected error occurred on the server.

Update Service

PUT /services/{serviceId}

Update a service

Parameters

  • serviceId (path, string, required)

    Uuid of the service

Request body

application/vnd.api+json · Service

Create or update a service

  • code (string, required)
  • name (string, required)
  • description (string)
  • currencyCode (Iso4217CurrencyCode, required) – Three alphabetic caracters representing the currency according to the [Iso4217 standards](https://www.iso.org/standard/64758.html).
  • amountWithTax (number (float), required)
  • amountWithoutTax (number (float), required)
  • pricingType (PricingType, required) – List of supported pricing types | Code | Code Name | Description | | :--- | :---------- | ------------------------ | | 12 | Stay | per stay | | 19 | Night | per night | | 20 | Person | per person per stay | | 21 | PersonNight | per person and per night | | 24 | Item | per item |
  • count (integer, required) – Multiplier for items, 1 for other pricing type.

Responses

  • 204

    No Content

Delete a service

DELETE /services/{serviceId}

Delete a service. A service cannot be deleted while referenced by a reservation.

Parameters

  • serviceId (path, string, required)

    Uuid of the service

Responses

  • 204

    No Content

  • 409

    The resource cannot be deleted because it is still referenced by other resources.

Status

System status

Get status

GET /status

Returns server status information.

Responses

  • 200

    OK

  • 401

    Authentication is required and has not been provided or has failed.

  • 403

    The server understood the request but refuses to authorize it.

  • 429

    The client has sent too many requests in a given amount of time.

  • 500

    An unexpected error occurred on the server.

Stays

Stay element of a reservation

Assign units to all stays of a reservation

POST /reservations/{reservationId}/unit-assignments

Request unit assignment for every stay of the reservation. The platform delegates unit selection to the configured integration; the API service does not pick units.

Stays that already have a unitId are returned unchanged (idempotent). Stays for which the integration cannot pick a unit are returned with unitId left empty — clients should re-fetch or retry per stay via POST /reservations/{reservationId}/stays/{stayId}/unit-assignment.

Request body is optional and MAY carry per-stay hints; integrations are free to ignore them.

To force reassignment of an already-assigned stay, first clear unitId via PUT /reservations/{reservationId}/stays/{stayId}.

Parameters

  • reservationId (path, string, required)

    The uuid of a reservation

Request body

application/vnd.api+json · object

  • stays (object[]) – Optional per-stay hints

Responses

  • 200

    Reservation response

  • 400

    The server could not understand the request due to invalid syntax.

  • 404

    The requested resource could not be found.

  • 422

    The request body failed validation.

  • 500

    An unexpected error occurred on the server.

Create Stay

POST /reservations/{reservationId}/stays

Add a stay to an existing reservation

Parameters

  • reservationId (path, string, required)

    The uuid of a reservation

Request body

application/vnd.api+json · ReservationStayRequest

Create or update a stay

  • startDate (string (date), required) – The start date of the stay
  • startTime (string (time)) – The start time of the stay
  • endDate (string (date), required) – The end date of the stay
  • endTime (string (time)) – The end time of the stay
  • status (ReservationStatus, required) – Possible status of a reservation
  • personCount (StayPersonCountDefinition, required) – Number of persons for this stay, must be <= maxOccupancy of unitType.
  • units (StayUnit[], required) – A stay has usually one unit/room, but supports many.
  • reservationIds (object[], required) – Reservation confirmation numbers. Each type must be unique per stay — only one entry per ReservationIdType is allowed (e.g. at most one Master, one Confirmation).
  • externalId (externalId) – external identifier of 3rd party system
  • services (Service[]) – list of services
  • amount (Amount)
  • profiles (Profile | ResourceReference[]) – list of profile ids

Responses

  • 201

    Created

  • 400

    The server could not understand the request due to invalid syntax.

  • 422

    The request body failed validation.

  • 500

    An unexpected error occurred on the server.

Update Stay

PUT /reservations/{reservationId}/stays/{stayId}

Overwrite the defined stay

Parameters

  • reservationId (path, string, required)

    The uuid of a reservation

  • stayId (path, string, required)

    The uuid of the stay

Request body

application/vnd.api+json · ReservationStayRequest

Create or update a stay

  • startDate (string (date), required) – The start date of the stay
  • startTime (string (time)) – The start time of the stay
  • endDate (string (date), required) – The end date of the stay
  • endTime (string (time)) – The end time of the stay
  • status (ReservationStatus, required) – Possible status of a reservation
  • personCount (StayPersonCountDefinition, required) – Number of persons for this stay, must be <= maxOccupancy of unitType.
  • units (StayUnit[], required) – A stay has usually one unit/room, but supports many.
  • reservationIds (object[], required) – Reservation confirmation numbers. Each type must be unique per stay — only one entry per ReservationIdType is allowed (e.g. at most one Master, one Confirmation).
  • externalId (externalId) – external identifier of 3rd party system
  • services (Service[]) – list of services
  • amount (Amount)
  • profiles (Profile | ResourceReference[]) – list of profile ids

Responses

  • 204

    No Content

Modify Stay

PATCH /reservations/{reservationId}/stays/{stayId}Deprecated

Updated limited stay properties without defining the full stay object

Parameters

  • reservationId (path, string, required)

    The uuid of a reservation

  • stayId (path, string, required)

    The uuid of the stay

Request body

application/vnd.api+json · object

  • startDate (startDate) – The start date of the stay
  • startTime (startTime) – The start time of the stay
  • endDate (endDate) – The end date of the stay
  • endTime (endTime) – The end time of the stay
  • status (ReservationStatus) – Possible status of a reservation
  • personCount (StayPersonCountDefinition) – Number of persons for this stay, must be <= maxOccupancy of unitType.

Responses

  • 204

    No Content

Delete Stay

DELETE /reservations/{reservationId}/stays/{stayId}

Remove a stay from a reservation. Requires a minimum of one stay remaining in the reservation.

Parameters

  • reservationId (path, string, required)

    The uuid of a reservation

  • stayId (path, string, required)

    The uuid of the stay

Responses

  • 204

    No Content

Update stay units

PUT /reservations/{reservationId}/stays/{stayId}/unitsDeprecated

Overwrite the units of a stay

Parameters

  • reservationId (path, string, required)

    The uuid of a reservation

  • stayId (path, string, required)

    The uuid of the stay

Request body

application/vnd.api+json · StayUnit[]

  • unitTypeId (string (uuid), required) – Id of the associated unit type
  • unitId (string (uuid)) – Id of the assigned unit

Responses

  • 204

    No Content

Update stays services

PUT /reservations/{reservationId}/stays/{stayId}/servicesDeprecated

Replace all services of a stay

Parameters

  • reservationId (path, string, required)

    The uuid of a reservation

  • stayId (path, string, required)

    The uuid of the stay

Request body

application/vnd.api+json · StayService[]

  • stayId (string (uuid)) – Id of the assigned unit

Responses

  • 204

    No Content

Assign a unit to a single stay

POST /reservations/{reservationId}/stays/{stayId}/unit-assignment

Request unit assignment for the stay. The platform delegates unit selection to the configured integration; the API service does not pick units.

Idempotent on the outcome: if the stay already has a unitId, the existing stay is returned unchanged with no integration round-trip.

Request body is optional and MAY carry hints (preferredUnitId, notes); the integration is free to ignore them.

Error semantics:

  • 409 — stay already assigned and the integration refused to change it.
  • 422 — no eligible unit (no unit of the required type, all occupied, all dirty, or integration rejected). The response problem detail carries the reason text from the integration where available.

To force reassignment, first clear unitId via PUT /reservations/{reservationId}/stays/{stayId} and call this endpoint again.

Parameters

  • reservationId (path, string, required)

    The uuid of a reservation

  • stayId (path, string, required)

    The uuid of the stay

Request body

application/vnd.api+json · object

  • preferredUnitId (string (uuid)) – Suggested unit; integration MAY still pick a different one.
  • notes (string) – Free-text passed through to the integration.

Responses

  • 200

    Stay with assigned unit

  • 400

    The server could not understand the request due to invalid syntax.

  • 404

    The requested resource could not be found.

  • 409

    The resource cannot be deleted because it is still referenced by other resources.

  • 422

    The request body failed validation.

  • 500

    An unexpected error occurred on the server.

Units

Unit types and units reflect room categories and rooms or apartments.

Unit types

Unit types in a hotel are room categories such as 'single rooms' or 'double rooms'.

Each unit in a unit type share the same properties such as how many guests can share a unit. Unit types are usually tightly coupled to the properties pricing rules.

Units

A unit can be seen as a hotel room, a flat or anything else which can be booked for a time period.

Units belong to a unitType and share their properties such as possible occupancy.

Its uncommon that a unit is assigned to a different unitType but it may happen. For instance a small double room could be converted to a single room.

List unit types

GET /unit-types

List all unit types available

Parameters

  • filter (query, object)

    Filter results using field/operator pairs. The format is filter[field][operator]=value.

    Supported operators: eq, ne, gt, gte, lt, lte, like.

    Multiple filters are combined with AND.

  • page (query, object)

    Cursor-based pagination. Use page[after] or page[before] with a resource id to navigate pages.

Responses

  • 200

    OK

  • 400

    The server could not understand the request due to invalid syntax.

  • 500

    An unexpected error occurred on the server.

Create unit type

POST /unit-types

Create a new unit type.

Request body

application/vnd.api+json

  • name (string, required)
  • code (string, required)
  • maxOccupancy (integer) – Max person who can rent this unit type
  • maxAdults (integer) – Max adults allowed in this unit type. Maps to OTA `MaxAdults` (AgeQualifyingCode=10). Required by Booking.com / Expedia for occupancy-based filtering and pricing.
  • maxChildren (integer) – Max children allowed in this unit type. Maps to OTA `MaxChildren` (AgeQualifyingCode=8).
  • quantity (integer) – Number of units of this unit type. Computed server-side from the count of child units; cannot be set via the request body.
  • amenities (string (uuid)[]) – list unit types

Responses

  • 201

    Unit type response

  • 400

    The server could not understand the request due to invalid syntax.

  • 415

    The request content type is not supported by the server.

  • 422

    The request body failed validation.

  • 500

    An unexpected error occurred on the server.

Show unit type

GET /unit-types/{unitTypeId}

Get unit type by code or id

Parameters

  • unitTypeId (path, string, required)

    the id of the unit type

Responses

  • 200

    Unit type response

  • 404

    The requested resource could not be found.

  • 500

    An unexpected error occurred on the server.

Update Unit Type

PUT /unit-types/{unitTypeId}

Overwrites the unit type

Parameters

  • unitTypeId (path, string, required)

    the id of the unit type

Request body

application/vnd.api+json

Create or update a unitTypes

  • name (string, required)
  • code (string, required)
  • maxOccupancy (integer) – Max person who can rent this unit type
  • maxAdults (integer) – Max adults allowed in this unit type. Maps to OTA `MaxAdults` (AgeQualifyingCode=10). Required by Booking.com / Expedia for occupancy-based filtering and pricing.
  • maxChildren (integer) – Max children allowed in this unit type. Maps to OTA `MaxChildren` (AgeQualifyingCode=8).
  • quantity (integer) – Number of units of this unit type. Computed server-side from the count of child units; cannot be set via the request body.
  • amenities (string (uuid)[]) – list of amenities

Responses

  • 204

    No Content

  • 400

    The server could not understand the request due to invalid syntax.

  • 404

    The requested resource could not be found.

  • 415

    The request content type is not supported by the server.

  • 422

    The request body failed validation.

  • 500

    An unexpected error occurred on the server.

Delete Unit Type

DELETE /unit-types/{unitTypeId}

Delete a unit type. Cannot be deleted while referenced by a unit or reservation.

Parameters

  • unitTypeId (path, string, required)

    the id of the unit type

Responses

  • 204

    No Content

  • 404

    The requested resource could not be found.

  • 409

    The resource cannot be deleted because it is still referenced by other resources.

  • 500

    An unexpected error occurred on the server.

Batch creation of unit types

POST /batch/unit-types

Create up to 100 new unit types with one request.

Request body

application/vnd.api+json · UnitType[]

Create many unit types in a batch request. Operation can be expected to take longer than usual. Use createUnitType whenever possible. (method may change).

  • name (string, required)
  • code (string, required)
  • maxOccupancy (integer) – Max person who can rent this unit type
  • maxAdults (integer) – Max adults allowed in this unit type. Maps to OTA `MaxAdults` (AgeQualifyingCode=10). Required by Booking.com / Expedia for occupancy-based filtering and pricing.
  • maxChildren (integer) – Max children allowed in this unit type. Maps to OTA `MaxChildren` (AgeQualifyingCode=8).
  • quantity (integer) – Number of units of this unit type. Computed server-side from the count of child units; cannot be set via the request body.

Responses

  • 201

    Created

  • 400

    The server could not understand the request due to invalid syntax.

  • 422

    The request body failed validation.

  • 500

    An unexpected error occurred on the server.

Batch creation of units

POST /batch/units

Create up to 100 new units with one request.

Request body

application/vnd.api+json · Unit[]

Create many units in a batch request. Operation can be expected to take longer than usual. Use createUnit whenever possible. (method may change).

  • name (string, required)
  • floor (string)
  • status (any) – Operational/housekeeping status of the unit. Owned by the unit (inventory) domain, not by reservations. Optional: when omitted on creation the unit defaults to Dirty, and reservation/stay sync must not set it at all — a unit outlives any single reservation and its status is managed separately.
  • unitTypeId (string (uuid)) – The id of the unit type (category) this unit belongs to

Responses

  • 201

    Created

  • 400

    The server could not understand the request due to invalid syntax.

  • 422

    The request body failed validation.

  • 500

    An unexpected error occurred on the server.

List all units

GET /unit-types/{unitTypeId}/units

List units belonging to a specific unit type

Parameters

  • unitTypeId (path, string, required)

    the id of the unit type

Responses

  • 200

    Example response

  • 404

    The requested resource could not be found.

  • 500

    An unexpected error occurred on the server.

List all units

GET /units

List all units

Parameters

  • filter (query, object)

    Filter results using field/operator pairs. The format is filter[field][operator]=value.

    Supported operators: eq, ne, gt, gte, lt, lte, like.

    Multiple filters are combined with AND.

  • page (query, object)

    Cursor-based pagination. Use page[after] or page[before] with a resource id to navigate pages.

Responses

  • 200

    Example response

  • 400

    The server could not understand the request due to invalid syntax.

  • 500

    An unexpected error occurred on the server.

Create Unit

POST /units

Create a new unit.

Amenities can be assigned to units by their id. If an amenity matches all units in the same unitType then it should be assigned to the unitType and not the unit.

Request body

application/vnd.api+json

Create or update a unit

  • name (string, required)
  • floor (string)
  • status (any) – Operational/housekeeping status of the unit. Owned by the unit (inventory) domain, not by reservations. Optional: when omitted on creation the unit defaults to Dirty, and reservation/stay sync must not set it at all — a unit outlives any single reservation and its status is managed separately.
  • unitTypeId (string (uuid)) – The id of the unit type (category) this unit belongs to
  • amenities (string (uuid)[]) – list amenities

Responses

  • 201

    Unit response

  • 400

    The server could not understand the request due to invalid syntax.

  • 404

    The requested resource could not be found.

  • 415

    The request content type is not supported by the server.

  • 422

    The request body failed validation.

  • 500

    An unexpected error occurred on the server.

Show unit

GET /units/{unitId}

Get a unit by id

Parameters

  • unitId (path, string, required)

    Uuid of the unit

Responses

  • 200

    Unit response

  • 404

    The requested resource could not be found.

  • 500

    An unexpected error occurred on the server.

Update Unit

PUT /units/{unitId}

Overwrites a unit

Parameters

  • unitId (path, string, required)

    Uuid of the unit

Request body

application/vnd.api+json

Create or update a unit

  • name (string, required)
  • floor (string)
  • status (any) – Operational/housekeeping status of the unit. Owned by the unit (inventory) domain, not by reservations. Optional: when omitted on creation the unit defaults to Dirty, and reservation/stay sync must not set it at all — a unit outlives any single reservation and its status is managed separately.
  • unitTypeId (string (uuid)) – The id of the unit type (category) this unit belongs to
  • amenities (string (uuid)[]) – list amenities

Responses

  • 204

    No Content

  • 400

    The server could not understand the request due to invalid syntax.

  • 404

    The requested resource could not be found.

  • 415

    The request content type is not supported by the server.

  • 422

    The request body failed validation.

  • 500

    An unexpected error occurred on the server.

Patch Unit

PATCH /units/{unitId}

Patch a unit with a partial payload.

Parameters

  • unitId (path, string, required)

    Uuid of the unit

Request body

application/vnd.api+json

Create or update a unit

  • name (string, required)
  • floor (string)
  • status (any) – Operational/housekeeping status of the unit. Owned by the unit (inventory) domain, not by reservations. Optional: when omitted on creation the unit defaults to Dirty, and reservation/stay sync must not set it at all — a unit outlives any single reservation and its status is managed separately.
  • unitTypeId (string (uuid)) – The id of the unit type (category) this unit belongs to
  • amenities (string (uuid)[]) – list amenities

Responses

  • 204

    No Content

  • 400

    The server could not understand the request due to invalid syntax.

  • 404

    The requested resource could not be found.

  • 415

    The request content type is not supported by the server.

  • 422

    The request body failed validation.

  • 500

    An unexpected error occurred on the server.

Delete Unit

DELETE /units/{unitId}

Delete a unit. Cannot be deleted while assigned to a reservation stay.

Parameters

  • unitId (path, string, required)

    Uuid of the unit

Responses

  • 204

    No Content

  • 404

    The requested resource could not be found.

  • 409

    The resource cannot be deleted because it is still referenced by other resources.

  • 500

    An unexpected error occurred on the server.

List unit amenities

GET /amenities

List all amenities which can be assigned to UnitTypes or Units

Parameters

  • filter (query, object)

    Filter results using field/operator pairs. The format is filter[field][operator]=value.

    Supported operators: eq, ne, gt, gte, lt, lte, like.

    Multiple filters are combined with AND.

  • page (query, object)

    Cursor-based pagination. Use page[after] or page[before] with a resource id to navigate pages.

Responses

  • 200

    OK

  • 400

    The server could not understand the request due to invalid syntax.

  • 500

    An unexpected error occurred on the server.

Create Amenity

POST /amenities

Create a new amenity

Request body

application/vnd.api+json · UnitAmenity

  • name (string, required)
  • description (string)

Responses

  • 201

    Example response

  • 400

    The server could not understand the request due to invalid syntax.

  • 422

    The request body failed validation.

  • 500

    An unexpected error occurred on the server.

Show Amenity

GET /amenities/{amenityId}

Get a single amenity by its id

Parameters

  • amenityId (path, string, required)

    The id of the amenity

Responses

  • 200

    Example response

  • 404

    The requested resource could not be found.

  • 500

    An unexpected error occurred on the server.

Update Amenity

PUT /amenities/{amenityId}

Overwrite the amenity

Parameters

  • amenityId (path, string, required)

    The id of the amenity

Request body

application/vnd.api+json · UnitAmenity

  • name (string, required)
  • description (string)

Responses

  • 204

    No Content

Delete Amenity

DELETE /amenities/{amenityId}

Delete an amenity

Parameters

  • amenityId (path, string, required)

    The id of the amenity

Responses

  • 204

    No Content