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'