openapi: 3.0.0
info:
title: 'Cloudbeds API v2'
description: '
Welcome to the documentation for Cloudbeds API Version v2! If you are looking to learn how to use the Cloudbeds API to access guest information, reservations, or similar data for your Cloudbeds customers, then you''ve come to the right place.
In this document you will find all the API methods we provide along with explanations for parameters and response examples.
If you have questions about different implementation steps (e.g. how to implement OAuth 2.0), please refer to our Integrations Portal.
Be sure to subscribe to the monthly Cloudbeds API announcement mailing list to receive information on new additions and improvements to the Cloudbeds API and related developer tools.
Endpoint: https://api.cloudbeds.com/{method}
HTTPS: Our API requires HTTPS. We''ll respond with an appropriate error if you''re not using it.
Request Format: HTTP GET, POST, PUT, PATCH and DELETE; request bodies are JSON (Content-Type: application/json)
Response Format: JSON
Response Header: X-Request-ID is added to response headers in all calls to help accelerate support and troubleshooting.
use this link to access our Public collection in Postman.
'
version: v2
servers:
-
url: 'https://api.cloudbeds.com/'
description: 'Cloudbeds API v2'
paths:
/addons/v1/addons:
get:
tags:
- Addons
summary: 'Retrieve property add-ons'
description: 'Fetches list of Add-ons with basic information for a specific property'
operationId: 'AddonController::getAddons'
parameters:
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
-
name: limit
in: query
description: 'The maximum number of items to return in the response. Default is 100.'
required: false
schema:
type: integer
default: 100
maximum: 500
minimum: 1
example: '100'
-
name: offset
in: query
description: 'The number of items to skip before starting to collect the result set. Used for pagination.'
required: false
schema:
type: integer
default: 0
minimum: 0
example: '0'
-
name: filters
in: query
description: 'This parameter should be formatted as a list of strings separated by ; Use \; for a literal semicolon inside a value.'
required: false
schema:
$ref: '#/components/schemas/QueryParameterDynamicFilterSchema'
example: 'field1:value;field2:operator:value'
-
name: Accept-Language
in: header
description: 'The preferred language(s) for localized strings (e.g., en-US)'
required: false
schema:
type: string
responses:
'200':
description: 'Successful response'
content:
application/json:
schema:
$ref: '#/components/schemas/AddonsResponseSchema'
'400':
description: 'Bad Request - Invalid input parameters'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'401':
description: 'Unauthorized - Invalid or missing authentication'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'403':
description: 'Forbidden - Insufficient permissions'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'500':
description: 'Internal Server Error'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'read:addon'
'/addons/v1/reservations/{reservationId}/addons/{soldAddonId}':
delete:
tags:
- Addons
summary: 'Void an add-on on a reservation'
description: 'Voids one add-on on a reservation, with its charge, taxes and fees, the same way the MFD UI does. Idempotent: voiding an already-voided add-on returns 204.'
operationId: 'AddonController::deleteReservationAddon'
parameters:
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
-
name: reservationId
in: path
description: 'The reservation ID, as returned by getReservation.'
required: true
schema:
type: string
-
name: soldAddonId
in: path
description: 'The add-on''s soldProductID from reservationAddOnProducts in getReservation.'
required: true
schema:
type: string
pattern: '^[1-9][0-9]{0,17}$'
responses:
'204':
description: 'Add-on voided (or already voided - idempotent).'
content:
application/json:
schema:
$ref: '#/components/schemas/NoContentResponseSchema'
'400':
description: 'Bad Request - soldAddonId is not a positive whole number'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'401':
description: 'Unauthorized - Invalid or missing authentication'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'403':
description: 'Forbidden - Missing the write:item scope or access to the property'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'404':
description: 'Not found - no add-on with this ID on this reservation and property (ADDON_NOT_FOUND)'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/NotFoundResponseSchema'
'500':
description: 'Internal Server Error'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'write:item'
/amenities/v1/catalogs/amenities:
get:
tags:
- Amenities
summary: 'Get amenity catalog'
description: 'Returns the complete list of amenities available for the specified scope (property or room) with their translated names and category codes.'
operationId: 'AmenityCatalogController::getAmenityCatalog'
parameters:
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
-
name: Accept-Language
in: header
description: 'RFC 5646 language preferences used for negotiation (e.g. es-ES, en;q=0.8).'
required: false
schema:
type: string
example: 'es-ES, en;q=0.8'
-
name: scope
in: query
description: 'The scope of amenities to retrieve'
required: true
schema:
type: string
enum:
- property
- room
example: property
responses:
'200':
description: 'A list of amenities in the catalog for the requested scope.'
content:
application/json:
schema:
$ref: '#/components/schemas/GetAmenityCatalogResponseSchema'
'400':
description: 'Invalid or missing scope parameter'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'401':
description: 'Unauthorized response'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'403':
description: 'Forbidden response'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'500':
description: 'Internal server error'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'hotel:read'
/amenities/v1/catalogs/categories:
get:
tags:
- Amenities
summary: 'Get amenity category catalog'
description: 'Returns the complete list of amenity categories available for the specified scope (property or room) with their translated names.'
operationId: 'AmenityCatalogController::getAmenityCategoryCatalog'
parameters:
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
-
name: Accept-Language
in: header
description: 'RFC 5646 language preferences used for negotiation (e.g. es-ES, en;q=0.8).'
required: false
schema:
type: string
example: 'es-ES, en;q=0.8'
-
name: scope
in: query
description: 'The scope of amenities to retrieve'
required: true
schema:
type: string
enum:
- property
- room
example: property
responses:
'200':
description: 'A list of amenity categories in the catalog for the requested scope.'
content:
application/json:
schema:
$ref: '#/components/schemas/GetAmenityCategoryCatalogResponseSchema'
'400':
description: 'Invalid or missing scope parameter'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'401':
description: 'Unauthorized response'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'403':
description: 'Forbidden response'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'500':
description: 'Internal server error'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'hotel:read'
'/amenities/v1/properties/{propertyId}/amenities':
get:
tags:
- Amenities
summary: 'Get property amenities'
description: 'Retrieve the complete set of active property amenities.'
operationId: 'PropertyAmenityController::getPropertyAmenities'
parameters:
-
name: propertyId
in: path
description: 'The property ID'
required: true
schema:
type: integer
example: 1
-
name: Accept-Language
in: header
description: 'RFC 5646 language preferences used for negotiation (e.g. es-ES, en;q=0.8).'
required: false
schema:
type: string
example: 'es-ES, en;q=0.8'
responses:
'200':
description: 'Property amenities retrieved successfully.'
content:
application/json:
schema:
$ref: '#/components/schemas/GetPropertyAmenitiesResponseSchema'
'401':
description: 'Unauthorized response'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'403':
description: 'Forbidden - missing required permissions'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'404':
description: 'Property not found'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'500':
description: 'Internal server error'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'hotel:read'
put:
tags:
- Amenities
summary: 'Update property amenities'
description: 'Replace the complete set of active property amenities in a single atomic transaction.'
operationId: 'PropertyAmenityController::updatePropertyAmenities'
parameters:
-
name: propertyId
in: path
description: 'The property ID'
required: true
schema:
type: integer
example: 1
-
name: Accept-Language
in: header
description: 'RFC 5646 language preferences used for negotiation (e.g. es-ES, en;q=0.8).'
required: false
schema:
type: string
example: 'es-ES, en;q=0.8'
requestBody:
description: 'List of amenity codes to set for the property.'
content:
application/json:
schema:
$ref: '#/components/schemas/UpdatePropertyAmenitiesRequestSchema'
responses:
'200':
description: 'Property amenities updated successfully.'
content:
application/json:
schema:
$ref: '#/components/schemas/UpdatePropertyAmenitiesResponseSchema'
'400':
description: 'Validation error - invalid amenity codes'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'401':
description: 'Unauthorized response'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'403':
description: 'Forbidden - missing required permissions'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'404':
description: 'Property not found'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'500':
description: 'Internal server error'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'hotel:write'
'/amenities/v1/properties/{propertyId}/room-amenities':
get:
tags:
- Amenities
summary: 'Get amenities for all rooms in a property'
description: 'Retrieve the complete set of active amenities for all rooms in a property.'
operationId: 'RoomAmenityController::getPropertyRoomsAmenities'
parameters:
-
name: propertyId
in: path
description: 'The property ID'
required: true
schema:
type: integer
example: 1
-
name: Accept-Language
in: header
description: 'RFC 5646 language preferences used for negotiation (e.g. es-ES, en;q=0.8).'
required: false
schema:
type: string
example: 'es-ES, en;q=0.8'
responses:
'200':
description: 'Room amenities retrieved successfully.'
content:
application/json:
schema:
$ref: '#/components/schemas/GetPropertyRoomsAmenitiesResponseSchema'
'401':
description: 'Unauthorized response'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'403':
description: 'Forbidden - missing required permissions'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'404':
description: 'Property not found'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponseSchema'
'500':
description: 'Internal server error'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'hotel:read'
put:
tags:
- Amenities
summary: 'Update amenities for multiple rooms'
description: 'Replace the complete set of active amenities for multiple rooms in a single atomic transaction.'
operationId: 'RoomAmenityController::updatePropertyRoomsAmenities'
parameters:
-
name: propertyId
in: path
description: 'The property ID'
required: true
schema:
type: integer
example: 1
-
name: Accept-Language
in: header
description: 'RFC 5646 language preferences used for negotiation (e.g. es-ES, en;q=0.8).'
required: false
schema:
type: string
example: 'es-ES, en;q=0.8'
requestBody:
description: 'List of rooms with amenity codes to set.'
content:
application/json:
schema:
$ref: '#/components/schemas/UpdatePropertyRoomsAmenitiesRequestSchema'
responses:
'200':
description: 'Room amenities updated successfully.'
content:
application/json:
schema:
$ref: '#/components/schemas/UpdatePropertyRoomsAmenitiesResponseSchema'
'400':
description: 'Validation error - invalid amenity codes or room IDs'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'401':
description: 'Unauthorized response'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'403':
description: 'Forbidden - missing required permissions'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'404':
description: 'Property or room not found'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponseSchema'
'500':
description: 'Internal server error'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'hotel:write'
'/amenities/v1/properties/{propertyId}/rooms/{roomTypeId}/amenities':
get:
tags:
- Amenities
summary: 'Get room amenities'
description: 'Retrieve the complete set of active room amenities.'
operationId: 'RoomAmenityController::getRoomAmenities'
parameters:
-
name: roomTypeId
in: path
description: 'The room type id'
required: true
schema:
type: integer
example: 12345
-
name: propertyId
in: path
description: 'The property ID'
required: true
schema:
type: integer
example: 1
-
name: Accept-Language
in: header
description: 'RFC 5646 language preferences used for negotiation (e.g. es-ES, en;q=0.8).'
required: false
schema:
type: string
example: 'es-ES, en;q=0.8'
responses:
'200':
description: 'Room amenities retrieved successfully.'
content:
application/json:
schema:
$ref: '#/components/schemas/GetRoomAmenitiesResponseSchema'
'401':
description: 'Unauthorized response'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'403':
description: 'Forbidden - missing required permissions'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'404':
description: 'Property or room not found'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponseSchema'
'500':
description: 'Internal server error'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'hotel:read'
put:
tags:
- Amenities
summary: 'Update room amenities'
description: 'Replace the complete set of active room amenities in a single atomic transaction.'
operationId: 'RoomAmenityController::updateRoomAmenities'
parameters:
-
name: roomTypeId
in: path
description: 'The room type id'
required: true
schema:
type: integer
example: 12345
-
name: propertyId
in: path
description: 'The property ID'
required: true
schema:
type: integer
example: 1
-
name: Accept-Language
in: header
description: 'RFC 5646 language preferences used for negotiation (e.g. es-ES, en;q=0.8).'
required: false
schema:
type: string
example: 'es-ES, en;q=0.8'
requestBody:
description: 'List of amenity codes to set for the room.'
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateRoomAmenitiesRequestSchema'
responses:
'200':
description: 'Room amenities updated successfully.'
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateRoomAmenitiesResponseSchema'
'400':
description: 'Validation error - invalid amenity codes'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'401':
description: 'Unauthorized response'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'403':
description: 'Forbidden - missing required permissions'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'404':
description: 'Property or room not found'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponseSchema'
'500':
description: 'Internal server error'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'hotel:write'
/integration/v1/connected-applications:
get:
tags:
- Applications
summary: 'Get all connected API clients for a property'
operationId: 'ApiClientController::connectedApiClients'
parameters:
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
-
name: scopes
in: query
description: 'List of OAuth scopes to filter by. Only API clients that have all specified scopes will be returned.'
required: false
style: form
explode: false
schema:
type: array
items:
type: string
enum:
- 'delete:appPropertySettings'
- 'delete:calendarView'
- 'delete:doorLockKey'
- 'delete:item'
- 'delete:marketsegment'
- 'delete:roomblock'
- 'read:addon'
- 'read:adjustment'
- 'read:allotmentBlock'
- 'read:appPropertySettings'
- 'read:calendarView'
- 'read:communication'
- 'read:currency'
- 'read:customFields'
- 'read:dashboard'
- 'read:dataInsightsFinancialTransactions'
- 'read:dataInsightsGuests'
- 'read:dataInsightsInvoices'
- 'read:dataInsightsOccupancy'
- 'read:dataInsightsPayments'
- 'read:dataInsightsReservations'
- 'read:doorLockKey'
- 'read:externalOffer'
- 'read:group'
- 'read:guest'
- 'read:hotel'
- 'read:houseAccount'
- 'read:housekeeping'
- 'read:item'
- 'read:marketingPerformance'
- 'read:marketsegment'
- 'read:nightAudit'
- 'read:package'
- 'read:payment'
- 'read:rate'
- 'read:reservation'
- 'read:resourceReservations'
- 'read:resourceTypes'
- 'read:room'
- 'read:roomblock'
- 'read:tag'
- 'read:taxesAndFees'
- 'read:user'
- 'write:adjustment'
- 'write:allotmentBlock'
- 'write:appError'
- 'write:appPropertySettings'
- 'write:calendarView'
- 'write:communication'
- 'write:customFields'
- 'write:doorLockKey'
- 'write:externalOffer'
- 'write:group'
- 'write:guest'
- 'write:hotel'
- 'write:houseAccount'
- 'write:housekeeping'
- 'write:item'
- 'write:marketsegment'
- 'write:payment'
- 'write:rate'
- 'write:reservation'
- 'write:resourceReservations'
- 'write:resourceTypes'
- 'write:room'
- 'write:roomblock'
- 'write:tag'
- 'write:tagDefinition'
- 'write:taxesAndFees'
example:
- 'read:reservation,write:appError'
responses:
'200':
description: 'List of connected API clients'
content:
application/json:
schema:
$ref: '#/components/schemas/ApplicationListResponseSchema'
'400':
description: 'Bad request response'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'403':
description: 'Forbidden response'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'500':
description: 'Internal server error'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default: []
'/booking-room/v1/{bookingRoomId}/assignable-rooms':
get:
tags:
- booking-room
summary: 'Get rooms a reservation can be reassigned to'
description: 'Returns the reservation''s current room assignment, the property''s room types, and the rates and rooms available for a room type: the reservation''s current type when roomTypeId is omitted, or the requested type when it is provided.'
operationId: 'AssignableRoomsController::getAssignableRooms'
parameters:
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
-
name: bookingRoomId
in: path
description: 'The reservation''s current room assignment.'
required: true
schema:
type: string
pattern: ^\d+$
example: '713'
-
name: roomTypeId
in: query
description: 'Scopes rates and rooms to this room type. Omit to use the reservation''s current type.'
required: false
schema:
type: string
pattern: ^\d+$
example: '713'
responses:
'200':
description: 'Assignable rooms and supporting data'
content:
application/json:
schema:
oneOf:
- { $ref: '#/components/schemas/AssignableRoomsResponseSchema' }
- { $ref: '#/components/schemas/LegacyAssignableRoomsResponseSchema' }
'400':
description: 'Malformed request'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'403':
description: 'No permission for the property'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'404':
description: 'Booking room not found / out of scope'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponseSchema'
'422':
description: 'Invalid room type for property, or reservation not reassignable'
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationErrorResponseSchema'
'500':
description: 'Server error'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'read:reservation'
/folio/v1/checks:
post:
tags:
- Checks
summary: 'Post a completed POS check (e.g., F&B) to a guest folio, house account, or group profile'
description: 'Replaces postCustomItem with first-class folio transactions enriched with hospitality POS context (check identity, revenue center, meal period, gratuity, service charge). Items posted via this endpoint are recorded as regular folio items, not Custom Items, and are tagged as POS-originated for UI differentiation.'
operationId: 'CheckController::createCheck'
parameters:
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
-
name: Idempotency-Key
in: header
description: 'Required per-request idempotency key and the sole dedup key for this endpoint: a retry carrying the same key and the same payload replays the original posting (notice populated); the same key with a different payload is rejected with IDEMPOTENCY_KEY_REUSED, which means a check under this key is already stored. The account target is validated before the replay, so a retry whose target has since become invalid (e.g. RESERVATION_CHECKED_OUT) gets that error rather than the original posting. Absent, empty, or whitespace-only → 400.'
required: true
schema:
type: string
maxLength: 255
example: req-2026-05-05-2047-9b3f
requestBody:
description: 'Check details: account target, line items, optional gratuities, service charge, discounts and payments.'
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PostCheckRequestSchema'
responses:
'201':
description: 'Check successfully posted. The response includes the public checkId (for downstream void/reversal) and the resolved checkNumber.'
content:
application/json:
schema:
$ref: '#/components/schemas/PostCheckResponseSchema'
'400':
description: 'Bad request — missing/oversized Idempotency-Key header, invalid parameters, validation failures, or unmatched tax/fee IDs. See CheckErrorCodeEnumSchema for the structured error codes returned in the body.'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'403':
description: 'Forbidden — insufficient permissions on the requested property.'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'404':
description: 'Not found — reservation, house account, group, or folio not found.'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponseSchema'
'409':
description: 'Conflict — see CheckErrorCodeEnumSchema for the structured codes: IDEMPOTENCY_KEY_REUSED (Idempotency-Key header reused with a different payload), DUPLICATE_CHECK_ID (an active check on the property already has this checkId), PRODUCT_NAME_CONFLICT (line''s name collides with an existing active product that has a different SKU).'
content:
application/json:
schema:
$ref: '#/components/schemas/ConflictResponseSchema'
'500':
description: 'Internal server error.'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'write:item'
'/folio/v1/checks/{checkId}':
delete:
tags:
- Checks
summary: 'Void a posted check end-to-end (ledger + payments + its gratuities) by its checkId'
description: 'Voids the whole check: reverses each line (item / service charge / discount) and its tax/fee children on both CDC and DOMAIN, cascade-voids every gratuity linked to the check (each with its own tax children), and voids the anchored payments via the payments service. Idempotent — voiding an already-voided check returns 204.'
operationId: 'CheckController::deleteCheck'
parameters:
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
-
name: checkId
in: path
description: 'The check''s public checkId (partner-supplied or Cloudbeds-generated) returned by createCheck.'
required: true
schema:
type: string
responses:
'204':
description: 'Check voided (or already voided — idempotent).'
content:
application/json:
schema:
$ref: '#/components/schemas/NoContentResponseSchema'
'403':
description: 'Forbidden — insufficient permissions on the requested property.'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'404':
description: 'Not found — no check matches the checkId on this property (CHECK_NOT_FOUND).'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponseSchema'
'400':
description: 'Bad request — the check''s reservation is already checked out (RESERVATION_CHECKED_OUT).'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'409':
description: 'Conflict — the check''s folio target was never persisted (pre-feature posting) (CHECK_VOID_UNAVAILABLE).'
content:
application/json:
schema:
$ref: '#/components/schemas/ConflictResponseSchema'
'500':
description: 'Internal server error — ledger void completed but one or more payment voids failed (PAYMENT_VOID_FAILED). Retry to converge.'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'write:item'
'/doorlock/v1/keys/{propertyId}':
get:
tags:
- 'Door Locks'
summary: 'Get a list of doorlock keys for a specific app client and property.'
operationId: 'DoorLockKeyController::index'
parameters:
-
name: propertyId
in: path
description: 'The property ID'
required: true
schema:
type: integer
example: 1
-
name: reservationId
in: query
schema:
$ref: '#/components/schemas/DoorLockKeyListRequestSchema/properties/reservationId'
-
name: subReservationId
in: query
schema:
$ref: '#/components/schemas/DoorLockKeyListRequestSchema/properties/subReservationId'
-
name: keyIds
in: query
description: 'Comma separated list of key ids'
schema:
type: string
example: '1,2,3'
-
name: reservationIds
in: query
description: 'Comma separated list of reservation ids, max 100. Cannot be combined with reservationId or subReservationId.'
schema:
type: string
example: 'reservation-1,reservation-2'
responses:
'200':
description: 'List of door lock keys.'
content:
application/json:
schema:
$ref: '#/components/schemas/DoorLockKeyListResponseSchema'
'400':
description: 'Bad Request response'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'500':
description: 'Internal server error'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'read:doorLockKey'
/doorlock/v1/keys:
post:
tags:
- 'Door Locks'
summary: 'Create a new doorlock key.'
operationId: 'DoorLockKeyController::create'
requestBody:
description: 'Key data'
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DoorLockKeyCreateRequestSchema'
responses:
'201':
description: 'The key is completed: it was created with status completed, or the integration completed it while this request waited.'
content:
application/json:
schema:
$ref: '#/components/schemas/DoorLockKeyResponseSchema'
'202':
description: 'The key was created but the integration has not completed it within the 60 second wait, on a property that still keeps such keys processing. The body is the key with status processing; fetch it by keyId until it is completed or failed. Do not create it again.'
content:
application/json:
schema:
$ref: '#/components/schemas/DoorLockKeyResponseSchema'
'400':
description: 'Bad Request response'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'404':
description: 'Not found response'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponseSchema'
'422':
description: 'The key could not be issued and is stored with status failed. message carries the integration''s errorMessage, or "The door lock partner did not confirm the key in time" when the integration did not confirm it within the 60 second wait. If the integration confirms such a key afterwards, it may be invalidated rather than made live (see the update endpoint), so check the key list before creating it again.'
content:
application/json:
schema:
$ref: '#/components/schemas/DoorLockKeyFailedToGenerateResponseSchema'
'500':
description: 'Internal server error'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'write:doorLockKey'
delete:
tags:
- 'Door Locks'
summary: 'Delete a list of doorlock keys.'
operationId: 'DoorLockKeyController::batchDelete'
parameters:
-
name: keyIds
in: query
required: true
schema:
type: string
example: '1,2'
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
responses:
'204':
description: 'Keys were cancelled.'
content:
application/json:
schema:
$ref: '#/components/schemas/NoContentResponseSchema'
'207':
description: 'Per-key invalidation results. Opt-in; by default this endpoint answers 204.'
content:
application/json:
schema:
$ref: '#/components/schemas/DoorLockKeyBatchDeleteResultResponseSchema'
'400':
description: 'Bad Request response'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'404':
description: 'Not found response'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponseSchema'
'500':
description: 'Internal server error'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'delete:doorLockKey'
'/doorlock/v1/keys/{id}':
delete:
tags:
- 'Door Locks'
summary: 'Delete a doorlock key.'
operationId: 'DoorLockKeyController::delete'
parameters:
-
name: id
in: path
required: true
schema:
type: string
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
responses:
'204':
description: 'A key that was just created.'
content:
application/json:
schema:
$ref: '#/components/schemas/NoContentResponseSchema'
'400':
description: 'Bad Request response'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'404':
description: 'Not found response'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponseSchema'
'500':
description: 'Internal server error'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'delete:doorLockKey'
patch:
tags:
- 'Door Locks'
summary: 'Update a doorlock key.'
operationId: 'DoorLockKeyController::update'
parameters:
-
name: id
in: path
required: true
schema:
type: string
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
requestBody:
description: 'Key data'
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DoorLockKeyUpdateRequestSchema'
responses:
'200':
description: 'Updated key. Completing a key that failed because the 60 second issuance wait expired may not make it live, because the caller was already told it failed: the key can instead move to status deleting and a doorLockKey/key_cancelled webhook asks the integration to cancel it on the lock. Confirm the cancellation with status deleted.'
content:
application/json:
schema:
$ref: '#/components/schemas/DoorLockKeyResponseSchema'
'400':
description: 'Bad Request response'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'404':
description: 'Not found response'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponseSchema'
'500':
description: 'Internal server error'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'write:doorLockKey'
'/doorlock/v1/settings/{propertyId}':
get:
tags:
- 'Door Locks'
summary: 'Get doorlock settings for property for specific application client.'
operationId: 'DoorLockSettingsController::single'
parameters:
-
name: propertyId
in: path
description: 'The property ID'
required: true
schema:
type: integer
example: 1
responses:
'200':
description: 'Doorlock settings for property for specific application client.'
content:
application/json:
schema:
$ref: '#/components/schemas/DoorLockSettingsResponseSchema'
'400':
description: 'Bad Request response'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'404':
description: 'Not Found response'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponseSchema'
'500':
description: 'Internal Server Error'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'read:doorLockKey'
put:
tags:
- 'Door Locks'
summary: 'Upsert doorlock settings for property for specific application client.'
operationId: 'DoorLockSettingsController::upsert'
parameters:
-
name: propertyId
in: path
description: 'The property ID'
required: true
schema:
type: integer
example: 1
requestBody:
description: 'Settings data'
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DoorLockSettingsCreateRequestSchema'
responses:
'201':
description: 'Empty response on successful create'
content:
application/json:
schema:
$ref: '#/components/schemas/CreatedResponseSchema'
'400':
description: 'Bad Request response'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'500':
description: 'Internal Server Error'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'write:doorLockKey'
delete:
tags:
- 'Door Locks'
summary: 'Delete doorlock settings for property for specific application client.'
operationId: 'DoorLockSettingsController::delete'
parameters:
-
name: propertyId
in: path
description: 'The property ID'
required: true
schema:
type: integer
example: 1
responses:
'204':
description: 'Empty response on successful delete'
content:
application/json:
schema:
$ref: '#/components/schemas/NoContentResponseSchema'
'400':
description: 'Bad Request response'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'404':
description: 'Not Found response'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponseSchema'
'500':
description: 'Internal Server Error'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'delete:doorLockKey'
/events/v2/events:
get:
tags:
- Events
summary: 'List events for a property'
description: 'Returns a paginated list of events for a property. Events contain operational data and reference group profiles via profileId.'
operationId: 'EventController::list'
parameters:
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
-
name: eventCode
in: query
schema:
type: string
-
name: profileId
in: query
schema:
type: string
-
name: status
in: query
schema:
type: string
-
name: createdFrom
in: query
schema:
type: string
format: date-time
-
name: createdTo
in: query
schema:
type: string
format: date-time
-
name: startDateFrom
in: query
schema:
type: string
format: date
-
name: startDateTo
in: query
schema:
type: string
format: date
-
name: endDateFrom
in: query
schema:
type: string
format: date
-
name: endDateTo
in: query
schema:
type: string
format: date
-
name: limit
in: query
schema:
type: integer
default: 100
maximum: 100
minimum: 0
-
name: offset
in: query
schema:
type: integer
default: 0
minimum: 0
responses:
'200':
description: 'List of events'
content:
application/json:
schema:
$ref: '#/components/schemas/EventListResponseSchema'
'400':
description: 'Bad request'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'500':
description: 'Internal server error'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'read:group'
post:
tags:
- Events
summary: 'Create a new event'
description: 'Creates a new event associated with an existing group profile or without any profile association.'
operationId: 'EventController::create'
parameters:
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EventCreateRequestSchema'
responses:
'201':
description: 'Event created'
content:
application/json:
schema:
$ref: '#/components/schemas/EventSingleResponseSchema'
'400':
description: 'Bad request'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'500':
description: 'Internal server error'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'write:group'
'/events/v2/events/{eventId}':
get:
tags:
- Events
summary: 'Get a single event'
description: 'Returns detailed information about a specific event.'
operationId: 'EventController::show'
parameters:
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
-
name: eventId
in: path
description: 'Event ID or event code (e.g., "12345" or "g162795")'
required: true
schema:
type: string
responses:
'200':
description: 'Event details'
content:
application/json:
schema:
$ref: '#/components/schemas/EventSingleResponseSchema'
'404':
description: 'Event not found'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponseSchema'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'500':
description: 'Internal server error'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'read:group'
delete:
tags:
- Events
summary: 'Delete an event'
description: 'Deletes an event by ID or event code. This is a soft delete.'
operationId: 'EventController::destroy'
parameters:
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
-
name: eventId
in: path
description: 'Event ID or event code'
required: true
schema:
type: string
responses:
'204':
description: 'Event deleted'
'404':
description: 'Event not found'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponseSchema'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'500':
description: 'Internal server error'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'write:group'
patch:
tags:
- Events
summary: 'Update an existing event'
description: 'Updates an event. Only provided fields are updated. For profileId: omit to keep, null to clear, string to replace.'
operationId: 'EventController::update'
parameters:
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
-
name: eventId
in: path
description: 'Event ID or event code'
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EventUpdateRequestSchema'
responses:
'200':
description: 'Event updated'
content:
application/json:
schema:
$ref: '#/components/schemas/EventSingleResponseSchema'
'400':
description: 'Bad request'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'404':
description: 'Event not found'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponseSchema'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'500':
description: 'Internal server error'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'write:group'
'/events/v2/events/{eventId}/notes':
get:
tags:
- Events
summary: 'List notes for an event'
description: 'Returns a paginated list of notes for a specific event.'
operationId: 'EventNoteController::list'
parameters:
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
-
name: eventId
in: path
description: 'Event ID or event code'
required: true
schema:
type: string
-
name: limit
in: query
schema:
type: integer
default: 100
maximum: 100
minimum: 0
-
name: offset
in: query
schema:
type: integer
default: 0
minimum: 0
-
name: includeArchived
in: query
schema:
type: boolean
default: false
responses:
'200':
description: 'List of notes'
content:
application/json:
schema:
$ref: '#/components/schemas/EventNoteListResponseSchema'
'404':
description: 'Event not found'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponseSchema'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'500':
description: 'Internal server error'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'read:group'
post:
tags:
- Events
summary: 'Create a note for an event'
description: 'Creates a new note for a specific event.'
operationId: 'EventNoteController::create'
parameters:
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
-
name: eventId
in: path
description: 'Event ID or event code'
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EventNoteCreateRequestSchema'
responses:
'201':
description: 'Note created'
content:
application/json:
schema:
$ref: '#/components/schemas/EventNoteSingleResponseSchema'
'400':
description: 'Bad request'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'404':
description: 'Event not found'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponseSchema'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'500':
description: 'Internal server error'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'write:group'
'/events/v2/events/{eventId}/notes/{noteId}':
patch:
tags:
- Events
summary: 'Update an event note'
description: 'Updates an existing note or archives it.'
operationId: 'EventNoteController::update'
parameters:
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
-
name: eventId
in: path
description: 'Event ID or event code'
required: true
schema:
type: string
-
name: noteId
in: path
description: 'Note ID'
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EventNoteUpdateRequestSchema'
responses:
'200':
description: 'Note updated'
content:
application/json:
schema:
$ref: '#/components/schemas/EventNoteSingleResponseSchema'
'400':
description: 'Bad request'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'404':
description: 'Event or note not found'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponseSchema'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'500':
description: 'Internal server error'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'write:group'
/folio/v1/gratuities:
post:
tags:
- Gratuities
summary: 'Post one or more guest tips to a folio, house account, or group profile'
description: 'Posts one or more tips (ITC 8995) as first-class folio transactions. Recipient attribution and POS context are stored MFD-side only; the Accounting Service Transaction carries the accounting state alone. Idempotent via the required Idempotency-Key header.'
operationId: 'GratuityController::createGratuity'
parameters:
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
-
name: Idempotency-Key
in: header
description: 'Required per-request idempotency key and the sole dedup key for this endpoint: a retry carrying the same key and the same payload replays the original posting (notice populated); the same key with a different payload is rejected with IDEMPOTENCY_KEY_REUSED. Absent, empty, or whitespace-only → 400.'
required: true
schema:
type: string
maxLength: 255
example: req-2026-05-05-2047-9b3f
requestBody:
description: 'Gratuity posting request: folio target and one or more gratuity entries.'
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PostGratuityRequestSchema'
responses:
'201':
description: 'Gratuity successfully posted. Returns the Cloudbeds-assigned gratuityId for each posted gratuity and notice=null.'
content:
application/json:
schema:
$ref: '#/components/schemas/PostGratuityResponseSchema'
'400':
description: 'Bad request — missing/oversized Idempotency-Key header, validation failure, unmatched tax externalId/taxId, unknown recipient userId, or an unresolvable folio target. See GratuityErrorCodeEnumSchema for structured error codes.'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'403':
description: 'Forbidden — insufficient permissions on the requested property.'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'409':
description: 'Conflict — see GratuityErrorCodeEnumSchema for the structured codes: IDEMPOTENCY_KEY_REUSED (Idempotency-Key reused with a different payload) or DUPLICATE_GRATUITY_ID (a partner-supplied gratuityId collides with an active gratuity).'
content:
application/json:
schema:
$ref: '#/components/schemas/ConflictResponseSchema'
'500':
description: 'Internal server error.'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'write:item'
'/folio/v1/checks/{checkId}/gratuities':
post:
tags:
- Gratuities
summary: 'Post one or more guest tips linked to an existing check'
description: 'Posts one or more tips (ITC 8995) linked to the check identified by the path {checkId}. The gratuities inherit the check''s folio target and checkNumber; POS context stays an attribute of the linked check (not copied onto the gratuity). The body carries only the gratuity entries. A check may carry many gratuities. Idempotent via the required Idempotency-Key header.'
operationId: 'GratuityController::createCheckGratuity'
parameters:
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
-
name: Idempotency-Key
in: header
description: 'Required per-request idempotency key and the sole dedup key for this endpoint: a retry carrying the same key and the same payload replays the original posting (notice populated); the same key with a different payload is rejected with IDEMPOTENCY_KEY_REUSED. Absent, empty, or whitespace-only → 400.'
required: true
schema:
type: string
maxLength: 255
example: req-2026-05-05-2047-9b3f
-
name: checkId
in: path
description: 'The partner checkId of the check to link these gratuities to.'
required: true
schema:
type: string
requestBody:
description: 'Gratuity entries to link to the check.'
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PostCheckGratuityRequestSchema'
responses:
'201':
description: 'Gratuity successfully posted. Returns the Cloudbeds-assigned gratuityId for each posted gratuity and notice=null.'
content:
application/json:
schema:
$ref: '#/components/schemas/PostGratuityResponseSchema'
'400':
description: 'Bad request — missing/oversized Idempotency-Key header, validation failure, unmatched tax externalId/taxId, unknown recipient userId, or the resolved check carries no folio target. See GratuityErrorCodeEnumSchema.'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'403':
description: 'Forbidden — insufficient permissions on the requested property.'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'404':
description: 'Not found — no check matches {checkId} on this property (CHECK_NOT_FOUND).'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponseSchema'
'409':
description: 'Conflict — IDEMPOTENCY_KEY_REUSED (Idempotency-Key reused with a different payload) or DUPLICATE_GRATUITY_ID (a partner-supplied gratuityId collides with an active gratuity).'
content:
application/json:
schema:
$ref: '#/components/schemas/ConflictResponseSchema'
'500':
description: 'Internal server error.'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'write:item'
'/folio/v1/gratuities/{gratuityId}':
delete:
tags:
- Gratuities
summary: 'Void a posted gratuity by its gratuityId'
description: 'Voids a single gratuity (as returned at post time) — reverses its tip line and its tax children on both CDC and DOMAIN. Idempotent: voiding an already-voided gratuity returns 204. The gratuityId is not re-issued after void.'
operationId: 'GratuityController::deleteGratuity'
parameters:
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
-
name: gratuityId
in: path
description: 'The public gratuityId of the gratuity to void, as returned at post time.'
required: true
schema:
type: string
responses:
'204':
description: 'Gratuity voided (or already voided — idempotent).'
content:
application/json:
schema:
$ref: '#/components/schemas/NoContentResponseSchema'
'403':
description: 'Forbidden — insufficient permissions on the requested property.'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'404':
description: 'Not found — no gratuity matches the gratuityId on this property (GRATUITY_NOT_FOUND).'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponseSchema'
'409':
description: 'Conflict — the gratuity predates void support and cannot be voided (GRATUITY_VOID_UNAVAILABLE).'
content:
application/json:
schema:
$ref: '#/components/schemas/ConflictResponseSchema'
'500':
description: 'Internal server error.'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'write:item'
'/housekeeping/v1/inspections/{propertyId}':
get:
tags:
- Housekeeping
summary: 'Housekeeping inspection list'
operationId: 27abd48cb30106ec3251cf3baf34174c
parameters:
-
name: propertyId
in: path
description: 'The property ID'
required: true
schema:
type: integer
example: 1
-
name: limit
in: query
description: 'The maximum number of items to return in the response. Default is 100.'
required: false
schema:
type: integer
default: 100
maximum: 500
minimum: 1
example: '100'
-
name: offset
in: query
description: 'The number of items to skip before starting to collect the result set. Used for pagination.'
required: false
schema:
type: integer
default: 0
minimum: 0
example: '0'
-
name: filters
in: query
description: 'This parameter should be formatted as a list of strings separated by ; Use \; for a literal semicolon inside a value.'
required: false
schema:
$ref: '#/components/schemas/QueryParameterDynamicFilterSchema'
example: 'field1:value;field2:operator:value'
responses:
'200':
description: 'A paged array of inspections'
content:
application/json:
schema:
$ref: '#/components/schemas/InspectionListResponseSchema'
'400':
description: 'Bad Request response'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
security:
-
default:
- 'read:housekeeping'
/integration/v1/events:
get:
tags:
- 'Integration Events'
summary: 'Get a list of integration events for a specific property.'
operationId: 'IntegrationEventController::index'
parameters:
-
name: sort
in: query
description: 'A string specifying fields for sorting with optional directions (e.g., asc or desc).'
required: false
schema:
$ref: '#/components/schemas/QueryParameterSortSchema'
example: 'checkin_date:desc;checkout_date'
-
name: limit
in: query
description: 'The maximum number of items to return in the response. Default is 100.'
required: false
schema:
type: integer
default: 100
maximum: 500
minimum: 1
example: '100'
-
name: offset
in: query
description: 'The number of items to skip before starting to collect the result set. Used for pagination.'
required: false
schema:
type: integer
default: 0
minimum: 0
example: '0'
-
name: filters
in: query
description: 'This parameter should be formatted as a list of strings separated by ; Use \; for a literal semicolon inside a value.'
required: false
schema:
$ref: '#/components/schemas/QueryParameterDynamicFilterSchema'
example: 'field1:value;field2:operator:value'
-
name: search
in: query
description: 'Returns only events matching every word of this text in their id, objectId, system, description or details. Text in double quotes is matched as one phrase.'
required: false
schema:
type: string
maxLength: 255
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
responses:
'200':
description: 'List of integration events.'
content:
application/json:
schema:
$ref: '#/components/schemas/IntegrationEventListResponseSchema'
'400':
description: 'Bad Request response'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'401':
description: 'Unauthorized response'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'403':
description: 'Forbidden response'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'500':
description: 'Internal server error'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default: []
post:
tags:
- 'Integration Events'
summary: 'Create a new integration event.'
operationId: 'IntegrationEventController::create'
parameters:
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
requestBody:
description: 'Integration event data'
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/IntegrationEventCreateRequestSchema'
responses:
'201':
description: 'An integration event that was just created.'
content:
application/json:
schema:
$ref: '#/components/schemas/IntegrationEventResponseSchema'
'400':
description: 'Bad Request response'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'401':
description: 'Unauthorized response'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'500':
description: 'Internal server error'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'write:appError'
'/integration/v1/events/{id}':
patch:
tags:
- 'Integration Events'
summary: 'Update an integration event.'
operationId: 'IntegrationEventController::update'
parameters:
-
name: id
in: path
required: true
schema:
type: string
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
requestBody:
description: 'Integration event data'
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/IntegrationEventUpdateRequestSchema'
responses:
'200':
description: 'An integration event that was just updated.'
content:
application/json:
schema:
$ref: '#/components/schemas/IntegrationEventResponseSchema'
'400':
description: 'Bad Request response'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'401':
description: 'Unauthorized response'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'500':
description: 'Internal server error'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'write:appError'
'/integration/v1/events/{id}/retry':
post:
tags:
- 'Integration Events'
summary: 'Retry an integration event.'
operationId: 'IntegrationEventController::retry'
parameters:
-
name: id
in: path
required: true
schema:
type: string
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
responses:
'202':
description: 'A request was sent to initiate integration event retry.'
content:
application/json:
schema:
$ref: '#/components/schemas/AcceptedResponseSchema'
'400':
description: 'Bad Request response'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'401':
description: 'Unauthorized response'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'403':
description: 'Forbidden response'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'500':
description: 'Internal server error'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default: []
/item/v1/custom-items:
get:
tags:
- Items
summary: 'Get a list of custom items for a specific property.'
operationId: 'CustomItemController::index'
parameters:
-
name: limit
in: query
description: 'The maximum number of items to return in the response. Default is 100.'
required: false
schema:
type: integer
default: 100
maximum: 500
minimum: 1
example: '100'
-
name: offset
in: query
description: 'The number of items to skip before starting to collect the result set. Used for pagination.'
required: false
schema:
type: integer
default: 0
minimum: 0
example: '0'
-
name: filters
in: query
description: 'This parameter should be formatted as a list of strings separated by ; Use \; for a literal semicolon inside a value.'
required: false
schema:
$ref: '#/components/schemas/QueryParameterDynamicFilterSchema'
example: 'field1:value;field2:operator:value'
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
responses:
'200':
description: 'List of custom items.'
content:
application/json:
schema:
$ref: '#/components/schemas/CustomItemListResponseSchema'
'400':
description: 'Bad Request response'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'401':
description: 'Unauthorized response'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'403':
description: 'Forbidden response'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'500':
description: 'Internal server error'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'read:item'
/item/v1/items:
post:
tags:
- Items
summary: 'Post one or more items to a reservation, house account, or group profile'
description: 'Adds items to a reservation, house account, or group profile. This endpoint supports batch operations, allowing multiple items to be posted in a single request. Each item can have associated payments and custom pricing.'
operationId: 'ItemController::createItems'
parameters:
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
requestBody:
description: 'Items to post with optional payment information'
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PostItemsRequestSchema'
responses:
'201':
description: 'Items successfully posted'
content:
application/json:
schema:
$ref: '#/components/schemas/PostItemsResponseSchema'
'400':
description: 'Bad request - invalid parameters or validation errors'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'403':
description: 'Forbidden - insufficient permissions'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'404':
description: 'Not found - reservation, house account, or group not found'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponseSchema'
'500':
description: 'Internal server error'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'write:item'
/market-segmentation/v1/groups:
get:
tags:
- 'Market Segmentation'
summary: 'Get a list of Market Segmentation Groups.'
operationId: 'GroupController::index'
parameters:
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
-
name: offset
in: query
description: 'The number of items to skip before starting to collect the result set. Used for pagination.'
required: false
schema:
type: integer
default: 0
minimum: 0
example: '0'
-
name: limit
in: query
description: 'The maximum number of items to return in the response. Default is 100.'
required: false
schema:
type: integer
default: 100
maximum: 500
minimum: 1
example: '100'
responses:
'200':
description: 'List of Market Segmentation Groups.'
content:
application/json:
schema:
$ref: '#/components/schemas/GroupListResponseSchema'
'400':
description: 'Bad request response.'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'403':
description: 'Forbidden response.'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'500':
description: 'Internal server error.'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'read:marketsegment'
post:
tags:
- 'Market Segmentation'
summary: 'Create a new Market Segmentation Group.'
operationId: 'GroupController::create'
parameters:
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
requestBody:
description: 'Group data.'
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GroupCreateRequestSchema'
responses:
'201':
description: 'Created Market Segmentation Group.'
content:
application/json:
schema:
$ref: '#/components/schemas/GroupResponseSchema'
'400':
description: 'Bad request response.'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'403':
description: 'Forbidden response.'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'404':
description: 'Not found response.'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponseSchema'
'500':
description: 'Internal server error.'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'write:marketsegment'
'/market-segmentation/v1/groups/{id}':
get:
tags:
- 'Market Segmentation'
summary: 'Get Market Segmentation Group data.'
operationId: 'GroupController::single'
parameters:
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
-
name: id
in: path
description: 'Group ID.'
required: true
schema:
$ref: '#/components/schemas/GroupSingleRequestSchema/properties/id'
responses:
'200':
description: 'Market Segmentation Group data.'
content:
application/json:
schema:
$ref: '#/components/schemas/GroupResponseSchema'
'400':
description: 'Bad request response.'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'403':
description: 'Forbidden response.'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'404':
description: 'Not Found response.'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponseSchema'
'500':
description: 'Internal Server Error.'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'read:marketsegment'
delete:
tags:
- 'Market Segmentation'
summary: 'Delete a Market Segmentation Group.'
operationId: 'GroupController::delete'
parameters:
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
-
name: id
in: path
description: 'Group ID.'
required: true
schema:
$ref: '#/components/schemas/GroupDeleteRequestSchema/properties/id'
responses:
'204':
description: 'Market Segmentation Group was deleted.'
content:
application/json:
schema:
$ref: '#/components/schemas/NoContentResponseSchema'
'400':
description: 'Bad request response.'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'403':
description: 'Forbidden response.'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'404':
description: 'Not found response.'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponseSchema'
'500':
description: 'Internal server error.'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'delete:marketsegment'
patch:
tags:
- 'Market Segmentation'
summary: 'Update a Market Segmentation Group.'
operationId: 'GroupController::update'
parameters:
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
-
name: id
in: path
description: 'Group ID.'
required: true
schema:
$ref: '#/components/schemas/GroupUpdateRequestSchema/properties/id'
requestBody:
description: 'Group data.'
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GroupUpdateRequestSchema'
responses:
'200':
description: 'Updated Market Segmentation Group.'
content:
application/json:
schema:
$ref: '#/components/schemas/GroupResponseSchema'
'400':
description: 'Bad request response.'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'403':
description: 'Forbidden response.'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'404':
description: 'Not found response.'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponseSchema'
'500':
description: 'Internal server error.'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'write:marketsegment'
'/market-segmentation/v1/groups/{id}/enable':
post:
tags:
- 'Market Segmentation'
summary: 'Enable a Market Segmentation Group.'
operationId: 'GroupController::enable'
parameters:
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
-
name: id
in: path
description: 'Group ID.'
required: true
schema:
$ref: '#/components/schemas/GroupEnableRequestSchema/properties/id'
responses:
'204':
description: 'Market Segmentation Group was enabled.'
content:
application/json:
schema:
$ref: '#/components/schemas/NoContentResponseSchema'
'400':
description: 'Bad request response.'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'403':
description: 'Forbidden response.'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'404':
description: 'Not found response.'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponseSchema'
'500':
description: 'Internal server error.'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'write:marketsegment'
'/market-segmentation/v1/groups/{id}/disable':
post:
tags:
- 'Market Segmentation'
summary: 'Disable a Market Segmentation Group.'
operationId: 'GroupController::disable'
parameters:
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
-
name: id
in: path
description: 'Group ID.'
required: true
schema:
$ref: '#/components/schemas/GroupDisableRequestSchema/properties/id'
responses:
'204':
description: 'Market Segmentation Group was disabled.'
content:
application/json:
schema:
$ref: '#/components/schemas/NoContentResponseSchema'
'400':
description: 'Bad request response.'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'403':
description: 'Forbidden response.'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'404':
description: 'Not found response.'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponseSchema'
'500':
description: 'Internal server error'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'write:marketsegment'
'/market-segmentation/v1/segments/{enabled}':
get:
tags:
- 'Market Segmentation'
summary: 'Get a list of Market Segmentation Segments.'
operationId: 'SegmentController::index'
parameters:
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
-
name: enabled
in: path
description: 'List only enabled segments.'
required: true
schema:
type: boolean
example: 'false'
-
name: offset
in: query
description: 'The number of items to skip before starting to collect the result set. Used for pagination.'
required: false
schema:
type: integer
default: 0
minimum: 0
example: '0'
-
name: limit
in: query
description: 'The maximum number of items to return in the response. Default is 100.'
required: false
schema:
type: integer
default: 100
maximum: 500
minimum: 1
example: '100'
-
name: filters
in: query
description: 'This parameter should be formatted as a list of strings separated by ; Use \; for a literal semicolon inside a value.'
required: false
schema:
$ref: '#/components/schemas/QueryParameterDynamicFilterSchema'
example: 'field1:value;field2:operator:value'
responses:
'200':
description: 'List of Market Segmentation Segments.'
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentListResponseSchema'
'400':
description: 'Bad request response.'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'403':
description: 'Forbidden response.'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'500':
description: 'Internal server error.'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'read:marketsegment'
'/market-segmentation/v1/segments/{id}':
get:
tags:
- 'Market Segmentation'
summary: 'Get Market Segmentation Segment data.'
operationId: 'SegmentController::single'
parameters:
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
-
name: id
in: path
description: 'Segment ID.'
required: true
schema:
$ref: '#/components/schemas/SegmentSingleRequestSchema/properties/id'
responses:
'200':
description: 'Market Segmentation Segment data.'
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentResponseSchema'
'400':
description: 'Bad request response.'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'403':
description: 'Forbidden response.'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'404':
description: 'Not Found response.'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponseSchema'
'500':
description: 'Internal Server Error.'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'read:marketsegment'
delete:
tags:
- 'Market Segmentation'
summary: 'Delete a Market Segmentation Segment.'
operationId: 'SegmentController::delete'
parameters:
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
-
name: id
in: path
description: 'Segment ID.'
required: true
schema:
$ref: '#/components/schemas/SegmentDeleteRequestSchema/properties/id'
responses:
'204':
description: 'Market Segmentation Segment was deleted.'
content:
application/json:
schema:
$ref: '#/components/schemas/NoContentResponseSchema'
'400':
description: 'Bad request response.'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'403':
description: 'Forbidden response.'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'404':
description: 'Not found response.'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponseSchema'
'500':
description: 'Internal server error.'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'delete:marketsegment'
patch:
tags:
- 'Market Segmentation'
summary: 'Update a Market Segmentation Segment.'
operationId: 'SegmentController::update'
parameters:
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
-
name: id
in: path
description: 'Segment ID.'
required: true
schema:
$ref: '#/components/schemas/SegmentUpdateRequestSchema/properties/id'
requestBody:
description: 'Segment data.'
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentUpdateRequestSchema'
responses:
'200':
description: 'Updated Market Segmentation Segment.'
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentResponseSchema'
'400':
description: 'Bad request response.'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'403':
description: 'Forbidden response.'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'404':
description: 'Not found response.'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponseSchema'
'500':
description: 'Internal server error.'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'write:marketsegment'
'/market-segmentation/v1/segments/{id}/reservations/{active}':
get:
tags:
- 'Market Segmentation'
summary: 'Get a list of reservations linked to a Market Segmentation Segment.'
operationId: 'SegmentController::reservations'
parameters:
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
-
name: id
in: path
description: 'Segment ID.'
required: true
schema:
type: string
example: 1-b
-
name: active
in: path
description: 'List only active reservations.'
required: true
schema:
type: boolean
example: 'false'
-
name: offset
in: query
description: 'The number of items to skip before starting to collect the result set. Used for pagination.'
required: false
schema:
type: integer
default: 0
minimum: 0
example: '0'
-
name: limit
in: query
description: 'The maximum number of items to return in the response. Default is 100.'
required: false
schema:
type: integer
default: 100
maximum: 500
minimum: 1
example: '100'
responses:
'200':
description: 'List of reservations linked to a Market Segmentation Segment.'
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentListReservationsResponseSchema'
'400':
description: 'Bad request response.'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'403':
description: 'Forbidden response.'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'500':
description: 'Internal server error.'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'read:marketsegment'
/market-segmentation/v1/segments:
post:
tags:
- 'Market Segmentation'
summary: 'Create a new Market Segmentation Segment.'
operationId: 'SegmentController::create'
parameters:
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
requestBody:
description: 'Segment data.'
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentCreateRequestSchema'
responses:
'201':
description: 'Created Market Segmentation Segment.'
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentResponseSchema'
'400':
description: 'Bad request response.'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'403':
description: 'Forbidden response.'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'404':
description: 'Not found response.'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponseSchema'
'500':
description: 'Internal server error.'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'write:marketsegment'
'/market-segmentation/v1/segments/{id}/enable':
post:
tags:
- 'Market Segmentation'
summary: 'Enable a Market Segmentation Segment.'
operationId: 'SegmentController::enable'
parameters:
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
-
name: id
in: path
description: 'Segment ID.'
required: true
schema:
$ref: '#/components/schemas/SegmentEnableRequestSchema/properties/id'
responses:
'204':
description: 'Market Segmentation Segment was enabled.'
content:
application/json:
schema:
$ref: '#/components/schemas/NoContentResponseSchema'
'400':
description: 'Bad request response.'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'403':
description: 'Forbidden response.'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'404':
description: 'Not found response.'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponseSchema'
'500':
description: 'Internal server error.'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'write:marketsegment'
'/market-segmentation/v1/segments/{id}/disable':
post:
tags:
- 'Market Segmentation'
summary: 'Disable a Market Segmentation Segment.'
operationId: 'SegmentController::disable'
parameters:
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
-
name: id
in: path
description: 'Segment ID.'
required: true
schema:
$ref: '#/components/schemas/SegmentDisableRequestSchema/properties/id'
responses:
'204':
description: 'Market Segmentation Segment was disabled.'
content:
application/json:
schema:
$ref: '#/components/schemas/NoContentResponseSchema'
'400':
description: 'Bad request response.'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'403':
description: 'Forbidden response.'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'404':
description: 'Not found response.'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponseSchema'
'500':
description: 'Internal server error'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'write:marketsegment'
'/market-segmentation/v1/segments/{id}/default':
post:
tags:
- 'Market Segmentation'
summary: 'Set Market Segmentation Segment as Default.'
operationId: 'SegmentController::default'
parameters:
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
-
name: id
in: path
description: 'Segment ID.'
required: true
schema:
$ref: '#/components/schemas/SegmentEnableRequestSchema/properties/id'
responses:
'204':
description: 'Market Segmentation Segment was set as default.'
content:
application/json:
schema:
$ref: '#/components/schemas/NoContentResponseSchema'
'400':
description: 'Bad request response.'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'403':
description: 'Forbidden response.'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'404':
description: 'Not found response.'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponseSchema'
'500':
description: 'Internal server error.'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'write:marketsegment'
/digital-marketing/v1/daily-performance:
get:
tags:
- 'Marketing Performance'
summary: 'Get daily Digital Marketing (Amplify) performance.'
description: 'Returns Digital Marketing (Amplify) performance per property, day and campaign type: impressions, clicks, spend, attributed reservations and revenue, for the properties named in the required x-property-id header. Covers every requested property or none: if the API key or app cannot access a requested property, the property''s account status does not allow API access, or the export is not enabled for it, the whole call fails with HTTP 403, listing the rejected property IDs when the denial can be attributed to specific properties. The token must carry the read:marketingPerformance scope, whatever other access it has: select "Read Digital Marketing performance (clicks, spend, bookings, revenue)" under Marketing Performance when creating the API key, or request the scope in the OAuth app. Up to 50 properties and 90 days per call, and 20 calls per minute per API client (HTTP 429 with a Retry-After header above that). JSON responses are paged with limit and offset over rows sorted by propertyId (as a number), date and campaignType in the order METASEARCH, METASEARCH_MANAGED, PMAX, PMAX_MANAGED, RETARGETING, OTA_TRAVEL_ADS; keep paging until a page has fewer than limit rows. Spend is converted from USD with the daily exchange rate of each row''s date, so for past dates it can differ from the Performance Dashboard cards, which use today''s rate. Rows of the last 14 days are PROVISIONAL. Accept: text/csv returns the same fields for the whole date range as one CSV document, not paged, with a header row naming each field, where spendUsd, spend and revenue are plain decimal amounts in major currency units (spendUsd in USD, spend and revenue in the currency named by currencyCode) and an omitted field is an empty cell; application/json or an omitted Accept returns JSON; anything else is answered with HTTP 406.'
operationId: 'MarketingPerformanceController::daily'
parameters:
-
name: x-property-id
in: header
description: 'Comma-separated IDs of the properties to export, at most 50. A missing or empty header is an HTTP 400, and so is a property ID sent in a query or body parameter alongside it.'
required: true
schema:
type: string
example: '123,456'
-
name: startDate
in: query
description: 'First date (YYYY-MM-DD, property-local).'
required: true
schema:
type: string
format: date
-
name: endDate
in: query
description: 'Last date (YYYY-MM-DD, property-local), at most 89 days after startDate.'
required: true
schema:
type: string
format: date
-
name: filters
in: query
description: 'Restricts the campaign types of the rows, with the field:operator:value syntax: campaignType:in:METASEARCH,RETARGETING or campaignType:equals:PMAX. Several ;-separated filters are ANDed, so campaignType:in:METASEARCH,PMAX;campaignType:equals:PMAX returns PMAX rows only. Campaign type values are case-sensitive. Defaults to every campaign type the property is subscribed to, plus any campaign type with activity in the date range (for example a product the property has since cancelled). Any other field or operator, or an unknown campaign type, is an HTTP 400.'
required: false
schema:
type: string
example: 'campaignType:in:METASEARCH,RETARGETING'
-
name: limit
in: query
description: 'The maximum number of rows to return in a JSON page. Default is 100, at most 1000. JSON only: sent with an Accept that resolves to CSV it is an HTTP 400.'
required: false
schema:
type: integer
default: 100
maximum: 1000
minimum: 1
example: '100'
-
name: offset
in: query
description: 'The number of rows to skip, in the propertyId, date, campaignType order, before collecting the page. Default is 0. An offset past the last row returns an empty data list. JSON only: sent with an Accept that resolves to CSV it is an HTTP 400.'
required: false
schema:
type: integer
default: 0
minimum: 0
example: '0'
-
name: includeTotal
in: query
description: 'Return total, the number of rows matching the request, ignoring limit and offset. Boolean values are accepted case-insensitively, so true, TRUE, True and 1 all enable it. JSON only: sent with an Accept that resolves to CSV it is an HTTP 400.'
required: false
schema:
type: boolean
default: false
example: true
responses:
'200':
description: 'Daily marketing performance rows.'
content:
text/csv:
schema:
description: 'The rows as a CSV document with a header row; money fields are plain decimals in major currency units.'
type: string
application/json:
schema:
$ref: '#/components/schemas/MarketingPerformanceResponseSchema'
'400':
description: 'Invalid query or header: a missing or empty x-property-id, bad or reversed dates, more than 90 days or 50 properties, a filter field, operator or value this endpoint does not support, an invalid limit, offset or includeTotal, or one of them sent for CSV.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/MarketingPerformanceErrorResponseSchema'
'401':
description: 'Missing, invalid or expired access token. The shared authentication layer answers this before the endpoint runs, so the body is application/json carrying message, not problem+json.'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'403':
description: 'The whole request is rejected: the token lacks read:marketingPerformance, or a requested property is not accessible, has an account status without API access, or does not have the export enabled. The body carries a code (MISSING_SCOPE, ACCESS_DENIED, PROPERTY_ACCOUNT_INACTIVE or EXPORT_NOT_ENABLED), plus rejectedPropertyIds when the denial can be attributed to specific properties. A partner app or any other client type without the scope is refused earlier, by the shared layer, with application/json and a body that carries only message.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/MarketingPerformanceErrorResponseSchema'
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'406':
description: 'The Accept header asks for a representation this endpoint does not produce.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/MarketingPerformanceErrorResponseSchema'
'429':
description: 'Rate limit exceeded: more than 20 calls per minute for the API client.'
headers:
Retry-After:
description: 'Seconds until the API client can call again.'
schema:
type: integer
content:
application/problem+json:
schema:
$ref: '#/components/schemas/MarketingPerformanceErrorResponseSchema'
'502':
description: 'The marketing data service failed or returned an invalid response; no partial data is returned.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/MarketingPerformanceErrorResponseSchema'
'500':
description: 'Unexpected server error. The shared exception handler answers it, so the body is application/json, not problem+json.'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'read:marketingPerformance'
/payments/v1/payments:
post:
tags:
- Payments
summary: 'Create a payment or authorization'
description: 'Creates a payment with the specified capture mode. Use ''auto'' for immediate charge, ''manual'' for authorization only.'
operationId: createPayment
parameters:
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
requestBody:
description: 'Payment creation request'
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePaymentRequestSchema'
responses:
'201':
description: 'Payment created successfully'
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePaymentResponseSchema'
'400':
description: 'Bad request - invalid parameters or validation errors'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'403':
description: 'Forbidden - insufficient permissions'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'404':
description: 'Not found - inventory object not found'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponseSchema'
'500':
description: 'Internal server error'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'write:payment'
/property/v1/system:
get:
tags:
- Property
summary: 'Retrieves the property''s system component versions'
operationId: 'SystemController::getSystem'
parameters:
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
responses:
'200':
description: 'Successfully retrieved property features'
content:
application/json:
schema:
$ref: '#/components/schemas/SystemResponseSchema'
'400':
description: 'Bad Request - Invalid input parameters or business rule violation'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'401':
description: 'Unauthorized - Invalid or missing authentication'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'403':
description: 'Forbidden - Insufficient permissions'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'404':
description: 'Not Found - Property not found'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponseSchema'
'500':
description: 'Internal Server Error'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'read:hotel'
/rates/v1/rate-plans:
get:
tags:
- 'Rate Plans'
summary: 'Get a list of Rates Plans.'
operationId: 'RatePlanController::index'
parameters:
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
-
name: offset
in: query
description: 'The number of items to skip before starting to collect the result set. Used for pagination.'
required: false
schema:
type: integer
default: 0
minimum: 0
example: '0'
-
name: limit
in: query
description: 'The maximum number of items to return in the response. Default is 100.'
required: false
schema:
type: integer
default: 100
maximum: 500
minimum: 1
example: '100'
-
name: filters
in: query
description: 'Filter the list. Each clause is written field:operator:value, and multiple clauses are separated by a semicolon (;) — not a comma, which the sort parameter uses. Clauses are combined with AND; grouping and OR are not supported here. Supported fields: isActive (equals), isDerived (equals), promoCode (contains), code (contains), category (equals, in), status (equals, in), policyId (equals, in), segmentId (equals, in), derivedRatePlanId (equals, in, is_null, is_not_null). A status filter takes one of active, expired, no-intervals, disabled; with `in`, several separated by a comma. It is applied before limit and offset, so a page and its total both describe the rate plans in those statuses. The in operator takes a comma-separated list of up to 100 IDs (policyId:in:1,2,3); is_null and is_not_null take no value (derivedRatePlanId:is_null). derivedRatePlanId takes 0 for the property base rate, alone or in a list (derivedRatePlanId:in:0,12), and 0 matches plans with no parent plan. derivedRatePlanId:is_null matches plans with no parent plan, which includes plans derived from the base rate; derivedRatePlanId:is_not_null matches plans whose parent is another rate plan. None of these checks isDerived, so add isDerived:equals:true to keep derived plans only. policyId, segmentId and derivedRatePlanId are filters only and cannot be sorted on.'
required: false
schema:
type: string
example: 'isActive:equals:true;status:in:active,expired;policyId:in:1,2;derivedRatePlanId:is_null'
-
name: sort
in: query
description: 'Sort the list. Supported fields: createdAt, updatedAt, isActive, code, category, status. Multiple fields are separated by a comma (,), and each may carry a direction written as field:asc or field:desc; a field given on its own sorts ascending. status sorts in the order active, expired, no-intervals, disabled (reversed for desc). category sorts alphabetically by its value. When omitted, the list is returned newest first (createdAt descending).'
required: false
schema:
type: string
example: 'createdAt:desc,updatedAt:asc'
-
name: includeTotal
in: query
description: 'Return the total number of items matching the request, ignoring limit and offset. Boolean values are accepted case-insensitively, so true, TRUE, True and 1 all enable it.'
required: false
schema:
type: boolean
default: false
example: true
responses:
'200':
description: 'List of Rates Plans.'
content:
application/json:
schema:
$ref: '#/components/schemas/RatePlanListResponseSchema'
'400':
description: 'Bad request response.'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'403':
description: 'Forbidden response.'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'500':
description: 'Internal server error.'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'read:rate'
post:
tags:
- 'Rate Plans'
summary: 'Create a new Rate Plan.'
operationId: 'RatePlanController::create'
parameters:
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
requestBody:
description: 'Rate Plan data.'
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RatePlanCreateRequestSchema'
responses:
'201':
description: 'Created Rate Plan.'
content:
application/json:
schema:
$ref: '#/components/schemas/RatePlanResponseSchema'
'400':
description: 'Bad request response.'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'403':
description: 'Forbidden response.'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'404':
description: 'Not found response.'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponseSchema'
'500':
description: 'Internal server error.'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'write:rate'
'/rates/v1/rate-plans/{id}':
get:
tags:
- 'Rate Plans'
summary: 'Get Rate Plan data.'
operationId: 'RatePlanController::single'
parameters:
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
-
name: id
in: path
description: 'Rate Plan ID.'
required: true
schema:
$ref: '#/components/schemas/RatePlanSingleRequestSchema/properties/id'
responses:
'200':
description: 'Rate Plan data.'
content:
application/json:
schema:
$ref: '#/components/schemas/RatePlanResponseSchema'
'400':
description: 'Bad request response.'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'403':
description: 'Forbidden response.'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'404':
description: 'Not Found response.'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponseSchema'
'500':
description: 'Internal Server Error.'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'read:rate'
delete:
tags:
- 'Rate Plans'
summary: 'Delete a Rate Plan.'
operationId: 'RatePlanController::delete'
parameters:
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
-
name: id
in: path
description: 'Rate Plan ID.'
required: true
schema:
$ref: '#/components/schemas/RatePlanDeleteRequestSchema/properties/id'
responses:
'204':
description: 'Rate Plan was deleted.'
content:
application/json:
schema:
$ref: '#/components/schemas/NoContentResponseSchema'
'400':
description: 'Bad request response.'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'403':
description: 'Forbidden response.'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'404':
description: 'Not found response.'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponseSchema'
'500':
description: 'Internal server error.'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'write:rate'
patch:
tags:
- 'Rate Plans'
summary: 'Update an existing Rate Plan.'
operationId: 'RatePlanController::update'
parameters:
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
-
name: id
in: path
description: 'Rate Plan ID.'
required: true
schema:
$ref: '#/components/schemas/RatePlanUpdateRequestSchema/properties/id'
requestBody:
description: 'Rate Plan data.'
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RatePlanUpdateRequestSchema'
responses:
'200':
description: 'Updated Rate Plan.'
content:
application/json:
schema:
$ref: '#/components/schemas/RatePlanResponseSchema'
'400':
description: 'Bad request response.'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'403':
description: 'Forbidden response.'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'404':
description: 'Not found response.'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponseSchema'
'500':
description: 'Internal server error.'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'write:rate'
/rates/v1/rate-plans/bulk-status:
post:
tags:
- 'Rate Plans'
summary: 'Activate or deactivate several Rate Plans in one request.'
description: 'Every id must belong to the property, otherwise the whole request is rejected. Rate plans already in the requested state are reported as `unchanged`. A rate plan cannot be deactivated while an allotment block uses it or a derived rate plan depends on it; those are reported as `blocked` with the reason. All activity-log entries written by the request share the returned `batchId`.'
operationId: 'RatePlanController::bulkStatus'
parameters:
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RatePlanBulkStatusRequestSchema'
responses:
'200':
description: 'Per-rate-plan outcomes.'
content:
application/json:
schema:
$ref: '#/components/schemas/RatePlanBulkResponseSchema'
'400':
description: 'Bad request response.'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'403':
description: 'Forbidden response.'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'500':
description: 'Internal server error.'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'write:rate'
'/smart-policies/v1/reservations/{reservationId}/policy-information':
get:
tags:
- 'Smart Policies'
summary: 'Get the rendered smart policy text and scheduled payments for a reservation.'
operationId: 'GetBookingPolicyInformationController::getBookingPolicyInformation'
parameters:
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
-
name: reservationId
in: path
description: 'Reservation identifier.'
required: true
schema:
$ref: '#/components/schemas/GetBookingPolicyInformationRequestSchema/properties/reservationId'
-
name: languageCode
in: query
description: 'Language code for the rendered policy text (e.g. "fr", "en-US"). Defaults to the property''s language when omitted.'
required: false
schema:
type: string
nullable: true
responses:
'200':
description: 'Policy information for the reservation. When the reservation is not governed by a smart policy, falls back to the property''s legacy cancellation policy text (policyTextSource="legacy"); when neither is available, returns a null policyText rather than an error.'
content:
application/json:
schema:
$ref: '#/components/schemas/BookingPolicyInformationResponseSchema'
'400':
description: 'Bad request response.'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'403':
description: 'The API client is not authorized for this property or lacks the required scope.'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'404':
description: 'No reservation with the given identifier exists for the requesting property.'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponseSchema'
'500':
description: 'Internal server error.'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'read:reservation'
/smart-policies/v1/exceptions/eligible-rates/search:
post:
tags:
- 'Smart Policy Exceptions'
summary: 'Search eligible rate plans and base rates with conflict info.'
operationId: 'PolicyExceptionController::eligibleRates'
parameters:
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
requestBody:
description: 'Search criteria for eligible rates with conflict detection.'
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EligibleRatesRequestSchema'
responses:
'200':
description: 'Eligible rate plans and base rates with conflict info.'
content:
application/json:
schema:
$ref: '#/components/schemas/EligibleRatesResponseSchema'
'400':
description: 'Bad request response.'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'403':
description: 'Forbidden response.'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'500':
description: 'Internal server error.'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'read:rate'
/smart-policies/v1/exceptions:
get:
tags:
- 'Smart Policy Exceptions'
summary: 'List all policy exceptions for a property.'
operationId: 'PolicyExceptionController::index'
parameters:
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
-
name: filters
in: query
description: 'This parameter should be formatted as a list of strings separated by ; Use \; for a literal semicolon inside a value.'
required: false
schema:
$ref: '#/components/schemas/QueryParameterDynamicFilterSchema'
example: 'field1:value;field2:operator:value'
-
name: limit
in: query
description: 'The maximum number of items to return in the response. Default is 100.'
required: false
schema:
type: integer
default: 100
maximum: 500
minimum: 1
example: '100'
-
name: offset
in: query
description: 'The number of items to skip before starting to collect the result set. Used for pagination.'
required: false
schema:
type: integer
default: 0
minimum: 0
example: '0'
-
name: sort
in: query
description: 'A string specifying fields for sorting with optional directions (e.g., asc or desc).'
required: false
schema:
$ref: '#/components/schemas/QueryParameterSortSchema'
example: 'checkin_date:desc;checkout_date'
responses:
'200':
description: 'List of policy exceptions.'
content:
application/json:
schema:
$ref: '#/components/schemas/PolicyExceptionListResponseSchema'
'400':
description: 'Bad request response.'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'403':
description: 'Forbidden response.'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'500':
description: 'Internal server error.'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'read:rate'
post:
tags:
- 'Smart Policy Exceptions'
summary: 'Create a new policy exception.'
operationId: 'PolicyExceptionController::create'
parameters:
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
requestBody:
description: 'Policy exception data.'
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePolicyExceptionRequestSchema'
responses:
'201':
description: 'Created policy exception.'
content:
application/json:
schema:
$ref: '#/components/schemas/PolicyExceptionResponseSchema'
'400':
description: 'Bad request response.'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'403':
description: 'Forbidden response.'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'409':
description: 'Conflict response (exception overlaps with existing exception).'
content:
application/json:
schema:
$ref: '#/components/schemas/ConflictResponseSchema'
'500':
description: 'Internal server error.'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'write:rate'
'/smart-policies/v1/exceptions/{exceptionId}':
get:
tags:
- 'Smart Policy Exceptions'
summary: 'Get a single policy exception by ID.'
operationId: 'PolicyExceptionController::show'
parameters:
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
-
name: exceptionId
in: path
description: 'Policy exception ID.'
required: true
schema:
$ref: '#/components/schemas/GetPolicyExceptionRequestSchema/properties/exceptionId'
responses:
'200':
description: 'Policy exception details.'
content:
application/json:
schema:
$ref: '#/components/schemas/PolicyExceptionResponseSchema'
'400':
description: 'Bad request response.'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'403':
description: 'Forbidden response.'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'404':
description: 'Not found response.'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponseSchema'
'500':
description: 'Internal server error.'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'read:rate'
put:
tags:
- 'Smart Policy Exceptions'
summary: 'Update an existing policy exception.'
operationId: 'PolicyExceptionController::update'
parameters:
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
-
name: exceptionId
in: path
description: 'Policy exception ID.'
required: true
schema:
$ref: '#/components/schemas/UpdatePolicyExceptionRequestSchema/properties/exceptionId'
requestBody:
description: 'Policy exception data.'
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdatePolicyExceptionRequestSchema'
responses:
'200':
description: 'Updated policy exception.'
content:
application/json:
schema:
$ref: '#/components/schemas/PolicyExceptionResponseSchema'
'400':
description: 'Bad request response.'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'403':
description: 'Forbidden response.'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'404':
description: 'Not found response.'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponseSchema'
'409':
description: 'Conflict response (exception overlaps with existing exception).'
content:
application/json:
schema:
$ref: '#/components/schemas/ConflictResponseSchema'
'500':
description: 'Internal server error.'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'write:rate'
delete:
tags:
- 'Smart Policy Exceptions'
summary: 'Delete a policy exception.'
operationId: 'PolicyExceptionController::destroy'
parameters:
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
-
name: exceptionId
in: path
description: 'Policy exception ID.'
required: true
schema:
$ref: '#/components/schemas/DeletePolicyExceptionRequestSchema/properties/exceptionId'
responses:
'204':
description: 'Policy exception was deleted.'
content:
application/json:
schema:
$ref: '#/components/schemas/NoContentResponseSchema'
'400':
description: 'Bad request response.'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'403':
description: 'Forbidden response.'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'404':
description: 'Not found response.'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponseSchema'
'500':
description: 'Internal server error.'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'write:rate'
patch:
tags:
- 'Smart Policy Exceptions'
summary: 'Partially update a policy exception.'
operationId: 'PolicyExceptionController::partialUpdate'
parameters:
-
name: x-property-id
in: header
description: 'A numeric, comma-separated string representing the property IDs, sent in the header.'
required: true
schema:
type: string
example: '1,2,3'
-
name: exceptionId
in: path
description: 'Policy exception ID.'
required: true
schema:
$ref: '#/components/schemas/PatchPolicyExceptionRequestSchema/properties/exceptionId'
requestBody:
description: 'Policy exception fields to update.'
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PatchPolicyExceptionRequestSchema'
responses:
'200':
description: 'Updated policy exception.'
content:
application/json:
schema:
$ref: '#/components/schemas/PolicyExceptionResponseSchema'
'400':
description: 'Bad request response.'
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseSchema'
'403':
description: 'Forbidden response.'
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseSchema'
'404':
description: 'Not found response.'
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponseSchema'
'409':
description: 'Conflict response (exception overlaps with existing exception).'
content:
application/json:
schema:
$ref: '#/components/schemas/ConflictResponseSchema'
'500':
description: 'Internal server error.'
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponseSchema'
security:
-
default:
- 'write:rate'
components:
schemas:
DeleteReservationAddonRequestSchema:
required:
- reservationId
- soldAddonId
properties:
reservationId:
description: 'The reservation ID, as returned by getReservation.'
type: string
example: '4207311534285'
soldAddonId:
description: 'The add-on''s soldProductID from reservationAddOnProducts in getReservation.'
type: string
example: '5002'
type: object
GetAddonsRequestSchema:
allOf:
-
$ref: '#/components/schemas/LimitOffsetPaginationSchema'
-
$ref: '#/components/schemas/QueryParameterDynamicFilterSchema'
AddonDayPriceResponseSchema:
required:
- dayOfWeek
- available
- adultPrice
- childPrice
- infantPrice
properties:
dayOfWeek:
description: 'Day of the week these prices apply to, from 0 (Sunday) to 6 (Saturday)'
type: integer
maximum: 6
minimum: 0
example: 1
available:
description: 'Whether the add-on can be sold on this day of the week within the interval'
type: boolean
example: true
adultPrice:
description: 'Price charged per adult. For charge types that are not per guest, this is the price of one unit, night, accommodation or reservation. Includes inclusive taxes and fees; exclusive taxes and fees are added on top. This is a unit price: booking rounds the add-on''s total with the property''s rounding rules, so a total computed from unit prices can differ by a few cents.'
type: object
allOf:
-
$ref: '#/components/schemas/MoneySchema'
childPrice:
description: 'Price charged per child. Charged only when the add-on''s `chargeForChildren` is true; otherwise children are not charged. Includes inclusive taxes and fees; exclusive taxes and fees are added on top. This is a unit price: booking rounds the add-on''s total with the property''s rounding rules, so a total computed from unit prices can differ by a few cents.'
type: object
allOf:
-
$ref: '#/components/schemas/MoneySchema'
infantPrice:
oneOf:
-
$ref: '#/components/schemas/MoneySchema'
nullable: true
description: 'Price charged per infant when the property''s Age Policy prices this add-on by age group. Charged only when the add-on''s `chargeForChildren` is true, the same setting that governs children. Null when the add-on is not priced by age group; infants are then not charged separately. Includes inclusive taxes and fees; exclusive taxes and fees are added on top. This is a unit price: booking rounds the add-on''s total with the property''s rounding rules, so a total computed from unit prices can differ by a few cents.'
type: object
AddonIntervalResponseSchema:
required:
- roomTypeId
- startDate
- endDate
- minNights
- maxNights
- days
properties:
roomTypeId:
description: 'Room type the interval''s prices apply to'
type: string
example: '123456'
startDate:
description: 'First date the interval applies to'
type: string
format: date
example: '2026-12-01'
endDate:
description: 'Last date the interval applies to, inclusive'
type: string
format: date
example: '2027-03-31'
minNights:
description: 'Shortest stay this interval applies to, counted as the reservation''s total nights (check-out minus check-in), not the nights that fall inside the interval. A shorter stay is not offered or charged this interval. Null when there is no minimum.'
type: integer
minimum: 1
example: 3
nullable: true
maxNights:
description: 'Longest stay this interval applies to, counted as the reservation''s total nights (check-out minus check-in), not the nights that fall inside the interval. A longer stay is not offered or charged this interval. Null when there is no maximum.'
type: integer
minimum: 1
example: 14
nullable: true
days:
description: 'Prices for each day of the week, Sunday first'
type: array
items:
$ref: '#/components/schemas/AddonDayPriceResponseSchema'
type: object
AddonResponseSchema:
required:
- id
- name
- description
- productId
- price
- chargeType
- chargeForChildren
- isFixedPrice
- intervals
properties:
id:
description: 'Unique identifier of the add-on'
type: string
example: '98765'
name:
description: 'Display name of the add-on, localized based on the Accept-Language header'
type: string
example: Breakfast
description:
description: 'Human-readable description, localized based on the Accept-Language header'
type: string
example: 'A basic continental breakfast...'
productId:
description: 'Identifier of the underlying product this add-on is based on'
type: string
example: '12345'
price:
description: 'Price of the underlying product this add-on is based on. This is not what the add-on charges on a reservation; see `chargeType` and `intervals` for that.'
type: object
allOf:
-
$ref: '#/components/schemas/MoneySchema'
availabilityWindow:
description: 'Dates a nightly add-on is charged for. `all` charges each stay night; `all_except_arrival` charges the day after each stay night, ending on the checkout date. Always `all` for charge types that are not nightly.'
type: string
enum:
- all
- all_except_arrival
example: all
chargeType:
description: 'How the add-on is charged on a reservation. `per_guest_per_night`: each charged guest, each night. `per_guest`: each charged guest, once. `per_accommodation_per_night`: each room, each night. `per_accommodation`: each room, once. `per_night`: once per night. `quantity`: per unit ordered. `per_reservation`: once per reservation. `n/a`: no charge type is set.'
type: string
enum:
- n/a
- per_guest_per_night
- per_guest
- per_accommodation_per_night
- per_accommodation
- per_night
- quantity
- per_reservation
example: per_guest_per_night
chargeForChildren:
description: 'Whether children and infants are charged for the add-on. When false, only adults are charged and `childPrice` and `infantPrice` do not apply.'
type: boolean
example: true
isFixedPrice:
description: 'Whether the add-on keeps its own price when it is included in a rate plan''s package. When false, booking rescales an included add-on''s price, together with the room''s, so that room plus included add-ons equal the package rate for each night.'
type: boolean
example: false
intervals:
description: 'Current and future date ranges the add-on is priced for, one entry per room type and date range, with the adult, child and infant price for each day of the week. These are the add-on''s own prices, before a rate plan''s package allocation: when the add-on is included in a package, booking can rescale them (see `isFixedPrice`) or include them at no charge. An interval applies to a reservation only when the stay''s total nights fit its `minNights` and `maxNights`. When two date ranges of the same room type overlap, which one applies to a shared date is not defined. Empty when the add-on has no current or future prices, or is not active.'
type: array
items:
$ref: '#/components/schemas/AddonIntervalResponseSchema'
type: object
AddonsResponseSchema:
required:
- offset
- limit
- data
properties:
offset:
description: 'Number of results to skip'
type: integer
example: 0
limit:
description: 'Maximum number of results to return'
type: integer
example: 100
data:
description: 'Contains the list of add-on details'
type: array
items:
$ref: '#/components/schemas/AddonResponseSchema'
type: object
AgePolicyCreateRequestSchema:
required:
- config
- extraGuestsConfig
- groups
properties:
config:
description: 'Configuration. A `single` policy holds only the adult group: child and infant groups sent with it are ignored. A `multiple` policy whose only group is the adult group is stored as `single`.'
type: string
enum:
- single
- multiple
example: single
extraGuestsConfig:
description: 'Extra guests configuration.'
type: string
enum:
- per_age_group
- per_each_guest
example: per_age_group
groups:
description: 'List of age groups. The adult group requires a minimum age. With a `multiple` config, child and infant groups must not overlap each other, and each must start and end below the adult minimum age.'
type: array
items:
required:
- groupType
- minAge
properties:
groupType:
description: 'Age group type. Must be one of the valid age group types.'
type: string
enum:
- child
- adult
- infant
minAge:
description: 'Minimum age for this age group.'
type: integer
maxAge:
description: 'Maximum age for this age group.'
type: integer
otaGroupFallback:
description: 'Whether this group is used for channels that do not accept granular age groups. Exactly one child or infant group must set it when the request contains one; adult groups cannot.'
type: boolean
type: object
example:
-
groupType: child
minAge: 0
maxAge: 17
otaGroupFallback: true
countsTowardBaseOccupancy:
description: 'Whether guests under this age policy count toward base occupancy.'
type: boolean
example: false
nullable: true
type: object
AgePolicyPatchRequestSchema:
required:
- id
- config
- extraGuestsConfig
properties:
id:
description: 'Age Policy ID.'
type: string
example: 1-b
config:
description: 'Configuration. Changing a `multiple` policy to `single` is rejected while it has a child or infant group; remove those groups with a PUT instead. `multiple` on a policy whose only group is the adult group is stored as `single`.'
type: string
enum:
- single
- multiple
example: single
nullable: true
extraGuestsConfig:
description: 'Extra guests configuration.'
type: string
enum:
- per_age_group
- per_each_guest
example: per_age_group
nullable: true
countsTowardBaseOccupancy:
description: 'Whether guests under this age policy count toward base occupancy.'
type: boolean
example: false
nullable: true
type: object
AgePolicyUpdateRequestSchema:
required:
- id
- config
- extraGuestsConfig
- groups
properties:
id:
description: 'Age Policy ID.'
type: string
example: 1-b
config:
description: 'Configuration. A `single` policy holds only the adult group: child and infant groups sent with it are ignored, and on an update the stored ones are removed. A `multiple` policy whose only group is the adult group is stored as `single`.'
type: string
enum:
- single
- multiple
example: single
extraGuestsConfig:
description: 'Extra guests configuration.'
type: string
enum:
- per_age_group
- per_each_guest
example: per_age_group
groups:
description: 'List of age groups. The adult group requires a minimum age. With a `multiple` config, child and infant groups must not overlap each other, and each must start and end below the adult minimum age. An update removes every stored group it does not list.'
type: array
items:
required:
- groupType
- minAge
properties:
id:
description: 'Age group ID.'
type: string
groupType:
description: 'Age group type. Must be one of the valid age group types.'
type: string
enum:
- child
- adult
- infant
minAge:
description: 'Minimum age for this age group.'
type: integer
maxAge:
description: 'Maximum age for this age group.'
type: integer
applyRateFromId:
description: 'Apply rate from age group ID.'
type: string
otaGroupFallback:
description: 'Whether this group is used for channels that do not accept granular age groups. Exactly one child or infant group must set it when the request contains one; adult groups cannot.'
type: boolean
type: object
example:
-
id: group-2
groupType: child
minAge: 0
maxAge: 17
applyRateFromId: group-1
otaGroupFallback: true
countsTowardBaseOccupancy:
description: 'Whether guests under this age policy count toward base occupancy.'
type: boolean
example: false
nullable: true
type: object
PricingCreateRequestSchema:
required:
- id
- pricing
properties:
id:
description: 'Rate ID.'
type: integer
pricing:
description: 'List of pricing items to create.'
type: array
items:
required:
- ageGroupId
- intervalId
- isExtraGuestsPricing
- days
properties:
ageGroupId:
description: 'Age group ID.'
type: integer
intervalId:
description: 'Rate interval ID.'
type: integer
isExtraGuestsPricing:
description: 'Whether this is extra guests pricing. Only the adult age group can have base pricing (false); child and infant age groups take extra guests pricing only, and a base pricing entry for one is ignored.'
type: boolean
extraGuestsType:
description: 'Extra guests pricing type.'
type: string
enum:
- per_age_group
- per_each_guest
nullable: true
guestNumber:
description: 'Guest number for per-guest pricing.'
type: integer
nullable: true
days:
type: array
items:
required: [dayOfWeek, priceAmount, priceCurrency]
properties: { dayOfWeek: { description: 'Day of week (0=Sunday, 6=Saturday).', type: integer }, priceAmount: { description: 'Price amount: a non-negative amount with at most 24 integer digits and 4 decimal places.', type: string, pattern: '^(\d{1,24})(?:\.(\d{1,4}))?$' }, priceCurrency: { description: 'ISO 4217 currency code.', type: string } }
type: object
type: object
type: object
PricingListRequestSchema:
required:
- rateIds
properties:
rateIds:
description: 'List of rate IDs to retrieve pricing for.'
type: array
items:
type: integer
example:
- 1
- 2
- 3
startDate:
description: 'Start date filter (YYYY-MM-DD).'
type: string
format: date
example: '2026-01-01'
nullable: true
endDate:
description: 'End date filter (YYYY-MM-DD).'
type: string
format: date
example: '2026-12-31'
nullable: true
type: object
PricingRateRequestSchema:
required:
- id
properties:
id:
description: 'Rate ID.'
type: integer
type: object
AgeGroupResponseSchema:
required:
- id
- groupType
- minAge
- createdAt
- otaGroupFallback
properties:
id:
type: string
groupType:
type: string
minAge:
type: integer
maxAge:
type: integer
nullable: true
createdAt:
type: string
format: 'Y-m-d\TH:i:sP'
updatedAt:
type: string
format: 'Y-m-d\TH:i:sP'
nullable: true
otaGroupFallback:
description: 'Whether this group is used for channels that do not accept granular age groups.'
type: boolean
type: object
AgePolicyResponseSchema:
required:
- id
- config
- extraGuestsConfig
- createdAt
properties:
id:
type: string
config:
type: string
extraGuestsConfig:
type: string
countsTowardBaseOccupancy:
description: 'Whether guests under this age policy count toward base occupancy.'
type: boolean
groups:
type: array
items:
$ref: '#/components/schemas/AgeGroupResponseSchema'
nullable: true
createdAt:
type: string
format: 'Y-m-d\TH:i:sP'
updatedAt:
type: string
format: 'Y-m-d\TH:i:sP'
nullable: true
type: object
PricingCollectionResponseSchema:
properties:
items:
type: array
items:
$ref: '#/components/schemas/PricingResponseSchema'
type: object
PricingDayResponseSchema:
required:
- id
- dayOfWeek
- priceAmount
- priceCurrency
properties:
id:
description: 'Pricing day ID.'
type: string
dayOfWeek:
description: 'Day of week (0=Sunday, 6=Saturday).'
type: integer
priceAmount:
description: 'Price amount, with at least two decimal places and up to four — a price finer than cents keeps the decimals it needs, so do not parse this as a fixed-width two-decimal string.'
type: string
priceCurrency:
description: 'ISO 4217 currency code.'
type: string
type: object
PricingResponseSchema:
required:
- id
- ageGroupId
- rateIntervalId
- isExtraGuestsPricing
- days
properties:
id:
description: 'Pricing ID.'
type: string
ageGroupId:
description: 'Age group ID.'
type: string
rateIntervalId:
description: 'Rate interval ID.'
type: string
isExtraGuestsPricing:
description: 'Whether this is extra guests pricing.'
type: boolean
extraGuestsType:
description: 'Extra guests pricing type.'
type: string
nullable: true
extraGuestsNumber:
description: 'Guest number for per-guest pricing.'
type: integer
nullable: true
days:
description: 'Day pricing data.'
type: array
items:
$ref: '#/components/schemas/PricingDayResponseSchema'
type: object
AiAvailabilityRequestSchema:
description: 'Query string of the AI availability search. Dates are ISO-8601 calendar dates (YYYY-MM-DD) and the departure day is not charged.'
required:
- propertyCode
- checkIn
- checkOut
type: object
allOf:
-
$ref: '#/components/schemas/QueryParameterDynamicFilterSchema'
-
properties:
propertyCode:
description: 'Opaque alphanumeric property short code, as published in the `@id` URL returned by the property metadata endpoint.'
type: string
maxLength: 50
example: N2FKyS
checkIn:
description: 'Arrival date in YYYY-MM-DD format. Today or later in the property''s time zone.'
type: string
format: date
example: '2026-05-01'
checkOut:
description: 'Departure date in YYYY-MM-DD format. Exclusive: the departure day is not charged. Must fall after checkIn, at most 730 nights later.'
type: string
format: date
example: '2026-05-04'
adults:
description: 'Number of adults. Omitted, the offer is priced at the base occupancy of each room type.'
type: integer
maximum: 20
minimum: 1
example: 2
children:
description: 'Number of children. Omitted, the offer is priced without children.'
type: integer
maximum: 10
minimum: 0
example: 0
currencyCode:
description: 'ISO 4217 code to price the response in. Omitted, prices are returned in the property''s own currency.'
type: string
maxLength: 3
minLength: 3
example: EUR
lang:
description: 'Preferred language. A hint, not a filter: translatable fields always carry the property''s default language and English, and add this language when a translation exists.'
type: string
example: pt-BR
ratePlans:
description: 'Which rate plans each room type offers. `cheapest` (the default) returns one priced offer per room type; `all` also lists every other rate plan, in-stock ones cheapest first, then any sold out, without a price. Price a listed plan by asking for it with the `rateId` filter.'
type: string
enum:
- cheapest
- all
example: all
type: object
AiAvailabilityErrorResponseSchema:
description: 'An error, in the same schema.org vocabulary as a successful response, carrying the standard `code` and per-field `errors` alongside.'
required:
- '@context'
- '@type'
- name
- description
- statusCode
- code
- errors
properties:
'@context':
description: 'JSON-LD vocabulary the document is expressed in.'
type: string
example: 'https://schema.org'
'@type':
type: string
example: Error
name:
description: 'Stable token an agent can branch on.'
type: string
enum:
- InvalidRequest
- Forbidden
- NotFound
- MethodNotAllowed
- RateLimitExceeded
- InternalError
- ServiceUnavailable
- HttpError
description:
description: 'Human-readable detail.'
type: string
example: 'checkIn must be today or later'
statusCode:
type: integer
example: 400
code:
description: 'Upper-case machine code, as on every Public API error.'
type: string
example: INVALID_REQUEST
errors:
description: 'The offending fields, one entry per violation. Empty when the error is not about a field.'
type: array
items:
required:
- field
- message
properties:
field:
type: string
example: checkIn
message:
type: string
example: 'checkIn must be today or later'
type: object
type: object
AiAvailabilityResponseSchema:
description: 'A schema.org `LodgingBusiness` whose `containsPlace` lists every room type that can host the stay, each with an `Offer` per rate plan: the cheapest one, tax-inclusive, plus the other plans unpriced when `ratePlans=all`, or exactly the plans a `rateId` filter names, each priced. Room types with no unit left are omitted rather than marked out of stock. Money is expressed as schema.org `price` (a decimal number) plus `priceCurrency`, not as the Public API minor-unit `amount` object: the document has to validate against the vocabulary AI agents already parse. Decimal places follow the currency (JPY 0, USD 2, BHD 3).'
required:
- '@context'
- '@type'
- '@id'
- name
- availabilitySearch
- containsPlace
properties:
'@context':
description: 'JSON-LD vocabulary the document is expressed in.'
type: string
example: 'https://schema.org'
'@type':
type: string
example: LodgingBusiness
'@id':
description: 'Same URL the property metadata endpoint publishes for the property.'
type: string
format: uri
example: 'https://hotels.cloudbeds.com/reservation/N2FKyS'
name:
type: string
example: 'Seaside Hotel'
availabilitySearch:
description: 'The search as it was answered, with defaults filled in.'
required:
- propertyCode
- checkIn
- checkOut
- nights
- adults
- children
- currencyCode
properties:
propertyCode:
type: string
example: N2FKyS
checkIn:
type: string
format: date
example: '2026-05-01'
checkOut:
type: string
format: date
example: '2026-05-04'
nights:
type: integer
example: 3
adults:
description: 'Null when the request left it out and each offer is priced at its room type''s base occupancy.'
type: integer
example: 2
nullable: true
children:
type: integer
example: 0
currencyCode:
type: string
example: USD
type: object
containsPlace:
type: array
items:
$ref: '#/components/schemas/AiAvailabilityHotelRoomSchema'
type: object
AiAvailabilityHotelRoomSchema:
required:
- '@type'
- '@id'
- name
- occupancy
- offers
- additionalProperty
properties:
'@type':
type: string
example: HotelRoom
'@id':
description: 'Booking-engine URL of the room type, keyed by `roomId`.'
type: string
format: uri
example: 'https://hotels.cloudbeds.com/reservation/N2FKyS?roomId=101'
name:
description: 'Language-tagged values: always the property''s default language and English, plus the requested `lang` when a translation exists.'
type: array
items:
required:
- '@value'
- '@language'
properties:
'@value':
type: string
example: 'King Suite'
'@language':
type: string
example: en
type: object
occupancy:
required:
- '@type'
- maxValue
properties:
'@type':
type: string
example: QuantitativeValue
maxValue:
type: integer
example: 2
type: object
offers:
type: array
items:
$ref: '#/components/schemas/AiAvailabilityOfferSchema'
additionalProperty:
description: '`unitsAvailable` (integer) and `policyId` (string, or null when the room type has no policy). Identifiers are strings; only counts and amounts are numbers.'
type: array
items:
required:
- '@type'
- name
- value
properties:
'@type':
type: string
example: PropertyValue
name:
type: string
enum:
- unitsAvailable
- policyId
value:
example: '42'
nullable: true
oneOf:
- { type: integer }
- { type: string }
type: object
type: object
AiAvailabilityOfferSchema:
required:
- '@type'
- identifier
- name
- availability
- inventoryLevel
- priceSpecification
- validFrom
- validThrough
- url
properties:
'@type':
type: string
example: Offer
identifier:
description: 'The rate plan. Pass it as `rate_id` in the Booking Engine `cart` to book exactly this rate plan.'
type: string
example: '987'
name:
description: 'Guest-facing rate plan name; null for the room type''s base rate.'
type: string
example: 'Breakfast included'
nullable: true
availability:
type: string
enum:
- 'https://schema.org/InStock'
- 'https://schema.org/OutOfStock'
inventoryLevel:
description: 'Units of this rate plan bookable for the stay. A cart may ask for at most this many.'
required:
- '@type'
- value
properties:
'@type':
type: string
example: QuantitativeValue
value:
type: integer
example: 3
type: object
priceSpecification:
description: 'Tax-inclusive total for the whole stay, itemized in `priceComponent`. Components always sum to `price`. Null for a rate plan `ratePlans=all` lists without pricing it; ask for it with the `rateId` filter to get its price.'
required:
- '@type'
- price
- priceCurrency
- unitText
- referenceQuantity
- priceComponent
properties:
'@type':
type: string
example: CompoundPriceSpecification
price:
type: number
example: 660
priceCurrency:
type: string
example: USD
unitText:
type: string
example: 'total stay (tax-inclusive)'
referenceQuantity:
required:
- '@type'
- value
- unitCode
properties:
'@type':
type: string
example: QuantitativeValue
value:
description: Nights.
type: integer
example: 3
unitCode:
type: string
example: NIG
type: object
priceComponent:
type: array
items:
required:
- '@type'
- name
- price
- priceCurrency
properties:
'@type': { type: string, example: UnitPriceSpecification }
name: { type: string, example: 'City tax' }
price: { type: number, example: 60 }
priceCurrency: { type: string, example: USD }
priceComponentType: { description: 'Absent on the base rate.', type: string, enum: [GenericTax, ResortFee, ServiceFee] }
type: object
type: object
nullable: true
validFrom:
type: string
format: date
example: '2026-05-01'
validThrough:
type: string
format: date
example: '2026-05-04'
url:
description: 'Deep link into the booking engine with the stay pre-filled.'
type: string
format: uri
potentialAction:
description: 'Present only while the offer is InStock: a Booking Engine link whose cart already holds one unit of this rate plan. Fill `{ai_source}` with the agent''s name.'
properties:
'@type':
type: string
example: ReserveAction
target:
properties:
'@type':
type: string
example: EntryPoint
urlTemplate:
type: string
type: object
type: object
type: object
AllotmentBlockAutoReleaseScheduleCreateRequestSchema:
required:
- releaseDate
- allotmentBlockId
- roomTypeId
- startDate
- endDate
- releaseValueType
- releaseValue
properties:
releaseDate:
type: string
example: '2025-01-01'
allotmentBlockId:
type: string
example: '10'
roomTypeId:
type: string
example: '5'
startDate:
type: string
example: '2025-01-01'
endDate:
type: string
example: '2025-01-07'
releaseValueType:
type: string
example: quantity
releaseValue:
type: integer
example: 5
releaseUnits:
type: string
example: '1,2,3'
nullable: true
type: object
AllotmentBlockAutoReleaseScheduleDeleteRequestSchema:
required:
- id
properties:
id:
type: string
example: '123'
allotmentBlockId:
type: string
example: '10'
type: object
AllotmentBlockAutoReleaseScheduleListRequestSchema:
required:
- allotmentBlockId
properties:
allotmentBlockId:
type: string
example: '10'
roomTypeIds:
description: 'Filter by room type IDs. Comma-separated list of room type IDs. Values passed as strings to avoid precision loss'
type: string
example: '5,6'
nullable: true
releaseDate:
description: 'Filter by schedule release date. Use single date (2025-01-01) or range (2025-01-01..2025-01-31)'
type: string
example: 2025-01-01..2025-01-31
nullable: true
startDate:
description: 'Filter by schedule start date. Use single date (2025-01-01) or range (2025-01-01..2025-01-31)'
type: string
example: 2025-01-01..2025-01-31
nullable: true
endDate:
description: 'Filter by schedule end date. Use single date (2025-01-01) or range (2025-01-01..2025-01-31)'
type: string
example: 2025-01-01..2025-01-31
nullable: true
type: object
AllotmentBlockAutoReleaseScheduleUpdateRequestSchema:
required:
- id
properties:
id:
type: string
example: '123'
releaseDate:
type: string
example: '2025-01-01'
nullable: true
allotmentBlockId:
type: string
example: '10'
nullable: true
roomTypeId:
type: string
example: '5'
nullable: true
startDate:
type: string
example: '2025-01-01'
nullable: true
endDate:
type: string
example: '2025-01-07'
nullable: true
releaseValueType:
type: string
example: quantity
nullable: true
releaseValue:
type: integer
example: 5
nullable: true
releaseUnits:
type: string
example: '1,2,3'
nullable: true
type: object
AllotmentBlockAutoReleaseScheduleBulkCreateItemSchema:
required:
- releaseDate
- roomTypeId
- startDate
- endDate
- releaseValueType
- releaseValue
properties:
releaseDate:
type: string
example: '2025-01-01'
roomTypeId:
type: string
example: '5'
startDate:
type: string
example: '2025-01-01'
endDate:
type: string
example: '2025-01-07'
releaseValueType:
type: string
example: quantity
releaseValue:
type: integer
example: 5
releaseUnits:
type: string
example: '1,2,3'
nullable: true
type: object
AllotmentBlockAutoReleaseScheduleBulkCreateRequestSchema:
required:
- allotmentBlockId
- items
properties:
allotmentBlockId:
type: string
example: '10'
items:
type: array
items:
$ref: '#/components/schemas/AllotmentBlockAutoReleaseScheduleBulkCreateItemSchema'
type: object
AllotmentBlockAutoReleaseScheduleBulkSyncItemSchema:
required:
- releaseDate
- roomTypeId
- startDate
- endDate
- releaseValueType
- releaseValue
properties:
id:
type: string
example: '123'
nullable: true
releaseDate:
description: 'Release date and time in Y-m-d H:i:s format'
type: string
example: '2025-01-01 14:00:00'
roomTypeId:
type: string
example: '5'
startDate:
type: string
example: '2025-01-01'
endDate:
type: string
example: '2025-01-07'
releaseValueType:
type: string
example: quantity
releaseValue:
type: integer
example: 5
releaseUnits:
type: string
example: '1,2,3'
nullable: true
type: object
AllotmentBlockAutoReleaseScheduleBulkSyncRequestSchema:
required:
- allotmentBlockId
- items
properties:
allotmentBlockId:
type: string
example: '10'
items:
type: array
items:
$ref: '#/components/schemas/AllotmentBlockAutoReleaseScheduleBulkSyncItemSchema'
type: object
AllotmentBlockAutoReleaseScheduleBulkUpdateItemSchema:
required:
- id
properties:
id:
type: string
example: '123'
releaseDate:
type: string
example: '2025-01-01'
nullable: true
allotmentBlockId:
type: string
example: '10'
nullable: true
roomTypeId:
type: string
example: '5'
nullable: true
startDate:
type: string
example: '2025-01-01'
nullable: true
endDate:
type: string
example: '2025-01-07'
nullable: true
releaseValueType:
type: string
example: quantity
nullable: true
releaseValue:
type: integer
example: 5
nullable: true
releaseUnits:
type: string
example: '1,2,3'
nullable: true
type: object
AllotmentBlockAutoReleaseScheduleBulkUpdateRequestSchema:
required:
- allotmentBlockId
- items
properties:
allotmentBlockId:
type: string
example: '10'
items:
type: array
items:
$ref: '#/components/schemas/AllotmentBlockAutoReleaseScheduleBulkUpdateItemSchema'
type: object
AllotmentBlockReleaseCreateRequestSchema:
required:
- allotmentBlockId
- roomTypeId
- startDate
- endDate
- releasedQuantity
properties:
allotmentBlockId:
type: string
example: '10'
roomTypeId:
type: string
example: '5'
startDate:
type: string
example: '2025-01-01'
endDate:
type: string
example: '2025-01-07'
releasedQuantity:
type: integer
example: 3
releasedUnits:
type: string
example: '1,2,3'
nullable: true
type: object
AllotmentBlockReleaseDeleteRequestSchema:
required:
- id
properties:
id:
type: string
example: '123'
allotmentBlockId:
type: string
example: '10'
type: object
AllotmentBlockReleaseListRequestSchema:
properties:
roomTypeIds:
description: 'Filter by room type IDs. Comma-separated list of room type IDs. Values passed as strings to avoid precision loss'
type: string
example: '657822,657825'
nullable: true
releaseDate:
description: 'Filter by release date. Use single date (2025-01-01) or range (2025-01-01..2025-01-31)'
type: string
example: 2025-01-01..2025-01-31
nullable: true
startDate:
description: 'Filter by schedule start date. Use single date (2025-01-01) or range (2025-01-01..2025-01-31)'
type: string
example: 2025-01-01..2025-01-31
nullable: true
endDate:
description: 'Filter by schedule end date. Use single date (2025-01-01) or range (2025-01-01..2025-01-31)'
type: string
example: 2025-01-01..2025-01-31
nullable: true
type: object
AllotmentBlockReleaseUpdateRequestSchema:
required:
- id
properties:
id:
type: string
example: '123'
allotmentBlockId:
type: string
example: '10'
nullable: true
roomTypeId:
type: string
example: '5'
nullable: true
startDate:
type: string
example: '2025-01-01'
nullable: true
endDate:
type: string
example: '2025-01-07'
nullable: true
releasedQuantity:
type: integer
example: 3
nullable: true
releasedUnits:
type: string
example: '1,2,3'
nullable: true
type: object
AllotmentBlockReleaseBulkCreateItemSchema:
required:
- roomTypeId
- startDate
- endDate
- releasedQuantity
properties:
roomTypeId:
type: string
example: '5'
startDate:
type: string
example: '2025-01-01'
endDate:
type: string
example: '2025-01-07'
releasedQuantity:
type: integer
example: 3
releasedUnits:
type: string
example: '1,2,3'
nullable: true
type: object
AllotmentBlockReleaseBulkCreateRequestSchema:
required:
- allotmentBlockId
- items
properties:
allotmentBlockId:
type: string
example: '10'
items:
type: array
items:
$ref: '#/components/schemas/AllotmentBlockReleaseBulkCreateItemSchema'
type: object
AllotmentBlockReleaseBulkUpdateItemSchema:
required:
- id
properties:
id:
type: string
example: '123'
allotmentBlockId:
type: string
example: '10'
nullable: true
roomTypeId:
type: string
example: '5'
nullable: true
startDate:
type: string
example: '2025-01-01'
nullable: true
endDate:
type: string
example: '2025-01-07'
nullable: true
releasedQuantity:
type: integer
example: 3
nullable: true
releasedUnits:
type: string
example: '1,2,3'
nullable: true
type: object
AllotmentBlockReleaseBulkUpdateRequestSchema:
required:
- allotmentBlockId
- items
properties:
allotmentBlockId:
type: string
example: '10'
items:
type: array
items:
$ref: '#/components/schemas/AllotmentBlockReleaseBulkUpdateItemSchema'
type: object
AllotmentBlockAutoReleaseScheduleBulkResponseSchema:
required:
- data
properties:
data:
type: array
items:
$ref: '#/components/schemas/AllotmentBlockAutoReleaseScheduleResponseSchema'
type: object
AllotmentBlockAutoReleaseScheduleListResponseSchema:
required:
- data
properties:
data:
type: array
items:
$ref: '#/components/schemas/AllotmentBlockAutoReleaseScheduleResponseSchema'
type: object
AllotmentBlockAutoReleaseScheduleResponseSchema:
required:
- id
- propertyId
- releaseDate
- allotmentBlockId
- roomTypeId
- startDate
- endDate
- releaseValueType
- releaseValue
- releaseUnits
- appliedAt
properties:
id:
type: string
example: '123'
propertyId:
type: string
example: '1'
releaseDate:
type: string
example: '2025-01-01'
allotmentBlockId:
type: string
example: '10'
roomTypeId:
type: string
example: '5'
startDate:
type: string
example: '2025-01-01'
endDate:
type: string
example: '2025-01-07'
releaseValueType:
type: string
example: quantity
releaseValue:
type: integer
example: 5
releaseUnits:
type: string
example: '1,2,3'
nullable: true
appliedAt:
type: string
format: date-time
nullable: true
createdAt:
type: string
format: date-time
nullable: true
updatedAt:
type: string
format: date-time
nullable: true
type: object
AllotmentBlockReleaseBulkResponseSchema:
required:
- data
properties:
data:
type: array
items:
$ref: '#/components/schemas/AllotmentBlockReleaseResponseSchema'
type: object
AllotmentBlockReleaseListResponseSchema:
required:
- data
properties:
data:
type: array
items:
$ref: '#/components/schemas/AllotmentBlockReleaseResponseSchema'
type: object
AllotmentBlockReleaseResponseSchema:
required:
- id
- propertyId
- allotmentBlockId
- roomTypeId
- startDate
- endDate
- releasedQuantity
- releasedUnits
properties:
id:
type: string
example: '123'
propertyId:
type: string
example: '1'
allotmentBlockId:
type: string
example: '10'
roomTypeId:
type: string
example: '5'
startDate:
type: string
example: '2025-01-01'
endDate:
type: string
example: '2025-01-07'
releasedQuantity:
type: integer
example: 3
releasedUnits:
type: string
example: '1,2,3'
nullable: true
createdAt:
type: string
format: date-time
nullable: true
updatedAt:
type: string
format: date-time
nullable: true
type: object
DeleteRoomCustomAmenitiesRequestSchema:
properties:
customAmenities:
description: 'List of custom room amenities to remove from the room'
type: array
items:
type: string
example: 'in-room hammocks'
type: object
GetAmenityCatalogRequestSchema: { }
GetAmenityCategoryCatalogRequestSchema: { }
GetPropertyAmenitiesRequestSchema: { }
GetPropertyRoomsAmenitiesRequestSchema: { }
GetRoomAmenitiesRequestSchema: { }
RoomAmenitiesUpdateRequestSchema:
required:
- id
- amenities
properties:
id:
description: 'Room ID to update'
type: string
example: '101'
amenities:
description: 'List of amenity codes to set for the room (full replace)'
type: array
items:
type: string
example: wifi
type: object
UpdatePropertyAmenitiesRequestSchema:
properties:
amenities:
description: 'List of amenity codes to set for the property'
type: array
items:
type: string
example: wifi
type: object
UpdatePropertyRoomsAmenitiesRequestSchema:
required:
- rooms
properties:
rooms:
description: 'List of rooms with amenities to update'
type: array
items:
$ref: '#/components/schemas/RoomAmenitiesUpdateRequestSchema'
type: object
UpdateRoomAmenitiesRequestSchema:
properties:
amenities:
description: 'List of amenity codes to set for the room'
type: array
items:
type: string
example: wifi
type: object
AmenityItemSchema:
required:
- code
- name
- categoryCode
- isTop
properties:
code:
description: 'Unique amenity code'
type: string
example: wifi
name:
description: 'Translated amenity name'
type: string
example: Wi-fi
categoryCode:
description: 'Category code'
type: string
example: technology
isTop:
description: 'Whether this is a top amenity'
type: boolean
example: true
type: object
GetAmenityCatalogResponseSchema:
required:
- amenities
properties:
amenities:
description: 'List of amenities in the catalog'
type: array
items:
$ref: '#/components/schemas/AmenityItemSchema'
type: object
GetAmenityCategoryCatalogResponseSchema:
required:
- categories
properties:
categories:
description: 'List of amenity categories in the catalog'
type: array
items:
required:
- code
- name
properties:
code:
description: 'Unique category code'
type: string
example: technology
name:
description: 'Translated category name'
type: string
example: Technology
type: object
type: object
GetPropertyAmenitiesResponseSchema:
required:
- amenities
- customAmenities
properties:
amenities:
description: 'List of active property amenities'
type: array
items:
$ref: '#/components/schemas/AmenityItemSchema'
customAmenities:
description: 'List of custom property amenities'
type: array
items:
type: string
type: object
GetPropertyRoomsAmenitiesResponseSchema:
required:
- rooms
properties:
rooms:
description: 'List of rooms with their amenities'
type: array
items:
$ref: '#/components/schemas/RoomAmenitiesSchema'
type: object
GetRoomAmenitiesResponseSchema:
required:
- amenities
- customAmenities
properties:
amenities:
description: 'List of active room amenities'
type: array
items:
$ref: '#/components/schemas/AmenityItemSchema'
customAmenities:
description: 'List of custom room amenities'
type: array
items:
type: string
type: object
RoomAmenitiesSchema:
required:
- id
- amenities
- customAmenities
properties:
id:
description: 'Room ID'
type: string
example: '101'
amenities:
description: 'List of active amenities for this room'
type: array
items:
$ref: '#/components/schemas/AmenityItemSchema'
customAmenities:
description: 'List of custom amenities for this room'
type: array
items:
type: string
type: object
RoomAmenitiesUpdateSchema:
required:
- id
- amenities
properties:
id:
description: 'Room ID'
type: string
example: '101'
amenities:
description: 'List of active amenities for this room'
type: array
items:
$ref: '#/components/schemas/AmenityItemSchema'
type: object
RoomCustomAmenitiesResponseSchema:
required:
- customAmenities
properties:
customAmenities:
description: 'List of custom room amenities'
type: array
items:
type: string
type: object
UpdatePropertyAmenitiesResponseSchema:
required:
- amenities
properties:
amenities:
description: 'Updated list of property amenities'
type: array
items:
$ref: '#/components/schemas/AmenityItemSchema'
type: object
UpdatePropertyRoomsAmenitiesResponseSchema:
required:
- rooms
properties:
rooms:
description: 'Updated rooms with their amenities'
type: array
items:
$ref: '#/components/schemas/RoomAmenitiesUpdateSchema'
type: object
UpdateRoomAmenitiesResponseSchema:
required:
- amenities
properties:
amenities:
description: 'Updated list of room amenities'
type: array
items:
$ref: '#/components/schemas/AmenityItemSchema'
type: object
ConnectedApplicationListRequestSchema:
type: object
ApplicationCollectionResponseSchema:
required:
- items
type: array
items:
$ref: '#/components/schemas/ApplicationResponseSchema'
ApplicationListResponseSchema:
required:
- data
properties:
data:
$ref: '#/components/schemas/ApplicationCollectionResponseSchema'
type: object
ApplicationResponseSchema:
required:
- id
- name
- oauthScopes
- applicationTypes
properties:
id:
description: 'Application ID'
type: string
example: app_123456
name:
description: 'Application name'
type: string
example: 'Example PMS Application'
oauthScopes:
description: 'OAuth scopes'
type: array
items:
type: string
example:
- reservation.read
- reservation.write
applicationTypes:
description: 'Application types'
type: array
items:
type: string
example:
- 'Mobile App'
- Accounting
type: object
AmountsForSaleListRequestSchema:
required:
- roomTypeId
- startDate
- endDate
properties:
roomTypeId:
description: 'Room Type ID.'
type: integer
example: 12345
startDate:
description: 'Start date (YYYY-MM-DD).'
type: string
pattern: '^\d{4}-\d{2}-\d{2}$'
example: '2030-01-01'
endDate:
description: 'End date (YYYY-MM-DD), inclusive.'
type: string
pattern: '^\d{4}-\d{2}-\d{2}$'
example: '2030-01-31'
type: object
AmountsForSalePatchRequestSchema:
required:
- availability
properties:
availability:
description: 'Availability adjustments per room type.'
type: array
items:
$ref: '#/components/schemas/AvailabilityUpdatePatchRequestSchema'
testRequest:
description: 'Mark as test request (honored in non-production only).'
type: boolean
example: false
type: object
AmountsForSalePutRequestSchema:
required:
- availability
properties:
availability:
description: 'Availability updates per room type.'
type: array
items:
$ref: '#/components/schemas/AvailabilityUpdatePutRequestSchema'
testRequest:
description: 'Mark as test request (honored in non-production only).'
type: boolean
example: false
type: object
AvailabilityUpdatePatchRequestSchema:
required:
- roomTypeId
- intervals
properties:
roomTypeId:
description: 'Room Type ID.'
type: integer
example: 12345
intervals:
description: 'Date intervals to adjust.'
type: array
items:
$ref: '#/components/schemas/PatchIntervalRequestSchema'
type: object
AvailabilityUpdatePutRequestSchema:
required:
- roomTypeId
- intervals
properties:
roomTypeId:
description: 'Room Type ID.'
type: integer
example: 12345
intervals:
description: 'Date intervals to set.'
type: array
items:
$ref: '#/components/schemas/PutIntervalRequestSchema'
type: object
PatchIntervalRequestSchema:
required:
- startDate
- endDate
- amountAllottedForSaleDelta
properties:
startDate:
description: 'Interval start date (YYYY-MM-DD).'
type: string
pattern: '^\d{4}-\d{2}-\d{2}$'
example: '2030-01-01'
endDate:
description: 'Interval end date (YYYY-MM-DD), inclusive.'
type: string
pattern: '^\d{4}-\d{2}-\d{2}$'
example: '2030-01-07'
amountAllottedForSaleDelta:
description: 'Relative change (must be non-zero; may be negative; result is floored at 0).'
type: integer
example: -2
nullable: true
type: object
PutIntervalRequestSchema:
required:
- startDate
- endDate
- amountAllottedForSale
properties:
startDate:
description: 'Interval start date (YYYY-MM-DD).'
type: string
pattern: '^\d{4}-\d{2}-\d{2}$'
example: '2030-01-01'
endDate:
description: 'Interval end date (YYYY-MM-DD), inclusive.'
type: string
pattern: '^\d{4}-\d{2}-\d{2}$'
example: '2030-01-07'
amountAllottedForSale:
description: 'New amount allotted for sale (>= 0).'
type: integer
example: 10
nullable: true
type: object
AmountsForSaleListResponseSchema:
required:
- data
properties:
data:
description: 'Per-date amounts allotted for sale.'
type: array
items:
$ref: '#/components/schemas/DateAmountResponseSchema'
type: object
DateAmountResponseSchema:
required:
- date
- amountAllottedForSale
properties:
date:
description: 'Date (YYYY-MM-DD).'
type: string
example: '2030-01-01'
amountAllottedForSale:
description: 'Operator-set amount allotted for sale.'
type: integer
example: 12
type: object
JobAcceptedResponseSchema:
required:
- jobReferenceId
properties:
jobReferenceId:
description: 'Reference ID for tracking via getAsyncApiJob.'
type: integer
example: 1234
type: object
AssignableRoomsRequestSchema:
properties:
roomTypeId:
description: 'Scope rates and rooms to this room type. Absent returns the reservation''s current type.'
type: string
example: '713'
nullable: true
type: object
AssignableRoomSchema:
required:
- roomId
- name
- housekeepingStatus
properties:
roomId:
description: 'Composite room id "{roomTypeId}-{roomNumber}" used by the reassign action.'
type: string
example: 713-2
name:
type: string
example: 'Room 201'
housekeepingStatus:
description: 'Housekeeping status key.'
type: string
enum:
- clean
- dirty
- inspected
example: clean
type: object
AssignableRoomsResponseSchema:
required:
- reservation
- roomTypes
- selectedRoomTypeId
- rates
- rooms
properties:
reservation:
$ref: '#/components/schemas/ReservationContextSchema'
roomTypes:
description: 'Selectable room types (names only, no pricing).'
type: array
items:
$ref: '#/components/schemas/RoomTypeOptionSchema'
selectedRoomTypeId:
description: 'The room type the rates and rooms below are scoped to.'
type: string
example: '713'
rates:
description: 'Rate plans for the selected room type, totalled over the stay.'
type: array
items:
$ref: '#/components/schemas/RatePlanSchema'
rooms:
description: 'Rooms of the selected type free for the whole stay. Includes the reservation''s currently-assigned room when the selected type matches its current type (match on reservation.currentRoomId), so the drawer can render it as selected.'
type: array
items:
$ref: '#/components/schemas/AssignableRoomSchema'
type: object
LegacyAssignableRoomsResponseSchema:
description: "An earlier, narrower shape of this response. See AssignableRoomsResponseSchema for the\ncurrent shape."
required:
- reservation
- roomTypes
- selectedRoomTypeId
- rates
- rooms
properties:
reservation:
$ref: '#/components/schemas/LegacyReservationContextSchema'
roomTypes:
description: 'Selectable room types (names only, no pricing).'
type: array
items:
$ref: '#/components/schemas/LegacyRoomTypeOptionSchema'
selectedRoomTypeId:
description: 'The room type the rates and rooms below are scoped to.'
type: integer
example: 713
rates:
description: 'Rate plans for the selected room type, totalled over the stay.'
type: array
items:
$ref: '#/components/schemas/LegacyRatePlanSchema'
rooms:
description: 'Rooms of the selected type free for the whole stay. Includes the reservation''s currently-assigned room when the selected type matches its current type (match on reservation.currentRoomId), so the drawer can render it as selected.'
type: array
items:
$ref: '#/components/schemas/AssignableRoomSchema'
type: object
LegacyRatePlanSchema:
description: "An earlier, narrower assignable-rooms rate-plan shape: rateId is an integer, rateTotal is a\nraw float, and detailedRates is not present. See RatePlanSchema for the current shape."
required:
- rateId
- rateType
- name
- rateTotal
properties:
rateId:
type: integer
example: 4521
rateType:
description: 'Rate plan type.'
type: string
enum:
- standard
- derived
- package
- allotment
example: standard
name:
type: string
example: 'Deluxe King Room'
rateTotal:
description: 'Total for the stay (sum of nightly rates).'
type: number
format: float
example: 320
packageId:
type: integer
example: null
nullable: true
packageName:
type: string
example: null
nullable: true
type: object
LegacyReservationContextSchema:
description: "An earlier, narrower assignable-rooms reservation-context shape: ids are integers,\noriginalRateTotal is a raw float, and none of the save-context fields are present. See\nReservationContextSchema for the current shape."
required:
- bookingRoomId
- checkinDate
- checkoutDate
- currentRoomTypeId
- currentRateId
- originalRateTotal
properties:
bookingRoomId:
type: integer
example: 123456
checkinDate:
type: string
format: date
example: '2026-04-04'
checkoutDate:
type: string
format: date
example: '2026-04-06'
currentRoomTypeId:
type: integer
example: 713
currentRoomId:
description: 'Composite room id "{roomTypeId}-{roomNumber}", or null when no room is assigned.'
type: string
example: 713-2
nullable: true
currentRateId:
type: integer
example: 4521
originalRateTotal:
description: 'Total for the stay under the current rate.'
type: number
format: float
example: 320
allotmentBlockCode:
description: 'Allotment block code the reservation belongs to, if any.'
type: string
nullable: true
type: object
LegacyRoomTypeOptionSchema:
description: "An earlier, narrower assignable-rooms room-type-option shape: id is an integer. See\nRoomTypeOptionSchema for the current shape."
required:
- id
- name
properties:
id:
type: integer
example: 713
name:
type: string
example: 'Deluxe King Room'
type: object
NightlyRateSchema:
required:
- date
- rate
- adults
- kids
properties:
date:
type: string
format: date
example: '2026-04-04'
rate:
$ref: '#/components/schemas/MoneySchema'
adults:
$ref: '#/components/schemas/MoneySchema'
kids:
$ref: '#/components/schemas/MoneySchema'
type: object
RatePlanSchema:
required:
- rateId
- rateType
- name
- rateTotal
- detailedRates
properties:
rateId:
type: string
example: '4521'
rateType:
description: 'Rate plan type.'
type: string
enum:
- standard
- derived
- package
- allotment
example: standard
name:
type: string
example: 'Deluxe King Room'
rateTotal:
$ref: '#/components/schemas/MoneySchema'
packageId:
type: string
example: null
nullable: true
packageName:
type: string
example: null
nullable: true
detailedRates:
description: 'Per-night rates for the stay under this plan.'
type: array
items:
$ref: '#/components/schemas/NightlyRateSchema'
type: object
ReservationContextSchema:
required:
- bookingRoomId
- checkinDate
- checkoutDate
- currentRoomTypeId
- currentRateId
- originalRateTotal
- adults
- children
- confirmationNumber
- roomGroup
- guestName
- currentPackageId
- detailedRates
properties:
bookingRoomId:
type: string
example: '123456'
checkinDate:
type: string
format: date
example: '2026-04-04'
checkoutDate:
type: string
format: date
example: '2026-04-06'
currentRoomTypeId:
type: string
example: '713'
currentRoomId:
description: 'Composite room id "{roomTypeId}-{roomNumber}", or null when no room is assigned.'
type: string
example: 713-2
nullable: true
currentRateId:
type: string
example: '4521'
originalRateTotal:
$ref: '#/components/schemas/MoneySchema'
allotmentBlockCode:
description: 'Allotment block code the reservation belongs to, if any.'
type: string
nullable: true
adults:
description: 'Adults on the current assignment.'
type: integer
example: 2
children:
description: 'Children on the current assignment.'
type: integer
example: 0
confirmationNumber:
description: 'Confirmation number for this specific room within the reservation.'
type: string
example: 1234567-1
roomGroup:
description: 'Group key shared by the rooms that were booked together in this reservation.'
type: string
example: '1'
guestName:
description: 'Guest full name for the current assignment; empty when unset.'
type: string
example: 'Jane Doe'
currentPackageId:
description: 'Package id of the current rate, or null when the current rate has no package.'
type: string
example: null
nullable: true
detailedRates:
description: 'Current assignment''s per-night rates (for "preserve original price" saves).'
type: array
items:
$ref: '#/components/schemas/NightlyRateSchema'
type: object
RoomTypeOptionSchema:
required:
- id
- name
properties:
id:
type: string
example: '713'
name:
type: string
example: 'Deluxe King Room'
type: object
ValidationErrorFieldSchema:
required:
- field
- message
properties:
field:
type: string
example: roomTypeId
message:
type: string
example: 'Room type 999 is not valid for this property.'
type: object
ValidationErrorResponseSchema:
required:
- message
- code
properties:
message:
type: string
example: 'Room type 999 is not valid for this property.'
code:
description: 'Machine-readable error code.'
type: string
enum:
- INVALID_ROOM_TYPE
- RESERVATION_NOT_REASSIGNABLE
example: INVALID_ROOM_TYPE
errors:
type: array
items:
$ref: '#/components/schemas/ValidationErrorFieldSchema'
type: object
ClearActiveRevisionRequestSchema:
description: "Taking a view down: clears the live revision, leaving nothing published.\n\nRevisions and their publish history survive, so the view can be brought back by making one live\nagain. On a customized built-in, clearing the pointer is the revert-to-default."
required:
- viewId
properties:
viewId:
description: 'The view to take down.'
type: string
example: 8f3k2
type: object
CreateRevisionRequestSchema:
description: "Saving a new revision under an existing view id. Existing revisions are never mutated — the id is\nthe stable key, the revisions are immutable content.\n\n`baseRevision` is the optimistic-concurrency assertion and must equal the view's latest revision.\n`baseRevision: 0` asserts the view has no stored revision yet, which is how a built-in is\nmaterialized in place: the same id starts fronting a stored definition, so preferences and shared\nlinks keep working. Against an already-stored view that is a 409."
required:
- name
- sections
- baseRevision
properties:
name:
description: 'Display name for the view.'
type: string
maxLength: 60
minLength: 1
example: 'Front Desk Sweep'
sections:
description: 'Sections in order, replacing the previous revision''s wholesale.'
type: array
items:
$ref: '#/components/schemas/DefinitionSectionRequestSchema'
maxItems: 200
minItems: 1
baseRevision:
description: 'The revision this save is based on. Must equal the view''s latest revision; `"0"` asserts none exists yet and materializes a built-in.'
type: string
example: '4'
nullable: true
status:
description: 'Status of the new revision.'
type: string
default: draft
enum:
- draft
- published
type: object
CreateViewRequestSchema:
description: "Creating a stored view. The server mints the key — a client cannot choose one, and passing a\nreserved built-in id is a 400 rather than a way to pre-empt a built-in.\n\n`status` defaults to `draft` so the normal flow is build-then-publish; pass `published` to\nsave-and-publish in one step."
required:
- name
- sections
properties:
name:
description: 'Display name for the view.'
type: string
maxLength: 60
minLength: 1
example: 'Front Desk Sweep'
sections:
description: 'Sections in order. The uncategorized tail is computed at render time and must not be submitted.'
type: array
items:
$ref: '#/components/schemas/DefinitionSectionRequestSchema'
maxItems: 200
minItems: 1
status:
description: 'Initial status of revision 1.'
type: string
default: draft
enum:
- draft
- published
type: object
DefinitionSectionRequestSchema:
description: "One section of a submitted definition — the same `{id, label, unitIds}` a read returns, because\nthe read and the write of a definition are the same document.\n\nReserved ids (the `sec_rt_` prefix, `sec_alpha`, `sec_uncat`) are rejected: those belong to\nserver-computed sections, and letting a client claim one would collide at render time."
required:
- label
- unitIds
properties:
id:
description: 'The section''s id, stable across saves. **Omit it for a new section** — the server assigns one. Round-trip the id from a definition read to keep an existing section''s identity, and with it whatever the client hangs off that id. Must not be a server-reserved id such as `sec_uncat`.'
type: string
maxLength: 64
pattern: '^[A-Za-z0-9_-]+$'
example: sec_a1
label:
description: 'Section label as the admin typed it.'
type: string
maxLength: 60
minLength: 1
example: 'Tower — Low Floors'
unitIds:
description: 'Units placed in this section, in order. A unit may appear in only one section, and a bed must sit in the same section as its dorm — placing the dorm alone brings its beds along, which is the normal case. At most 20,000 unit ids across the whole definition; the ceiling is on the definition, not on one section, so it cannot be expressed as `maxItems` here.'
type: array
items:
type: string
example:
- 12345-0
- 12350-0
type: object
DeleteRevisionRequestSchema:
description: "Discarding a draft an admin tried and rejected. Only drafts are deletable — the active revision,\npublished history and a view's last remaining revision refuse with `REVISION_NOT_DELETABLE`."
required:
- viewId
- revision
properties:
viewId:
description: 'The view the revision belongs to.'
type: string
example: 8f3k2
revision:
description: 'The draft revision to discard.'
type: string
example: '6'
type: object
DeleteViewRequestSchema:
description: "Deleting a view. On a built-in this deletes the property's customization rather than the view: the\nid reverts to its derived layout and keeps working, which is why a reserved id is accepted here."
required:
- viewId
properties:
viewId:
description: 'The view to delete.'
type: string
example: 8f3k2
type: object
GetViewLayoutRequestSchema:
description: "Parameters for resolving a view into a layout.\n\n`filters` and `date` travel together: a day-scoped filter (`busy`) needs the day it is\nevaluated against, while a structural one (`kind`) does not. `revision` selects a\nspecific revision instead of the published resolution."
required:
- viewId
type: object
allOf:
-
$ref: '#/components/schemas/QueryParameterDynamicFilterSchema'
-
properties:
viewId:
description: 'A reserved built-in id (`accommodation-type`, `alphabetical`) or a stored view key.'
type: string
example: accommodation-type
revision:
description: 'Render a specific revision instead of the published resolution. Requires the manage permission when the revision is a draft.'
type: string
example: '5'
nullable: true
date:
description: 'The day day-scoped filters are evaluated against, `yyyy-MM-dd`. Required when such a filter is present (`busy`), ignored otherwise — `kind` is structural and needs no date.'
type: string
format: date
example: '2026-08-12'
nullable: true
type: object
GetViewRequestSchema:
description: 'Reading a stored view''s definition — what the builder edits.'
required:
- viewId
properties:
viewId:
description: 'The view whose definition to read.'
type: string
example: 8f3k2
type: object
ListRevisionsRequestSchema:
description: 'Listing a view''s revisions. Metadata only — no definition content is decoded.'
required:
- viewId
properties:
viewId:
description: 'The view whose revisions to list.'
type: string
example: 8f3k2
type: object
ListViewsRequestSchema:
description: "Listing the property's views. No pagination: two built-ins plus at most five stored keys is\nbounded by the model, not by a page size."
SetActiveRevisionRequestSchema:
description: "Which revision the view should serve.\n\nThe live revision belongs to the view, not to the revision, so this writes the view's pointer\nand copies no content: what an admin previewed is exactly what goes live. Any revision\nqualifies — naming an older one is the rollback — and naming the one already live changes\nnothing."
required:
- revision
properties:
revision:
description: 'The revision to make live.'
type: string
example: '4'
type: object
DefinitionSectionResponseSchema:
description: "A section as stored — exactly the shape a save accepts back, because the read and the write of a\ndefinition are the same document.\n\nNot to be confused with a section in a rendered layout: a definition holds the unit ids, while a\nlayout puts the id on each unit and leaves the section carrying only its label and kind."
required:
- id
- label
- unitIds
properties:
id:
description: 'Client-assigned section id, stable across saves.'
type: string
example: sec_a1
label:
description: 'Admin-authored label.'
type: string
example: 'Tower — Low Floors'
unitIds:
description: 'Units placed in this section, in order. Ids the catalog cannot resolve are kept here verbatim and reported in `unresolvedUnitIds`.'
type: array
items:
type: string
example:
- 12345-0
- 12350-0
type: object
LayoutMetaResponseSchema:
description: "What was rendered and how much of it. `revision`/`status` appear only for a view resolved from a\nstored revision — their absence is how a client tells a derived built-in from a materialized one,\nwithout a discriminator field."
required:
- viewId
- totalUnits
- hiddenUnits
- filtersApplied
properties:
viewId:
description: 'The view this layout was resolved from.'
type: string
example: 8f3k2
totalUnits:
description: 'Sellable spaces in the property. A dorm container is a structural row and is not counted; each of its beds is.'
type: integer
example: 148
hiddenUnits:
description: 'Units the filters removed from this response.'
type: integer
example: 145
filtersApplied:
description: 'Whether any filter was applied.'
type: boolean
example: true
revision:
description: 'Revision rendered. Absent when the view resolved to its derived layout.'
type: string
example: '5'
nullable: true
status:
description: 'Status of the rendered revision. Absent alongside `revision`.'
type: string
enum:
- draft
- published
example: draft
nullable: true
focusedDate:
description: 'Echo of the `date` the filters were evaluated against. Present only when a day-scoped filter ran.'
type: string
format: date
example: '2026-08-12'
nullable: true
type: object
RevisionListResponseSchema:
description: "A view's revisions, newest first. Unpaginated: retention keeps at most the three newest published\nrevisions, but drafts staged ahead of the live revision are never swept — so what actually\nbounds this collection is the ceiling of 50 revisions per view, enforced on save."
required:
- data
properties:
data:
description: 'Revision metadata, newest first.'
type: array
items:
$ref: '#/components/schemas/RevisionResponseSchema'
type: object
RevisionResponseSchema:
description: "Revision metadata — no definition content, which is why listing revisions never decodes the\nlayout blobs.\n\n`status` is immutable history: a revision stamped `published` was live at some point, whether or\nnot it is the active one now. Which revision is live is the view's active-revision pointer.\n\nThe revision number is this resource's `id` — an item in `/revisions` is identified by `id`, not by\na field repeating the resource name — and it is a string, as every numeric identifier is."
required:
- id
- name
- status
- created
properties:
id:
description: 'Revision number, from a monotonic per-view counter. Never reused, so a discard leaves a gap and an old preview link cannot come to point at new content.'
type: string
example: '5'
name:
description: 'The view''s name as of this revision. Names are versioned with the layout, so a rename staged in a draft shows here before it reaches the picker.'
type: string
example: 'Front Desk Sweep'
status:
description: 'Whether this revision has ever been published. History, not state: a revision that was taken down keeps it. What is live now is the view''s active revision.'
type: string
enum:
- draft
- published
example: published
created:
description: 'When the revision was stamped.'
type: string
format: date-time
example: '2026-08-16T10:41:02Z'
createdBy:
description: 'User who stamped it.'
type: string
example: '541223'
nullable: true
type: object
SectionEntityResponseSchema:
description: "A generic record reference, so adding a sectioning dimension is a new `type` value rather than a\nschema change."
required:
- type
- id
properties:
type:
description: 'Record kind.'
type: string
example: unit_type
id:
description: 'Record id.'
type: string
example: '12345'
type: object
SectionResponseSchema:
description: "One entry of the ordered section index. Carries no units — every unit names its section by\n`sectionId`, so a unit appears exactly once no matter how the sections are arranged.\n\n`id` is opaque and must never be parsed. What a section *is* comes from `kind` plus its companion\nfield: `entity` for an entity-backed section, `systemLabel` for a computed one. A new sectioning\ndimension (floor, building) adds an `entity.type` value rather than a new section shape."
required:
- id
- kind
- label
properties:
id:
description: 'Opaque section id. Never parsed by the client.'
type: string
example: sec_a1
kind:
description: '`entity`: backed by a domain record, see `entity`. `custom`: named by an admin. `system`: computed by the server, see `systemLabel`.'
type: string
enum:
- entity
- custom
- system
example: custom
label:
description: 'Display label, resolved server-side and rendered verbatim. Not localized: property-authored labels come back as authored, and the two server-generated labels ship English here plus a `systemLabel` token for the client to translate. Rendered verbatim.'
type: string
example: 'Tower — Low Floors'
systemLabel:
description: 'Which computed section this is, for clients that need to treat one specially — the uncategorized tail is default-collapsed, for instance.'
type: string
enum:
- alphabetical
- uncategorized
example: uncategorized
nullable: true
entity:
oneOf:
-
$ref: '#/components/schemas/SectionEntityResponseSchema'
nullable: true
description: 'The record this section is derived from, for `kind: entity`.'
type: object
UnitRelationResponseSchema:
description: 'Generic `{type, unitId}` so a new relation kind is a new value, not a new shape.'
required:
- type
- unitId
properties:
type:
description: 'Relation kind.'
type: string
enum:
- part_of
- composed_of
example: part_of
unitId:
description: 'The related unit.'
type: string
example: 12350-g0
type: object
UnitResponseSchema:
description: "One unit — a space that can be filled. Identity and structure only; volatile per-day state\n(housekeeping, busy/free) lives on the existing state endpoints.\n\n`restrictions` and `relations` are `required` so an empty one serializes as `[]` rather than\nbeing dropped: a client reading `unit.relations` must never meet an undefined.\n\n`sectionId` is always present: a unit only crosses the wire as part of a layout, and a unit in a\nlayout always renders under exactly one section."
required:
- id
- name
- kind
- unitTypeId
- restrictions
- relations
- sectionId
properties:
id:
description: 'PMS room identifier.'
type: string
example: 12345-0
name:
description: 'Server-resolved display name.'
type: string
example: '101'
kind:
description: '`standard`: a room in its own right. `dorm`: a shared unit whose beds sell individually — a structural row, not inventory. `bed`: an individually sellable bed. `virtual`: a space composed of other units.'
type: string
enum:
- standard
- dorm
- bed
- virtual
example: standard
unitTypeId:
description: 'Accommodation type this unit belongs to.'
type: string
example: '12345'
restrictions:
description: 'What the unit restricts, e.g. dorm gender. A mixed dorm carries no entry — absence already means anyone.'
type: array
items:
$ref: '#/components/schemas/UnitRestrictionResponseSchema'
relations:
description: 'Structural links: `part_of` (bed to its dorm) and `composed_of` (virtual to each physical component).'
type: array
items:
$ref: '#/components/schemas/UnitRelationResponseSchema'
sectionId:
description: 'The section this unit renders under.'
type: string
example: sec_a1
type: object
UnitRestrictionResponseSchema:
description: 'Generic `{type, value}` so a new restriction kind is a new value, not a new shape.'
required:
- type
- value
properties:
type:
description: 'Restriction kind.'
type: string
example: gender
value:
description: 'Restriction value.'
type: string
example: female
type: object
ViewDetailResponseSchema:
description: "A stored view's definition at one revision — what the builder edits, and symmetric with the save.\n\n`unresolvedUnitIds` is computed at read time: saved ids the current catalog can no longer resolve,\nbecause the unit was deactivated or re-typed (re-typing mints a new id). They stay in `sections`\nverbatim and are flagged here rather than dropped, so a read/modify/write cycle cannot silently\ndelete units that may come back."
required:
- id
- name
- revision
- status
- sections
properties:
id:
description: 'The view id.'
type: string
example: 8f3k2
name:
description: 'Display name.'
type: string
example: 'Front Desk Sweep'
revision:
description: 'The revision this definition is from.'
type: string
example: '5'
status:
description: 'Status of this revision.'
type: string
enum:
- draft
- published
example: draft
sections:
description: 'Sections in order. The uncategorized tail is computed at render time and is not stored here.'
type: array
items:
$ref: '#/components/schemas/DefinitionSectionResponseSchema'
publishedRevision:
description: 'The active revision, if any.'
type: string
example: '3'
nullable: true
created:
description: 'When the view was created.'
type: string
format: date-time
example: '2026-08-12T09:21:44Z'
nullable: true
modified:
description: 'When this revision was stamped.'
type: string
format: date-time
example: '2026-08-16T10:41:02Z'
nullable: true
createdBy:
description: 'User who created the view.'
type: string
example: '541223'
nullable: true
unresolvedUnitIds:
description: 'Saved unit ids the current catalog cannot resolve. Absent when every id still resolves.'
type: array
items:
type: string
type: object
ViewLayoutResponseSchema:
description: "A view resolved into a layout: every unit to draw, flat and in final render order, each naming\nits section; the ordered section index; and what was rendered.\n\nThe units are under `units` rather than the platform's `data`: this is not a collection of the\nresource in the path — it is one layout, whose parts happen to include units.\n\nDeliberately unpaginated. A partial layout is not a layout: the calendar needs every row before\nit can draw one, so paging this would mean N requests before first paint. Bounded by\nconstruction instead — a stored view is capped on write, a built-in by the property's inventory."
required:
- units
- sections
- meta
properties:
units:
description: 'Units in final render order, each carrying its `sectionId`.'
type: array
items:
$ref: '#/components/schemas/UnitResponseSchema'
sections:
description: "The ordered section index.\n\nWhat it contains depends on how the view resolved. A view resolved from a stored definition ends with the uncategorized tail, always last and always present even when every unit is placed. The two derived built-ins have no tail: `accommodation-type` returns one section per unit type, and `alphabetical` returns a single band. Do not index off the last section to find the tail — match on `systemLabel`."
type: array
items:
$ref: '#/components/schemas/SectionResponseSchema'
meta:
$ref: '#/components/schemas/LayoutMetaResponseSchema'
type: object
ViewListResponseSchema:
description: "The property's views. Unpaginated: two built-ins plus at most five stored keys, so the collection\nis bounded at seven by the model itself rather than by a page size.\n\nA caller with the manage permission additionally sees views with nothing published; everyone else\nsees only what is live."
required:
- data
properties:
data:
description: 'View summaries, built-ins first.'
type: array
items:
$ref: '#/components/schemas/ViewSummaryResponseSchema'
type: object
ViewSummaryResponseSchema:
description: "One entry in the view picker.\n\nA view with no `publishedRevision` has nothing active: it is out of the picker for everyone but\nan admin, which is how a view is put away. `latestRevision` above `publishedRevision` means an\nadmin has work staged ahead of what is live."
required:
- id
- name
- isDefault
properties:
id:
description: 'Either a reserved built-in id (`accommodation-type`, `alphabetical`) or a stored key.'
type: string
example: 8f3k2
name:
description: 'Display name. For a built-in the property has not customized this is server-generated English — localize it from `systemLabel` instead of showing it verbatim.'
type: string
example: 'Front Desk Sweep'
isDefault:
description: 'Whether this is the default view and the client''s fallback target.'
type: boolean
example: false
publishedRevision:
description: 'The active revision. Absent when nothing is published — a derived built-in, or a view that has been put away.'
type: string
example: '3'
nullable: true
latestRevision:
description: 'Highest revision that exists. Above `publishedRevision` when work is staged ahead of what is live.'
type: string
example: '5'
nullable: true
modified:
description: 'When the view last changed.'
type: string
format: date-time
example: '2026-08-16T10:41:02Z'
nullable: true
systemLabel:
description: 'Token for a built-in view''s server-generated name, so the client can localize it. Absent for a stored view and for a customized built-in, whose names the admin typed. `name` carries the English fallback.'
type: string
enum:
- accommodation-type
- alphabetical
example: accommodation-type
nullable: true
type: object
CheckDiscountRequestSchema:
description: 'A discount applied to the whole check. It posts as its own negative folio line. To discount a single line instead, nest the discount inside that item as `items[].discounts[]`.'
required:
- amount
- name
- code
properties:
amount:
description: 'Discount amount as a positive value in the property currency. Cloudbeds posts it as a negative folio line.'
type: string
pattern: '^\d+(\.\d{1,4})?$'
example: '5.00'
nullable: true
name:
description: 'Human-readable label displayed on the folio line.'
type: string
example: 'Happy Hour 20%'
code:
description: 'Partner-supplied code identifying the discount (e.g., promotion or coupon code).'
type: string
example: HAPPY_HOUR
note:
description: 'Optional free-text note attached to the discount line item.'
type: string
example: 'Manager comp'
nullable: true
type: object
CheckItemDetailsSchema:
description: 'Marker base for the polymorphic `details` block on a check item. Concrete shape is selected by the sibling `type` field — see CheckItemRequestSchema.details.'
type: object
CheckItemDiscountRequestSchema:
description: 'A discount applied to the line it is nested under. Cloudbeds reduces that line''s `amount` by this value and appends the discount to the line''s `note`, so it stays visible on the folio; an item-level discount does not post a separate negative line. Several may be applied to one line, in which case their values are summed. A discount that applies to the whole check goes in the check-level `discounts[]` instead.'
required:
- amount
- name
- code
properties:
amount:
description: 'Discount amount as a positive value in the property currency. It is subtracted from the line''s amount. The combined discounts on a line may not exceed that line''s amount.'
type: string
pattern: '^\d+(\.\d{1,4})?$'
example: '5.00'
nullable: true
name:
description: 'Human-readable label. Appended to the line''s note so the reduction is explained on the folio.'
type: string
example: 'Happy Hour 20%'
code:
description: 'Partner-supplied code identifying the discount (e.g. promotion or coupon code).'
type: string
example: HAPPY_HOUR
note:
description: 'Optional free-text note.'
type: string
example: 'Manager comp'
nullable: true
type: object
CheckItemModifierRequestSchema:
required:
- modifierOptionId
properties:
modifierOptionId:
description: 'Modifier option identifier'
type: string
example: '970011'
quantity:
description: 'How many times the option is applied per item unit'
type: integer
example: 1
type: object
CheckItemRequestSchema:
description: 'A single line on a POS check. Shared envelope fields — externalLineId, name, quantity, price, amount, taxes, fees, note, customTransactionCode, generalLedgerCustomCode — describe the line. quantity is the unit count; price, when supplied, is the per-unit rate but is informational metadata only. The `details` block is polymorphic: its concrete shape is selected by the `type` discriminator. Today only PRODUCT is accepted, so `details` carries product-specific fields (sku, category, sub-reservation routing). Bookable-resource details will land alongside as a second `oneOf` branch when that flow is reintroduced. amount is the financial source of truth — the server posts it verbatim without recomputing from price * quantity.'
required:
- type
- name
- quantity
- amount
- details
properties:
type:
description: 'Discriminator selecting the kind of line — see CheckItemTypeEnum.'
type: string
enum:
- PRODUCT
example: PRODUCT
name:
description: 'Human-readable line name displayed on the folio (dish or beverage name).'
type: string
example: Cheeseburger
externalLineId:
description: 'Optional partner-supplied identifier for this line occurrence on the check (the POS system''s own line reference — e.g., Clover lineItem.id, Toast Selection.guid, Square line uid, or a per-check line sequence). Per line, not per unit: a quantity-2 line carries one reference. When provided, must be unique among this check''s items and service charges; a duplicate is rejected with DUPLICATE_EXTERNAL_LINE_ID. When omitted, the line is stored with no reference — Cloudbeds does not generate one. Supplied values are echoed back on the response and on line events so the partner can correlate the posted line without storing any Cloudbeds identifier.'
type: string
example: ABC8903421
nullable: true
quantity:
description: 'Number of units. Informational metadata only — not used for accounting math (amount is the line total, not price * quantity).'
type: integer
example: 2
price:
description: 'Per-unit price. Optional informational metadata — recorded on the folio for display and reporting; not used for accounting math. amount is the financial source of truth for this line; when price is omitted, amount is used as the per-unit price on the folio row. Decimal string in major units of the property currency.'
type: string
pattern: '^\d+(\.\d{1,4})?$'
example: '20.00'
nullable: true
amount:
description: 'Total line amount — the financial source of truth for this line. The server posts this value to the folio without recomputing it from price * quantity. Decimal string in major units of the property currency.'
type: string
pattern: '^\d+(\.\d{1,4})?$'
example: '20.00'
nullable: true
note:
description: 'Optional free-text note for this line (modifier, allergen, special request).'
type: string
example: 'No onions'
nullable: true
customTransactionCode:
description: 'Custom Transaction Code (chart-of-accounts mapping) snapshotted onto the folio transaction at posting time. If omitted, the property''s default mapping is applied.'
type: string
example: FOOD-REVENUE
nullable: true
generalLedgerCustomCode:
description: 'General Ledger custom code, snapshotted onto the folio transaction at posting time. If omitted, the property''s default mapping is applied.'
type: string
example: GL-4100
nullable: true
taxes:
description: 'Tax rows for this line. Each row identifies a configured tax by exactly one of `externalId` / `taxId`; unmatched values are rejected.'
type: array
items:
$ref: '#/components/schemas/TaxSchema'
fees:
description: 'Fee amounts for this line. Each row identifies a configured fee by exactly one of `externalId` / `feeId`; unmatched values are rejected.'
type: array
items:
$ref: '#/components/schemas/FeeSchema'
discounts:
description: 'Discounts applied to this line. The line''s amount is reduced by their total and each is appended to the line''s note; they do not post separate negative lines. A discount covering the whole check belongs in the check-level `discounts[]`.'
type: array
items:
$ref: '#/components/schemas/CheckItemDiscountRequestSchema'
modifiers:
description: 'Modifier options selected for this product line.'
type: array
items:
$ref: '#/components/schemas/CheckItemModifierRequestSchema'
details:
oneOf:
-
$ref: '#/components/schemas/ProductDetailsSchema'
nullable: true
description: 'Type-specific block. Concrete shape is selected by the sibling `type` field — today PRODUCT → ProductDetailsSchema (sku, category, sub-reservation routing). Additional branches (e.g. bookable resource) will be added as further `oneOf` variants without renaming. A formal OpenAPI `discriminator` is not declared because the discriminator field lives on the parent schema, not inside each variant — out of spec for discriminator.propertyName. Server-side dispatch into the right variant is handled by CheckItemRequestSchemaDenormalizer.'
type: object
CheckItemTypeEnum:
description: 'Line item kind — also the discriminator that selects the concrete shape of the `details` block on the same item. Currently only PRODUCT is accepted (ordinary POS items: food / beverage / retail), and `details` is a ProductDetailsSchema. BOOKABLE_RESOURCE will be reintroduced once the bookable-resource service exposes the synchronous create-reservation RPC postCheck needs to route those lines.'
type: string
enum:
- PRODUCT
CheckPaymentRequestSchema:
required:
- paymentType
- amount
properties:
paymentType:
description: 'Payment method type. Use the getPaymentMethods API to retrieve available payment methods for the property.'
type: string
example: cash
amount:
description: 'Payment amount in the property currency.'
type: string
pattern: '^\d+(\.\d{1,4})?$'
example: '24.30'
nullable: true
cardType:
description: 'Card type, when paymentType is a card. Optional.'
type: string
example: visa
nullable: true
note:
description: 'Optional payment note'
type: string
example: 'Paid at checkout'
nullable: true
type: object
CheckServiceChargeRequestSchema:
description: 'Service charge associated with the check. Posted as a distinct folio line item, separate from items[] and gratuity. Reported and routed independently from food/beverage revenue.'
required:
- amount
properties:
amount:
description: 'Service charge amount in the property currency.'
type: string
pattern: '^\d+(\.\d{1,4})?$'
example: '5.40'
nullable: true
taxes:
description: 'Tax rows applied to the service charge. Each row references a property-configured tax by ID. Schema reused from the Gratuity domain.'
type: array
items:
$ref: '#/components/schemas/TaxSchema'
maxItems: 20
customTransactionCode:
description: 'Override the property''s default service-charge Custom Transaction Code for this posting. If omitted, the property''s configured default applies.'
type: string
example: SVC-CHRG-VIP
nullable: true
generalLedgerCustomCode:
description: 'Override the property''s default service-charge General Ledger code for this posting. If omitted, the property''s configured default applies.'
type: string
example: GL-2410
nullable: true
note:
description: 'Optional free-text note attached to the service charge line item.'
type: string
maxLength: 255
example: '20% mandatory service charge'
nullable: true
externalLineId:
description: 'Optional partner-supplied identifier for this service charge on the check (the POS system''s own line reference — e.g., Clover''s order-fee lineItem.id). Shares one namespace with items[].externalLineId: when provided, must be unique among this check''s items and service charges; a duplicate is rejected with DUPLICATE_EXTERNAL_LINE_ID. A service charge posted with one can later be refunded on its own by that reference.'
type: string
maxLength: 255
example: 3J9PBSGJHDZ6C
nullable: true
type: object
CheckTotalsSchema:
description: 'Partner-supplied check totals broken out by component. Used for two purposes: (1) totals-only postings — when items[] is empty, totalItems carries the items subtotal and the server posts a single synthetic items folio line; inline serviceCharges[] / discounts[] continue to write their own rows; (2) cross-validation — when items[] is also supplied, each total field cross-validates against the corresponding server-computed sum (items / SC / gratuity / discount / tax / fees). Mismatches surface as INVALID_TOTAL_MISMATCH with the failing component identified. totalTax / totalFee are cross-cutting aggregates: in items mode they cross-validate the sum across the whole check; in totals-only mode totalTax is whole-check tax and only its remainder after inline service-charge / gratuity taxes routes to the lazily-created "Default POS tax" catch-all, while totalFee routes to the "Default POS fee" catch-all. Both ensure every catch-all tax / fee line references a real catalog record.'
required:
- totalItems
properties:
totalItems:
description: 'Items subtotal. Per item: amount + its taxes[] + its fees[] + the taxes on those fees — the nested fee-tax term is the one most often left out. When items[] is supplied alongside, this value must equal the server-computed subtotal within 1 minor unit per currency; a larger difference is rejected with INVALID_TOTAL_MISMATCH. When an item carries a discount this figure is the amount BEFORE that discount — the comparison runs on the items as sent, and the discount is applied afterwards, so a 20.00 item with a 5.00 discount is declared as 20.00 and posts 15.00. When items[] is empty, this is the gross figure the single synthesised line carries. Not a grand total — service charge, gratuity and discount have their own fields below.'
type: string
pattern: '^\d+(\.\d{1,4})?$'
example: '24.30'
nullable: true
totalServiceCharge:
description: 'Service-charge subtotal — sum of each serviceCharges[].amount and its taxes. Optional; cross-validates against the inline serviceCharges[] data ONLY when both are supplied. In totals-only mode without inline serviceCharges[], this value is the partner-declared SC aggregate (validation deferred to the persistence layer).'
type: string
pattern: '^\d+(\.\d{1,4})?$'
example: '24.30'
nullable: true
totalGratuity:
description: 'Gratuity subtotal — sum(gratuities[].amount + gratuities[].taxes). Optional; accepted on the wire but server-side validation is deferred until the embedded-gratuity domain handling lands (today gratuities are accepted but not mapped to the domain payload).'
type: string
pattern: '^\d+(\.\d{1,4})?$'
example: '24.30'
nullable: true
totalDiscount:
description: 'Discount subtotal — sum(discounts[].amount), partner-supplied as a positive value. Optional; cross-validates against the inline discounts[] ONLY when both are supplied. In totals-only mode without inline discounts, this value is the partner-declared discount aggregate.'
type: string
pattern: '^\d+(\.\d{1,4})?$'
example: '24.30'
nullable: true
totalTax:
description: 'Total tax across the check — sum of every tax line (items[].taxes, items[].fees[].taxes, serviceCharges[].taxes, gratuities[].taxes). Optional. When items[] is supplied, the partner value cross-validates against the server-computed sum (INVALID_TOTAL_MISMATCH on drift). In totals-only mode (items[] empty), this is whole-check tax; only the positive remainder after inline service-charge and gratuity taxes is posted as a catch-all tax line on the synthetic POS-sale item, linked to the property''s lazily-created "Default POS tax" catalog record. Zero or omitted skips the synthesis.'
type: string
pattern: '^\d+(\.\d{1,4})?$'
example: '24.30'
nullable: true
totalFee:
description: 'Total fees across the check — sum of items[].fees[].amount. Fees only attach to items in the postCheck data model, so the sum is items-scoped. Optional. In items mode, cross-validates against the server-computed sum. In totals-only mode, the declared amount is routed through the property''s "Default POS fee" catalog record. Zero or omitted skips the synthesis.'
type: string
pattern: '^\d+(\.\d{1,4})?$'
example: '24.30'
nullable: true
type: object
DeleteCheckRequestSchema:
required:
- checkId
properties:
checkId:
description: 'The check''s public checkId (partner-supplied or Cloudbeds-generated) returned by createCheck.'
type: string
type: object
PostCheckRequestSchema:
description: 'Posts a completed POS check (e.g., F&B) to a guest folio, house account, or group profile. Replaces postCustomItem with first-class folio transactions enriched with hospitality POS context (check identity, revenue center, meal period, gratuity, service charge). All items, taxes, fees, gratuities, service charges, discounts, and payments in this request belong to the single check identified by checkNumber/checkId. Multi-check batching is not supported — issue a separate postCheck call per check.'
properties:
checkNumber:
description: 'Partner-assigned check number visible on the customer receipt (e.g., POS terminal display number). Stored on each posted folio line and visible in the folio UI. Optional — when omitted, the server mints a Cloudbeds reference (cb-) and returns it in the response so the partner can echo it back.'
type: string
example: '2047'
nullable: true
checkId:
description: 'Partner-assigned durable external reference for the check (UUID or opaque string). Optional — when omitted, Cloudbeds generates one and returns it. Echoed on the response and used to void the check later. Must be unique among the property''s active checks; a value released by a void can be reused. Letters, digits, and . _ ~ - only (addressed as a URL path segment for void).'
type: string
example: 8f2c1e3a-9b6d-4f1e-9d2a-3b6c0a1f7e51
nullable: true
reservationId:
description: 'Reservation identifier. Required if houseAccountId and eventCode are not provided. Per-item sub-reservation targeting is expressed via items[].subReservationId.'
type: string
example: RES123456
nullable: true
houseAccountId:
description: 'House account identifier. Required if reservationId and eventCode are not provided.'
type: string
example: HA-99812
nullable: true
eventCode:
description: 'Event code. Required if reservationId and houseAccountId are not provided.'
type: string
example: GRP2026
nullable: true
folioId:
description: 'Folio identifier within the chosen account target. Numeric string (the underlying folio_id is a 64-bit unsigned integer). Optional — when omitted, the default folio for the target is used.'
type: string
example: '12345'
nullable: true
roomId:
description: 'Room identifier where the charge originated, when applicable.'
type: string
example: ROOM-204
nullable: true
guestId:
description: 'Guest identifier. Optional — used for guest-attributed POS reporting.'
type: string
example: GST-77123
nullable: true
guestName:
description: 'Guest name as captured at the POS. Used when no guestId is provided.'
type: string
example: 'Jane Smith'
nullable: true
saleDate:
description: 'Sale date in RFC 3339 format. If not provided, the current timestamp is used. A future saleDate produces a ''pending'' transaction.'
type: string
example: '2026-05-05T20:30:00-04:00'
nullable: true
posContext:
oneOf:
-
$ref: '#/components/schemas/PosContextSchema'
nullable: true
description: 'Optional POS source metadata for the check (restaurant, revenue center, meal period, staff reference). Inherited by every gratuity, item, and service charge posted as part of this request — embedded gratuities therefore omit their own posContext.'
coverCount:
description: 'Number of guests on the check. Used for per-cover F&B reporting.'
type: integer
example: 4
nullable: true
totals:
oneOf:
-
$ref: '#/components/schemas/CheckTotalsSchema'
nullable: true
description: 'Optional partner-supplied totals. Required when items[] is empty (totals-only posting). When supplied alongside items[], the server validates totalItems against the computed sum and rejects with INVALID_TOTAL_MISMATCH if they disagree (tolerance: 1 minor unit per currency).'
items:
description: 'Line items on the check. Each line is posted as a regular folio item, not a Custom Item. At least one of items[] or totals must be supplied — when items[] is empty, totals is required, and the server posts a single folio line carrying totals.totalItems.'
type: array
items:
$ref: '#/components/schemas/CheckItemRequestSchema'
gratuities:
description: 'Optional list of gratuities on the check. Each entry becomes its own folio line item and its own Accounting Service transaction. Use multiple entries when both AUTO_GRATUITY (system-applied) and TIP (voluntary) are present, or when several servers each receive a tip. Embedded gratuities use GratuitySchema (without posContext) — POS context (checkNumber, restaurantName, revenueCenter, mealPeriod, staffReference) is inherited from this parent check.'
type: array
items:
$ref: '#/components/schemas/GratuitySchema'
serviceCharge:
oneOf:
-
$ref: '#/components/schemas/CheckServiceChargeRequestSchema'
nullable: true
description: 'Optional single service charge for the check. Equivalent to serviceCharges with one entry; must not be combined with serviceCharges.'
serviceCharges:
description: 'Optional list of service charges on the check. Each entry posts as its own service-charge folio line with its own taxes and accounting event, distinct from gratuity.'
type: array
items:
$ref: '#/components/schemas/CheckServiceChargeRequestSchema'
maxItems: 20
discounts:
description: 'Optional discounts applied to the check. Each entry becomes a distinct (negative) folio line item.'
type: array
items:
$ref: '#/components/schemas/CheckDiscountRequestSchema'
payments:
description: 'Optional payments to register against the check at posting time. If provided, payFullBalance is ignored.'
type: array
items:
$ref: '#/components/schemas/CheckPaymentRequestSchema'
payFullBalance:
description: 'If true, a cash payment is automatically registered for the full check total (items + taxes + fees + gratuity + service charge - discounts). Ignored when payments[] is provided.'
type: boolean
example: false
type: object
oneOf:
-
required:
- reservationId
-
required:
- houseAccountId
-
required:
- eventCode
ProductDetailsSchema:
description: 'Product-only fields for a check item whose type is PRODUCT. sku is required — it is the catalog dedup key. Category and sub-reservation override remain optional.'
required:
- sku
type: object
allOf:
-
$ref: '#/components/schemas/CheckItemDetailsSchema'
-
properties:
sku:
description: 'Partner-supplied SKU for the item. Required — used as the catalog dedup key and recorded on the folio line for cross-reference.'
type: string
example: SKU-CHEESE-001
nullable: true
categoryName:
description: 'Category name as classified by the POS (e.g., ''Food'', ''Beverage'', ''Alcohol''). Used for reporting and item classification.'
type: string
example: Food
nullable: true
subReservationId:
description: 'Sub-reservation identifier. If provided, this item is routed to the specified sub-reservation within the parent reservation (request-level reservationId). If omitted on a reservation with a single stay and no item in the request carries a subReservationId, the item is attributed to the room assigned to that stay; when the stay is split across rooms because of an in-stay move, the room assigned on the sale date is used. Multi-stay reservations, and requests that set subReservationId on only some items, need an explicit identifier on each item for room attribution. Has no effect when the request-level target is houseAccountId or eventCode.'
type: string
example: SUB123
nullable: true
type: object
RefundCheckItemRequestSchema:
description: 'A line of the check to refund, named by the externalLineId it was posted with. The line is refunded whole, together with its taxes and fees.'
required:
- externalLineId
properties:
externalLineId:
description: 'The externalLineId an item or service charge was posted with on this check. A line posted without one cannot be refunded on its own.'
type: string
maxLength: 255
example: ABC8903421
type: object
RefundCheckRequestSchema:
required:
- checkId
properties:
checkId:
description: 'The check''s public checkId (partner-supplied or Cloudbeds-generated) returned by createCheck.'
type: string
items:
description: 'The lines to refund. Omitted or empty refunds everything left on the check. When items are refunded, each check-level discount gives back the refunded items'' share of what is left of it, in proportion to the amounts of the items not yet refunded and rounded to the minor unit; once no item is left, whatever is left of the discount goes. An item''s amount here is the one it was posted with, after its own item-level discounts. A line already refunded in full is rejected with REFUND_EXCEEDS_LINE; a line posted at zero adds nothing to the refund. A service charge is refunded only when named, and gratuities only when the whole check is refunded.'
type: array
items:
$ref: '#/components/schemas/RefundCheckItemRequestSchema'
expectedTotal:
description: 'What the partner refunded for this request, taxes included, in the property currency. When supplied, it is checked against what the refund reverses, allowing one minor unit of rounding per reversed line; a larger difference is rejected with REFUND_TOTAL_MISMATCH and nothing is reversed.'
type: string
pattern: '^\d+(\.\d{1,4})?$'
example: '4.32'
nullable: true
externalRefundId:
description: 'The partner''s own id for this refund, carried with the refund for reconciliation.'
type: string
maxLength: 255
example: MJD5E74KPXD3Y
nullable: true
type: object
CheckErrorCodeEnumSchema:
description: 'Machine-readable error code returned in BadRequest / NotFound / Conflict responses for postCheck. Aligned with the structured error approach used by STS Gen2 and the Accounting API.'
type: string
enum:
- FOLIO_NOT_FOUND
- RESERVATION_CHECKED_OUT
- IDEMPOTENCY_KEY_REUSED
- DUPLICATE_CHECK_ID
- DUPLICATE_EXTERNAL_LINE_ID
- TAX_NOT_FOUND
- FEE_NOT_FOUND
- PRODUCT_NAME_CONFLICT
- INVALID_TOTAL_MISMATCH
- MISSING_ITEMS_OR_TOTALS
- INVALID_AMOUNT
- INVALID_TARGET
- SUBRESERVATION_NOT_FOUND
- CHECK_NOT_FOUND
- CHECK_VOID_UNAVAILABLE
- PAYMENT_VOID_FAILED
- MODIFIERS_NOT_ENABLED
- MODIFIER_OPTION_NOT_FOUND
- MODIFIER_OPTION_KITCHEN_ONLY
- MODIFIER_OPTION_NOT_ATTACHED
- MODIFIER_QUANTITY_INVALID
- MODIFIER_GROUP_SELECTION_INVALID
- CHECK_REFUND_FORBIDDEN
- CHECK_REFUND_UNAVAILABLE
- PAYMENT_REFUND_FAILED
- CHECK_LINE_NOT_FOUND
- REFUND_EXCEEDS_LINE
- REFUND_TOTAL_MISMATCH
PostCheckResponseSchema:
required:
- data
properties:
data:
$ref: '#/components/schemas/PostedCheckResponseSchema'
type: object
PostedCheckItemResponseSchema:
description: 'A posted check line echo — position-matched to the request items[] entry so the caller can correlate each accepted line to its own POS-side identity.'
required:
- externalLineId
properties:
externalLineId:
description: 'The partner-supplied line reference accepted on items[].externalLineId, echoed verbatim — null when the line was posted without one. Address this value (with the check''s checkId) in any future line-scoped operation such as a partial refund or partial void.'
type: string
example: ABC8903421
nullable: true
type: object
PostedCheckResponseSchema:
description: 'Result of a postCheck call. checkId is the public, partner-addressable handle for the posted check — use it for downstream void/reversal.'
required:
- checkNumber
- checkId
- items
properties:
checkNumber:
description: 'Resolved receipt-visible check number — either the partner-supplied value from the request, or a server-minted Cloudbeds reference (cb-) when the partner omitted it. Always returned so the partner can echo it back.'
type: string
example: '2047'
checkId:
description: 'Public, partner-addressable check identifier (accept-or-generate): the value the partner supplied, or a Cloudbeds-generated handle when omitted. Use it to address the check for void via DELETE /folio/v1/checks/{checkId}. Always returned.'
type: string
example: CHK-9911283
items:
description: 'Per-line echo of the accepted items[], position-matched to the request items[] (entry i describes request line i) — each entry carries back the partner-supplied externalLineId, or null where the line supplied none, so the caller can correlate posted lines to its own POS line ids without storing any Cloudbeds identifier. Empty for totals-only postings.'
type: array
items:
$ref: '#/components/schemas/PostedCheckItemResponseSchema'
notice:
description: 'Set when this request replayed an earlier one: the same Idempotency-Key was sent with the same body. When present, no new posting was created and the original response is returned.'
type: string
example: 'Duplicate Idempotency-Key — returning original posting.'
nullable: true
type: object
RefundCheckResponseSchema:
required:
- data
properties:
data:
$ref: '#/components/schemas/RefundedCheckResponseSchema'
type: object
RefundedCheckResponseSchema:
description: 'Result of a refundCheck call: every reversal now standing against the check.'
required:
- checkId
- refunds
properties:
checkId:
description: 'Public, partner-addressable check identifier the refund was applied to.'
type: string
example: CHK-9911283
refundId:
description: 'Cloudbeds id of the refund. A replay under the same Idempotency-Key returns the same id; null when the request reversed nothing.'
type: string
example: '9000000000000000100'
nullable: true
refunds:
description: 'One entry per refunded payment. A replay under the same Idempotency-Key returns the same entries as the original call.'
type: array
items:
$ref: '#/components/schemas/RefundedPaymentResponseSchema'
notice:
description: 'Set when the request reversed nothing because the check had nothing left to refund.'
type: string
example: 'Nothing new was reversed; the check carries nothing left to refund.'
nullable: true
type: object
RefundedPaymentResponseSchema:
description: 'One reversal: the Refund payment recorded against an original check payment.'
required:
- paymentId
- refundPaymentId
properties:
paymentId:
description: 'Identifier of the original payment that was refunded.'
type: integer
example: 8812345
refundPaymentId:
description: 'Identifier of the Refund payment created to reverse it.'
type: integer
example: 8812999
type: object
ChecklistConfigUpdateRequestSchema:
description: 'A full replacement of the property''s check-in checklist configuration. A replace rather than a patch, because the order of the items is part of the configuration. Sending both stages empty removes the configuration, leaving the property with no checklist.'
required:
- checkIn
- checkOut
properties:
checkIn:
description: 'Items guarding check-in, in the order they should appear.'
type: array
items:
type: object
example:
-
key: balance_due
severity: block
requireSkipReason: false
-
key: guest_required_fields
severity: block
requirePrimaryGuests: true
requireAdditionalGuests: true
roomScope: all_rooms
checkOut:
description: 'Items guarding check-out, in the order they should appear.'
type: array
items:
type: object
example:
-
key: balance_due
severity: warn
type: object
ChecklistConfigResponseSchema:
description: 'A property''s check-in checklist configuration, as the platform applies it.'
required:
- isConfigured
- checkIn
- checkOut
properties:
isConfigured:
description: 'False when the property has no checklist at all, which is the default and the behaviour that predates the feature. Both item lists are then empty.'
type: boolean
checkIn:
description: 'Items guarding check-in, in display order.'
type: array
items:
$ref: '#/components/schemas/ChecklistItemResponseSchema'
checkOut:
description: 'Items guarding check-out, in display order.'
type: array
items:
$ref: '#/components/schemas/ChecklistItemResponseSchema'
type: object
ChecklistItemResponseSchema:
required:
- key
- severity
- severityIsFixed
properties:
key:
description: 'The checklist item.'
type: string
example: balance_due
severity:
description: 'The severity actually applied to this item, which is not always the one stored.'
type: string
enum:
- block
- warn
example: block
severityIsFixed:
description: 'True when the severity is a property of the platform rather than a choice. The settings page must not offer a severity control for these items: the value cannot be changed, and showing a control implies otherwise.'
type: boolean
requireSkipReason:
description: 'Whether a reason is required to skip a warn balance at check-in. A required balance always needs a reason.'
type: boolean
example: false
nullable: true
requirePrimaryGuests:
description: 'Whether guest details are required for primary guests.'
type: boolean
example: true
nullable: true
requireAdditionalGuests:
description: 'Whether guest details are required for additional guests.'
type: boolean
example: true
nullable: true
roomScope:
description: 'The rooms where guest details are required.'
type: string
enum:
- all_rooms
- first_room
example: all_rooms
nullable: true
type: object
DynamicFilterFieldSchema:
description: 'Represents a single filter condition'
properties:
field:
description: 'The field to apply the filter on'
type: string
example: checkin_date
operator:
$ref: '#/components/schemas/FilterOperatorEnumSchema'
value:
description: 'The value for the filter'
nullable: true
oneOf:
-
type: string
example: '2023-10-19T00:00:00'
-
type: string
format: date-time
example: '2023-10-19T00:00:00'
-
type: string
format: date
example: '2023-10-19'
-
type: integer
example: 42
-
type: boolean
example: true
-
type: array
items:
type: string
example:
- cancelled
- disabled
-
type: array
items:
type: integer
example:
- 1
- 2
- 3
-
type: array
items:
type: string
format: date
example:
- '2023-10-19'
- '2023-10-20'
-
type: array
items:
type: string
format: date-time
example:
- '2023-10-19T00:00:01'
- '2023-10-19T23:59:09'
type: object
DynamicFilterSchema:
description: 'Represents a logical group of filters with keys like ''and'' or ''or'''
properties:
and:
description: 'Logical operator grouping filters or nested logical groups'
type: array
items:
oneOf:
-
$ref: '#/components/schemas/DynamicFilterFieldSchema'
-
$ref: '#/components/schemas/DynamicFilterSchema'
or:
description: 'Logical operator grouping filters or nested logical groups'
type: array
items:
oneOf:
-
$ref: '#/components/schemas/DynamicFilterFieldSchema'
-
$ref: '#/components/schemas/DynamicFilterSchema'
type: object
example: "{\n \"and\": [\n {\n \"field\": \"checkin_date\",\n \"operator\": \"less_than_or_equal\",\n \"value\": \"2023-12-01T00:00:00\"\n },\n {\n \"or\": [\n {\n \"and\": [\n {\n \"field\": \"checkin_date\",\n \"operator\": \"less_than_or_equal\",\n \"value\": \"2023-12-01T00:00:00\"\n },\n {\n \"field\": \"guest_first_name\",\n \"operator\": \"starts_with\",\n \"value\": [\n \"John\",\n \"Doe\"\n ]\n }\n ]\n },\n {\n \"field\": \"guest_last_name\",\n \"operator\": \"ends_with\",\n \"value\": \"Doe\"\n },\n {\n \"field\": \"guest_name\",\n \"operator\": \"in\",\n \"value\": [\n \"John Smith\",\n \"Doe Family\"\n ]\n },\n {\n \"field\": \"guest_email\",\n \"operator\": \"not_in\",\n \"value\": [\n \"test@example.com\",\n \"fakeuser@example.org\"\n ]\n },\n {\n \"field\": \"status\",\n \"operator\": \"is_null\"\n },\n {\n \"field\": \"reservation_notes\",\n \"operator\": \"is_not_null\"\n }\n ]\n },\n {\n \"field\": \"room_price\",\n \"operator\": \"equals\",\n \"value\": 150\n },\n {\n \"field\": \"discount_code\",\n \"operator\": \"not_equals\",\n \"value\": \"BLACKFRIDAY2024\"\n },\n {\n \"field\": \"guest_comments\",\n \"operator\": \"contains\",\n \"value\": \"great service\"\n },\n {\n \"field\": \"special_requests\",\n \"operator\": \"not_contains\",\n \"value\": \"late check-out\"\n },\n {\n \"field\": \"property_name\",\n \"operator\": \"starts_with\",\n \"value\": \"Luxury\"\n },\n {\n \"field\": \"property_location\",\n \"operator\": \"not_starts_with\",\n \"value\": \"Downtown\"\n },\n {\n \"field\": \"booking_reference\",\n \"operator\": \"ends_with\",\n \"value\": \"-2023\"\n },\n {\n \"field\": \"transaction_id\",\n \"operator\": \"not_ends_with\",\n \"value\": \"-VOID\"\n },\n {\n \"field\": \"internal_notes\",\n \"operator\": \"is_empty\"\n },\n {\n \"field\": \"guest_feedback\",\n \"operator\": \"is_not_empty\"\n }\n ]\n }"
FilterOperatorEnumSchema:
description: 'The operator to use for the filter'
type: string
enum:
- greater_than_or_equal
- greater_than
- less_than_or_equal
- less_than
- equal
- in
- not_in
- is_null
- is_not_null
- equals
- not_equals
- contains
- not_contains
- starts_with
- not_starts_with
- ends_with
- not_ends_with
- is_empty
- is_not_empty
BodyDynamicFilterSchema:
properties:
filters:
oneOf:
-
$ref: '#/components/schemas/DynamicFilterSchema'
nullable: true
description: 'The filters for the query'
type: object
QueryParameterDynamicFilterSchema:
properties:
filters:
oneOf:
-
$ref: '#/components/schemas/DynamicFilterSchema'
nullable: true
description: 'This parameter should be formatted as a list of strings separated by ; Use \; for a literal semicolon inside a value.'
example: 'field1:value;field2:operator:value'
type: object
LimitOffsetPaginationSchema:
properties:
limit:
description: 'The limit for the number of items to return (max 500)'
type: integer
default: 100
example: 1
offset:
description: 'The offset for the current page of results'
type: integer
default: 0
example: 1
type: object
DirectionEnumSchema:
description: 'The direction of the sort'
type: string
enum:
- asc
- desc
BodySortSchema:
type: object
QueryParameterSortSchema:
properties:
sort:
$ref: '#/components/schemas/SortSchema'
type: object
SortFieldSchema:
description: 'Represents a sort field and its direction'
properties:
field:
description: 'The field to apply the sort on'
type: string
example: checkin_date
direction:
$ref: '#/components/schemas/DirectionEnumSchema'
type: object
SortSchema:
description: 'Represents a list of sort fields to apply to the request'
properties:
fields:
description: 'The list of fields to sort by'
type: array
items:
$ref: '#/components/schemas/SortFieldSchema'
type: object
example: "[\n {\n \"field\": \"checkin_date\",\n \"direction\": \"desc\"\n },\n {\n \"field\": \"checkout_date\"\n }\n ]"
FeeSchema:
description: 'A fee row applied to a parent object (today: a check line item). Same model as `taxes` — fees are referenced by identifier from the property''s configured fees catalog, not by free-text name. The fee is identified by exactly one of `externalId` / `feeId` — sending both or neither is rejected. Multiple fee rows per parent are supported, and each fee can carry its own `taxes[]` for tax-on-fee.'
required:
- amount
properties:
externalId:
description: 'The partner-owned identifier configured on the fee under the property''s fee settings (a 3rd-party reference the property has associated with one of its Cloudbeds fees). Required unless `feeId` is sent. Must resolve to an active fee on the property; unknown or inactive values are rejected with FEE_NOT_FOUND.'
type: string
example: fee_resort_daily
nullable: true
feeId:
description: 'Cloudbeds identifier of the fee, as returned in `feeID` by getTaxesAndFees. Required unless `externalId` is sent. This identifier is not permanent: when the property edits the fee, Cloudbeds replaces it with a new identifier. A previous identifier is still accepted and is recorded as sent, against the version of the fee it names. A deleted fee is rejected with FEE_NOT_FOUND. Use `externalId` when you need a reference that stays the same across edits.'
type: string
pattern: '^(0|[1-9]\d*)$'
example: '9804'
nullable: true
amount:
description: 'Fee amount applied to this item. Decimal string in major units of the property currency.'
type: string
pattern: '^\d+(\.\d{1,4})?$'
example: '2.50'
nullable: true
taxes:
description: 'Taxes applied to this fee (tax-on-fee). Each row identifies a configured tax by exactly one of `externalId` / `taxId`; unmatched values are rejected with TAX_NOT_FOUND.'
type: array
items:
$ref: '#/components/schemas/TaxSchema'
type: object
oneOf:
-
required:
- externalId
properties:
externalId:
type: string
pattern: \S
feeId:
type: string
pattern: '^\s*$'
nullable: true
type: object
-
required:
- feeId
properties:
externalId:
type: string
pattern: '^\s*$'
nullable: true
feeId:
type: string
pattern: '^(0|[1-9]\d*)$'
type: object
TaxSchema:
description: 'A tax row applied to a gratuity, an item, or a service charge. Multiple tax rows per parent object are supported. The tax is identified by exactly one of `externalId` / `taxId` — sending both or neither is rejected.'
required:
- amount
properties:
externalId:
description: 'The partner-owned identifier configured on the tax under the property''s tax settings (a 3rd-party reference the property has associated with one of its Cloudbeds taxes). Required unless `taxId` is sent. Must resolve to an active tax on the property; unknown or inactive values are rejected with TAX_NOT_FOUND.'
type: string
example: tax_state_va_8
nullable: true
taxId:
description: 'Cloudbeds identifier of the tax, as returned in `taxID` by getTaxesAndFees. Required unless `externalId` is sent. This identifier is not permanent: when the property edits the tax, Cloudbeds replaces it with a new identifier. A previous identifier is still accepted and is recorded as sent, against the version of the tax it names. A deleted tax is rejected with TAX_NOT_FOUND. Use `externalId` when you need a reference that stays the same across edits.'
type: string
pattern: '^(0|[1-9]\d*)$'
example: '29486'
nullable: true
amount:
description: 'Tax amount applied to the parent object — item, fee, service charge or gratuity, whichever this row is nested under. Decimal string in major units of the property currency.'
type: string
pattern: '^\d+(\.\d{1,4})?$'
example: '1.60'
nullable: true
type: object
oneOf:
-
required:
- externalId
properties:
externalId:
type: string
pattern: \S
taxId:
type: string
pattern: '^\s*$'
nullable: true
type: object
-
required:
- taxId
properties:
externalId:
type: string
pattern: '^\s*$'
nullable: true
taxId:
type: string
pattern: '^(0|[1-9]\d*)$'
type: object
AcceptedResponseSchema: { }
BadRequestErrorItemSchema:
required:
- field
- message
properties:
field:
type: string
message:
type: string
code:
description: 'Error code identifying the specific validation failure'
type: string
example: GROUP_CUSTOM_RATE_NOT_ALLOWED
nullable: true
details:
description: 'Additional details about the validation failure'
type: object
nullable: true
type: object
BadRequestErrorListSchema:
type: array
items:
$ref: '#/components/schemas/BadRequestErrorItemSchema'
BadRequestResponseSchema:
required:
- message
properties:
message:
type: string
errors:
oneOf:
-
$ref: '#/components/schemas/BadRequestErrorListSchema'
nullable: true
description: 'The list of errors'
code:
description: 'Error code identifying the type of error'
type: string
example: INVALID_REQUEST
nullable: true
type: object
ConflictErrorItemSchema:
required:
- field
- message
properties:
field:
type: string
message:
type: string
code:
description: 'Error code identifying the specific conflict'
type: string
example: OVERBOOKING_CONFIRMATION_REQUIRED
nullable: true
details:
description: 'Additional details about the conflict'
type: object
nullable: true
type: object
ConflictErrorListSchema:
type: array
items:
$ref: '#/components/schemas/ConflictErrorItemSchema'
ConflictResponseSchema:
required:
- message
properties:
message:
type: string
errors:
oneOf:
-
$ref: '#/components/schemas/ConflictErrorListSchema'
nullable: true
description: 'The list of errors'
code:
description: 'Error code identifying the type of conflict'
type: string
example: CONFIRMATION_REQUIRED
nullable: true
type: object
CreatedResponseSchema: { }
ForbiddenResponseSchema:
properties:
message:
type: string
code:
description: 'Error code identifying why access was refused, on endpoints that define one'
type: string
nullable: true
type: object
HttpErrorResponseSchema: { }
InternalServerErrorResponseSchema:
required:
- message
properties:
message:
type: string
code:
description: 'Error code identifying the type of error'
type: string
example: PAYMENT_VOID_FAILED
nullable: true
type: object
MoneySchema:
description: 'Money representation with amount in smallest currency unit and ISO 4217 currency code'
required:
- amount
- currencyCode
properties:
amount:
description: 'Amount in the smallest representable units of the currency (e.g., cents for USD). For example, USD $124.39 would be "12439".'
type: string
example: '12439'
currencyCode:
description: 'ISO 4217 currency code'
type: string
example: USD
type: object
NoContentResponseSchema: { }
NotFoundResponseSchema:
properties:
message:
type: string
code:
description: 'Error code identifying the type of error'
type: string
example: RESOURCE_NOT_FOUND
nullable: true
type: object
InventoryObjectType:
description: 'The type of inventory object'
type: string
enum:
- reservation
- house_account
- group_profile
- accounts_receivable_ledger
LastRoomValueDecisionSchema:
required:
- roomTypeId
- occupancyDate
- lastRoomValue
properties:
roomTypeId:
description: 'Room Type ID.'
type: integer
example: 67890
nullable: true
occupancyDate:
description: 'Occupancy date (YYYY-MM-DD).'
type: string
pattern: '^\d{4}-\d{2}-\d{2}$'
example: '2030-01-01'
nullable: true
lastRoomValue:
description: 'Last room value as sent by IDeaS. May be negative; a negative value is flagged as an anomaly downstream rather than rejected here.'
type: string
example: '150.00'
nullable: true
ceilingValue:
description: 'Ceiling value as sent by IDeaS, kept for context/audit.'
type: string
example: '200.00'
nullable: true
deltaValue:
description: 'Delta value as sent by IDeaS, kept for context/audit.'
type: string
example: '10.00'
nullable: true
maxSolds:
description: 'Maximum number of units sold as sent by IDeaS, kept for context/audit.'
type: integer
example: 5
nullable: true
currencyCode:
description: 'ISO 4217 currency code.'
type: string
example: USD
nullable: true
type: object
LastRoomValuePutRequestSchema:
required:
- correlationId
- data
properties:
correlationId:
description: 'Correlation id for tracing this request end-to-end.'
type: string
example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
data:
description: 'Last room value decisions to store.'
type: array
items:
$ref: '#/components/schemas/LastRoomValueDecisionSchema'
testRequest:
description: 'Mark as test request (honored in non-production only).'
type: boolean
example: false
type: object
OverbookingDecisionSchema:
required:
- level
- occupancyDate
- overbooking
properties:
level:
description: 'Overbooking level: house-wide or per room type.'
type: string
enum:
- house
- room_type
nullable: true
roomTypeId:
description: 'Room Type ID. Required and positive when level is room_type; 0 (or omitted) for house level.'
type: integer
example: 67890
nullable: true
occupancyDate:
description: 'Occupancy date (YYYY-MM-DD).'
type: string
pattern: '^\d{4}-\d{2}-\d{2}$'
example: '2030-01-01'
nullable: true
overbooking:
description: 'Overbooking limit in the Cloudbeds convention: positive = rooms sellable above capacity, negative = below. Stored as received (the integration translates its vendor sign).'
type: integer
example: 5
nullable: true
authorizedCapacity:
description: 'Authorized capacity as sent by IDeaS, kept for context/audit.'
type: integer
example: 20
nullable: true
type: object
OverbookingPutRequestSchema:
required:
- correlationId
- data
properties:
correlationId:
description: 'Correlation id for tracing this request end-to-end.'
type: string
example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
data:
description: 'Overbooking decisions to store.'
type: array
items:
$ref: '#/components/schemas/OverbookingDecisionSchema'
testRequest:
description: 'Mark as test request (honored in non-production only).'
type: boolean
example: false
type: object
LastRoomValueJobAcceptedResponseSchema:
required:
- jobReferenceId
properties:
jobReferenceId:
description: 'Reference ID for tracking via getAsyncApiJob.'
type: integer
example: 1234
type: object
OverbookingJobAcceptedResponseSchema:
required:
- jobReferenceId
properties:
jobReferenceId:
description: 'Reference ID for tracking via getAsyncApiJob.'
type: integer
example: 1234
type: object
MyallocatorProxyRequestSchema:
required:
- endpoint
- payload
properties:
endpoint:
description: 'MyAllocator endpoint name to proxy the request to.'
type: string
enum:
- RoomStaticContentSave
- RoomUpdate
example: RoomUpdate
payload:
description: 'Request payload to forward to MyAllocator. Opaque JSON body.'
type: object
meta:
description: 'Internal metadata used for activity logging (e.g. MfdAccommodationId, MaAccommodationId). Not forwarded to MyAllocator.'
type: object
type: object
MyallocatorProxyResponseSchema:
required:
- success
- data
- errors
properties:
success:
description: 'Whether the MyAllocator request was successful.'
type: boolean
data:
description: 'Response data from MyAllocator.'
type: object
errors:
description: 'Errors returned by MyAllocator.'
type: array
items:
type: object
type: object
GetDistributionSettingsRequestSchema: { }
PatchDistributionSettingsRequestSchema:
required:
- settings
properties:
settings:
description: 'List of distribution settings to update.'
type: array
items:
required:
- key
- value
properties:
key:
description: 'Key of the setting to update. Must be one of the valid distribution setting keys.'
type: string
enum:
- example_setting_key
- is_channel_revenue_allocation_enabled
- is_channel_derived_rate_plan_mapping_enabled
- groups_data_sync_enabled_channels
- full_reservation_sync_enabled_channels
- is_distribution_enabled
- allow_ota_reservation_cancellation
- allow_ota_reservation_reconciliation
- smart_policies_enabled_channels
- include_breakfast_pricing
- report_no_show_to_booking
example: example_setting_key
value:
description: 'Parsed setting value. Can be string, number, boolean, or structured data, depending on the setting you are updating.'
type: object
example:
-
key: example_setting_key
value: true
type: object
GetDistributionSettingsResponseSchema:
required:
- settings
properties:
settings:
description: 'List of distribution settings with their values and permissions.'
type: array
items:
properties:
key:
type: string
enum:
- example_setting_key
- is_channel_revenue_allocation_enabled
- is_channel_derived_rate_plan_mapping_enabled
- groups_data_sync_enabled_channels
- full_reservation_sync_enabled_channels
- is_distribution_enabled
- allow_ota_reservation_cancellation
- allow_ota_reservation_reconciliation
- smart_policies_enabled_channels
- include_breakfast_pricing
- report_no_show_to_booking
example: example_setting_key
value:
description: 'Parsed setting value. Can be string, number, boolean, or structured data, depending on the setting.'
nullable: true
permission:
type: string
enum:
- read
- write
- none
example: read
options:
description: 'Valid choices for this setting. Omitted when options are disabled for the property or the setting has no fixed list. Scalar labels use the requested language. Channel labels use catalogue names, or the channel identifier when no active row exists.'
type: array
items:
required: [value, label]
properties: { value: { description: 'The value to send back when saving this setting.', type: string }, label: { description: 'Display text for this choice. A raw value is returned if its label cannot be resolved.', type: string } }
type: object
type: object
example:
-
key: example_setting_key
value: true
permission: read
-
key: include_breakfast_pricing
value: IN
permission: read
options:
-
value: ''
label: 'Not available'
-
value: IN
label: 'Included in room/bed price'
-
value: EX
label: 'Excluded from room/bed price (i.e., extra charge)'
type: object
PatchDistributionSettingsErrorResponseSchema:
required:
- code
- message
- errors
properties:
message:
description: 'Human-readable explanation of the error.'
type: string
example: 'One or more settings failed validation. No changes were applied.'
errors:
description: 'List of errors encountered during the update.'
type: array
items:
required:
- field
- message
properties:
field:
description: 'The setting key that caused the error.'
type: string
enum:
- example_setting_key
- is_channel_revenue_allocation_enabled
- is_channel_derived_rate_plan_mapping_enabled
- groups_data_sync_enabled_channels
- full_reservation_sync_enabled_channels
- is_distribution_enabled
- allow_ota_reservation_cancellation
- allow_ota_reservation_reconciliation
- smart_policies_enabled_channels
- include_breakfast_pricing
- report_no_show_to_booking
example: example_setting_key
message:
description: 'The reason why the update failed.'
type: string
example: 'User does not have write permission for this setting.'
type: object
example:
-
field: example_setting_key
message: 'User does not have write permission for this setting.'
-
field: invalid_key
message: 'Setting key does not exist.'
type: object
DoorLockKeyBatchDeleteRequestSchema:
required:
- propertyId
DoorLockKeyCreateRequestSchema:
required:
- propertyId
- reservationId
- subReservationId
- issuerId
- startDateTime
- endDateTime
- keyType
properties:
propertyId:
type: string
reservationId:
description: 'Reservation identifier.'
type: string
subReservationId:
description: 'Sub-reservation identifier.'
type: string
issuerId:
type: string
startDateTime:
description: 'Start date and time of key.'
type: string
format: 'Y-m-d\TH:i:sP'
endDateTime:
description: 'End date and time of key.'
type: string
format: 'Y-m-d\TH:i:sP'
keyType:
description: 'Key type.'
type: string
enum:
- key_card
- access_code
- mobile_key
rooms:
description: 'List of common room IDs.'
type: array
items:
type: string
default: []
example:
- '1'
- '2'
- '3'
commonRooms:
description: 'List of common room ids.'
type: array
items:
type: string
default: []
example:
- '1'
- '2'
- '3'
externalId:
type: string
default: null
nullable: true
keyCode:
description: 'Custom key code.'
type: string
default: null
nullable: true
status:
description: 'Key status.'
type: string
default: processing
enum:
- processing
- completed
encoder:
type: string
default: null
nullable: true
mobileId:
type: string
default: null
nullable: true
guestId:
type: string
default: null
nullable: true
type: object
DoorLockKeyDeleteRequestSchema:
required:
- id
- propertyId
DoorLockKeyListRequestSchema:
required:
- propertyId
properties:
reservationId:
type: string
default: null
nullable: true
subReservationId:
type: string
default: null
nullable: true
type: object
DoorLockKeyUpdateRequestSchema:
required:
- propertyId
- id
properties:
status:
type: string
default: null
enum:
- processing
- completed
- failed
- deleted
nullable: true
keyCode:
type: string
default: null
nullable: true
errorMessage:
type: string
default: null
nullable: true
type: object
DoorLockKeyBatchDeleteItemSchema:
description: 'The outcome of invalidating one key in a batch request.'
required:
- keyId
- status
properties:
keyId:
type: string
status:
type: string
enum:
- deleted
- deleting
- failed
- not_found
message:
type: string
nullable: true
type: object
DoorLockKeyBatchDeleteResultResponseSchema:
description: 'Per-key outcomes for a batch invalidation, one entry per requested key.'
required:
- items
properties:
items:
type: array
items:
$ref: '#/components/schemas/DoorLockKeyBatchDeleteItemSchema'
type: object
DoorLockKeyCollectionResponseSchema:
required:
- items
type: array
items:
$ref: '#/components/schemas/DoorLockKeyResponseSchema'
DoorLockKeyFailedToGenerateResponseSchema:
required:
- message
properties:
message:
type: string
type: object
DoorLockKeyFailedToInvalidateResponseSchema:
required:
- message
properties:
message:
type: string
type: object
DoorLockKeyInvalidationTimeoutResponseSchema:
description: "INT-4076: separate schema for the \"no partner response yet\" case so the FE\naxios transient-retry interceptor treats it as a retryable network transient\n(504 is in TRANSIENT_STATUS_CODES) and re-issues the DELETE — effectively\nextending the wait while the partner is still working. Distinct from\nDoorLockKeyFailedToInvalidateResponseSchema (422), which is the terminal\n\"partner reported failure\" response that the FE surfaces to the user\nwithout retrying."
required:
- message
properties:
message:
type: string
type: object
DoorLockKeyListResponseSchema:
required:
- data
properties:
data:
type: array
items:
$ref: '#/components/schemas/DoorLockKeyCollectionResponseSchema'
nullable: true
type: object
DoorLockKeyResponseSchema:
required:
- keyId
- propertyId
- reservationId
- subReservationId
- issuerId
- rooms
- commonRooms
- startDateTime
- endDateTime
- keyType
- status
- createdAt
properties:
keyId:
type: string
propertyId:
type: string
reservationId:
type: string
subReservationId:
type: string
issuerId:
type: string
guestId:
type: string
nullable: true
rooms:
type: array
items:
type: string
commonRooms:
type: array
items:
type: string
startDateTime:
type: string
format: 'Y-m-d\TH:i:sP'
endDateTime:
type: string
format: 'Y-m-d\TH:i:sP'
encoder:
type: string
nullable: true
keyCode:
type: string
nullable: true
keyType:
type: string
mobileId:
type: string
nullable: true
externalId:
type: string
nullable: true
status:
type: string
errorMessage:
type: string
nullable: true
createdAt:
type: string
updatedAt:
type: string
nullable: true
type: object
DoorLockSettingsCommonRoomRequestSchema:
required:
- id
- name
- doors
properties:
id:
description: 'Common room ID.'
type: string
name:
description: 'Common room name.'
type: string
doors:
description: 'Common room doors.'
type: array
items:
type: string
type: object
DoorLockSettingsCreateRequestSchema:
required:
- encoders
- keyTypes
- commonRooms
properties:
encoders:
description: 'List of supported encoders.'
type: array
items:
$ref: '#/components/schemas/DoorLockSettingsEncoderRequestSchema'
default: []
keyTypes:
description: 'List of supported key types.'
type: array
items:
$ref: '#/components/schemas/DoorLockSettingsKeyTypeRequestSchema'
default: []
commonRooms:
description: 'List of common rooms.'
type: array
items:
$ref: '#/components/schemas/DoorLockSettingsCommonRoomRequestSchema'
default: []
awaitInvalidationConfirmation:
description: 'Wait for the door lock partner to confirm key invalidation before removing the key.'
type: boolean
default: false
example: false
invalidationScope:
description: 'How the lock system cancels keys. `key`: each key can be cancelled on its own. `room`: cancelling a key invalidates every key for its rooms.'
type: string
default: key
enum:
- key
- room
example: key
type: object
DoorLockSettingsDeleteRequestSchema: { }
DoorLockSettingsEncoderRequestSchema:
required:
- id
- name
properties:
id:
type: string
name:
type: string
type: object
DoorLockSettingsKeyTypeRequestSchema:
required:
- id
- name
properties:
id:
type: string
enum:
- key_card
- access_code
- mobile_key
name:
type: string
type: object
DoorLockSettingsSingleRequestSchema:
required:
- propertyId
DoorLockSettingsCommonRoomResponseSchema:
required:
- id
- name
- doors
properties:
id:
type: string
name:
type: string
doors:
description: $doors
type: array
items:
type: string
type: object
DoorLockSettingsEncoderResponseSchema:
required:
- id
- name
properties:
id:
type: string
name:
type: string
type: object
DoorLockSettingsKeyTypeResponseSchema:
required:
- id
- name
properties:
id:
type: string
enum:
- key_card
- access_code
- mobile_key
name:
type: string
type: object
DoorLockSettingsResponseSchema:
required:
- keyTypes
- encoders
- commonRooms
- awaitInvalidationConfirmation
- invalidationScope
properties:
keyTypes:
description: $keyTypes
type: array
items:
$ref: '#/components/schemas/DoorLockSettingsKeyTypeResponseSchema'
encoders:
description: $encoders
type: array
items:
$ref: '#/components/schemas/DoorLockSettingsEncoderResponseSchema'
commonRooms:
description: $commonRooms
type: array
items:
$ref: '#/components/schemas/DoorLockSettingsCommonRoomResponseSchema'
awaitInvalidationConfirmation:
description: 'Wait for the door lock partner to confirm key invalidation before removing the key.'
type: boolean
invalidationScope:
description: 'How the lock system cancels keys. `key`: each key can be cancelled on its own. `room`: cancelling a key invalidates every key for its rooms.'
type: string
default: key
enum:
- key
- room
example: key
type: object
EventCreateRequestSchema:
description: 'Request body for creating a new event'
required:
- name
- sourceId
properties:
name:
description: 'Event name'
type: string
maxLength: 255
example: 'Smith Wedding Reception'
profileId:
description: 'Positive numeric group profile ID to link to this event (not an event ID or group code)'
type: string
example: '987123456489'
nullable: true
status:
description: 'Event status (default: lead)'
type: string
enum:
- lead
- proposal
- tentative
- qualified
- definite
- open
- closed
- closed_lost
- canceled
example: lead
sourceId:
description: 'Source ID for the event booking source'
type: string
example: ss-123456
startDate:
description: 'Event start date (YYYY-MM-DD). NOTE: Informational only - effective event dates are calculated from linked reservations.'
type: string
example: '2025-06-15'
nullable: true
endDate:
description: 'Event end date (YYYY-MM-DD). NOTE: Informational only - effective event dates are calculated from linked reservations.'
type: string
example: '2025-06-17'
nullable: true
transactionMode:
description: 'Transaction routing mode (default: none)'
type: string
enum:
- none
- post_into_group
example: post_into_group
transactionTypes:
description: 'Transaction types to route (required when transactionMode is post_into_group). Matched exactly. Unknown values are stored but never match a transaction. Values by group. Room revenue: rate, roomRevenue_cancellation, roomRevenue_no_show, roomRevenue_manual. By identifier: `product_` from getItems, `tax_` and `fee_` from getTaxesAndFees, `addon_`, `custom_item_`, `bookable_resource_`. Other: channel_commission, accountsReceivable. Payments: the payment method `code` from getPaymentMethods, e.g. cash, cards, check (debit card), check_true (check), ebanking, pay_pal, terminal. Card brands: `cards_` and `terminal_` with cardCode from getPaymentMethods. Bare cards and terminal match only payments recorded without a brand.'
type: array
items:
type: string
example:
- rate
- product_42
- tax_5
- cards
- cards_visa
nullable: true
folioConfigId:
description: 'Folio configuration ID'
type: string
example: '456'
nullable: true
enableAggregateAllotmentBlock:
description: 'Enable aggregate allotment block feature'
type: boolean
example: false
aggregateAllotmentBlockPackageId:
description: 'Package ID for aggregate allotment block'
type: string
example: '123'
nullable: true
segmentId:
description: 'Market segment ID'
type: string
example: '5'
nullable: true
type: object
EventGetRequestSchema:
description: 'Request schema for getting a single event.'
required:
- eventId
properties:
eventId:
description: 'Event ID or event code (e.g., "12345" or "g162795")'
type: string
example: '12345'
type: object
EventListRequestSchema:
description: 'Request parameters for listing events'
properties:
eventCode:
description: 'Filter by event code'
type: string
example: g162795
nullable: true
profileId:
description: 'Filter by GPS profile ID'
type: string
example: '987123456489'
nullable: true
status:
description: 'Filter by event status'
type: string
enum:
- lead
- proposal
- tentative
- qualified
- definite
- open
- closed
- closed_lost
- canceled
example: definite
nullable: true
createdFrom:
description: 'Filter events created after this datetime (RFC 3339 format)'
type: string
example: '2025-01-01T00:00:00Z'
nullable: true
createdTo:
description: 'Filter events created before this datetime (RFC 3339 format)'
type: string
example: '2025-12-31T23:59:59Z'
nullable: true
startDateFrom:
description: 'Filter events where startDate is on or after this date (YYYY-MM-DD format)'
type: string
example: '2025-01-01'
nullable: true
startDateTo:
description: 'Filter events where startDate is on or before this date (YYYY-MM-DD format)'
type: string
example: '2025-12-31'
nullable: true
endDateFrom:
description: 'Filter events where endDate is on or after this date (YYYY-MM-DD format)'
type: string
example: '2025-01-01'
nullable: true
endDateTo:
description: 'Filter events where endDate is on or before this date (YYYY-MM-DD format)'
type: string
example: '2025-12-31'
nullable: true
limit:
description: 'Maximum number of items to return (default: 100, max: 100)'
type: integer
maximum: 100
minimum: 0
example: 100
offset:
description: 'Number of items to skip (default: 0)'
type: integer
minimum: 0
example: 0
type: object
EventNoteCreateRequestSchema:
description: 'Request body for creating an event note'
required:
- text
properties:
eventId:
description: 'Event ID or event code (e.g., "12345" or "g162795")'
type: string
example: '12345'
text:
description: 'Note content'
type: string
maxLength: 10000
example: 'Guest requested late checkout for the wedding party'
type: object
EventNoteListRequestSchema:
description: 'Request parameters for listing event notes'
properties:
eventId:
description: 'Event ID or event code (e.g., "12345" or "g162795")'
type: string
example: '12345'
limit:
description: 'Maximum number of items to return (default: 100, max: 100)'
type: integer
maximum: 100
minimum: 0
example: 100
offset:
description: 'Number of items to skip (default: 0)'
type: integer
minimum: 0
example: 0
includeArchived:
description: 'Include archived notes (default: false)'
type: boolean
example: false
type: object
EventNoteUpdateRequestSchema:
description: 'Request body for updating an event note. At least one field must be provided.'
properties:
eventId:
description: 'Event ID or event code (e.g., "12345" or "g162795")'
type: string
example: '12345'
noteId:
description: 'Note ID'
type: string
example: '456'
text:
description: 'Updated note content'
type: string
maxLength: 10000
example: 'Guest requested late checkout - confirmed with management'
nullable: true
archived:
description: 'Archive the note'
type: boolean
example: true
nullable: true
type: object
EventUpdateRequestSchema:
description: 'Request body for updating an event. Only provided fields are updated. For profileId: omit to keep, null to clear, string to replace.'
properties:
eventId:
description: 'Event ID or event code (e.g., "12345" or "g162795")'
type: string
example: '12345'
profileId:
description: 'Positive numeric group profile ID (not an event ID or group code). Omit to keep unchanged, send null to clear, or send a numeric string to replace.'
type: string
example: '987123456489'
nullable: true
name:
description: 'Event name'
type: string
maxLength: 255
example: 'Smith Wedding Reception - Updated'
nullable: true
status:
description: 'Event status'
type: string
enum:
- lead
- proposal
- tentative
- qualified
- definite
- open
- closed
- closed_lost
- canceled
example: definite
nullable: true
sourceId:
description: 'Source ID for the event booking source'
type: string
example: ss-123456
nullable: true
startDate:
description: 'Event start date (YYYY-MM-DD). NOTE: Informational only - effective event dates are calculated from linked reservations.'
type: string
example: '2025-06-15'
nullable: true
endDate:
description: 'Event end date (YYYY-MM-DD). NOTE: Informational only - effective event dates are calculated from linked reservations.'
type: string
example: '2025-06-17'
nullable: true
transactionMode:
description: 'Transaction routing mode'
type: string
enum:
- none
- post_into_group
example: post_into_group
nullable: true
transactionTypes:
description: 'Transaction types to route (replaces the whole list, omit to keep). An empty array is rejected when the resulting transactionMode is post_into_group and clears the list otherwise. Values: see Create a new event.'
type: array
items:
type: string
example:
- rate
- product_42
- tax_5
- cards
- cards_visa
nullable: true
folioConfigId:
description: 'Folio configuration ID'
type: string
example: '456'
nullable: true
enableAggregateAllotmentBlock:
description: 'Enable aggregate allotment block feature'
type: boolean
example: true
nullable: true
aggregateAllotmentBlockPackageId:
description: 'Package ID for aggregate allotment block'
type: string
example: '123'
nullable: true
segmentId:
description: 'Market segment ID'
type: string
example: '5'
nullable: true
type: object
EventListResponseSchema:
description: 'Paginated list of events'
required:
- success
- offset
- limit
- data
properties:
success:
description: 'Success status'
type: boolean
example: true
offset:
description: 'Number of items skipped (pagination offset)'
type: integer
minimum: 0
example: 0
limit:
description: 'Maximum number of items returned'
type: integer
maximum: 100
minimum: 0
example: 100
data:
description: 'List of events'
type: array
items:
$ref: '#/components/schemas/EventResponseSchema'
type: object
EventNoteListResponseSchema:
description: 'Paginated list of event notes'
required:
- success
- offset
- limit
- data
properties:
success:
description: 'Success status'
type: boolean
example: true
offset:
description: 'Number of items skipped (pagination offset)'
type: integer
minimum: 0
example: 0
limit:
description: 'Maximum number of items returned'
type: integer
maximum: 100
minimum: 0
example: 100
data:
description: 'List of event notes'
type: array
items:
$ref: '#/components/schemas/EventNoteResponseSchema'
type: object
EventNoteResponseSchema:
description: 'Event note response data'
required:
- id
- eventId
- text
- createdBy
- createdAt
- updatedAt
- archived
properties:
id:
description: 'Unique note ID'
type: string
example: '144'
eventId:
description: 'Parent event ID'
type: string
example: '12345'
text:
description: 'Note content'
type: string
example: 'Guest requested late checkout for the wedding party'
createdBy:
description: 'Creator name'
type: string
example: 'John Smith'
createdAt:
description: 'Creation timestamp (RFC 3339)'
type: string
format: date-time
example: '2025-01-15T10:30:00Z'
updatedAt:
description: 'Last update timestamp (RFC 3339)'
type: string
format: date-time
example: '2025-01-15T10:30:00Z'
archived:
description: 'Whether note is archived'
type: boolean
example: false
archivedAt:
description: 'Archive timestamp (RFC 3339)'
type: string
format: date-time
example: '2025-01-20T14:45:00Z'
nullable: true
type: object
EventNoteSingleResponseSchema:
description: 'Single event note response with success envelope'
required:
- success
- data
properties:
success:
description: 'Success status'
type: boolean
example: true
data:
$ref: '#/components/schemas/EventNoteResponseSchema'
type: object
EventResponseSchema:
description: 'Event response data'
required:
- id
- eventCode
- name
- status
- createdAt
- updatedAt
properties:
id:
description: 'Unique event ID'
type: string
example: '12345'
eventCode:
description: 'Event code'
type: string
example: g162795
profileId:
description: 'GPS Profile ID linked to this event'
type: string
example: '987123456489'
nullable: true
name:
description: 'Event name'
type: string
example: 'Smith Wedding Reception'
status:
description: 'Event status'
type: string
enum:
- lead
- proposal
- tentative
- qualified
- definite
- open
- closed
- closed_lost
- canceled
example: definite
sourceId:
description: 'Source ID'
type: string
example: ss-693577
nullable: true
sourceName:
description: 'Source name'
type: string
example: 'Website/Booking Engine'
nullable: true
startDate:
description: 'Event start date (YYYY-MM-DD)'
type: string
format: date
example: '2025-06-15'
nullable: true
endDate:
description: 'Event end date (YYYY-MM-DD)'
type: string
format: date
example: '2025-06-17'
nullable: true
transactionMode:
description: 'Transaction routing mode'
type: string
enum:
- none
- post_into_group
example: post_into_group
transactionTypes:
description: 'Transaction types as stored (no effect when transactionMode is none)'
type: array
items:
type: string
example:
- rate
- product_42
- tax_5
- cards
- cards_visa
nullable: true
folioConfigId:
description: 'Folio configuration ID'
type: string
example: '456'
nullable: true
enableAggregateAllotmentBlock:
description: 'Aggregate allotment block enabled'
type: boolean
example: true
aggregateAllotmentBlockPackageId:
description: 'Package ID for aggregate allotment block'
type: string
example: '123'
nullable: true
segmentId:
description: 'Market segment ID'
type: string
example: '5'
nullable: true
allotmentBlockCount:
description: 'Number of allotment blocks'
type: integer
example: 2
reservationsCount:
description: 'Number of linked reservations'
type: integer
example: 15
roomsHeld:
description: 'Total rooms held'
type: integer
example: 20
roomsPickedUp:
description: 'Rooms picked up'
type: integer
example: 15
roomsRemaining:
description: 'Rooms remaining'
type: integer
example: 5
total:
$ref: '#/components/schemas/MoneySchema'
grandTotal:
$ref: '#/components/schemas/MoneySchema'
paidValue:
$ref: '#/components/schemas/MoneySchema'
balanceDue:
$ref: '#/components/schemas/MoneySchema'
createdAt:
description: 'Creation timestamp (RFC 3339)'
type: string
format: date-time
example: '2025-01-15T10:30:00Z'
updatedAt:
description: 'Last update timestamp (RFC 3339)'
type: string
format: date-time
example: '2025-01-20T14:45:00Z'
type: object
EventSingleResponseSchema:
description: 'Single event response with success envelope'
required:
- success
- data
properties:
success:
description: 'Success status'
type: boolean
example: true
data:
$ref: '#/components/schemas/EventResponseSchema'
type: object
DeleteGratuityRequestSchema:
required:
- gratuityId
properties:
gratuityId:
description: 'The public gratuityId of the gratuity to void (as returned at post time). Voids that single gratuity and its tax children.'
type: string
type: object
GratuitySchema:
description: 'A single tip entry. Recipient is optional; absent recipient is allowed.'
required:
- amount
properties:
amount:
description: 'Gratuity amount in the property currency. Must be > 0; corrections require void + repost (negative amounts rejected).'
type: string
pattern: '^\d+(\.\d{1,4})?$'
example: '8.00'
nullable: true
taxes:
description: 'Optional tax rows applied to this gratuity. Each tax follows the item-tax pattern — identify the tax by exactly one of `externalId` / `taxId`; an unmatched value returns TAX_NOT_FOUND.'
type: array
items:
$ref: '#/components/schemas/TaxSchema'
note:
description: 'Free-text label displayed on the folio line item.'
type: string
example: 'Tip for Maria'
nullable: true
customTransactionCode:
description: 'Override the property default Custom Transaction Code for this posting.'
type: string
example: GRT-VIP
nullable: true
generalLedgerCustomCode:
description: 'Override the property default GL custom code for this posting.'
type: string
example: GL-2410
nullable: true
subReservationId:
description: 'Sub-reservation identifier. If provided, this gratuity entry is routed to the specified sub-reservation within the parent reservation (request-level reservationId). If omitted on a reservation with a single stay and no gratuity entry in the request carries a subReservationId, the gratuity is attributed to the room assigned to that stay; when the stay is split across rooms because of an in-stay move, the room assigned on the sale date is used. Multi-stay reservations, and requests that set subReservationId on only some gratuities, need an explicit identifier on each gratuity for room attribution. Has no effect when the request-level target is houseAccountId or eventCode.'
type: string
example: SUB123
nullable: true
recipient:
oneOf:
-
$ref: '#/components/schemas/RecipientSchema'
nullable: true
description: 'Recipient attribution. All sub-fields optional; absent recipient is allowed.'
gratuityId:
description: 'Optional partner-supplied public handle for this gratuity (accept-or-generate). When omitted, Cloudbeds generates one and returns it. Must be a non-empty string containing only letters, digits, and . _ ~ -, unique among active (non-voided) gratuities on the property; reusable after this gratuity is voided. Used to address the gratuity for void (DELETE /folio/v1/gratuities/{gratuityId}).'
type: string
maxLength: 255
pattern: '^[A-Za-z0-9._~-]+$'
example: partner-grat-7a3f
nullable: true
type: object
PostCheckGratuityRequestSchema:
description: 'Request body for posting tips onto an existing check. The check is identified by the `checkId` path parameter, so the body carries only the gratuity entries — a `checkId` sent in the body is ignored. The tips inherit the check''s folio target and check number; POS context stays an attribute of the check and is not copied onto them. Retry-safety is the required Idempotency-Key header. For a tip with no associated check, use POST /folio/v1/gratuities.'
required:
- gratuities
properties:
gratuities:
description: 'Gratuity entries to post to the check. At least one entry required. Each entry becomes its own folio line item and its own Accounting Service transaction.'
type: array
items:
$ref: '#/components/schemas/GratuitySchema'
type: object
PostGratuityRequestSchema:
description: 'Request body for the standalone postGratuity endpoint (a tip with no check). Exactly one of reservationId / houseAccountId / eventCode must be provided. Sub-reservation routing is per-gratuity via GratuitySchema.subReservationId. To link tips to a check, use POST /folio/v1/checks/{checkId}/gratuities instead — checkId / checkNumber / POS context are check attributes and are not accepted here.'
required:
- gratuities
properties:
reservationId:
description: 'Reservation identifier. Required if houseAccountId and eventCode are not provided.'
type: string
example: RES123456
nullable: true
houseAccountId:
description: 'House account identifier. Required if reservationId and eventCode are not provided.'
type: string
example: '123456'
nullable: true
eventCode:
description: 'Event code. Required if reservationId and houseAccountId are not provided.'
type: string
example: GRP2025
nullable: true
folioId:
description: 'Folio identifier within the chosen account target. Numeric string (the underlying folio_id is a 64-bit unsigned integer). Optional — when omitted, the default folio for the target is used.'
type: string
example: '12345'
nullable: true
gratuities:
description: 'Gratuity entries to post. At least one entry required. Each entry becomes its own folio line item and its own Accounting Service transaction.'
type: array
items:
$ref: '#/components/schemas/GratuitySchema'
type: object
oneOf:
-
required:
- reservationId
-
required:
- houseAccountId
-
required:
- eventCode
RecipientSchema:
description: 'Recipient attribution for a gratuity. All three fields are optional and independent. When more than one is provided, resolution priority is: userId > email > name.'
properties:
userId:
description: 'Cloudbeds user ID; must reference a valid user on the property or RECIPIENT_USER_NOT_FOUND is returned.'
type: string
example: usr_4821
nullable: true
email:
description: 'Recipient email; resolved to a user record if userId not provided.'
type: string
example: maria.santos@cloudbeds.com
nullable: true
name:
description: 'Free-text recipient name; always stored as a display string regardless of whether a user record is resolved.'
type: string
example: 'Maria Santos'
nullable: true
type: object
GratuityErrorCodeEnumSchema:
description: 'Machine-readable error code returned in BadRequest / Conflict / NotFound responses for postGratuity. Aligned with the structured error approach used by STS Gen2 and the Accounting API.'
type: string
enum:
- ACCOUNT_NOT_FOUND
- FOLIO_NOT_FOUND
- TAX_NOT_FOUND
- INVALID_AMOUNT
- RECIPIENT_USER_NOT_FOUND
- SUBRESERVATION_NOT_FOUND
- CHECK_NOT_FOUND
- IDEMPOTENCY_KEY_REUSED
- DUPLICATE_GRATUITY_ID
- GRATUITY_NOT_FOUND
- GRATUITY_VOID_UNAVAILABLE
PostGratuityResponseSchema:
required:
- data
properties:
data:
$ref: '#/components/schemas/PostedGratuityResponseSchema'
type: object
PostedGratuityResponseSchema:
description: 'Result of a postGratuity call. gratuityIds are the Cloudbeds-assigned public handles of the posted gratuities — one per gratuities[] entry — each addressable for void via DELETE /folio/v1/gratuities/{gratuityId}.'
required:
- gratuityIds
properties:
gratuityIds:
description: 'Public handles of the posted gratuities, one per gratuities[] entry. Each is addressable for void via DELETE /folio/v1/gratuities/{gratuityId}.'
type: array
items:
type: string
example:
- '9911283'
- '9911284'
notice:
description: 'Set when this request replayed an earlier one: the same Idempotency-Key was sent with the same body. When present, no new posting was created and the original response is returned.'
type: string
example: 'Duplicate Idempotency-Key — returning original posting.'
nullable: true
type: object
AvailabilitySearchRequestSchema:
required:
- propertyIds
- startDate
- endDate
properties:
propertyIds:
description: 'Property IDs to check availability for (max 20)'
type: array
items:
type: integer
example:
- 101
- 102
- 103
startDate:
description: 'Check-in date (YYYY-MM-DD)'
type: string
example: '2026-04-04'
endDate:
description: 'Check-out date (YYYY-MM-DD)'
type: string
example: '2026-04-06'
adults:
description: 'Number of adults'
type: integer
example: 2
children:
description: 'Number of children'
type: integer
example: 0
type: object
PropertySearchRequestSchema:
properties:
city:
description: 'City name to search for (partial match)'
type: string
example: 'San Diego'
nullable: true
latitude:
description: 'Latitude for geo-based search'
type: number
format: float
example: 32.7157
nullable: true
longitude:
description: 'Longitude for geo-based search'
type: number
format: float
example: -117.1611
nullable: true
radiusKm:
description: 'Search radius in kilometers (requires latitude/longitude)'
type: number
format: float
example: 25
nullable: true
limit:
description: 'Maximum number of results (max 20)'
type: integer
example: 20
offset:
description: 'Number of results to skip'
type: integer
example: 0
type: object
AvailabilitySearchResponseSchema:
required:
- data
properties:
data:
description: 'Properties with available room types'
type: array
items:
$ref: '#/components/schemas/PropertyAvailabilityResponseSchema'
type: object
PropertyAvailabilityResponseSchema:
required:
- propertyId
- propertyName
- currencyCode
- roomTypes
properties:
propertyId:
type: integer
example: 276
propertyName:
type: string
example: 'Seaside Inn San Diego'
currencyCode:
type: string
example: USD
roomTypes:
description: 'Available room types with rates'
type: array
items:
$ref: '#/components/schemas/RoomTypeAvailabilityResponseSchema'
type: object
PropertySearchResponseSchema:
required:
- data
- total
- limit
- offset
properties:
data:
description: 'List of matching properties'
type: array
items:
$ref: '#/components/schemas/PropertySummaryResponseSchema'
total:
description: 'Total number of matching properties'
type: integer
example: 42
limit:
type: integer
example: 20
offset:
type: integer
example: 0
type: object
PropertySummaryResponseSchema:
required:
- propertyId
- propertyName
- propertyType
- city
- state
- country
- latitude
- longitude
- currencyCode
- timezone
properties:
propertyId:
type: integer
example: 276
propertyName:
type: string
example: 'Seaside Inn San Diego'
propertyType:
type: string
example: Hotel
city:
type: string
example: 'San Diego'
state:
type: string
example: CA
country:
type: string
example: US
latitude:
type: number
format: float
example: 32.7157
longitude:
type: number
format: float
example: -117.1611
currencyCode:
type: string
example: USD
timezone:
type: string
example: America/Los_Angeles
distanceKm:
description: 'Distance from search coordinates in km'
type: number
format: float
example: 3.45
nullable: true
type: object
RoomTypeAvailabilityResponseSchema:
required:
- roomTypeId
- roomTypeName
- maxGuests
- roomsAvailable
- minRate
- maxRate
properties:
roomTypeId:
type: integer
example: 713
roomTypeName:
type: string
example: 'Deluxe King Room'
maxGuests:
type: integer
example: 2
roomsAvailable:
description: 'Minimum rooms available across all dates'
type: integer
example: 3
minRate:
description: 'Lowest nightly rate across the date range'
type: number
format: float
example: 149.99
maxRate:
description: 'Highest nightly rate across the date range'
type: number
format: float
example: 199.99
type: object
InspectionItemSchema:
required:
- updatedDate
- roomTypeId
- roomId
- roomCondition
- roomBlocked
- frontdeskStatus
- housekeeperId
- doNotDisturb
- refusedService
- vacantPickup
- roomNote
properties:
updatedDate:
type: string
roomTypeId:
type: string
roomId:
type: string
roomCondition:
type: string
roomOccupied:
type: boolean
roomBlocked:
type: boolean
frontdeskStatus:
type: string
housekeeperId:
type: string
doNotDisturb:
type: boolean
refusedService:
type: boolean
vacantPickup:
type: boolean
roomNote:
type: string
nullable: true
type: object
InspectionListRequestSchema:
type: object
allOf:
-
$ref: '#/components/schemas/LimitOffsetPaginationSchema'
-
$ref: '#/components/schemas/QueryParameterDynamicFilterSchema'
InspectionListResponseSchema:
required:
- limit
- offset
- data
properties:
limit:
description: 'The limit for the number of items to return'
type: integer
offset:
description: 'The offset for the current page of results'
type: integer
data:
description: 'The list of data objects'
type: array
items:
$ref: '#/components/schemas/InspectionItemSchema'
type: object
InspectionListSchema:
type: array
items:
$ref: '#/components/schemas/InspectionItemSchema'
ImportTaskCreateRequestSchema:
required:
- type
properties:
type:
description: 'Import task type.'
type: string
enum:
- addon
- group
- item
- reservation
- room_type
- rooming_list
priority:
description: 'Import task priority.'
type: string
enum:
- standard
- high
type: object
ImportTaskGetRecordListRequestSchema:
type: object
allOf:
-
$ref: '#/components/schemas/LimitOffsetPaginationSchema'
-
$ref: '#/components/schemas/QueryParameterDynamicFilterSchema'
ImportTaskGetRequestSchema:
type: object
ImportTaskListRequestSchema:
type: object
allOf:
-
$ref: '#/components/schemas/LimitOffsetPaginationSchema'
-
$ref: '#/components/schemas/QueryParameterDynamicFilterSchema'
-
properties:
includeChildren:
description: 'Include child tasks.'
type: boolean
default: false
example: true
nullable: true
type: object
ImportTaskReimportRequestSchema:
properties:
priority:
description: 'Import task priority.'
type: string
enum:
- standard
- high
nullable: true
reprocessFailedRecords:
description: 'Re-process failed records of parent task.'
type: boolean
nullable: true
type: object
ImportTaskReprocessRequestSchema:
type: object
ImportTaskToggleProcessingRequestSchema:
properties:
action:
description: 'Action to perform on the import task'
type: string
enum:
- start
- stop
example: start
type: object
ImportChangeStatusTaskResponse:
required:
- message
properties:
message:
type: string
type: object
ImportFailedChangeStatusTaskResponse:
required:
- message
properties:
message:
type: string
type: object
ImportFailedToCreateImportTaskSchema:
required:
- message
properties:
message:
type: string
type: object
ImportFailedToPreProcessResponseSchema:
required:
- message
properties:
message:
type: string
type: object
ImportFailedToProcessCsvResponseSchema:
required:
- message
properties:
message:
type: string
type: object
ImportTaskActionNotAllowedResponse:
required:
- message
properties:
message:
type: string
type: object
ImportTaskGetResponseSchema:
required:
- id
- name
- source
- parsedRecordsCount
- importedRecordsCount
- type
- priority
- fileStatus
- importStatus
properties:
id:
type: string
name:
type: string
source:
type: string
parsedRecordsCount:
type: string
importedRecordsCount:
type: string
type:
description: 'Import task type.'
type: string
enum:
- addon
- allotment_block
- event
- item
- reservation
- room_type
priority:
description: 'Import task priority.'
type: string
enum:
- standard
- high
- low
fileStatus:
type: string
importStatus:
description: 'Import task status.'
type: string
enum:
- uploaded
- parsing
- parsing_complete
- parsing_complete_with_errors
- updates_parsing_complete
- processing
- complete
- complete_with_errors
- error_file_handler
- error_file_resource
- error_file_parsing
- error_file_empty
- error_missing_columns
createdAt:
type: string
errors:
type: string
nullable: true
userId:
description: 'ID of the user who created the import task.'
type: string
updatedAt:
description: 'When the task last changed, RFC3339.'
type: string
parentId:
description: 'Parent task ID when this task re-imports failed records of another task.'
type: string
nullable: true
type: object
ImportTaskListFailedResponseSchema:
required:
- message
properties:
message:
type: string
type: object
ImportTaskListResponseSchema:
required:
- offset
- limit
- total
- data
properties:
offset:
type: integer
limit:
type: integer
total:
type: integer
data:
description: 'Logical operator grouping filters or nested logical groups'
type: array
items:
$ref: '#/components/schemas/ImportTaskGetResponseSchema'
type: object
ImportTaskRecordGetResponseSchema:
description: 'Import task record.'
required:
- id
- importId
- uuid
- createdAt
- propertyId
- objectId
- importStatus
- errors
- importAttemptedAt
- data
properties:
id:
type: string
importId:
type: string
uuid:
type: string
createdAt:
type: string
propertyId:
type: integer
objectId:
type: integer
nullable: true
importStatus:
description: 'Import task status.'
type: string
enum:
- uploaded
- parsing
- parsing_complete
- parsing_complete_with_errors
- processing
- complete
- complete_with_errors
- error_file_handler
- error_file_resource
- error_file_parsing
- error_file_empty
- error_missing_columns
errors:
type: string
importAttemptedAt:
type: string
nullable: true
data:
type: string
type: object
ImportTaskRecordListResponseSchema:
description: 'List of import task records.'
required:
- offset
- limit
- total
- data
properties:
offset:
type: integer
limit:
type: integer
total:
type: integer
data:
description: 'List of import task records.'
type: array
items:
$ref: '#/components/schemas/ImportTaskRecordGetResponseSchema'
type: object
ImportTaskResponseSchema:
required:
- id
- uploadUrl
properties:
id:
type: string
uploadUrl:
description: 'A temporary URL, valid for 10 minutes, used to upload the import file.'
type: string
type: object
IntegrationEventCreateRequestSchema:
required:
- propertyId
- objectType
- system
- status
- result
properties:
objectType:
description: 'Type of object related to the integration event.'
type: string
example: reservation
system:
description: 'System where the integration event occurred.'
type: string
example: gov
status:
description: 'Status of the integration event.'
type: string
enum:
- open
- completed
example: open
result:
description: 'Result of the integration event.'
type: string
enum:
- failure
- success
- action_required
- warning
example: success
objectId:
description: 'ID of object related to the integration event.'
type: string
default: null
example: '1234567890'
nullable: true
description:
description: 'Description of the integration event. Required when result is failure.'
type: string
default: null
example: 'Integration event description'
nullable: true
details:
description: 'Details of the integration event, that usually contain instructions.'
type: string
default: null
example: 'You need to check room mappings.'
nullable: true
actionText:
description: 'Text to be displayed on the UI for the action.'
type: string
default: null
example: Retry
nullable: true
retryUrl:
description: 'URL that is used to retry the action.'
type: string
default: null
example: 'https://example.com/retry'
nullable: true
type: object
IntegrationEventListRequestSchema:
type: object
allOf:
-
$ref: '#/components/schemas/LimitOffsetPaginationSchema'
-
$ref: '#/components/schemas/QueryParameterDynamicFilterSchema'
-
$ref: '#/components/schemas/QueryParameterSortSchema'
-
properties:
search:
description: 'Words to look for in the id, objectId, system, description and details of each event; every word must match. Text in double quotes is matched as one phrase.'
type: string
maxLength: 255
nullable: true
type: object
IntegrationEventRetryRequestSchema: { }
IntegrationEventUpdateRequestSchema:
required:
- status
properties:
status:
description: 'Status of the integration event.'
type: string
enum:
- open
- completed
example: open
result:
description: 'Result of the integration event. When provided, description and details are replaced with the values sent (omitted ones are cleared).'
type: string
default: null
enum:
- failure
- success
- action_required
- warning
example: success
nullable: true
description:
description: 'Description of the integration event. Required when result is failure.'
type: string
default: null
example: 'Integration event description'
nullable: true
details:
description: 'Details of the integration event, that usually contain instructions.'
type: string
default: null
example: 'You need to check room mappings.'
nullable: true
type: object
IntegrationEventCollectionResponseSchema:
required:
- items
type: array
items:
$ref: '#/components/schemas/IntegrationEventResponseSchema'
IntegrationEventListResponseSchema:
required:
- data
- total
properties:
data:
$ref: '#/components/schemas/IntegrationEventCollectionResponseSchema'
total:
description: 'The total number of items available'
type: integer
example: 100
type: object
IntegrationEventResponseSchema:
required:
- id
- propertyId
- objectType
- system
- status
- result
- createdAt
properties:
id:
description: 'Unique identifier for the integration event.'
type: string
example: '123456'
propertyId:
description: 'Unique identifier for the property.'
type: string
example: '123456'
objectId:
description: 'Unique identifier for the object associated with the integration event.'
type: string
example: '123456'
nullable: true
objectType:
description: 'Type of object associated with the integration event.'
type: string
example: reservation
system:
description: 'Type of system associated with the integration event.'
type: string
example: gov
status:
description: 'Status of the integration event.'
type: string
enum:
- open
- completed
example: open
result:
description: 'Result of the integration event.'
type: string
enum:
- failure
- success
- action_required
- warning
example: success
description:
description: 'Short description of the integration event.'
type: string
example: 'Integration event description.'
nullable: true
details:
description: 'Detailed information about the integration event.'
type: string
example: 'Integration event details.'
nullable: true
actionText:
description: 'Text to be displayed for the action associated with the integration event.'
type: string
example: Retry
nullable: true
createdAt:
type: string
format: 'Y-m-d\TH:i:sP'
example: '2023-10-01T12:00:00Z'
updatedAt:
type: string
format: 'Y-m-d\TH:i:sP'
example: '2023-10-01T12:00:00Z'
nullable: true
retriedAt:
type: string
format: 'Y-m-d\TH:i:sP'
example: '2023-10-01T12:00:00Z'
nullable: true
type: object
CustomItemListRequestSchema:
allOf:
-
$ref: '#/components/schemas/LimitOffsetPaginationSchema'
-
$ref: '#/components/schemas/QueryParameterDynamicFilterSchema'
-
$ref: '#/components/schemas/QueryParameterSortSchema'
ItemModifierRequestSchema:
required:
- modifierOptionId
properties:
modifierOptionId:
description: 'Modifier option identifier'
type: string
example: '9102'
quantity:
description: 'How many times the option is applied per item unit'
type: integer
example: 1
type: object
ItemRequestSchema:
required:
- itemId
- itemQuantity
properties:
itemId:
description: 'Item identifier'
type: string
example: '123456'
itemQuantity:
description: 'Item quantity (must be greater than 0)'
type: integer
example: 2
itemPrice:
description: 'Custom item price in the smallest currency unit (e.g., cents for USD). If not provided, the item''s registered price plus selected modifier options will be used. For example, $10.50 should be sent as ''1050''.'
type: string
example: '1050'
nullable: true
itemNote:
description: 'Optional item note'
type: string
example: 'Extra towels requested'
nullable: true
subReservationId:
description: 'Sub-reservation identifier (optional)'
type: string
example: SUB123
nullable: true
payments:
description: 'Optional list of payments for this item. If provided, itemPaid is ignored.'
type: array
items:
$ref: '#/components/schemas/PaymentRequestSchema'
itemPaid:
description: 'If true, a cash payment will be automatically registered for the total value of the item including taxes and fees. Ignored if payments array is provided.'
type: boolean
example: false
modifiers:
description: 'Modifier options selected for this item.'
type: array
items:
$ref: '#/components/schemas/ItemModifierRequestSchema'
type: object
ModifierAssignmentItemRequestSchema:
required:
- itemId
properties:
categoryId:
description: 'Informational; the item''s category is resolved server-side.'
type: string
example: '771'
nullable: true
itemId:
type: string
example: '920001'
type: object
ModifierAssignmentsRequestSchema:
required:
- groupId
properties:
groupId:
type: string
example: '812001'
categories:
type: array
items:
type: string
items:
type: array
items:
$ref: '#/components/schemas/ModifierAssignmentItemRequestSchema'
type: object
ModifierBulkAssignRequestSchema:
required:
- itemIds
properties:
itemIds:
type: array
items:
type: string
addGroupIds:
type: array
items:
type: string
removeGroupIds:
type: array
items:
type: string
type: object
ModifierGroupIdRequestSchema:
required:
- groupId
properties:
groupId:
type: string
example: '812001'
type: object
ModifierGroupListRequestSchema: { }
ModifierGroupOrderRequestSchema:
required:
- groupIds
properties:
groupIds:
description: 'Every modifier group id of the property, active and inactive, in the new order.'
type: array
items:
type: string
type: object
ModifierGroupWriteRequestSchema:
required:
- name
- options
properties:
groupId:
description: 'Group id from the path on PUT; ignored on POST.'
type: string
name:
description: 'Multilang name, keyed by language code.'
type: object
example:
en: Milk
minSelections:
description: '0 means optional; 1 or more means required.'
type: integer
example: 1
maxSelections:
description: 'Null means unlimited; 1 means pick one.'
type: integer
example: 1
nullable: true
allowRepeat:
description: 'Whether one option may be chosen more than once.'
type: boolean
example: false
guestVisible:
description: 'False means kitchen-only: never shown to the guest and every option must be free.'
type: boolean
example: true
isActive:
description: 'Switch the group on or off. Inactive groups stay editable here but are not offered at the point of sale and are rejected at posting.'
type: boolean
example: true
options:
type: array
items:
$ref: '#/components/schemas/ModifierOptionRequestSchema'
minItems: 1
type: object
ModifierOptionRequestSchema:
required:
- name
- price
properties:
id:
description: 'Existing option id to update. Omit for a new option.'
type: string
example: '812003'
nullable: true
name:
description: 'Multilang name, keyed by language code.'
type: object
example:
en: 'Oat milk'
es: 'Leche de avena'
info:
description: 'Optional multilang description.'
type: object
example:
en: 'Barista blend'
nullable: true
price:
description: 'Add-on charge, decimal string with no more decimals than the property currency allows (at most 4).'
type: string
example: '0.50'
isDefault:
type: boolean
example: false
type: object
PaymentRequestSchema:
required:
- paymentType
- amount
properties:
paymentType:
description: 'Payment method type. Use getPaymentMethods API to retrieve available payment methods for the property.'
type: string
example: cash
amount:
description: 'Payment amount in the smallest currency unit (e.g., cents for USD). For example, $10.50 should be sent as ''1050''.'
type: string
example: '1050'
notes:
description: 'Optional payment notes'
type: string
example: 'Paid at check-in'
nullable: true
type: object
PostItemsRequestSchema:
required:
- items
properties:
reservationId:
description: 'Reservation identifier. Required if houseAccountId and eventCode are not provided.'
type: string
example: RES123456
nullable: true
houseAccountId:
description: 'House account identifier. Required if reservationId and eventCode are not provided.'
type: string
example: '123456'
nullable: true
eventCode:
description: 'Event code. Required if reservationId and houseAccountId are not provided.'
type: string
example: GRP2025
nullable: true
saleDate:
description: 'Sale date in RFC 3339 format. If not provided, current timestamp will be used.'
type: string
example: '2025-10-06T14:30:00-07:00'
nullable: true
items:
description: 'Array of items to post (minimum 1 item required)'
type: array
items:
$ref: '#/components/schemas/ItemRequestSchema'
type: object
oneOf:
-
required:
- reservationId
-
required:
- houseAccountId
-
required:
- eventCode
CustomItemCollectionResponseSchema:
required:
- items
type: array
items:
$ref: '#/components/schemas/CustomItemResponseSchema'
CustomItemListResponseSchema:
required:
- data
- total
properties:
data:
$ref: '#/components/schemas/CustomItemCollectionResponseSchema'
total:
description: 'Total number of items'
type: integer
example: 100
type: object
CustomItemResponseSchema:
required:
- id
- propertyId
- sourceId
- sourceName
- appItemId
- name
properties:
id:
description: 'Unique identifier for the custom item'
type: string
example: '123456'
name:
description: 'Item name'
type: string
example: Coffee
propertyId:
description: 'Property ID'
type: string
example: '123456'
sourceId:
description: 'Source ID (POS app ID)'
type: string
example: '123456'
sourceName:
description: 'Source name (POS app name)'
type: string
example: 'Restaurant POS'
appItemId:
description: 'App item ID'
type: string
example: ITEM-001
sku:
description: SKU
type: string
example: SKU123
nullable: true
categoryName:
description: 'Category name'
type: string
example: Beverages
nullable: true
description:
description: 'Item description'
type: string
example: 'Fresh brewed coffee'
nullable: true
type: object
ModifierAssignmentItemResponseSchema:
required:
- categoryId
- itemId
properties:
categoryId:
description: 'Category of the item.'
type: string
example: '3001'
nullable: true
itemId:
type: string
example: '4001'
type: object
ModifierAssignmentSummaryResponseSchema:
required:
- categories
- items
properties:
categories:
description: 'Number of assigned categories.'
type: integer
example: 1
items:
description: 'Number of directly assigned items.'
type: integer
example: 2
type: object
ModifierAssignmentsResponseSchema:
required:
- categories
- items
properties:
categories:
type: array
items:
type: string
example:
- '3001'
items:
type: array
items:
$ref: '#/components/schemas/ModifierAssignmentItemResponseSchema'
type: object
ModifierBulkAssignGroupResponseSchema:
required:
- groupId
- categories
- items
properties:
groupId:
type: string
example: '812001'
categories:
type: array
items:
type: string
example:
- '3001'
items:
type: array
items:
$ref: '#/components/schemas/ModifierAssignmentItemResponseSchema'
type: object
ModifierBulkAssignResponseSchema:
required:
- groups
properties:
groups:
type: array
items:
$ref: '#/components/schemas/ModifierBulkAssignGroupResponseSchema'
type: object
ModifierCoverageGroupResponseSchema:
required:
- id
- name
- isActive
- source
properties:
id:
type: string
example: '812001'
name:
type: string
example: Milk
isActive:
type: boolean
example: true
source:
type: string
enum:
- category
- item
example: category
type: object
ModifierCoverageItemResponseSchema:
required:
- itemId
- itemName
- categoryId
- categoryName
- groups
properties:
itemId:
type: string
example: '4001'
itemName:
type: string
example: Latte
categoryId:
type: string
example: '3001'
nullable: true
categoryName:
type: string
example: Drinks
nullable: true
groups:
type: array
items:
$ref: '#/components/schemas/ModifierCoverageGroupResponseSchema'
type: object
ModifierCoverageResponseSchema:
required:
- data
properties:
data:
type: array
items:
$ref: '#/components/schemas/ModifierCoverageItemResponseSchema'
type: object
ModifierGroupListResponseSchema:
required:
- data
properties:
data:
type: array
items:
$ref: '#/components/schemas/ModifierGroupResponseSchema'
type: object
ModifierGroupResponseSchema:
required:
- id
- name
- minSelections
- maxSelections
- allowRepeat
- guestVisible
- sortOrder
- isActive
- options
- assignmentSummary
- createdAt
- updatedAt
properties:
id:
type: string
example: '812001'
name:
type: object
example:
en: Milk
minSelections:
type: integer
example: 1
maxSelections:
type: integer
example: 1
nullable: true
allowRepeat:
type: boolean
example: false
guestVisible:
type: boolean
example: true
sortOrder:
type: integer
example: 0
isActive:
description: 'Whether staff have the group switched on. Inactive groups are listed here but hidden from the point of sale.'
type: boolean
example: true
options:
type: array
items:
$ref: '#/components/schemas/ModifierOptionResponseSchema'
assignmentSummary:
$ref: '#/components/schemas/ModifierAssignmentSummaryResponseSchema'
createdAt:
type: string
format: date-time
example: '2026-10-19T10:41:02Z'
updatedAt:
type: string
format: date-time
example: '2026-10-19T10:41:02Z'
type: object
ModifierOptionResponseSchema:
required:
- id
- name
- info
- price
- isDefault
- sortOrder
properties:
id:
type: string
example: '812101'
name:
type: object
example:
en: 'Oat milk'
info:
type: object
example:
en: 'Barista blend'
nullable: true
price:
description: 'Add-on charge with at least two decimals, and more when the currency uses them.'
type: string
example: '0.50'
isDefault:
type: boolean
example: false
sortOrder:
type: integer
example: 0
type: object
ModifierRuleViolationResponseSchema:
description: 'A modifier write that is well-formed but breaks a group rule. Same envelope as 400, status 422.'
required:
- message
- code
properties:
message:
type: string
example: 'Kitchen-only groups cannot have priced options.'
errors:
oneOf:
-
$ref: '#/components/schemas/BadRequestErrorListSchema'
nullable: true
description: 'Field-level details, when the rule points at one field.'
code:
description: 'Stable code naming the rule.'
type: string
example: modifier_group.kitchen_only_priced_option
type: object
PostItemsResponseSchema:
required:
- data
properties:
data:
description: 'Array of posted item results, one for each item in the request'
type: array
items:
$ref: '#/components/schemas/PostedItemResponseSchema'
type: object
PostedItemResponseSchema:
required:
- soldProductId
- externalRelationId
properties:
soldProductId:
description: 'Sold product identifier (can be used to void this product in the future)'
type: string
example: '382900'
externalRelationId:
description: 'External relation ID (same as sold product ID). Together with external relation kind (ITEM) it can be used to get transaction from Accounting API'
type: string
example: '382900'
transactionStatus:
description: 'Transaction status. Returns ''pending'' when sale date is in the future, ''completed'' otherwise.'
type: string
enum:
- pending
- completed
example: completed
nullable: true
remainingItemQuantity:
description: 'Remaining number of items in stock (only returned if item has stock inventory tracking enabled)'
type: integer
example: 10
nullable: true
reorderNeeded:
description: 'Whether item is at or below the reorder threshold (only returned if item has stock inventory tracking enabled)'
type: boolean
example: false
nullable: true
stopSellMet:
description: 'Whether item is at or below the stop-sell threshold (only returned if item has stock inventory tracking enabled)'
type: boolean
example: false
nullable: true
type: object
GroupCreateRequestSchema:
required:
- name
- code
- description
properties:
name:
description: 'Group name.'
type: string
example: Abc
code:
description: 'Group code.'
type: string
maxLength: 16
example: '1000'
description:
description: 'Group description.'
type: string
example: 'This is a group'
type: object
GroupDeleteRequestSchema:
required:
- id
properties:
id:
description: 'Group ID.'
type: string
example: 1-b
type: object
GroupDisableRequestSchema:
required:
- id
properties:
id:
description: 'Group ID.'
type: string
example: 1-b
type: object
GroupEnableRequestSchema:
required:
- id
properties:
id:
description: 'Group ID.'
type: string
example: 1-b
type: object
GroupSingleRequestSchema:
required:
- id
properties:
id:
description: 'Group ID.'
type: string
example: 1-b
type: object
GroupUpdateRequestSchema:
required:
- id
- name
- code
- description
properties:
id:
description: 'Group ID.'
type: string
example: 1-b
name:
description: 'Group name.'
type: string
example: Abc
code:
description: 'Group code.'
type: string
maxLength: 16
example: '1000'
description:
description: 'Group description.'
type: string
example: 'This is a group'
type: object
SegmentCreateRequestSchema:
required:
- groupId
- name
- code
- description
- isEnabled
- ratePlanIds
properties:
groupId:
description: 'Group ID.'
type: string
example: 1-b
name:
description: 'Segment name.'
type: string
example: Abc
code:
description: 'Segment code.'
type: string
maxLength: 16
example: '1000'
description:
description: 'Segment description.'
type: string
example: 'This is a Segment'
isEnabled:
description: 'Is Segment enabled?.'
type: boolean
example: true
ratePlanIds:
description: 'List of Rate Plan IDs.'
type: array
items:
type: string
example:
- 1-a
- 2-b
- 3-c
type: object
SegmentDefaultRequestSchema:
required:
- id
properties:
id:
description: 'Segment ID.'
type: string
example: 1-b
type: object
SegmentDeleteRequestSchema:
required:
- id
properties:
id:
description: 'Segment ID.'
type: string
example: 1-b
type: object
SegmentDisableRequestSchema:
required:
- id
properties:
id:
description: 'Segment ID.'
type: string
example: 1-b
type: object
SegmentEnableRequestSchema:
required:
- id
properties:
id:
description: 'Segment ID.'
type: string
example: 1-b
type: object
SegmentListRequestSchema:
type: object
allOf:
-
$ref: '#/components/schemas/LimitOffsetPaginationSchema'
-
$ref: '#/components/schemas/QueryParameterDynamicFilterSchema'
-
properties:
enabled:
description: 'List only enabled segments.'
type: boolean
default: false
example: 'false'
type: object
SegmentListReservationsRequestSchema:
required:
- id
type: object
allOf:
-
$ref: '#/components/schemas/LimitOffsetPaginationSchema'
-
properties:
id:
description: 'Segment ID.'
type: string
example: 1-b
active:
description: 'List only active reservations.'
type: boolean
type: object
SegmentSingleRequestSchema:
required:
- id
properties:
id:
description: 'Segment ID.'
type: string
example: 1-b
type: object
SegmentUpdateRequestSchema:
required:
- id
- groupId
- name
- code
- description
- isEnabled
- ratePlanIds
properties:
id:
description: 'Segment ID.'
type: string
example: 1-b
groupId:
description: 'Group ID.'
type: string
example: 1-b
name:
description: 'Segment name.'
type: string
example: Abc
code:
description: 'Segment code.'
type: string
maxLength: 16
example: '1000'
description:
description: 'Segment description.'
type: string
example: 'This is a Segment'
isEnabled:
description: 'Is Segment enabled?.'
type: boolean
example: true
ratePlanIds:
description: 'List of Rate Plan IDs.'
type: array
items:
type: string
example:
- 1-a
- 2-b
- 3-c
type: object
GroupListResponseSchema:
properties:
limit:
type: integer
offset:
type: integer
data:
type: array
items:
$ref: '#/components/schemas/GroupResponseSchema'
nullable: true
type: object
GroupResponseSchema:
properties:
id:
type: string
name:
type: string
code:
type: string
description:
type: string
canEdit:
type: array
items:
type: string
canDelete:
type: boolean
canDisable:
type: boolean
createdAt:
type: string
format: 'Y-m-d\TH:i:sP'
updatedAt:
type: string
format: 'Y-m-d\TH:i:sP'
nullable: true
type: object
SegmentListReservationsResponseSchema:
properties:
id:
type: string
limit:
type: integer
offset:
type: integer
reservationIds:
type: array
items:
type: string
nullable: true
type: object
SegmentListResponseSchema:
properties:
limit:
type: integer
offset:
type: integer
data:
type: array
items:
$ref: '#/components/schemas/SegmentResponseSchema'
nullable: true
type: object
SegmentResponseSchema:
properties:
id:
type: string
groupId:
type: string
name:
type: string
code:
type: string
description:
type: string
isEnabled:
type: boolean
isDefault:
type: boolean
ratePlanIds:
type: array
items:
type: string
createdAt:
type: string
format: 'Y-m-d\TH:i:sP'
updatedAt:
type: string
format: 'Y-m-d\TH:i:sP'
nullable: true
canEdit:
type: array
items:
type: string
canDelete:
type: boolean
canDisable:
type: boolean
type: object
MarketingPerformanceErrorResponseSchema:
description: 'Error response (application/problem+json). errors items carry the field and message of each failed request field; rejectedPropertyIds is present only when the call was rejected for specific requested properties.'
required:
- code
- message
properties:
errors:
description: 'One item per failed request field.'
type: array
items:
$ref: '#/components/schemas/BadRequestErrorItemSchema'
rejectedPropertyIds:
description: 'Requested property IDs the call was rejected for.'
type: array
items:
type: string
code:
description: 'Stable identifier of the problem, in UPPER_CASE form.'
type: string
example: BAD_REQUEST
message:
description: 'Short summary of the problem, stable across occurrences.'
type: string
type: object
MarketingPerformanceResponseSchema:
description: 'A page of daily marketing performance rows. Rows sort by propertyId (as a number), date and campaignType; a page with fewer than limit rows is the last one.'
required:
- data
- limit
- offset
properties:
total:
description: 'Total number of rows matching the request; present only when includeTotal is requested.'
type: integer
data:
description: 'One row per property, date and campaign type.'
type: array
items:
$ref: '#/components/schemas/MarketingPerformanceRowSchema'
limit:
description: 'The limit the page was built with.'
type: integer
offset:
description: 'The offset the page was built with.'
type: integer
type: object
MarketingPerformanceRowSchema:
description: 'Marketing performance of one property, date and campaign type. Fields are omitted when the source has no value for them (impressions, spendUsd, spend, exchangeRate, revenue, updatedAt).'
required:
- propertyId
- date
- campaignType
- clicks
- reservationsCount
- dataStatus
properties:
propertyId:
description: 'Property ID.'
type: string
example: '123'
date:
description: 'Date (YYYY-MM-DD, property-local).'
type: string
format: date
campaignType:
description: 'Campaign type. Known values: METASEARCH (self-serve, includes Search Booster), METASEARCH_MANAGED, PMAX (self-serve), PMAX_MANAGED, RETARGETING, OTA_TRAVEL_ADS. Other values may appear, so do not treat the list as closed. The managed types are commission-billed, so their rows carry no spendUsd or spend.'
type: string
example: METASEARCH
impressions:
description: 'Impressions (omitted when the platform does not report them).'
type: integer
clicks:
description: Clicks.
type: integer
spendUsd:
description: 'Spend in USD including the Cloudbeds markup (omitted when the campaign type has no spend). Sent alongside spend so the converted amount can be checked against its USD source.'
type: object
allOf:
-
$ref: '#/components/schemas/MoneySchema'
exchangeRate:
description: 'Decimal string, USD → currencyCode: the exchange rate of the row''s date from USD to the property currency, the currencyCode of spend and revenue (omitted when no rate is available).'
type: string
example: '0.9321'
spend:
description: 'Spend in the property currency, spendUsd × exchangeRate (omitted when either is missing).'
type: object
allOf:
-
$ref: '#/components/schemas/MoneySchema'
reservationsCount:
description: 'Attributed reservations.'
type: integer
revenue:
description: 'Attributed revenue in the property currency (omitted only for OTA_TRAVEL_ADS rows when no exchange rate exists for the date).'
type: object
allOf:
-
$ref: '#/components/schemas/MoneySchema'
dataStatus:
description: 'PROVISIONAL for the last 14 days in the property''s time zone, otherwise FINAL.'
type: string
enum:
- PROVISIONAL
- FINAL
updatedAt:
description: 'Latest source update for the row (omitted when the row has no source data).'
type: string
format: date-time
type: object
OrganizationAvailabilityRequestSchema:
properties:
id:
description: 'Organization ID'
type: integer
example: 12
check_in:
description: 'Check-in date in YYYY-MM-DD format.'
type: string
format: date
example: '2026-05-01'
check_out:
description: 'Check-out date in YYYY-MM-DD format. Exclusive: the departure day is not charged.'
type: string
format: date
example: '2026-05-05'
currency:
description: 'ISO 4217 currency code every property is priced in. Required: the response is a comparison list, and prices only compare if they share a currency.'
type: string
example: EUR
type: object
OrganizationDetailRequestSchema:
properties:
id:
description: 'Organization ID'
type: integer
example: 12
lang:
description: 'Cloudbeds language code (e.g. en, pt-br, es-es). Defaults to en.'
type: string
example: en
currency:
description: 'ISO 4217 currency code. Optional: when omitted, each property keeps its own currency, and every monetary value carries the currency it is expressed in.'
type: string
example: EUR
nullable: true
type: object
OrganizationAddressSchema:
required:
- city
- state
- country
properties:
city:
type: string
example: 'Miami Beach'
state:
type: string
example: Florida
country:
type: string
example: 'United States'
type: object
OrganizationAvailabilityDataSchema:
required:
- checkIn
- checkOut
- properties
properties:
checkIn:
description: 'The requested check-in date, echoed back so a client can match a response to the date range currently on screen.'
type: string
format: date
example: '2026-05-01'
checkOut:
description: 'The requested check-out date. Exclusive: the departure day is not a charged night.'
type: string
format: date
example: '2026-05-05'
properties:
description: 'One entry per member property, including those with no vacancy. A property is omitted when it has no base currency configured, so a missing property id means no data for that property rather than no vacancy.'
type: array
items:
$ref: '#/components/schemas/OrganizationAvailabilityPropertySchema'
type: object
OrganizationAvailabilityPropertySchema:
required:
- id
- hasAvailability
- minNightlyRate
- minTotalPrice
properties:
id:
description: 'Property identifier, used to join this entry with the organization detail response.'
type: string
example: '101'
hasAvailability:
description: 'Whether the property can be booked for the requested dates.'
type: boolean
example: true
minNightlyRate:
oneOf:
-
$ref: '#/components/schemas/MoneySchema'
nullable: true
description: 'Lowest nightly price available for the requested dates. Null when there is no availability.'
minTotalPrice:
oneOf:
-
$ref: '#/components/schemas/MoneySchema'
nullable: true
description: 'Lowest total price for the whole stay. Null when there is no availability. Not the nightly minimum multiplied by the number of nights: the cheapest single night and the cheapest stay can come from different options.'
type: object
OrganizationAvailabilityResponseSchema:
required:
- success
- data
properties:
success:
type: boolean
example: true
data:
$ref: '#/components/schemas/OrganizationAvailabilityDataSchema'
type: object
OrganizationBadRequestSchema:
description: 'Returned when the request cannot be served as sent: a malformed or reversed date range, or an unsupported currency. The error string identifies which.'
required:
- success
- error
properties:
error:
type: string
example: 'Invalid date range'
success:
type: boolean
example: false
type: object
OrganizationDepositSchema:
required:
- type
- value
- includesTaxesAndFees
properties:
type:
type: string
enum:
- percent
- flat
- firstNight
example: percent
value:
description: 'Percentage of the reservation total when type is "percent"; Money (amount + currencyCode) charged per room per night when "flat"; null when "firstNight".'
nullable: true
oneOf:
-
$ref: '#/components/schemas/MoneySchema'
-
type: number
format: float
example: 30
includesTaxesAndFees:
description: 'For "percent" and "firstNight": true if the deposit also covers taxes and fees (grand total), false if it covers the subtotal only. Always false for "flat".'
type: boolean
example: false
type: object
OrganizationDetailDataSchema:
required:
- id
- name
- slug
- properties
properties:
id:
type: string
example: '12'
name:
type: string
example: 'Beach Hotels Group'
slug:
type: string
example: beach-hotels
logo:
description: 'URL of the organization''s main logo. Null when the organization has no logo.'
type: string
example: 'https://static.cloudbeds.com/img/beach-hotels-logo.png'
nullable: true
properties:
type: array
items:
$ref: '#/components/schemas/OrganizationPropertySchema'
type: object
OrganizationDetailResponseSchema:
required:
- success
- data
properties:
success:
type: boolean
example: true
data:
$ref: '#/components/schemas/OrganizationDetailDataSchema'
type: object
OrganizationLateCheckoutSchema:
required:
- hour
- feeType
- fee
properties:
hour:
description: 'Property-local latest late-checkout time-of-day (HH:MM); read with the property timeZone. Not an instant.'
type: string
example: '13:00'
feeType:
type: string
enum:
- flat
- percent
example: flat
fee:
description: 'Money (amount + currencyCode) when feeType is "flat"; a percentage number (e.g. 10 for 10%) when "percent".'
oneOf:
-
$ref: '#/components/schemas/MoneySchema'
-
type: number
format: float
example: 10
type: object
OrganizationNotFoundResponseSchema:
required:
- success
- error
properties:
error:
type: string
example: 'Organization not found'
success:
type: boolean
example: false
type: object
OrganizationPoliciesSchema:
properties:
checkinTime:
description: 'Property-local check-in time-of-day (HH:MM); read with the property timeZone. Not an instant.'
type: string
example: '15:00'
nullable: true
checkoutTime:
description: 'Property-local check-out time-of-day (HH:MM); read with the property timeZone. Not an instant.'
type: string
example: '11:00'
nullable: true
lateCheckout:
oneOf:
-
$ref: '#/components/schemas/OrganizationLateCheckoutSchema'
nullable: true
cancellationPolicyText:
description: 'Legacy cancellation policy text; null when not configured or the property uses Smart Policies.'
type: string
nullable: true
deposit:
oneOf:
-
$ref: '#/components/schemas/OrganizationDepositSchema'
nullable: true
description: 'Legacy deposit; null when no deposit is charged or the property uses Smart Policies.'
termsText:
description: 'Terms and conditions (HTML) in the requested language; null when not configured.'
type: string
nullable: true
smartPoliciesEnabled:
description: 'True when the property uses Smart Policies: policies vary by rate plan, so no legacy cancellation text or deposit is sent.'
type: boolean
type: object
OrganizationPropertySchema:
required:
- id
- code
- name
- currencyCode
- hotelAddress
- lat
- lng
- bookingUrl
- images
- amenities
- policies
properties:
id:
type: string
example: '101'
code:
type: string
example: SEASIDE
name:
type: string
example: 'Seaside Resort'
description:
type: string
nullable: true
currencyCode:
type: string
example: USD
timeZone:
description: 'Property IANA timezone; read together with policy times (which are property-local).'
type: string
example: America/Los_Angeles
nullable: true
hotelAddress:
$ref: '#/components/schemas/OrganizationAddressSchema'
lat:
type: number
format: float
example: 25.7907
lng:
type: number
format: float
example: -80.13
bookingUrl:
type: string
example: 'https://hotels.cloudbeds.com/reservation/SEASIDE'
website:
type: string
example: 'https://www.seasideresort.com'
nullable: true
images:
type: array
items:
type: string
logo:
type: string
example: 'https://static.cloudbeds.com/img/seaside-logo.png'
nullable: true
mainPhoto:
description: 'URL of the property''s main profile photo, the first photo in the property''s profile gallery. Null when the property has no profile photo.'
type: string
example: 'https://h-img3.cloudbeds.com/uploads/1/hotel_front~~abc.png'
nullable: true
amenities:
type: array
items:
$ref: '#/components/schemas/AmenityItemSchema'
policies:
$ref: '#/components/schemas/OrganizationPoliciesSchema'
type: object
OrganizationServiceUnavailableResponseSchema:
required:
- success
- error
properties:
error:
type: string
example: 'Service temporarily unavailable. Please retry.'
success:
type: boolean
example: false
type: object
CaptureModeSchema:
description: 'The capture mode for the payment'
type: string
enum:
- auto
- manual
CreatePaymentRequestSchema:
required:
- captureMode
- total
- inventoryObject
- paymentMethod
- redirectUrl
properties:
captureMode:
$ref: '#/components/schemas/CaptureModeSchema'
total:
$ref: '#/components/schemas/MoneySchema'
redirectUrl:
description: 'URL to redirect the user to after 3D Secure authentication or other payment actions'
type: string
example: 'https://example.com/payment/callback'
inventoryObject:
$ref: '#/components/schemas/InventoryObjectSchema'
paymentMethod:
$ref: '#/components/schemas/PaymentMethodSchema'
description:
description: 'Optional payment description that appears in the folio.'
type: string
example: Deposit
nullable: true
type: object
DuplicatePrecheckRequestSchema:
description: "Mirrors the `/connect/payment/add` envelope field-for-field: both values are the\nJSON strings the frontend already builds for that call, so the precheck sees exactly\nwhat the payment submission will see."
required:
- payment
- inventory_object
- propertyId
properties:
payment:
description: 'JSON-encoded payment params, identical to the `payment` field posted to `/connect/payment/add`.'
type: string
example: '{"amount":100,"payment_method":"cards","transaction_type":"Purchase","credit_card_id":123,"payment_date":"2026-01-15"}'
inventory_object:
description: 'JSON-encoded inventory object, identical to the `inventory_object` field posted to `/connect/payment/add`.'
type: string
example: '{"type":"reservation","id":456}'
type: object
ExecuteScheduledPaymentRequestSchema:
required:
- id
- propertyId
GetPaymentReferenceNumberRequestSchema:
required:
- paymentId
properties:
paymentId:
description: 'Payment ID.'
type: string
example: '900001'
type: object
InventoryObjectSchema:
required:
- type
- id
properties:
type:
$ref: '#/components/schemas/InventoryObjectType'
id:
description: 'The ID of the inventory object'
type: string
example: '12345'
type: object
PaymentMethodSchema:
required:
- type
properties:
type:
$ref: '#/components/schemas/PaymentMethodTypeSchema'
sdkToken:
description: 'SDK token (cbpm1_*) generated by the Cloudbeds Payment SDK. Required when type is ''sdk_token''.'
type: string
example: cbpm1_abc123def456
nullable: true
paymentMethodId:
description: 'A stored payment method, as a UUID. Either a Cloudbeds permanent card token issued by POST /vault/v1/tokens/card, or the paymentMethodId returned in a previous response from this endpoint. Required when type is ''payment_method_id''.'
type: string
format: uuid
example: 550e8400-e29b-41d4-a716-446655440000
nullable: true
type: object
PaymentMethodTypeSchema:
description: 'The type of payment method'
type: string
enum:
- sdk_token
- payment_method_id
CardDetailsResponseSchema:
required:
- last4
- brand
properties:
last4:
description: 'The last 4 digits of the card number'
type: string
example: '4242'
brand:
description: 'The card brand'
type: string
example: visa
paymentMethodId:
description: 'Identifier of the stored payment method, reusable as paymentMethod.paymentMethodId on a later request. Null when the payment did not store a card.'
type: string
format: uuid
example: 10000000-0000-0000-0000-000000000070
nullable: true
type: object
CreatePaymentResponseSchema:
properties:
paymentStatus:
$ref: '#/components/schemas/PaymentStatus'
paymentId:
description: 'The ID of the created payment'
type: string
example: '12345'
paymentMethodDetails:
oneOf:
-
$ref: '#/components/schemas/PaymentMethodDetailsResponseSchema'
nullable: true
description: 'Payment method details'
nextAction:
oneOf:
-
$ref: '#/components/schemas/NextActionResponseSchema'
nullable: true
description: 'Next action required, such as a redirect for 3D Secure'
type: object
DuplicatePrecheckMatchSchema:
description: 'A recent money-moving payment that looks like the one about to be submitted.'
required:
- paymentId
- total
- paymentMethod
- status
- description
- paymentDate
- createdAt
properties:
paymentId:
type: integer
example: 987654
total:
$ref: '#/components/schemas/MoneySchema'
paymentMethod:
type: string
example: cards
paymentMethodDetails:
oneOf:
-
$ref: '#/components/schemas/PaymentMethodDetailsResponseSchema'
nullable: true
description: 'Payment method details'
status:
$ref: '#/components/schemas/PaymentStatus'
description:
type: string
example: Deposit
paymentDate:
description: 'Business date of the payment.'
type: string
format: date
example: '2026-01-15'
createdAt:
description: 'When the payment row was created (UTC).'
type: string
format: date-time
example: '2026-01-15T14:02:11+00:00'
type: object
DuplicatePrecheckResponseSchema:
description: 'Advisory verdict for a payment about to be submitted. `action` is `confirm` exactly when `latestMatch` is non-null; every other outcome (disabled, not eligible, storage error) is `proceed`.'
required:
- action
- latestMatch
- matchCount
- reason
properties:
action:
type: string
enum:
- proceed
- confirm
example: confirm
latestMatch:
oneOf:
-
$ref: '#/components/schemas/DuplicatePrecheckMatchSchema'
nullable: true
description: 'Most recent matching payment in the lookback window; null unless `action` is `confirm`.'
matchCount:
description: 'Total matching payments in the lookback window, including `latestMatch`.'
type: integer
example: 3
reason:
type: string
enum:
- matches_found
- no_matches
- not_eligible
- disabled
- error
example: matches_found
type: object
NextActionType:
description: 'The type of next action required'
type: string
enum:
- redirect
PaymentMethodType:
description: 'The type of payment method used'
type: string
enum:
- card
PaymentStatus:
description: 'The payment status from the payment processor'
type: string
enum:
- successful
- failed
- pending
- canceled
- unconfirmed
- expired
- scheduled
ExecuteScheduledPaymentDataSchema:
description: 'Payload of a successful execute-scheduled-payment outcome.'
required:
- paymentStatus
- alreadyProcessed
properties:
paymentStatus:
description: 'The persisted payment status after dispatch (successful | failed | canceled | scheduled). Null only when the dispatch was not attempted (e.g. notYetDue with no prior status).'
type: string
example: successful
nullable: true
alreadyProcessed:
description: 'True when the persisted payment was already in a terminal state and the dispatch was a no-op idempotent retry.'
type: boolean
example: false
errorMessage:
description: 'Human-readable gateway error detail when paymentStatus="failed"; null otherwise.'
type: string
nullable: true
type: object
ExecuteScheduledPaymentResponseSchema:
description: 'Response envelope for a successful execute-scheduled-payment outcome.'
required:
- data
properties:
data:
$ref: '#/components/schemas/ExecuteScheduledPaymentDataSchema'
type: object
NextActionResponseSchema:
required:
- type
properties:
type:
$ref: '#/components/schemas/NextActionType'
redirect:
oneOf:
-
$ref: '#/components/schemas/RedirectResponseSchema'
nullable: true
description: 'Redirect details when type is ''redirect'''
type: object
PaymentMethodDetailsResponseSchema:
required:
- type
properties:
type:
$ref: '#/components/schemas/PaymentMethodType'
card:
oneOf:
-
$ref: '#/components/schemas/CardDetailsResponseSchema'
nullable: true
description: 'Card details when the payment method is a card'
type: object
PaymentReferenceNumberResponseSchema:
required:
- status
- referenceNumber
- updatedAt
properties:
status:
description: 'Whether the card network has issued a reference number for this refund, whatever the refund''s own status; "unavailable" means no reference exists or will exist.'
type: string
enum:
- available
- pending
- unavailable
example: available
referenceNumber:
description: 'The card network reference number; present only when status is "available".'
type: string
example: '138327253516763'
nullable: true
updatedAt:
description: 'When the reference number status was last updated (ISO-8601); null when nothing has been reported yet.'
type: string
format: date-time
example: '2026-10-06T14:02:11+00:00'
nullable: true
type: object
RedirectResponseSchema:
required:
- redirectUrl
properties:
redirectUrl:
description: 'The URL to redirect the user to for authentication'
type: string
example: 'https://payments.cloudbeds.com/3d_secure_2/authenticate'
type: object
PosContextSchema:
description: 'POS source metadata for the request. restaurantName / revenueCenter / mealPeriod / staffReference describe the POS session that produced the request as a whole; they apply uniformly to every item (postCheck) or gratuity entry (postGratuity) in the same POST.'
properties:
restaurantName:
description: 'Restaurant or outlet name.'
type: string
example: 'Sunset Grill'
nullable: true
revenueCenter:
description: 'Revenue center identifier.'
type: string
example: BAR
nullable: true
mealPeriod:
description: 'Meal period (e.g., breakfast, lunch, dinner).'
type: string
example: dinner
nullable: true
staffReference:
description: 'Free-text reference to a staff member or terminal in the source POS.'
type: string
example: server-014
nullable: true
type: object
SystemRequestSchema: { }
SystemFeatureResponseSchema:
description: 'System feature information'
required:
- name
- version
properties:
name:
description: 'Feature name'
type: string
example: occupancy
version:
description: 'Feature version'
type: string
example: '2.0'
type: object
SystemResponseSchema:
description: 'System features response'
required:
- features
properties:
features:
description: 'Array of system feature versions for this property'
type: array
items:
$ref: '#/components/schemas/SystemFeatureResponseSchema'
type: object
RatePlanAddonRequestSchema:
required:
- addonId
- settings
properties:
addonId:
description: 'The addon ID.'
type: string
settings:
description: 'The addon settings.'
type: string
enum:
- package_inclusive
- show_as_combined
- show_as_separate
example: package_inclusive
type: object
RatePlanBulkStatusRequestSchema:
required:
- ids
- isActive
properties:
ids:
description: 'Rate Plan IDs. Duplicates are collapsed; each id appears once in the response.'
type: array
items:
type: string
example: '123'
maxItems: 100
minItems: 1
example:
- '123'
- '456'
nullable: true
isActive:
description: 'Target status for every listed rate plan.'
type: boolean
example: false
nullable: true
type: object
RatePlanCreateRequestSchema:
required:
- isActive
- roomTypeId
- name
- description
- namePrivate
properties:
isActive:
description: 'The status of the rate plan.'
type: boolean
example: true
roomTypeId:
description: 'The room type ID assigned to this rate plan.'
type: integer
example: 123
name:
description: 'Name in multiple languages.'
type: object
example:
en: 'Standard Rate'
es: 'Tarifa Estándar'
additionalProperties:
type: string
description:
description: 'Description in multiple languages.'
type: object
example:
en: 'Our standard rate plan'
es: 'Nuestro plan de tarifas estándar'
additionalProperties:
type: string
namePrivate:
description: 'Internal name in multiple languages.'
type: object
example:
en: 'Standard Internal'
es: 'Estándar Interno'
additionalProperties:
type: string
allotmentBlockId:
description: 'The allotment block''s ID this rate belongs to.'
type: string
example: '4567'
nullable: true
promoCode:
description: 'Promotional code for the rate plan.'
type: string
maxLength: 50
example: SUMMER2023
nullable: true
code:
description: 'Rate plan code, up to 5 uppercase letters or digits. Unique per property. An empty string is stored as null.'
type: string
maxLength: 5
pattern: '^[A-Z0-9]{0,5}$'
example: BAR1
nullable: true
category:
description: 'Rate plan category. An empty string is stored as null.'
type: string
enum:
- RACK
- BAR
- CORP
- GOV
- NEG
- PROMO
- PACKAGE
- COMP
- HOUSE
nullable: true
sources:
description: 'List of sources for the rate plan.'
type: array
items:
type: string
example:
- source1
- source2
nullable: true
derivedValue:
description: 'Value for the derived rate plan.'
type: number
format: float
default: 0
example: 150.5
nullable: true
derivedRatePlanId:
description: 'Derived rate plan ID.'
type: integer
example: 456
nullable: true
derivedType:
description: 'Rate plan derived type.'
type: string
default: fixed
enum:
- fixed
- percentage
terms:
description: 'Terms and conditions in multiple languages.'
type: object
example:
en: 'Standard terms apply'
es: 'Se aplican términos estándar'
nullable: true
additionalProperties:
type: string
intervals:
description: 'List of rate plan intervals.'
type: array
items:
$ref: '#/components/schemas/RatePlanIntervalRequestSchema'
nullable: true
addons:
description: 'List of addons.'
type: array
items:
$ref: '#/components/schemas/RatePlanAddonRequestSchema'
nullable: true
segmentId:
description: 'Segment ID associated with the rate plan.'
type: integer
example: 789
nullable: true
policyId:
description: 'Policy ID associated with the rate plan.'
type: integer
example: 321
nullable: true
type: object
RatePlanDeleteRequestSchema:
required:
- id
properties:
id:
description: 'Rate Plan ID.'
type: string
example: '123'
type: object
RatePlanIntervalRequestSchema:
required:
- startDate
- endDate
properties:
startDate:
description: 'Start date of the interval.'
type: string
format: date
example: '2025-01-27'
endDate:
description: 'End date of the interval.'
type: string
format: date
example: '2025-02-27'
name:
description: 'Name of the interval. Optional: when omitted, null or empty, the interval is saved without a name and returned with an empty name.'
type: string
example: 'Winter Season'
nullable: true
roomTypeId:
description: 'Room type ID.'
type: string
example: '82828'
minLos:
description: 'Minimum length of stay.'
type: integer
example: 1
nullable: true
maxLos:
description: 'Maximum length of stay.'
type: integer
example: 10
nullable: true
eventCode:
description: 'Event code.'
type: string
example: '990'
nullable: true
days:
description: 'Days of the week pricing (0=Sunday, 1=Monday, etc.).'
type: object
example:
- 65.5
- 50
- 50
- 50
- 50
- 70
- 70.5
nullable: true
additionalProperties:
type: number
format: float
adultDays:
description: 'Extra adults pricing (0=Sunday, 1=Monday, etc.).'
type: object
example:
-
'3': 35
'4': 35
-
'3': 20
'4': 20
-
'3': 20
'4': 20
-
'3': 20
'4': 20
-
'3': 20
'4': 20
-
'3': 35
'4': 35
-
'3': 40
'4': 40
nullable: true
additionalProperties:
type: object
additionalProperties:
type: number
format: float
childDays:
description: 'Extra children pricing (0=Sunday, 1=Monday, etc.).'
type: object
example:
-
'1': 10
'2': 15
-
'1': 5
'2': 10
-
'1': 5
'2': 10
-
'1': 5
'2': 10
-
'1': 5
'2': 10
-
'1': 10
'2': 15
-
'1': 12
'2': 18
nullable: true
additionalProperties:
type: object
additionalProperties:
type: number
format: float
cutOff:
description: 'Cut-off: minimum number of days in advance a booking must be made. 0 = no restriction.'
type: integer
example: 3
nullable: true
lastMinuteBooking:
description: 'Last-minute booking: maximum number of days before arrival a booking may be made. 0 = no restriction.'
type: integer
example: 1
nullable: true
closedToArrival:
description: 'Closed to arrival: when true, guests cannot start a stay on dates within this interval.'
type: boolean
example: false
nullable: true
closedToDeparture:
description: 'Closed to departure: when true, guests cannot end a stay on dates within this interval.'
type: boolean
example: false
nullable: true
limitToNumberOfRooms:
description: 'Saleable Accommodations: caps how many rooms of the room type this rate may sell. Null, absent or 0 means no limit — the rate may sell the room type''s full capacity. A value above the room type''s capacity is accepted and stored as sent.'
type: integer
example: 5
nullable: true
chargeGuestsType:
description: 'Where the interval''s extra-guest prices come from. custom: the adultDays and childDays sent with the interval. base: the room type''s base rate. derived: the parent rate plan''s extra-guest prices, adjusted the way this derived rate plan adjusts its rates. Sending adultDays or childDays always saves custom, and derived on a rate plan that is not derived saves base. When omitted, the interval keeps the mode already saved for its dates; dates with no saved mode take custom when adultDays or childDays are sent and base otherwise. custom without adultDays or childDays keeps the extra-guest prices already saved for its dates, and saves base where there are none unless the rate is priced by age policy.'
type: string
enum:
- custom
- base
- derived
example: derived
nullable: true
type: object
RatePlanSingleRequestSchema:
required:
- id
properties:
id:
description: 'Rate Plan ID.'
type: string
example: '123'
type: object
RatePlanUpdateRequestSchema:
required:
- id
properties:
id:
description: 'Rate Plan ID.'
type: string
example: '123'
isActive:
description: 'Whether the rate plan is active.'
type: boolean
example: true
allotmentBlockId:
description: 'The allotment block''s ID this rate belongs to.'
type: string
example: '4567'
nullable: true
promoCode:
description: 'Promotional code for the rate plan.'
type: string
maxLength: 50
example: SUMMER2023
nullable: true
code:
description: 'Rate plan code, up to 5 uppercase letters or digits. Unique per property. An empty string is stored as null.'
type: string
maxLength: 5
pattern: '^[A-Z0-9]{0,5}$'
example: BAR1
nullable: true
category:
description: 'Rate plan category. An empty string is stored as null.'
type: string
enum:
- RACK
- BAR
- CORP
- GOV
- NEG
- PROMO
- PACKAGE
- COMP
- HOUSE
nullable: true
sources:
description: 'List of sources for the rate plan.'
type: array
items:
type: string
example:
- source1
- source2
nullable: true
derivedValue:
description: 'Value for the derived rate plan.'
type: number
format: float
default: 0
example: 150.5
nullable: true
derivedRatePlanId:
description: 'Derived rate plan ID.'
type: integer
example: 456
nullable: true
derivedType:
description: 'Rate plan derived type.'
type: string
default: fixed
enum:
- fixed
- percentage
name:
description: 'Name in multiple languages.'
type: object
example:
en: 'Standard Rate'
es: 'Tarifa Estándar'
nullable: true
additionalProperties:
type: string
description:
description: 'Description in multiple languages.'
type: object
example:
en: 'Our standard rate plan'
es: 'Nuestro plan de tarifas estándar'
nullable: true
additionalProperties:
type: string
namePrivate:
description: 'Internal name in multiple languages.'
type: object
example:
en: 'Standard Internal'
es: 'Estándar Interno'
nullable: true
additionalProperties:
type: string
terms:
description: 'Terms and conditions in multiple languages.'
type: object
example:
en: 'Standard terms apply'
es: 'Se aplican términos estándar'
nullable: true
additionalProperties:
type: string
intervals:
description: 'List of rate plan intervals.'
type: array
items:
$ref: '#/components/schemas/RatePlanIntervalRequestSchema'
nullable: true
addons:
description: 'List of addons for the rate plan. Omitted or null leaves the current addons unchanged; an empty array removes all of them.'
type: array
items:
$ref: '#/components/schemas/RatePlanAddonRequestSchema'
nullable: true
segmentId:
description: 'Segment ID associated with the rate plan.'
type: integer
example: 789
nullable: true
policyId:
description: 'Policy ID associated with the rate plan.'
type: integer
example: 321
nullable: true
type: object
RatePlanAvailabilityListRequestSchema:
required:
- ratePlanId
- startDate
- endDate
properties:
ratePlanId:
description: 'Rate Plan ID (the rate plan package id).'
type: integer
example: 12345
roomTypeId:
description: 'Optional Room Type ID filter; omit to return all room types of the rate plan.'
type: integer
example: 67890
nullable: true
startDate:
description: 'Start date (YYYY-MM-DD).'
type: string
pattern: '^\d{4}-\d{2}-\d{2}$'
example: '2030-01-01'
endDate:
description: 'End date (YYYY-MM-DD), inclusive. The range may span at most 366 days.'
type: string
pattern: '^\d{4}-\d{2}-\d{2}$'
example: '2030-01-31'
type: object
RatePlanAvailabilityPutRequestSchema:
required:
- data
properties:
data:
description: 'Stop-sell updates per rate plan / room type.'
type: array
items:
$ref: '#/components/schemas/RatePlanStopSellUpdateSchema'
testRequest:
description: 'Mark as test request (honored in non-production only).'
type: boolean
example: false
type: object
RatePlanStopSellUpdateSchema:
required:
- ratePlanId
- roomTypeId
- intervals
properties:
ratePlanId:
description: 'Rate Plan ID (the rate plan package id).'
type: integer
example: 12345
roomTypeId:
description: 'Room Type ID.'
type: integer
example: 67890
intervals:
description: 'Date intervals to set stop-sell for.'
type: array
items:
$ref: '#/components/schemas/StopSellIntervalSchema'
type: object
StopSellIntervalSchema:
required:
- startDate
- endDate
- stopSell
properties:
startDate:
description: 'Interval start date (YYYY-MM-DD).'
type: string
pattern: '^\d{4}-\d{2}-\d{2}$'
example: '2030-01-01'
endDate:
description: 'Interval end date (YYYY-MM-DD), inclusive.'
type: string
pattern: '^\d{4}-\d{2}-\d{2}$'
example: '2030-01-07'
stopSell:
description: 'Whether the rate plan is closed for sale (stop-sell) on these dates.'
type: boolean
example: true
nullable: true
type: object
RatePlanAddonResponseSchema:
required:
- id
- addonId
- settings
properties:
id:
type: string
example: '1234567'
nullable: true
addonId:
type: string
example: '4674899'
nullable: true
settings:
description: 'The addon settings.'
type: string
enum:
- package_inclusive
- show_as_combined
- show_as_separate
example: package_inclusive
nullable: true
type: object
RatePlanBulkOutcomeResponseSchema:
required:
- id
- status
properties:
id:
type: string
example: '1234567'
status:
description: 'Outcome for this rate plan.'
type: string
enum:
- updated
- unchanged
- blocked
- failed
example: updated
reasons:
description: 'Why the rate plan was blocked. Present only when status is `blocked`.'
type: array
items:
type: string
enum:
- USED_BY_ALLOTMENT_BLOCK
- HAS_DERIVED_RATE_PLANS
example: HAS_DERIVED_RATE_PLANS
nullable: true
type: object
RatePlanBulkResponseSchema:
required:
- batchId
- data
properties:
batchId:
description: 'Shared id stamped on every activity-log entry written by this request.'
type: string
format: uuid
example: 0f8fad5b-d9cb-469f-a165-70867728950e
data:
description: 'One outcome per distinct requested id, in request order.'
type: array
items:
$ref: '#/components/schemas/RatePlanBulkOutcomeResponseSchema'
type: object
RatePlanIntervalResponseSchema:
required:
- name
- ratePlanId
- roomTypeId
- startDate
- endDate
- days
properties:
name:
description: 'Name of the interval. An empty string when the interval has no name.'
type: string
example: BaseRate1
ratePlanId:
type: integer
example: 123
nullable: true
roomTypeId:
type: integer
example: 456
nullable: true
startDate:
type: string
format: date-time
example: '2025-07-03'
nullable: true
endDate:
type: string
format: date-time
example: '2025-07-10'
nullable: true
minLos:
type: integer
example: 1
nullable: true
maxLos:
type: integer
example: 0
nullable: true
days:
description: 'Base price per day-of-week, indexed 0=Sunday … 6=Saturday. A day with no base price is null.'
type: array
items:
type: number
format: float
nullable: true
example:
- 60
- 50
- 50
- 50
- 50
- 65.99
- 65.99
nullable: true
adultDays:
description: 'Extra adults pricing. Outer key = day-of-week (0=Sunday … 6=Saturday); inner key = extra-guest count; value = additional price for that guest. Note: when fees are set on a contiguous run of days starting at day 0 (e.g. all 7 days), the payload serializes as a JSON array of per-day objects rather than the day-of-week-keyed object shown here.'
type: object
example:
'1':
'3': 20
'4': 20
'5':
'3': 35
'4': 35
nullable: true
additionalProperties:
type: object
additionalProperties:
type: number
format: float
childDays:
description: 'Extra children pricing. Outer key = day-of-week (0=Sunday … 6=Saturday); inner key = extra-guest count; value = additional price for that guest. Note: when fees are set on a contiguous run of days starting at day 0 (e.g. all 7 days), the payload serializes as a JSON array of per-day objects rather than the day-of-week-keyed object shown here.'
type: object
example:
'1':
'1': 5
'2': 10
'5':
'1': 10
'2': 15
nullable: true
additionalProperties:
type: object
additionalProperties:
type: number
format: float
chargeGuestsType:
description: 'Where the interval''s extra-guest prices come from. custom: adultDays and childDays, or agePolicyPricing on a rate priced by age policy. base: the room type''s base rate. derived: the parent rate plan''s extra-guest prices, adjusted the way this derived rate plan adjusts its rates.'
type: string
enum:
- custom
- base
- derived
example: base
nullable: true
cutOff:
description: 'Cut-off: minimum number of days in advance a booking must be made. 0 = no restriction.'
type: integer
example: 3
nullable: true
lastMinuteBooking:
description: 'Last-minute booking: maximum number of days before arrival a booking may be made. 0 = no restriction.'
type: integer
example: 1
nullable: true
closedToArrival:
description: 'Closed to arrival: when true, guests cannot start a stay on dates within this interval.'
type: boolean
example: false
nullable: true
closedToDeparture:
description: 'Closed to departure: when true, guests cannot end a stay on dates within this interval.'
type: boolean
example: false
nullable: true
limitToNumberOfRooms:
description: 'Saleable Accommodations: caps how many rooms of the room type this rate may sell. Null means no limit — the rate may sell the room type''s full capacity.'
type: integer
example: 5
nullable: true
agePolicyPricing:
description: 'Age-group pricing for this interval, one entry per priced age group — or, under per_each_guest pricing, one entry per extra-guest position within a group, so several entries can share an ageGroupId and differ by guestNumber. Null when the property does not use age-group pricing, or when this interval''s rate still prices guests with the adultDays / childDays model — in which case those two fields carry the pricing. An empty array means age-group pricing applies to this interval but nothing is priced on it yet. Join ageGroupId against GET /age-policy/v1/policies for each group''s name and age range.'
type: array
items:
required:
- ageGroupId
- isExtraGuestsPricing
- days
properties:
ageGroupId:
description: 'Age group this price applies to.'
type: integer
minimum: 1
example: 7
isExtraGuestsPricing:
description: 'True when the price applies to a guest beyond base occupancy rather than to the base rate.'
type: boolean
example: false
extraGuestsType:
description: 'The property''s extra-guest pricing mode: per_age_group prices every extra guest of a group alike, per_each_guest prices each position separately.'
type: string
enum:
- per_age_group
- per_each_guest
example: per_age_group
nullable: true
guestNumber:
description: 'Extra-guest position this price applies to, counting from the first guest beyond base occupancy. Only set under per_each_guest pricing.'
type: integer
minimum: 1
example: null
nullable: true
days:
description: 'Price per day-of-week. A day with no price is absent from the list.'
type: array
items:
required: [dayOfWeek, priceAmount, priceCurrency]
properties: { dayOfWeek: { description: '0=Sunday … 6=Saturday.', type: integer, example: 1 }, priceAmount: { description: 'Decimal amount, with at least two decimal places and up to four — a price finer than cents keeps the decimals it needs, so do not parse this as a fixed-width two-decimal string.', type: string, example: '12.00' }, priceCurrency: { description: 'ISO 4217 currency code.', type: string, example: USD } }
type: object
type: object
nullable: true
type: object
RatePlanListResponseSchema:
required:
- limit
- offset
- data
properties:
limit:
type: integer
offset:
type: integer
data:
type: array
items:
$ref: '#/components/schemas/RatePlanResponseSchema'
nullable: true
total:
description: 'Total number of items matching the request; present only when includeTotal is requested.'
type: integer
nullable: true
type: object
RatePlanResponseSchema:
required:
- mealPlans
properties:
id:
type: string
propertyId:
type: string
example: '9876'
nullable: true
isActive:
type: boolean
example: true
status:
description: 'Derived from isActive and the intervals'' end dates, using the property''s current date. `disabled`: isActive is false. `no-intervals`: active with no intervals. `expired`: active and every interval''s endDate is in the past. `active`: active with at least one interval whose endDate is today or later (or has no endDate).'
type: string
enum:
- active
- expired
- no-intervals
- disabled
example: active
isDeleted:
type: boolean
example: false
derivedRatePlanId:
type: string
example: '456'
nullable: true
isDerived:
type: boolean
example: true
derivedType:
type: string
example: fixed
nullable: true
derivedValue:
type: number
format: float
example: 150.5
nullable: true
addons:
type: array
items:
$ref: '#/components/schemas/RatePlanAddonResponseSchema'
nullable: true
promoCode:
type: string
example: SUMMER2023
nullable: true
sources:
type: array
items:
type: string
example:
- source1
- source2
nullable: true
name:
type: object
example:
en: 'Standard Rate'
es: 'Tarifa Estándar'
nullable: true
additionalProperties:
type: string
description:
type: object
example:
en: 'Our standard rate plan'
es: 'Nuestro plan de tarifas estándar'
nullable: true
additionalProperties:
type: string
namePrivate:
type: object
example:
en: 'Standard Internal'
es: 'Estándar Interno'
nullable: true
additionalProperties:
type: string
terms:
type: object
example:
en: 'Standard terms apply'
es: 'Se aplican términos estándar'
nullable: true
additionalProperties:
type: string
intervals:
type: array
items:
$ref: '#/components/schemas/RatePlanIntervalResponseSchema'
nullable: true
createdAt:
type: string
format: date-time
example: '2023-10-01T12:00:00+00:00'
nullable: true
updatedAt:
type: string
format: date-time
example: '2023-10-01T12:00:00+00:00'
nullable: true
policyId:
type: string
example: '9888000'
nullable: true
segmentId:
type: string
example: '789'
nullable: true
mealPlans:
description: 'Meal plans carried by the add-ons listed in `addons` (any attachment setting), as raw keys (not localized labels), deduplicated. Empty when none of them is a meal plan.'
type: array
items:
type: string
enum:
- breakfast
- lunch
- dinner
- all-inclusive
example:
- breakfast
- dinner
code:
type: string
example: BAR1
nullable: true
category:
type: string
enum:
- RACK
- BAR
- CORP
- GOV
- NEG
- PROMO
- PACKAGE
- COMP
- HOUSE
nullable: true
type: object
RatePlanAvailabilityDayResponseSchema:
required:
- date
- ratePlanId
- roomTypeId
- stopSell
properties:
date:
description: 'Date (YYYY-MM-DD).'
type: string
example: '2030-01-01'
ratePlanId:
description: 'Rate Plan ID (the rate plan package id).'
type: integer
example: 12345
roomTypeId:
description: 'Room Type ID.'
type: integer
example: 67890
stopSell:
description: 'Whether the rate plan is closed for sale (stop-sell) on this date.'
type: boolean
example: true
type: object
RatePlanAvailabilityListResponseSchema:
required:
- data
properties:
data:
description: 'Per-date stop-sell values for the rate plan / room type(s).'
type: array
items:
$ref: '#/components/schemas/RatePlanAvailabilityDayResponseSchema'
type: object
StopSellJobAcceptedResponseSchema:
required:
- jobReferenceId
properties:
jobReferenceId:
description: 'Reference ID for tracking via getAsyncApiJob.'
type: integer
example: 1234
type: object
ReservationCommissionRequestSchema:
required:
- reservationId
properties:
reservationId:
type: string
type: object
ReservationCommissionResponseSchema:
required:
- id
- propertyId
- reservationId
- effectiveCommission
- effectiveCommissionType
- createdAt
- updatedAt
properties:
id:
type: string
propertyId:
type: string
reservationId:
type: string
effectiveCommission:
$ref: '#/components/schemas/MoneySchema'
effectiveCommissionType:
type: string
estimatedCommissionFromSource:
oneOf:
-
$ref: '#/components/schemas/MoneySchema'
nullable: true
estimatedCommissionableRevenue:
oneOf:
-
$ref: '#/components/schemas/MoneySchema'
nullable: true
channelCommission:
oneOf:
-
$ref: '#/components/schemas/MoneySchema'
nullable: true
channelCommissionType:
type: string
nullable: true
sourceCommissionPercentage:
type: number
format: float
nullable: true
createdAt:
type: string
format: 'Y-m-d\TH:i:sP'
updatedAt:
type: string
format: 'Y-m-d\TH:i:sP'
nullable: true
type: object
UpdateReservationRoomRequestSchema:
required:
- reservationId
- reservationRoomId
properties:
reservationId:
description: 'Reservation ID'
type: string
example: '12345'
reservationRoomId:
description: 'Reservation Room ID'
type: string
example: '67890'
roomId:
description: 'Room ID to assign (format: ''roomTypeId-roomNumber''), or null to unassign'
type: string
example: 10-101
nullable: true
roomTypeId:
description: 'Room type ID to change to (without assigning specific room), or null'
type: integer
example: 15
nullable: true
adjustPrice:
description: 'Whether the guest pays the difference when the assignment changes the rate. Omit it to leave the price decision unanswered — false is an answer, not a default.'
type: boolean
nullable: true
type: object
UpdateReservationRoomResponseSchema:
required:
- reservationRoomId
- roomId
- roomTypeId
- roomName
- total
properties:
reservationRoomId:
description: 'Reservation room ID that was updated'
type: integer
roomId:
description: 'Assigned room ID (null if unassigned)'
type: string
nullable: true
roomTypeId:
description: 'Room type ID'
type: integer
nullable: true
roomName:
description: 'Room name'
type: string
nullable: true
total:
oneOf:
-
$ref: '#/components/schemas/MoneySchema'
nullable: true
description: 'Room total after assignment in the booking''s currency'
type: object
AreaItemSchema:
required:
- typeCode
- position
- arrangements
properties:
typeCode:
description: 'Area type code. Valid values: BEDROOM, LIVING_ROOM (for MULTI layout), SLEEPING_AREA (for SINGLE layout)'
type: string
example: BEDROOM
position:
description: 'Position/order of this area'
type: integer
minimum: 0
example: 0
arrangements:
description: 'List of bed arrangements in this area. BEDROOM and SLEEPING_AREA require exactly 1 default arrangement (isDefault=true); LIVING_ROOM can have 0 to 2. An optional second arrangement with isDefault=false represents the alternative sleeping arrangement.'
type: array
items:
$ref: '#/components/schemas/ArrangementItemSchema'
maxItems: 2
minItems: 0
type: object
ArrangementItemSchema:
required:
- isDefault
- position
- beds
properties:
isDefault:
description: 'Whether this is the default arrangement'
type: boolean
example: true
position:
description: 'Position/order of this arrangement. Must be 0 for the default arrangement and 1 for the alternative.'
type: integer
maximum: 1
minimum: 0
example: 0
beds:
description: 'List of beds in this arrangement'
type: array
items:
$ref: '#/components/schemas/BedItemSchema'
minItems: 1
type: object
BathroomItemSchema:
required:
- type
- location
properties:
type:
description: 'Bathroom type.'
type: string
enum:
- FULL
- HALF
- OUTDOOR_FULL
- OUTDOOR_HALF
example: FULL
location:
description: 'Bathroom location.'
type: string
enum:
- IN_UNIT
- EXTERNAL
example: IN_UNIT
privacy:
description: 'Bathroom privacy. Required for private accommodations, must be omitted for shared accommodations.'
type: string
enum:
- PRIVATE
- SHARED
example: PRIVATE
nullable: true
type: object
BedItemSchema:
required:
- typeCode
- capacity
- quantity
properties:
typeCode:
description: 'Bed type code (e.g., KING_SIZE_BED, SINGLE_BED)'
type: string
example: KING_SIZE_BED
capacity:
description: 'Bed capacity (number of people)'
type: integer
minimum: 1
example: 2
quantity:
description: 'Quantity of this bed type'
type: integer
minimum: 1
example: 1
type: object
GetRoomTypeAreasRequestSchema:
required:
- roomTypeId
properties:
roomTypeId:
description: 'Room type ID'
type: integer
example: 12345
type: object
GetRoomTypeBathroomsRequestSchema:
required:
- roomTypeId
properties:
roomTypeId:
description: 'Room type ID'
type: integer
example: 12345
type: object
GetRoomTypeRequestSchema:
required:
- id
properties:
id:
description: 'Room type ID'
type: string
pattern: '^[0-9]+$'
example: '4242'
type: object
GetUnitRequestSchema: { }
GetUnitsRequestSchema: { }
OutOfServiceRequestSchema:
required:
- fromDate
- toDate
- reason
- roomId
properties:
fromDate:
description: 'RFC3339 Date to start the out of service period'
type: string
example: '2025-04-25T00:00:00-06:00'
toDate:
description: 'RFC3339 Date to end the out of service period'
type: string
example: '2025-04-26T00:00:00-06:00'
reason:
description: 'Wny is the room out of service?'
type: string
example: 'Flooding in the room.'
type: object
PatchUnitRequestSchema:
properties:
connectingUnitIds:
description: 'List of connecting unit IDs. Send empty array to clear all connections. Omit to leave unchanged.'
type: array
items:
type: string
example: 12345-0
nullable: true
name:
description: 'Unit name. Must be non-empty when provided.'
type: string
example: 'Room 101'
nullable: true
description:
description: 'Unit description (empty string to clear).'
type: string
example: 'King bed, ocean view'
nullable: true
images:
description: 'Unit images. Send empty array to clear. FE is responsible for uploading the assets and passing back the resulting image objects.'
type: array
items:
type: object
nullable: true
nameLangs:
description: 'Per-language map of the unit name (keys are IETF language codes, e.g. "en", "pt-br", "es-es"). Send the full map the property supports — missing keys will be persisted as empty strings on read.'
type: object
example:
en: 'Room 101'
pt-br: 'Quarto 101'
pt-pt: ''
es: ''
es-es: ''
nullable: true
additionalProperties:
type: string
descriptionLangs:
description: 'Per-language map of the unit description (keys are IETF language codes). Same shape as `nameLangs`.'
type: object
example:
en: 'King bed, ocean view'
pt-br: ''
es: ''
nullable: true
additionalProperties:
type: string
doorlockId:
description: 'Door lock integration identifier (null to clear).'
type: string
example: DL-8842
nullable: true
type: object
PlaceRoomsOutOfServiceRequest:
properties:
items:
description: 'List of rooms to be placed out of service.'
type: array
items:
$ref: '#/components/schemas/OutOfServiceRequestSchema'
type: object
PutRoomTypeAreasRequestSchema:
required:
- layoutTypeCode
- areas
properties:
layoutTypeCode:
description: 'Layout type: SINGLE (1 area) or MULTI (2+ areas). Set to null to clear all areas configuration.'
type: string
enum:
- SINGLE
- MULTI
example: MULTI
nullable: true
areas:
description: 'List of areas for this room type. Must be empty when layoutTypeCode is null. Must have at least 1 area when layoutTypeCode is not null.'
type: array
items:
$ref: '#/components/schemas/AreaItemSchema'
type: object
PutRoomTypeBathroomsRequestSchema:
required:
- bathrooms
properties:
bathrooms:
description: 'List of bathrooms for this room type. Replaces the entire bathroom configuration. Pass an empty array to clear all bathrooms.'
type: array
items:
$ref: '#/components/schemas/BathroomItemSchema'
maxItems: 50
type: object
AreaItemResponseSchema:
description: 'Room type area in response'
required:
- id
- typeCode
- position
- arrangements
properties:
id:
description: 'Area ID'
type: integer
example: 789
typeCode:
description: 'Area type code'
type: string
example: BEDROOM
position:
description: 'Display position'
type: integer
minimum: 0
example: 0
arrangements:
description: 'Bed arrangements in this area. An arrangement with isDefault=false is the alternative sleeping arrangement.'
type: array
items:
$ref: '#/components/schemas/ArrangementItemResponseSchema'
type: object
ArrangementItemResponseSchema:
description: 'Bed arrangement in response'
required:
- id
- isDefault
- position
- beds
properties:
id:
description: 'Arrangement ID'
type: integer
example: 456
isDefault:
description: 'Whether this is the default arrangement'
type: boolean
example: true
position:
description: 'Display position'
type: integer
minimum: 0
example: 0
beds:
description: 'Beds in this arrangement'
type: array
items:
$ref: '#/components/schemas/BedItemResponseSchema'
type: object
BathroomItemResponseSchema:
description: 'Room type bathroom in response'
required:
- id
- type
- location
- position
properties:
id:
description: 'Bathroom ID'
type: integer
example: 789
type:
description: 'Bathroom type'
type: string
enum:
- FULL
- HALF
- OUTDOOR_FULL
- OUTDOOR_HALF
example: FULL
location:
description: 'Bathroom location'
type: string
enum:
- IN_UNIT
- EXTERNAL
example: IN_UNIT
position:
description: 'Display position (0-indexed)'
type: integer
minimum: 0
example: 0
privacy:
description: 'Bathroom privacy. Set only for private accommodations; null for shared accommodations.'
type: string
enum:
- PRIVATE
- SHARED
example: PRIVATE
nullable: true
type: object
BedItemResponseSchema:
description: 'Bed item in response'
required:
- id
- typeCode
- capacity
- quantity
properties:
id:
description: 'Bed ID'
type: integer
example: 123
typeCode:
description: 'Bed type code'
type: string
example: KING_SIZE_BED
capacity:
description: 'Bed capacity'
type: integer
minimum: 1
example: 2
quantity:
description: 'Quantity of this bed type'
type: integer
minimum: 1
example: 1
type: object
DeletedUnitItem:
description: 'A unit (room) that has been deleted.'
required:
- id
- propertyId
- roomTypeId
- name
- archivedAt
properties:
id:
description: 'Unit ID'
type: string
example: 12345-0
propertyId:
description: 'Property ID'
type: integer
example: 12345
roomTypeId:
description: 'Room type (accommodation) ID'
type: integer
example: 67890
name:
description: 'Unit name at the time it was deleted'
type: string
example: 'Room 101'
archivedAt:
description: 'When the unit was archived.'
type: string
format: date-time
example: '2026-01-01T01:00:00+00:00'
type: object
GetRoomLabelsResponseSchema:
required:
- labels
properties:
labels:
description: 'List of room labels in the catalog'
type: array
items:
$ref: '#/components/schemas/RoomLabelItemSchema'
type: object
GetRoomTypeAreasResponseSchema:
description: 'Response for GET /rooms/v1/{roomTypeId}/areas'
required:
- layoutTypeCode
- areas
properties:
layoutTypeCode:
description: 'Layout type code (empty string if not set)'
type: string
example: MULTI
areas:
description: 'Areas in the room type (ordered by position)'
type: array
items:
$ref: '#/components/schemas/AreaItemResponseSchema'
type: object
GetRoomTypeBathroomsResponseSchema:
description: 'Response for GET /rooms/v1/{roomTypeId}/bathrooms'
required:
- bathrooms
properties:
bathrooms:
description: 'Bathrooms in the room type (ordered by position)'
type: array
items:
$ref: '#/components/schemas/BathroomItemResponseSchema'
type: object
GetRoomTypeResponseSchema:
description: 'Response for GET /rooms/v1/room-types/{id}'
required:
- id
- name
- shortName
- description
- maxGuests
- adultsIncluded
- childrenIncluded
- isPrivate
- unitCount
properties:
id:
description: 'ID of the room type.'
type: string
example: '4242'
name:
description: 'Room type name, in the language that Content-Language names.'
type: string
example: 'Standard Double'
shortName:
description: 'Short name.'
type: string
example: STD
description:
description: 'Room type description, in the language that Content-Language names. Blank when the description has no value in that language.'
type: string
example: 'A quiet room at the back of the property.'
maxGuests:
description: 'Maximum number of guests in one unit.'
type: integer
example: 2
adultsIncluded:
description: 'Adults included in the base price.'
type: integer
example: 2
childrenIncluded:
description: 'Children included in the base price.'
type: integer
example: 0
isPrivate:
description: 'True for a private room type, false for a shared one.'
type: boolean
example: true
unitCount:
description: 'Number of units.'
type: integer
example: 3
bedsPerUnit:
description: 'Beds in one unit of a shared room type. Not sent for a private one.'
type: integer
example: 4
nullable: true
type: object
GetUnitsResponseSchema:
description: 'Response for GET /rooms/v1/units'
required:
- units
properties:
units:
description: 'List of units for the property'
type: array
items:
$ref: '#/components/schemas/UnitItemResponseSchema'
type: object
OutOfServiceResponseItemSchema:
required:
- event_id
- code
properties:
event_id:
description: 'The event id of the request'
type: string
message:
description: 'Response message'
type: string
code:
description: 'The HTTP status code of the response'
type: integer
example: 201
type: object
OutOfServiceResponseSchema:
required:
- items
properties:
items:
type: array
items:
$ref: '#/components/schemas/OutOfServiceResponseItemSchema'
type: object
PatchUnitResponseSchema:
description: 'Response for PATCH /rooms/v1/units/{unitId}'
properties:
unit:
$ref: '#/components/schemas/UnitItemResponseSchema'
type: object
PutRoomTypeAreasResponseSchema:
description: 'Response for PUT /rooms/v1/{roomTypeId}/areas'
required:
- layoutTypeCode
- areas
properties:
layoutTypeCode:
description: 'Layout type code (null when areas are cleared)'
type: string
example: MULTI
nullable: true
areas:
description: 'Areas in the room type'
type: array
items:
$ref: '#/components/schemas/AreaItemResponseSchema'
type: object
PutRoomTypeBathroomsResponseSchema:
description: 'Response for PUT /rooms/v1/{roomTypeId}/bathrooms'
required:
- bathrooms
properties:
bathrooms:
description: 'Bathrooms in the room type after update'
type: array
items:
$ref: '#/components/schemas/BathroomItemResponseSchema'
type: object
RoomLabelItemSchema:
required:
- code
- title
- category
- accommodationPrivacyCode
properties:
code:
description: 'Unique label code'
type: string
example: STUDIO_APARTMENT
title:
description: 'Translated label title'
type: string
example: 'Studio Apartment'
category:
description: 'Label category code'
type: string
example: APARTMENT
accommodationPrivacyCode:
description: 'Accommodation privacy code'
type: string
enum:
- PRIVATE
- SHARED
- PRIVATE_SHARED
example: PRIVATE
type: object
UnitItemResponseSchema:
description: 'A single unit (room) within an accommodation type'
required:
- id
- propertyId
- roomTypeId
- name
- description
- images
- connectingUnitIds
- nameLangs
- descriptionLangs
- doorlockId
properties:
id:
description: 'Unit ID'
type: string
example: 12345-0
propertyId:
description: 'Property ID'
type: integer
example: 12345
roomTypeId:
description: 'Room type (accommodation) ID'
type: integer
example: 67890
name:
description: 'Unit name'
type: string
example: 'Room 101'
connectingUnitIds:
description: 'IDs of connecting units'
type: array
items:
type: string
example: 12345-1
description:
description: 'Unit description'
type: string
example: 'King bed, ocean view'
images:
description: 'Unit images (JSON objects as stored on the unit).'
type: array
items:
type: object
nameLangs:
description: 'Per-language unit name map (IETF language codes → localized strings).'
type: object
example:
en: 'Room 101'
pt-br: 'Quarto 101'
es: ''
additionalProperties:
type: string
descriptionLangs:
description: 'Per-language unit description map (IETF language codes → localized strings).'
type: object
example:
en: 'King bed, ocean view'
es: ''
additionalProperties:
type: string
doorlockId:
description: 'Door lock integration identifier.'
type: string
example: DL-8842
nullable: true
type: object
AddedItemPreviewInputSchema:
required:
- productId
- salePrice
- quantity
- isAutoDate
- dateTime
properties:
productId:
description: 'Id of the item that is added.'
type: string
example: '42'
salePrice:
oneOf:
-
$ref: '#/components/schemas/SmartPolicyMoneyInputSchema'
nullable: true
description: 'Price of one unit as entered in the drawer, including any inclusive taxes.'
quantity:
type: integer
example: 2
nullable: true
isAutoDate:
type: boolean
nullable: true
dateTime:
type: string
example: '2026-07-09 13:30'
type: object
AddedRoomRevenuePreviewInputSchema:
required:
- amount
- taxIds
- feeIds
- bookingRoomId
- isAutoDate
- dateTime
properties:
amount:
oneOf:
-
$ref: '#/components/schemas/SmartPolicyMoneyInputSchema'
nullable: true
taxIds:
type: array
items:
type: integer
feeIds:
type: array
items:
type: integer
bookingRoomId:
type: string
example: '555'
isAutoDate:
type: boolean
nullable: true
dateTime:
type: string
example: '2026-07-09 13:30'
type: object
AddedTaxFeePreviewInputSchema:
required:
- target
- taxFeeId
- amount
- bookingRoomId
- isAutoDate
- dateTime
properties:
target:
description: 'Whether a tax or a fee is added.'
type: string
enum:
- TAX
- FEE
taxFeeId:
description: 'Id of the tax or fee that is added.'
type: string
example: '34'
amount:
oneOf:
-
$ref: '#/components/schemas/SmartPolicyMoneyInputSchema'
nullable: true
description: 'Amount entered in the drawer, before the taxes charged on it.'
bookingRoomId:
type: string
example: '555'
isAutoDate:
type: boolean
nullable: true
dateTime:
type: string
example: '2026-07-09 13:30'
type: object
CreatePolicyExceptionRequestSchema:
required:
- name
- policyRootId
- intervals
- rates
properties:
policyRootId:
description: 'Smart policy root ID.'
type: integer
example: 1001
intervals:
description: 'List of date intervals for this exception.'
type: array
items:
$ref: '#/components/schemas/PolicyExceptionIntervalSchema'
rates:
description: 'List of rates this exception applies to.'
type: array
items:
$ref: '#/components/schemas/PolicyExceptionRateSchema'
name:
description: 'Internal name for this exception.'
type: string
example: 'Winter holiday exception'
enabled:
description: 'Whether the exception is enabled.'
type: boolean
example: true
type: object
DeletePolicyExceptionRequestSchema:
required:
- exceptionId
properties:
exceptionId:
description: 'Policy exception ID.'
type: string
example: '5001'
type: object
DisableSmartPolicyRequestSchema:
required:
- reservationId
properties:
reservationId:
description: 'Reservation ID.'
type: string
example: '900001'
trigger:
description: 'What caused the disable. "manual-action" marks a side-effect disable (SP-332: manual payment/refund/void/cancel) and skips the override_policy_payment_rules check; absent or "explicit" is the deliberate kill-switch and enforces it.'
type: string
example: manual-action
type: object
EligibleRatesRequestSchema:
required:
- startDate
- endDate
- intervals
type: object
allOf:
-
$ref: '#/components/schemas/LimitOffsetPaginationSchema'
-
$ref: '#/components/schemas/BodySortSchema'
-
properties:
startDate:
description: 'Start date of the date range to filter rate plans.'
type: string
format: date
example: '2024-01-01'
endDate:
description: 'End date of the date range to filter rate plans.'
type: string
format: date
example: '2024-01-31'
intervals:
description: 'List of exception intervals for conflict detection.'
type: array
items:
$ref: '#/components/schemas/PolicyExceptionIntervalSchema'
exceptionId:
description: 'Exception ID to exclude from conflict detection (when editing an existing exception).'
type: string
example: '123'
nullable: true
type: object
GetBookingPolicyInformationRequestSchema:
required:
- reservationId
properties:
reservationId:
description: 'Reservation identifier.'
type: string
example: '1234567890'
languageCode:
description: 'Language code for the rendered policy text (e.g. "fr", "en-US"). Defaults to the property''s language when omitted.'
type: string
example: en-US
nullable: true
type: object
GetPaymentScheduleRequestSchema:
required:
- reservationId
properties:
reservationId:
description: 'Reservation ID.'
type: string
example: '900001'
skipPaymentProcessorCheck:
description: 'Skip the payment processor check and return the full theoretical schedule even when the property has no active processor.'
type: boolean
default: false
example: false
type: object
GetPolicyExceptionRequestSchema:
required:
- exceptionId
properties:
exceptionId:
description: 'Policy exception ID.'
type: string
example: '5001'
type: object
GetSmartPolicyPaymentsRequestSchema:
required:
- reservationId
properties:
reservationId:
description: 'Reservation ID.'
type: string
example: '900001'
type: object
ListPolicyExceptionsRequestSchema:
allOf:
-
$ref: '#/components/schemas/LimitOffsetPaginationSchema'
-
$ref: '#/components/schemas/QueryParameterDynamicFilterSchema'
-
$ref: '#/components/schemas/QueryParameterSortSchema'
PatchPolicyExceptionRequestSchema:
required:
- exceptionId
properties:
exceptionId:
description: 'Policy exception ID.'
type: string
example: '5001'
policyRootId:
description: 'Smart policy root ID.'
type: integer
example: 1001
nullable: true
intervals:
description: 'List of date intervals for this exception.'
type: array
items:
$ref: '#/components/schemas/PolicyExceptionIntervalSchema'
nullable: true
rates:
description: 'List of rates this exception applies to.'
type: array
items:
$ref: '#/components/schemas/PolicyExceptionRateSchema'
nullable: true
name:
description: 'Internal name for this exception.'
type: string
example: 'Winter holiday exception'
nullable: true
enabled:
description: 'Whether the exception is enabled.'
type: boolean
example: true
nullable: true
type: object
PolicyExceptionIntervalSchema:
required:
- startDate
- endDate
properties:
startDate:
description: 'Start date of the interval.'
type: string
format: date
example: '2024-01-01'
endDate:
description: 'End date of the interval.'
type: string
format: date
example: '2024-01-31'
day0:
description: 'Sunday (day 0) -- apply exception on this day of the week.'
type: boolean
example: true
day1:
description: 'Monday (day 1) -- apply exception on this day of the week.'
type: boolean
example: true
day2:
description: 'Tuesday (day 2) -- apply exception on this day of the week.'
type: boolean
example: true
day3:
description: 'Wednesday (day 3) -- apply exception on this day of the week.'
type: boolean
example: true
day4:
description: 'Thursday (day 4) -- apply exception on this day of the week.'
type: boolean
example: true
day5:
description: 'Friday (day 5) -- apply exception on this day of the week.'
type: boolean
example: true
day6:
description: 'Saturday (day 6) -- apply exception on this day of the week.'
type: boolean
example: true
type: object
PolicyExceptionRateSchema:
required:
- packageId
properties:
packageId:
description: 'Package/rate plan ID. Use 0 for base rate.'
type: integer
example: 123
roomTypeId:
description: 'Room type ID. Required when packageId is 0 (base rate).'
type: integer
example: 456
nullable: true
type: object
PreviewAdjustmentInputSchema:
required:
- target
- token
- amount
properties:
target:
description: 'The type of adjustment to preview.'
type: string
enum:
- TAX
- FEE
- RATE
- ROOM_REVENUE
token:
description: 'Folio adjustment id token, exactly as the save receives it (e.g. ''tax_42'', ''fee_7'', ''rate'', ''roomRevenue_manual'').'
type: string
example: tax_42
amount:
oneOf:
-
$ref: '#/components/schemas/SmartPolicyMoneyInputSchema'
nullable: true
description: 'Adjustment amount (positive magnitude); the charge is REDUCED by this.'
bookingRoomId:
description: 'Booking room id the adjustment targets (rate / room-revenue).'
type: string
example: '555'
nullable: true
rateSourceId:
description: 'Rate source id — required for RATE adjustments to resolve the applicable taxes/fees.'
type: string
example: '777'
nullable: true
isRootSource:
description: 'Whether the rate source is a root source (RATE adjustments).'
type: boolean
nullable: true
isHotelCollectBooking:
description: 'Whether the booking is hotel-collect (RATE adjustments).'
type: boolean
nullable: true
type: object
PreviewAdjustmentRequestSchema:
description: 'Provide exactly one of adjustment, addedRoomRevenue, addedTaxFee or addedItem.'
required:
- reservationId
properties:
reservationId:
description: 'Reservation ID to preview an adjustment or added room revenue for.'
type: string
example: '12345'
adjustment:
oneOf:
-
$ref: '#/components/schemas/PreviewAdjustmentInputSchema'
nullable: true
description: 'Existing adjustment preview input.'
addedRoomRevenue:
oneOf:
-
$ref: '#/components/schemas/AddedRoomRevenuePreviewInputSchema'
nullable: true
description: 'Room-revenue preview input.'
addedTaxFee:
oneOf:
-
$ref: '#/components/schemas/AddedTaxFeePreviewInputSchema'
nullable: true
description: 'Manual tax or fee preview input.'
addedItem:
oneOf:
-
$ref: '#/components/schemas/AddedItemPreviewInputSchema'
nullable: true
description: 'Added item preview input, for an item collected with the scheduled payments.'
type: object
example:
reservationId: '12345'
addedRoomRevenue:
amount:
amount: '5000'
currencyCode: EUR
taxIds:
- 12
feeIds:
- 34
bookingRoomId: '555'
isAutoDate: true
dateTime: '2026-07-09 13:30'
SmartPolicyMoneyInputSchema:
description: "Money input as per the REST API Modeling Specification: amount in the smallest representable units\nof the currency, paired with an ISO 4217 currency code."
required:
- amount
- currencyCode
properties:
amount:
description: 'Amount in the smallest representable units of the currency (e.g., cents for USD).'
type: string
example: '500'
currencyCode:
description: 'ISO 4217 currency code.'
type: string
example: EUR
type: object
UpdatePolicyExceptionRequestSchema:
required:
- exceptionId
- name
- policyRootId
- intervals
- rates
properties:
exceptionId:
description: 'Policy exception ID.'
type: string
example: '5001'
policyRootId:
description: 'Smart policy root ID.'
type: integer
example: 1001
intervals:
description: 'List of date intervals for this exception.'
type: array
items:
$ref: '#/components/schemas/PolicyExceptionIntervalSchema'
rates:
description: 'List of rates this exception applies to.'
type: array
items:
$ref: '#/components/schemas/PolicyExceptionRateSchema'
name:
description: 'Internal name for this exception.'
type: string
example: 'Winter holiday exception'
enabled:
description: 'Whether the exception is enabled. Omit to preserve current value.'
type: boolean
example: true
nullable: true
type: object
BookingPolicyInformationResponseSchema:
required:
- policyText
- scheduledPayments
- policyTextSource
properties:
policyText:
oneOf:
-
$ref: '#/components/schemas/PolicyTextSchema'
nullable: true
description: 'Rendered policy text for the reservation: smart policy text when the reservation is governed by one, otherwise the property''s legacy cancellation policy text (only cancellationText is populated in that case). Null when neither is available — consumers must hide the policy section in that case rather than render an empty one.'
scheduledPayments:
description: 'Upcoming scheduled payments (deposit and installments), pre-formatted for display. Empty for canceled and no-show reservations.'
type: array
items:
$ref: '#/components/schemas/ScheduledPaymentDisplayItemSchema'
policyTextSource:
description: 'Where policyText came from: "smart" when rendered from the reservation''s smart policy, "legacy" when it is the property''s legacy cancellation policy text. Null when policyText is null.'
type: string
enum:
- smart
- legacy
example: smart
nullable: true
type: object
DisableSmartPolicyResponseSchema:
required:
- matched
- modified
properties:
matched:
description: 'Count of booking room-policy rows found for the reservation.'
type: integer
modified:
description: 'Count of rows whose state actually flipped. 0 with a non-zero "matched" means Smart Policy was already off for the reservation (the call is idempotent).'
type: integer
type: object
EligibleRateConflictSchema:
required:
- exceptionId
- exceptionName
properties:
exceptionId:
description: 'ID of the blocking exception.'
type: string
example: '123'
exceptionName:
description: 'Name of the blocking exception.'
type: string
example: 'Holiday Override'
type: object
EligibleRateItemSchema:
required:
- name
- type
properties:
name:
description: 'Name of the rate plan or room type.'
type: string
example: 'Standard Rate'
type:
description: 'Type of rate: "rate_plan" or "base_rate".'
type: string
example: rate_plan
packageId:
description: 'Package/rate plan ID. Present only when type is "rate_plan".'
type: string
example: '123'
nullable: true
roomTypeId:
description: 'Room type ID. Present only when type is "base_rate".'
type: string
example: '789'
nullable: true
policyId:
description: 'Smart policy ID associated with this rate plan, if any. Always null for base rates.'
type: string
example: '456'
nullable: true
conflict:
oneOf:
-
$ref: '#/components/schemas/EligibleRateConflictSchema'
nullable: true
description: 'Conflict info if this rate is blocked by another exception. Null/absent when assignable.'
type: object
EligibleRatesResponseSchema:
required:
- total
- limit
- offset
- data
properties:
total:
description: 'The total number of items available.'
type: integer
limit:
description: 'The limit for the number of items to return.'
type: integer
offset:
description: 'The offset for the current page of results.'
type: integer
data:
description: 'Eligible rates for exception creation (rate plans and base rates combined).'
type: array
items:
$ref: '#/components/schemas/EligibleRateItemSchema'
type: object
PaymentScheduleResponseSchema:
required:
- payments
- degraded
properties:
payments:
description: 'Scheduled payments (deposit and installments) for the reservation.'
type: array
items:
$ref: '#/components/schemas/ScheduledPaymentItemSchema'
degraded:
description: 'True when the schedule calculation failed and the result is degraded (partial or unavailable), as opposed to a legitimately empty schedule. Consumers must treat a degraded empty result differently from a genuine "no payments owed".'
type: boolean
type: object
PolicyCancellationTypeSchema:
required:
- text
- type
properties:
text:
description: 'Human-readable cancellation type label.'
type: string
example: 'Fully refundable until Nov 8, 2026'
type:
description: 'Machine-readable cancellation type.'
type: string
enum:
- FULLY_REFUNDABLE
- PARTIALLY_REFUNDABLE
- NON_REFUNDABLE
example: FULLY_REFUNDABLE
fullyRefundableUntilDaysBeforeCheckIn:
description: 'Days before check-in midnight until which the reservation is fully refundable (floored, legacy field); -1 when the deadline is the end of the arrival day; null when not applicable.'
type: integer
example: 3
nullable: true
fullyRefundableUntilDaysBeforeDate:
description: 'ISO date (YYYY-MM-DD) of the refund deadline (legacy, day-rounded); null when not applicable.'
type: string
example: '2026-11-08'
nullable: true
fullyRefundableUntilDateTime:
description: 'Exact ISO 8601 datetime of the refund deadline; null when not applicable.'
type: string
format: date-time
example: '2026-11-08T15:00:00+00:00'
nullable: true
fullyRefundableUntilMinutesBeforeCheckIn:
description: 'Minutes before check-in date midnight (not check-in time) of the refund deadline; negative when a deadline set from the check-in date is after that midnight; null when not applicable.'
type: integer
example: 4320
nullable: true
type: object
PolicyExceptionIntervalResponseSchema:
properties:
startDate:
type: string
format: date
example: '2024-01-01'
endDate:
type: string
format: date
example: '2024-01-31'
day0:
description: 'Sunday (day 0) -- apply exception on this day of the week.'
type: boolean
example: true
day1:
description: 'Monday (day 1) -- apply exception on this day of the week.'
type: boolean
example: true
day2:
description: 'Tuesday (day 2) -- apply exception on this day of the week.'
type: boolean
example: true
day3:
description: 'Wednesday (day 3) -- apply exception on this day of the week.'
type: boolean
example: true
day4:
description: 'Thursday (day 4) -- apply exception on this day of the week.'
type: boolean
example: true
day5:
description: 'Friday (day 5) -- apply exception on this day of the week.'
type: boolean
example: true
day6:
description: 'Saturday (day 6) -- apply exception on this day of the week.'
type: boolean
example: true
type: object
PolicyExceptionListResponseSchema:
required:
- total
- limit
- offset
- data
properties:
total:
description: 'The total number of items available.'
type: integer
limit:
description: 'The limit for the number of items to return.'
type: integer
offset:
description: 'The offset for the current page of results.'
type: integer
data:
type: array
items:
$ref: '#/components/schemas/PolicyExceptionResponseSchema'
type: object
PolicyExceptionRateResponseSchema:
properties:
packageId:
description: 'Package/rate plan ID. 0 = base rate.'
type: string
example: '123'
roomTypeId:
description: 'Room type ID.'
type: string
example: '456'
nullable: true
type: object
PolicyExceptionResponseSchema:
properties:
id:
type: string
example: '5001'
propertyId:
type: string
example: '1234'
name:
type: string
example: 'Winter holiday exception'
policyRootId:
type: string
example: '1001'
enabled:
type: boolean
example: true
createdBy:
type: string
example: '9876'
createdAt:
type: string
format: date-time
example: '2024-01-01T10:00:00+00:00'
updatedAt:
type: string
format: date-time
example: '2024-01-15T12:00:00+00:00'
intervals:
type: array
items:
$ref: '#/components/schemas/PolicyExceptionIntervalResponseSchema'
rates:
type: array
items:
$ref: '#/components/schemas/PolicyExceptionRateResponseSchema'
type: object
PolicySummaryRowSchema:
required:
- timingLabel
- actionCopy
properties:
timingLabel:
description: 'When the row applies, as display copy.'
type: string
example: 'Until Nov 8, 2026'
actionCopy:
description: 'What happens at that time, as display copy.'
type: string
example: 'Free cancellation'
detail:
description: 'Additional detail for the row; null when there is none.'
type: string
example: 'Full refund of the deposit.'
nullable: true
anchor:
description: 'Machine-readable anchor the timing is relative to; null when not applicable.'
type: string
example: CHECK_IN
nullable: true
anchorOffsetMinutes:
description: 'Offset from the anchor in minutes; null when not applicable.'
type: integer
example: -1440
nullable: true
dateTime:
description: 'Resolved ISO 8601 datetime for the row; null when not resolvable.'
type: string
format: date-time
example: '2026-11-08T00:00:00+00:00'
nullable: true
type: object
PolicyTextSchema:
required:
- id
- name
- rootId
- guaranteeText
- cancellationText
- noShowText
- additionalPolicyText
properties:
id:
description: 'Smart policy ID; null when the text comes from the legacy policy fallback.'
type: string
example: '42310212898960'
nullable: true
name:
description: 'Smart policy name; null when the text comes from the legacy policy fallback.'
type: string
example: 'Standard 3-day policy'
nullable: true
rootId:
description: 'Root ID of the smart policy version chain; null when the text comes from the legacy policy fallback.'
type: string
example: '42310212898960'
nullable: true
guaranteeText:
description: 'Human-readable guarantee / payment policy text; empty when the text comes from the legacy policy fallback (which only provides cancellation text).'
type: string
example: 'A deposit of 20% is collected at the time of booking.'
cancellationText:
description: 'Human-readable cancellation policy text.'
type: string
example: 'Free cancellation until 3 days before check-in; the deposit is forfeited afterwards.'
noShowText:
description: 'Human-readable no-show policy text; empty when the policy has none.'
type: string
example: 'No-shows are charged the full reservation amount.'
additionalPolicyText:
description: 'Additional free-form policy text configured by the property; empty when none.'
type: string
example: ''
cancellationType:
oneOf:
-
$ref: '#/components/schemas/PolicyCancellationTypeSchema'
nullable: true
description: 'Cancellation refundability classification; null when not determinable.'
paymentSummaryRows:
description: 'Payment milestone rows for timeline display; null when not available.'
type: array
items:
$ref: '#/components/schemas/PolicySummaryRowSchema'
nullable: true
cancellationSummaryRows:
description: 'Cancellation milestone rows for timeline display; null when not available.'
type: array
items:
$ref: '#/components/schemas/PolicySummaryRowSchema'
nullable: true
noShowSummaryRows:
description: 'No-show milestone rows for timeline display; null when not available.'
type: array
items:
$ref: '#/components/schemas/PolicySummaryRowSchema'
nullable: true
type: object
PreviewAdjustmentResponseSchema:
properties:
resultType:
description: 'The outcome of the preview.'
type: string
enum:
- SCHEDULED_PAYMENT_REDUCED
- SCHEDULED_PAYMENT_INCREASED
- SCHEDULED_PAYMENT_CANCELLED
- NEW_PAYMENT_SCHEDULED
- REFUND_REQUIRED
- NO_SCHEDULE_CHANGE
- NO_SMART_POLICY
example: SCHEDULED_PAYMENT_INCREASED
newReservationTotal:
$ref: '#/components/schemas/MoneySchema'
alreadyPaid:
$ref: '#/components/schemas/MoneySchema'
refundRequired:
$ref: '#/components/schemas/MoneySchema'
scheduledPayments:
type: array
items:
$ref: '#/components/schemas/PreviewScheduledPaymentSchema'
cardLast4:
description: 'Last four digits of the card when a newly scheduled payment charges soon.'
type: string
example: '4242'
nullable: true
type: object
PreviewScheduledPaymentSchema:
properties:
id:
type: string
example: '1001'
nullable: true
originalAmount:
$ref: '#/components/schemas/MoneySchema'
newAmount:
$ref: '#/components/schemas/MoneySchema'
status:
description: 'Status of the scheduled payment after the preview input.'
type: string
enum:
- REDUCED
- INCREASED
- CANCELLED
- NEW
example: REDUCED
chargesSoon:
description: 'Whether this created payment would be moved to now or the 15-minute grace period.'
type: boolean
type: object
ScheduledPaymentDisplayItemSchema:
required:
- formattedDate
- formattedAmountWithIsoCode
- formattedAmountWithSymbol
- type
properties:
formattedDate:
description: 'Payment collection date, formatted for display in the property''s locale.'
type: string
example: 'Nov 10, 2026'
formattedAmountWithIsoCode:
description: 'Payment amount formatted with the ISO 4217 currency code.'
type: string
example: 'USD 100.00'
formattedAmountWithSymbol:
description: 'Payment amount formatted with the currency symbol.'
type: string
example: $100.00
type:
description: 'Scheduled payment type.'
type: string
example: deposit
type: object
ScheduledPaymentItemSchema:
required:
- actionIds
- timestamp
- amount
- currency
- orderId
- isInitialDeposit
properties:
actionIds:
description: 'Identifiers of the actions covered by this scheduled payment.'
type: array
items:
type: string
example:
- '19'
- '20'
timestamp:
description: 'When the payment is scheduled to be collected; null when not yet determined.'
type: string
format: date-time
example: '2024-11-10T00:00:00.000Z'
nullable: true
amount:
description: 'Payment amount in minor units.'
type: integer
example: 4000
currency:
description: 'ISO 4217 currency code.'
type: string
example: EUR
orderId:
description: 'Order identifier the payment belongs to.'
type: string
example: '0'
isInitialDeposit:
description: 'Whether this payment is the initial deposit.'
type: boolean
example: false
type: object
SmartPolicyPaymentItemSchema:
required:
- paymentId
- amount
- cardType
- cardLast4
- createdAt
- scheduledFor
- transactionType
properties:
paymentId:
description: 'Payment ID.'
type: string
example: '542543'
amount:
$ref: '#/components/schemas/MoneySchema'
cardType:
description: 'Card brand when the payment is card-backed.'
type: string
example: master
nullable: true
cardLast4:
description: 'Last 4 digits of the card when the payment is card-backed.'
type: string
example: '4675'
nullable: true
createdAt:
description: 'Payment creation datetime in the property''s local time (Y-m-d H:i:s).'
type: string
pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
example: '2026-06-07 10:09:54'
nullable: true
scheduledFor:
description: 'When the payment is or was scheduled to be collected, property-local (Y-m-d H:i:s).'
type: string
pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
example: '2026-06-12 00:00:00'
nullable: true
transactionType:
description: 'Transaction type (Purchase, Authorize, or Capture).'
type: string
example: Purchase
type: object
SmartPolicyPaymentsResponseSchema:
required:
- scheduled
- processed
- canceledScheduled
- totalScheduled
- totalProcessed
- totalCanceledScheduled
- smartPolicyEnabled
properties:
scheduled:
description: 'Smart Policy payments still scheduled for automatic execution, including future authorization holds.'
type: array
items:
$ref: '#/components/schemas/SmartPolicyPaymentItemSchema'
processed:
description: 'Smart Policy payments already executed: successful purchases and captures, plus active authorization holds.'
type: array
items:
$ref: '#/components/schemas/SmartPolicyPaymentItemSchema'
canceledScheduled:
description: 'Formerly scheduled Smart Policy payments that were canceled (e.g. by turning Smart Policy off).'
type: array
items:
$ref: '#/components/schemas/SmartPolicyPaymentItemSchema'
totalScheduled:
oneOf:
-
$ref: '#/components/schemas/MoneySchema'
nullable: true
description: 'Sum of the scheduled payments, excluding authorization holds; null when the reservation has no Smart Policy payments.'
totalProcessed:
oneOf:
-
$ref: '#/components/schemas/MoneySchema'
nullable: true
description: 'Sum of the processed (collected) payments, excluding authorization holds; null when the reservation has no Smart Policy payments.'
totalCanceledScheduled:
oneOf:
-
$ref: '#/components/schemas/MoneySchema'
nullable: true
description: 'Sum of the canceled formerly-scheduled payments, excluding authorization holds; null when the reservation has no Smart Policy payments.'
smartPolicyEnabled:
description: 'Whether Smart Policy automation is currently on for the reservation: true while at least one of its rooms still has the policy active, false once it was turned off (or the reservation has no policy rows).'
type: boolean
example: true
type: object
AddonSchema:
required:
- addonId
- name
- amount
- quantity
properties:
addonId:
description: 'Add-on ID'
type: string
example: '789'
name:
description: 'Add-on display name'
type: string
example: Parking
amount:
oneOf:
-
$ref: '#/components/schemas/MoneyInputSchema'
nullable: true
description: 'Add-on unit price'
quantity:
description: 'Quantity (>= 1)'
type: integer
example: 2
taxesAndFees:
description: 'Tax/fee configuration for this addon'
type: array
items:
$ref: '#/components/schemas/TaxFeeConfigSchema'
isDefault:
description: 'Whether this is a default (package) add-on'
type: boolean
example: false
type: object
CalculateTotalsRequestSchema:
required:
- type
- taxesAndFees
properties:
type:
description: 'Entity type. Determines the calculation strategy.'
type: string
enum:
- reservation
- product
- addon
- custom_item
- resource
- room_revenue
- adjustment
- manual_tax_fee
example: product
taxesAndFees:
description: 'Array of tax/fee configuration objects. Can be empty.'
type: array
items:
$ref: '#/components/schemas/TaxFeeConfigSchema'
convenienceFeeConfig:
oneOf:
-
$ref: '#/components/schemas/ConvenienceFeeConfigSchema'
nullable: true
description: 'Convenience fee configuration'
date:
description: 'Calculation date (YYYY-MM-DD). Used for context and monitoring. Defaults to current date.'
type: string
example: '2026-04-01'
nullable: true
roundingMethod:
description: 'Rounding method. 0 = legacy (default), 1 = item-level rounding.'
type: integer
example: 0
nullable: true
exclusiveTaxesOnTotal:
description: 'Deprecated: each tax/fee''s own typeSettings.exclusiveBase decides. Only effect: false stamps gross on exclusive percentage rows that carry no exclusiveBase. For simulations use tax-fee-service.'
type: boolean
example: true
deprecated: true
amount:
oneOf:
-
$ref: '#/components/schemas/MoneyInputSchema'
nullable: true
description: 'Base amount for entity types. Required for product/addon/custom_item/resource.'
adults:
description: 'Number of adults. Used by fixed_per_person. Defaults to 1.'
type: integer
example: 1
children:
description: 'Number of children. Used by fixed_per_person. Defaults to 0.'
type: integer
example: 0
nights:
description: 'Number of nights. Used by fixed_per_person, fixed_per_accommodation. Defaults to 1.'
type: integer
example: 1
accommodations:
description: 'Number of accommodations. Used by fixed_per_accommodation. Defaults to 1.'
type: integer
example: 1
rooms:
description: 'Room configurations. Required for reservation type. Must be null (not empty array) for entity types.'
type: array
items:
$ref: '#/components/schemas/RoomSchema'
nullable: true
currencyCode:
description: 'ISO 4217 currency code. Required for reservation type. For entity types, derived from amount.currencyCode.'
type: string
example: USD
nullable: true
depositConfig:
oneOf:
-
$ref: '#/components/schemas/DepositConfigSchema'
nullable: true
description: 'Deposit calculation rules. Reservation type only.'
allotmentBlockCode:
description: 'Allotment block code. Reservation type only.'
type: string
nullable: true
type: object
ConvenienceFeeConfigSchema:
required:
- name
- rate
- rateType
- mode
properties:
name:
description: 'Display name for the surcharge'
type: string
example: 'Credit Card Surcharge'
rate:
description: 'Fee rate in minor units. For percentage: the rate in minor units (e.g., "300" = 3.00%).'
type: string
example: '300'
rateType:
description: 'How the fee is calculated'
type: string
enum:
- percentage
- fixed
example: percentage
mode:
description: 'Calculation mode. fee_on_top = added to total. fee_from_total = extracted from total.'
type: string
enum:
- fee_on_top
- fee_from_total
example: fee_on_top
type: object
DateRangeSchema:
required:
- range
properties:
range:
description: 'Date range in "start/end" format. Dates can be full (YYYY-MM-DD) or recurring annual (--MM-DD). End date can be omitted for open-ended ranges.'
type: string
example: 2026-03-01/2026-03-31
amount:
description: 'Override tax/fee amount when this date range matches, in minor currency units (e.g. 1500 = $15.00).'
type: string
example: '1500'
nullable: true
amountAdult:
description: 'Override per-adult amount in minor currency units (e.g. 500 = $5.00).'
type: string
example: '500'
nullable: true
amountChild:
description: 'Override per-child amount in minor currency units (e.g. 250 = $2.50).'
type: string
example: '250'
nullable: true
amountRateBased:
description: 'Override rate-based tiers.'
type: array
items:
$ref: '#/components/schemas/RateBasedTierSchema'
nullable: true
maxLength:
description: 'Override max nights to charge.'
type: integer
example: 10
nullable: true
lengthOfStay:
oneOf:
-
$ref: '#/components/schemas/LengthOfStaySchema'
nullable: true
description: 'Nested length-of-stay rules that apply within this date range.'
amountPerPersonRateBased:
description: 'Override per-person rate tiers.'
type: array
items:
$ref: '#/components/schemas/PerPersonRateBasedTierSchema'
nullable: true
type: object
DepositConfigSchema:
required:
- type
properties:
type:
description: 'How deposit is calculated'
type: string
enum:
- percentage
- fixed
- first_night
- first_night_with_taxes
- full_stay
- none
example: percentage
value:
description: 'Deposit value in minor currency units. Required for percentage and fixed types. For percentage: "5000" = 50.00%. For fixed: "5000" = $50.00.'
type: string
example: '5000'
nullable: true
type: object
DetailedRateSchema:
required:
- date
- rate
properties:
date:
description: 'Night date (YYYY-MM-DD)'
type: string
example: '2026-04-01'
rate:
description: 'Base room rate for this night in minor currency units (e.g. 15000 = $150.00)'
type: string
example: '15000'
adults:
description: 'Adult surcharge for this night in minor currency units (e.g. 2500 = $25.00)'
type: string
example: '2500'
children:
description: 'Child surcharge for this night in minor currency units (e.g. 1000 = $10.00)'
type: string
example: '1000'
type: object
FeeExternalIdSchema:
required:
- feeId
properties:
feeId:
description: 'Cloudbeds fee id, as returned in `feeID` by getTaxesAndFees: a positive integer without leading zeros, at most 9223372036854775807. An id replaced by a later edit of the fee is accepted and resolved to the fee''s current version.'
type: string
maxLength: 19
pattern: '^[1-9][0-9]*$'
example: '55210'
externalId:
description: 'External ID to assign, at most 64 characters after leading and trailing whitespace is trimmed. Null, an empty value or an omitted field clears the mapping.'
type: string
example: CLVR_SVC_FEE
nullable: true
type: object
LengthOfStayRangeSchema:
required:
- minimumNights
properties:
minimumNights:
description: 'Minimum nights for this range to apply (inclusive).'
type: integer
example: 1
maximumNights:
description: 'Maximum nights for this range (inclusive). Null means no upper limit.'
type: integer
example: 28
nullable: true
amount:
description: 'Override tax/fee amount for this range, in minor currency units (e.g. 1000 = $10.00).'
type: string
example: '1000'
nullable: true
amountAdult:
description: 'Override per-adult amount for this range, in minor currency units (e.g. 500 = $5.00).'
type: string
example: '500'
nullable: true
amountChild:
description: 'Override per-child amount for this range, in minor currency units (e.g. 250 = $2.50).'
type: string
example: '250'
nullable: true
amountRateBased:
description: 'Override rate-based tiers for this range.'
type: array
items:
$ref: '#/components/schemas/RateBasedTierSchema'
nullable: true
maxLength:
description: 'Override max nights to charge for per-person taxes.'
type: integer
example: 10
nullable: true
amountPerPersonRateBased:
description: 'Override per-person rate tiers for this range.'
type: array
items:
$ref: '#/components/schemas/PerPersonRateBasedTierSchema'
nullable: true
type: object
LengthOfStaySchema:
required:
- applicationType
- ranges
properties:
applicationType:
description: 'How length-of-stay rules are applied. "progressive_application" applies per-night based on which night it is. "retroactive_adjustment" applies uniformly based on total stay length.'
type: string
enum:
- progressive_application
- retroactive_adjustment
example: progressive_application
ranges:
description: 'Length-of-stay ranges. Each range defines amount overrides for a night count bracket.'
type: array
items:
$ref: '#/components/schemas/LengthOfStayRangeSchema'
type: object
MoneyInputSchema:
required:
- amount
- currencyCode
properties:
amount:
description: 'Amount in the smallest representable units of the currency (e.g., cents for USD)'
type: string
example: '10000'
currencyCode:
description: 'ISO 4217 currency code'
type: string
example: USD
type: object
PerPersonRateBasedTierSchema:
required:
- rate
properties:
rate:
description: 'Gross nightly rate floor in minor currency units. The tier with the highest rate at or below the room''s nightly rate applies (e.g. 10000 = 100.00).'
type: string
example: '10000'
amountAdult:
description: 'Charged once per adult per night, in minor currency units. Absent means adults are not charged.'
type: string
example: '100'
nullable: true
amountChild:
description: 'Charged once per child per night, in minor currency units. Absent means children are not charged.'
type: string
example: '50'
nullable: true
type: object
RateBasedTierSchema:
required:
- rate
- percentage
properties:
rate:
description: 'Rate threshold in minor currency units. Tax tier applies when the base rate is >= this value (e.g. 15000 = $150.00).'
type: string
example: '0'
percentage:
description: 'Tax percentage to apply when the rate threshold is met, in minor units (e.g. 1000 = 10.00%).'
type: string
example: '1000'
type: object
RoomSchema:
required:
- startDate
- endDate
- adults
- children
- detailedRates
properties:
roomTypeId:
description: 'Room type ID for per-room-type tax filtering'
type: string
example: '101'
nullable: true
startDate:
description: 'Check-in date (YYYY-MM-DD)'
type: string
example: '2026-04-01'
endDate:
description: 'Check-out date (YYYY-MM-DD)'
type: string
example: '2026-04-03'
adults:
description: 'Number of adults (>= 1)'
type: integer
example: 2
children:
description: 'Number of children (>= 0)'
type: integer
example: 1
rateId:
description: 'Rate plan ID (context only)'
type: string
example: '456'
nullable: true
detailedRates:
description: 'Per-night rate breakdown. One entry per night of the stay.'
type: array
items:
$ref: '#/components/schemas/DetailedRateSchema'
addons:
description: 'Add-ons to include in calculation'
type: array
items:
$ref: '#/components/schemas/AddonSchema'
nullable: true
type: object
TaxExternalIdSchema:
required:
- taxId
properties:
taxId:
description: 'Cloudbeds tax id, as returned in `taxID` by getTaxesAndFees: a positive integer without leading zeros, at most 9223372036854775807. An id replaced by a later edit of the tax is accepted and resolved to the tax''s current version.'
type: string
maxLength: 19
pattern: '^[1-9][0-9]*$'
example: '98123'
externalId:
description: 'External ID to assign, at most 64 characters after leading and trailing whitespace is trimmed. Null, an empty value or an omitted field clears the mapping.'
type: string
example: CLVR_TAX_8KJ2N1
nullable: true
type: object
TaxFeeConfigSchema:
required:
- id
- name
- category
- calculationType
- value
- taxTreatment
properties:
id:
description: 'Unique identifier within the request'
type: string
example: '101'
name:
description: 'Display name'
type: string
example: 'VAT 10%'
category:
description: 'Whether this is a tax or a fee'
type: string
enum:
- tax
- fee
example: tax
calculationType:
description: 'How the amount is calculated'
type: string
enum:
- percentage
- percentage_rate_based
- fixed
- fixed_per_person
- fixed_per_person_rate_based
- fixed_per_accomodation
- fixed_per_reservation
example: percentage
value:
description: 'Rate or amount value in minor units. For percentage types: the percentage in minor units (e.g., "1000" = 10.00%). For fixed types: the amount in minor currency units (e.g., "1500" = $15.00).'
type: string
example: '1000'
taxTreatment:
description: 'How this tax/fee relates to the base amount'
type: string
enum:
- inclusive
- exclusive
example: exclusive
appliedTo:
description: 'Application targets — where the tax/fee gets applied. A tax with `appliedTo=["rate","fee"]` is applied both to the base rate AND to each parent of type "fee". Defaults are derived from `category` + `parents` when omitted: a fee → `["rate"]`; a tax with no parent → `["rate"]`; a tax with a `fee` parent → `["fee"]`; a tax with a `tax` parent → `["tax"]`.'
type: array
items:
type: string
enum:
- product
- rate
- payment
- fee
- source
- sub_source
- room_revenue
- custom_item
- tax
example:
- rate
nullable: true
parents:
description: 'Compound parents (tax-on-fee, tax-on-tax). A tax may reference multiple parents.'
type: array
items:
$ref: '#/components/schemas/TaxFeeParentSchema'
nullable: true
parentId:
description: 'Deprecated — use `parents` instead. Single parent ID for tax-on-fee or tax-on-tax. Kept for backward compatibility; when set (and `parents` is omitted) it is mapped to a single-element `parents` list.'
type: string
nullable: true
deprecated: true
parentKind:
description: 'Deprecated — use `parents` instead. Kind of the legacy `parentId` parent.'
type: string
enum:
- tax
- fee
nullable: true
deprecated: true
roomTypeIds:
description: 'Room type IDs this tax/fee applies to. Empty means all room types.'
type: array
items:
type: string
nullable: true
typeSettings:
oneOf:
-
$ref: '#/components/schemas/TypeSettingsSchema'
nullable: true
description: 'Additional type settings (length-of-stay rules, date ranges, per-person amounts, rate-based tiers).'
type: object
TaxFeeParentSchema:
description: "Compound parent reference — points to another tax (tax-on-tax) or fee (tax-on-fee)\nin the same request. A tax row may carry multiple parents (e.g. taxed on both a\nparent fee AND a parent tax); see `TaxFeeConfigSchema::$parents`."
required:
- id
- kind
properties:
id:
description: 'ID of the parent tax or fee (must match an `id` in the same request).'
type: string
example: '101'
kind:
description: 'Whether the parent is a tax or a fee.'
type: string
enum:
- tax
- fee
example: fee
type: object
TypeSettingsSchema:
description: "Additional type settings for tax/fee calculation.\nAll properties are optional — only provide what applies to the specific tax/fee."
properties:
amountAdult:
description: 'Per-adult fixed amount in minor currency units (e.g. 1000 = $10.00). Used with fixed_per_person calculation type when adults and children have different rates.'
type: string
example: '1000'
nullable: true
amountChild:
description: 'Per-child fixed amount in minor currency units (e.g. 500 = $5.00). Used with fixed_per_person calculation type when adults and children have different rates.'
type: string
example: '500'
nullable: true
amountRateBased:
description: 'Rate-based percentage tiers. Required for percentage_rate_based calculation type. Each tier defines a rate threshold and the tax percentage to apply when the base rate meets it.'
type: array
items:
$ref: '#/components/schemas/RateBasedTierSchema'
nullable: true
maxLength:
description: 'Maximum number of nights to charge for per-person taxes. When set, per-person taxes stop accruing after this many nights per guest.'
type: integer
example: 28
nullable: true
dateRanges:
description: 'Date ranges with amount overrides. When present, the tax/fee only applies on nights that fall within a matching range, using the range''s overridden amounts. If no range matches a given night, the tax/fee is excluded for that night.'
type: array
items:
$ref: '#/components/schemas/DateRangeSchema'
nullable: true
lengthOfStay:
oneOf:
-
$ref: '#/components/schemas/LengthOfStaySchema'
nullable: true
description: 'Length-of-stay rules that override amounts based on the number of nights.'
exclusiveBase:
description: 'Base an exclusive percentage tax/fee multiplies: "net" carves inclusive taxes and fees out first, "gross" multiplies the quoted price. An explicit value always wins. When unset the row is charged on net — unless the deprecated request-level exclusiveTaxesOnTotal is false on a non-room_revenue calculation, where unset means gross. Meaningful only for exclusive percentage rows.'
type: string
enum:
- net
- gross
example: gross
nullable: true
amountPerPersonRateBased:
description: 'Per-person rate tiers. Required for fixed_per_person_rate_based calculation type. Each tier defines a gross nightly rate floor and the per-adult and per-child amounts charged when the room''s rate meets it.'
type: array
items:
$ref: '#/components/schemas/PerPersonRateBasedTierSchema'
nullable: true
type: object
UpdateExternalIdsRequestSchema:
description: 'Taxes and fees whose External ID to set or clear. At least one entry overall, at most 100 across both lists. Taxes and fees not listed keep their External ID.'
properties:
taxes:
description: 'Taxes to update. Each tax may appear once.'
type: array
items:
$ref: '#/components/schemas/TaxExternalIdSchema'
fees:
description: 'Fees to update. Each fee may appear once.'
type: array
items:
$ref: '#/components/schemas/FeeExternalIdSchema'
type: object
UpdateTaxRoundingSettingsRequestSchema:
required:
- scope
properties:
scope:
description: 'row: every tax and fee line is rounded. reservation: a percentage tax or fee is rounded once over the reservation.'
type: string
enum:
- row
- reservation
type: object
CalculateTotalsResponseSchema:
required:
- type
- netAmount
- subtotal
- inclusiveTaxesAndFees
- exclusiveTaxesAndFees
- taxes
- fees
- total
- paymentTotal
- currencyCode
properties:
type:
description: 'Echoed from request'
type: string
example: reservation
netAmount:
$ref: '#/components/schemas/MoneySchema'
subtotal:
$ref: '#/components/schemas/MoneySchema'
inclusiveTaxesAndFees:
$ref: '#/components/schemas/MoneySchema'
exclusiveTaxesAndFees:
$ref: '#/components/schemas/MoneySchema'
taxes:
$ref: '#/components/schemas/TaxFeeBreakdownResponseSchema'
fees:
$ref: '#/components/schemas/TaxFeeBreakdownResponseSchema'
total:
$ref: '#/components/schemas/MoneySchema'
convenienceFee:
oneOf:
-
$ref: '#/components/schemas/ConvenienceFeeResponseSchema'
nullable: true
description: 'Convenience fee details'
paymentTotal:
$ref: '#/components/schemas/MoneySchema'
currencyCode:
description: 'ISO 4217 currency code'
type: string
example: USD
deposit:
oneOf:
-
$ref: '#/components/schemas/MoneySchema'
nullable: true
description: 'Calculated deposit amount. Reservation only.'
balanceDue:
oneOf:
-
$ref: '#/components/schemas/MoneySchema'
nullable: true
description: 'total - deposit. Reservation only.'
defaultAddonsTotal:
oneOf:
-
$ref: '#/components/schemas/MoneySchema'
nullable: true
description: 'Total of default (package) add-ons. Reservation only.'
requestedAddonsTotal:
oneOf:
-
$ref: '#/components/schemas/MoneySchema'
nullable: true
description: 'Total of explicitly requested add-ons. Reservation only.'
rooms:
description: 'Per-room totals breakdown. Reservation only.'
type: array
items:
$ref: '#/components/schemas/RoomTotalsResponseSchema'
nullable: true
type: object
ConvenienceFeeResponseSchema:
required:
- name
- amount
- rate
- rateType
- mode
properties:
name:
description: 'Display name (echoed)'
type: string
example: 'Credit Card Surcharge'
amount:
$ref: '#/components/schemas/MoneySchema'
rate:
description: 'Fee rate (echoed)'
type: string
example: '3.00'
rateType:
description: 'How calculated (echoed)'
type: string
enum:
- percentage
- fixed
example: percentage
mode:
description: 'Mode used (echoed)'
type: string
enum:
- fee_on_top
- fee_from_total
example: fee_on_top
type: object
ExternalIdErrorCodeEnumSchema:
description: 'Machine-readable error code returned when updating tax and fee External IDs.'
type: string
enum:
- TAX_NOT_FOUND
- FEE_NOT_FOUND
- TAX_SYSTEM_MANAGED
- FEE_SYSTEM_MANAGED
- DUPLICATE_ID_IN_REQUEST
- DUPLICATE_EXTERNAL_ID_IN_REQUEST
- EXTERNAL_ID_CONFLICT
FeeExternalIdResponseSchema:
required:
- requestedFeeId
- feeId
- externalId
properties:
requestedFeeId:
description: 'Fee id as sent in the request.'
type: string
example: '55210'
feeId:
description: 'Current version of the fee the External ID was written to. Differs from requestedFeeId when the requested fee has since been edited.'
type: string
example: '55210'
externalId:
description: 'External ID now assigned; null when cleared.'
type: string
example: CLVR_SVC_FEE
nullable: true
type: object
RoomTotalsResponseSchema:
required:
- totalWithoutTaxes
- totalFirstNightWithoutTaxes
- taxesAndFees
- taxesAndFeesFirstNight
properties:
totalWithoutTaxes:
$ref: '#/components/schemas/MoneySchema'
totalFirstNightWithoutTaxes:
$ref: '#/components/schemas/MoneySchema'
taxesAndFees:
$ref: '#/components/schemas/MoneySchema'
taxesAndFeesFirstNight:
$ref: '#/components/schemas/MoneySchema'
type: object
TaxExternalIdResponseSchema:
required:
- requestedTaxId
- taxId
- externalId
properties:
requestedTaxId:
description: 'Tax id as sent in the request.'
type: string
example: '98123'
taxId:
description: 'Current version of the tax the External ID was written to. Differs from requestedTaxId when the requested tax has since been edited.'
type: string
example: '98410'
externalId:
description: 'External ID now assigned; null when cleared.'
type: string
example: CLVR_TAX_8KJ2N1
nullable: true
type: object
TaxFeeBreakdownResponseSchema:
required:
- total
- items
properties:
total:
$ref: '#/components/schemas/MoneySchema'
items:
description: 'Individual line items'
type: array
items:
$ref: '#/components/schemas/TaxFeeItemResponseSchema'
type: object
TaxFeeItemResponseSchema:
required:
- id
- name
- amount
- taxTreatment
properties:
id:
description: 'Tax/fee ID (echoed)'
type: string
example: '101'
name:
description: 'Display name (echoed)'
type: string
example: 'VAT 10%'
amount:
$ref: '#/components/schemas/MoneySchema'
taxTreatment:
description: 'Tax treatment (echoed)'
type: string
enum:
- inclusive
- exclusive
example: exclusive
parents:
description: 'Compound parents (tax-on-fee, tax-on-tax). Empty when the row is not a compound tax.'
type: array
items:
$ref: '#/components/schemas/TaxFeeParentResponseSchema'
type: object
TaxFeeParentResponseSchema:
description: "Compound parent reference echoed back on each tax/fee line item — counterpart of the\nrequest-side `TaxFeeParentSchema`."
required:
- id
- kind
properties:
id:
description: 'ID of the parent tax or fee.'
type: string
example: '101'
kind:
description: 'Whether the parent is a tax or a fee.'
type: string
enum:
- tax
- fee
example: fee
type: object
TaxRoundingSettingsResponseSchema:
required:
- data
properties:
data:
$ref: '#/components/schemas/TaxRoundingSettingsSchema'
type: object
TaxRoundingSettingsSchema:
required:
- scope
properties:
scope:
description: 'row: every tax and fee line is rounded. reservation: a percentage tax or fee is rounded once over the reservation. null: the property has not chosen yet and rounds as before.'
type: string
enum:
- row
- reservation
nullable: true
type: object
UpdateExternalIdsResponseSchema:
required:
- data
properties:
data:
$ref: '#/components/schemas/UpdatedExternalIdsResponseSchema'
type: object
UpdatedExternalIdsResponseSchema:
required:
- taxes
- fees
properties:
taxes:
description: 'Resulting External ID of each requested tax, in request order.'
type: array
items:
$ref: '#/components/schemas/TaxExternalIdResponseSchema'
fees:
description: 'Resulting External ID of each requested fee, in request order.'
type: array
items:
$ref: '#/components/schemas/FeeExternalIdResponseSchema'
type: object
parameters:
roomId:
name: roomId
in: path
description: 'Room ID'
required: true
schema:
type: string
example: 1-b
securitySchemes:
api_key:
type: apiKey
name: x-api-key
in: header
default:
type: oauth2
flows:
authorizationCode:
authorizationUrl: 'https://api.cloudbeds.com/auth/oauth/authorize'
tokenUrl: 'https://api.cloudbeds.com/auth/oauth/token'
scopes:
'read:addon': 'Read Addon information'
'read:doorLockKey': 'Read DoorLock keys and settings'
'write:doorLockKey': 'Write DoorLock keys and settings'
'delete:doorLockKey': 'Delete DoorLock keys and settings'
'read:housekeeping': 'Read Housekeeping inspections'
'read:marketsegment': 'Read Market Segmentation groups and segments'
'write:marketsegment': 'Write Market Segmentation groups and segments'
'delete:marketsegment': 'Delete Market Segmentation groups and segments'
'write:importTask': 'Create new data imports'
'read:importTask': 'Read data imports'
'hotel:read': 'Read Hotel information'
'hotel:write': 'Write Hotel information'
'hotel:delete': 'Delete Hotel information'
'write:appError': 'Write AppError information'
'read:agePolicy': 'Read Age Policy information'
'write:agePolicy': 'Write Age Policy information'
'delete:agePolicy': 'Delete Age Policy information'
'write:allotmentBlocks': 'Write AllotmentBlock information'
'read:allotmentBlocks': 'Read AllotmentBlock information'
'delete:allotmentBlocks': 'Delete AllotmentBlock information'
'read:marketingPerformance': 'Read Digital Marketing performance'
tags:
-
name: Addons
description: Addons
-
name: Amenities
description: Amenities
-
name: Applications
description: Applications
-
name: booking-room
description: booking-room
-
name: Checks
description: Checks
-
name: 'Door Locks'
description: 'Door Locks'
-
name: Events
description: Events
-
name: Gratuities
description: Gratuities
-
name: Housekeeping
description: Housekeeping
-
name: 'Integration Events'
description: 'Integration Events'
-
name: Items
description: Items
-
name: 'Market Segmentation'
description: 'Market Segmentation'
-
name: 'Marketing Performance'
description: 'Marketing Performance'
-
name: Payments
description: Payments
-
name: Property
description: Property
-
name: 'Rate Plans'
description: 'Rate Plans'
-
name: 'Smart Policies'
description: 'Smart Policies'
-
name: 'Smart Policy Exceptions'
description: 'Smart Policy Exceptions'