API docs by Redocly

CiaoBooking Public API (1.0.0)

Download OpenAPI specification:

CiaoBooking offers a variety of API products, tools, and resources to help you extend functionality and improve your experience with your PMS system.

Getting Started Guide

To begin using the CiaoBooking API, you must:

  • Create a new user in CiaoBooking

  • Assign the API - Pubbliche role to that user

Authentication

The authentication endpoint is used to retrieve the Bearer token, which must be included in the Authorization header of each request.

Authentication Error Response

If a token is missing, malformed, or invalid, the API will return an HTTP 401 Unauthorized status code.

Rate and Usage Limits

The default rate limit is 300 requests per minute.
Depending on your subscription plan, additional usage limits may apply.
If you exceed these limits, the API will return an HTTP 429 Too Many Requests status code.

503 Response

An HTTP 503 response indicates a temporary spike in API traffic.
The server is usually back online within five minutes.
If the issue persists or if you encounter other 5XX errors, please contact support.

Need help?

For assistance, contact us at info@ciaobooking.com

Auth

The CiaoBooking API uses Bearer Token authentication.

To access any of the endpoints, you must first authenticate by calling the login endpoint to obtain a Bearer token.

This token must then be included in the Authorization header of each subsequent request as follows:

Authorization: Bearer YOUR_TOKEN_HERE

Login

Authenticates the user using provided credentials and returns an access token to authorize subsequent API requests.

You can call this endpoint before each request, or manage session expiration using the expiresAt timestamp returned in the response to avoid unnecessary repeated logins.

Authorizations:
bearerAuth
header Parameters
locale
string
Example: {{locale}}
Request Body schema: multipart/form-data
email
string
password
string
source
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": [ ]
}

Booking Engine

The Booking Engine API provides endpoints to search and retrieve available room combinations, rates, and booking options within the CiaoBooking platform. It handles the complex logic of finding available rooms with appropriate pricing based on occupancy, dates, and other criteria.

All endpoints require authentication via Bearer Token.

Combinations

Retrieves available room combinations for a specific property based on search criteria. This endpoint calculates room availability, rates, and possible guest combinations while considering factors like occupancy limits and pricing rules.

Parameters

Parameter Type Required Description
property_id integer Yes The ID of the property to search combinations for
start_date date Yes Check-in date (format: YYYY-MM-DD)
end_date date Yes Check-out date (format: YYYY-MM-DD)
guests integer No Number of adult guests
children integer No Number of children
unit_category_ids array No Array of specific unit category IDs to filter results

Response

The endpoint returns a paginated list of available room combinations with the following information:

  • Property details (name, currency, etc.)

  • Unit categories with their configurations

  • Room types available for each category

  • Rate information including:

    • Base rates for the selected dates

    • Adjusted rates based on occupancy

    • Special pricing for additional guests

    • Children rates when applicable

  • Occupancy information:

    • Minimum and maximum guests

    • Standard occupancy

    • Maximum children allowed

    • Available guest combinations

Authorizations:
bearerAuth
query Parameters
property_id
string
Example: property_id=138228

The ID of the property to search combinations for (required)

start_date
string
Example: start_date=2025-06-12

Check-in date (format: YYYY-MM-DD) (required)

end_date
string
Example: end_date=2025-06-17

Check-out date (format: YYYY-MM-DD) (required)

unit_category_ids[0]
string
Example: unit_category_ids[0]=177

Array of specific unit category IDs to filter results

guest
string
Example: guest=1

Number of adult guests

childrens
string
Example: childrens=1

Number of childrens

limit
string
Example: limit=

Maximum number of results per page

page
string
Example: page=

Maximum number of clients returned per page.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": [ ]
}

Clients

The Clients API provides endpoints to create, update, and retrieve clients within the CiaoBooking platform.

All endpoints require authentication via Bearer Token.

Schema

type (integer)

Possible values:

  • 1 → PRIVATE

  • 2 → COMPANY

  • 3 → PUBLIC ADMINISTRATION

Field Descriptions

  • id – Unique identifier of the client

  • type – Client type (See above)

  • name – Full name of the client

  • email – Email address

  • country – Country of residence

  • city – City of residence

  • address – Physical address

  • phone – Contact phone number

  • phone_normalized – Client’s phone number formatted without +, spaces, or dashes

  • stripe_setup_intent_id – Stripe Setup Intent ID (if available)

  • is_blacklist – Boolean flag indicating if the client is blacklisted

  • tags – Array of associated tags

    • id – Tag identifier

    • name – Tag name

Get Paginated Clients

Retrieves a paginated collection list of clients with their basic information and associated tags.

Authorizations:
bearerAuth
query Parameters
limit
string
Example: limit=5

Maximum number of clients returned per page.

page
string
Example: page=1

Page number for paginated results.

search
string
Example: search=demo

Search filter applied to client name, email, or tags.

order
string
Example: order=asc

Sort direction: asc = ascending, desc = descending.

sortBy[]
string
Example: sortBy[]=name

Sort results by one or more fields. Available values: id, name, city, country, email, createdAt.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": [ ]
}

Create Client

Creates a new client in the system.

Request Body - Fields description

Field Type Description Notes
name string Full name of the client Required
company_id integer Valid company ID Required
type integer Client type: 1 = Private, 2 = Company, 3 = Public Administration Required
first_name string Client’s first name Optional
last_name string Client’s last name Optional
locale string Language/locale code (e.g., it, en) Optional
tags[n][value] integer Existing tag ID for the nth tag (0 to 4) Maximum 5 tags total
tags[n][text] string Existing tag label for the nth tag Maximum 5 tags total
tags[n] string New tag label for the nth tag (only label) Maximum 5 tags total
notes string Optional notes about the client Optional
birthday string (date) Birthday in YYYY-MM-DD format Optional
newsletter integer (bool) Subscribe to newsletter: 1 = yes, 0 = no Optional
is_blacklist integer (bool) Is the client blacklisted? 1 = yes, 0 = no Optional
email string Client’s email address Optional
pec string PEC (certified email), if applicable Optional
phone string Contact phone number Optional
tax_code string Client’s tax code Optional
sdi string SDI code for electronic invoicing Optional
address string Street address Optional
postcode string Postal code Optional
city string City of residence Optional
latitude number (float) Latitude (for geolocation) Optional
longitude number (float) Longitude (for geolocation) Optional
state string Province or state abbreviation Optional
country string Country code (ISO 3166-1 alpha-2) Optional
vat_code string Client’s VAT number Optional

Notes

  • Maximum 5 tags total (existing + new combined).

  • tags can contain existing tags (value and text) or new tags (label only).

  • Boolean fields (newsletter, is_blacklist) accept 1 for true, 0 for false.

  • Optional fields can be omitted if not applicable.

Authorizations:
bearerAuth
Request Body schema: application/json
address
string
birthday
string
city
string
company_id
number
country
string
email
string
first_name
string
is_blacklist
number
last_name
string
latitude
number
locale
string
longitude
number
name
string
newsletter
number
notes
string
pec
string
phone
string
postcode
string
sdi
string
state
string
Array of objects or strings
tax_code
string
type
number
vat_code
string

Responses

Request samples

Content type
application/json
{
  • "address": "Via Interna, 13",
  • "birthday": "1980-06-10",
  • "city": "Pordenone",
  • "company_id": 1359,
  • "country": "IT",
  • "email": "demo@ciaobooking.com",
  • "first_name": "Demo",
  • "is_blacklist": 0,
  • "last_name": "Name",
  • "latitude": 45.97211739999999,
  • "locale": "it",
  • "longitude": 12.6590859,
  • "name": "Demo Client Name",
  • "newsletter": 1,
  • "notes": "demo notes",
  • "pec": "demo_pec@ciaobooking.com",
  • "phone": "0123-12345678",
  • "postcode": "33170",
  • "sdi": "012345",
  • "state": "PN",
  • "tags": [
    ],
  • "tax_code": "CLTDMN87L05G888A",
  • "type": 1,
  • "vat_code": "IT0012345678"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": [ ]
}

Update Client

Updates an existing client by ID.

Request Body - Fields description

Field Type Description Notes
name string Full name of the client Required
company_id integer Valid company ID Required
type integer Client type: 1 = Private, 2 = Company, 3 = Public Administration Optional
first_name string Client’s first name Optional
last_name string Client’s last name Optional
locale string Language/locale code (e.g., it, en) Optional
tags[n][value] integer Existing tag ID for the nth tag (0 to 4) Maximum 5 tags total
tags[n][text] string Existing tag label for the nth tag Maximum 5 tags total
tags[n] string New tag label for the nth tag (only label) Maximum 5 tags total
notes string Optional notes about the client Optional
birthday string (date) Birthday in YYYY-MM-DD format Optional
newsletter integer (bool) Subscribe to newsletter: 1 = yes, 0 = no Optional
is_blacklist integer (bool) Is the client blacklisted? 1 = yes, 0 = no Optional
email string Client’s email address Optional
pec string PEC (certified email), if applicable Optional
phone string Contact phone number Optional
tax_code string Client’s tax code Optional
sdi string SDI code for electronic invoicing Optional
address string Street address Optional
postcode string Postal code Optional
city string City of residence Optional
latitude number (float) Latitude (for geolocation) Optional
longitude number (float) Longitude (for geolocation) Optional
state string Province or state abbreviation Optional
country string Country code (ISO 3166-1 alpha-2) Optional
vat_code string Client’s VAT number Optional

Notes

  • Maximum 5 tags total (existing + new combined).

  • tags can contain existing tags (value and text) or new tags (label only).

  • Boolean fields (newsletter, is_blacklist) accept 1 for true, 0 for false.

  • Optional fields can be omitted if not applicable.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1007119

Valid client ID

Request Body schema: application/json
company_id
number
name
string

Responses

Request samples

Content type
application/json
{
  • "company_id": 1359,
  • "name": "Demo Client Name"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": [ ]
}

Properties

The Properties API provides endpoints to access property information within the CiaoBooking platform.

Some endpoints require authentication via Bearer Token, while others are publicly accessible.

Schema

Response Fields

  • id – Property identifier

  • company_id – Associated company ID

  • name – Property name

  • email – Primary email address

  • email_alternative – Alternative email address

  • type – Property type

  • country – Property location country

  • is_active – Indicates if the property is active (boolean)

  • channel_manager – Channel manager information

  • octorate_accommodation_id – Octorate accommodation ID (if applicable)

  • channel_manager_id – Channel manager ID

  • Company details:

    • id – Company ID

    • name – Company name

  • Unit categories:

    • id – Unit category ID

    • property_id – Associated property ID

    • name – Unit category name

  • Units (excluding jolly and suite units):

    • id – Unit ID

    • property_id – Associated property ID

    • name – Unit name

Get All Properties (NO AUTH)

Retrieves a public collection of properties. This endpoint is cached for performance.

Authentication

No authentication required.

Parameters

  • company_id (required, encrypted) The encrypted company ID used to filter the properties.
Authorizations:
None
query Parameters
company_id
string
Example: company_id=7648486855465574556f452f306435785943443453673d3d

The encrypted company ID used to filter the properties. (required, encrypted)

limit
string
Example: limit=1

Maximum number of properties returned.

Responses

Response samples

Content type
application/json
{}

Get Paginated Properties

Retrieves a paginated list of properties with their basic information.

Authorizations:
bearerAuth
query Parameters
limit
string
Example: limit=5

Maximum number of properties returned per page.

page
string
Example: page=1

Page number for paginated results.

search
string
Example: search=demo

Search filter applied to properties name or email.

order
string
Example: order=asc

Sort direction: asc = ascending, desc = descending.

sortBy[]
string
Example: sortBy[]=name

Sort results by one or more fields. Available values: id, name, email, createdAt.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": [ ]
}

Get Properties by IDs

Returns detailed information about one or more properties, including unit categories, units, and room types.

This endpoint is useful when you need to retrieve the full structural data of a property.

The id or ids parameter is required to specify which property or properties to retrieve.

Authorizations:
bearerAuth
query Parameters
id
string
Example: id=139054

Single property ID. Must be provided if ids is omitted.

ids[]
string
Example: ids[]=139054

Array of property IDs. Must be provided if id is omitted.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": [ ]
}

Properties v3 (3.0)

Get All Properties (v3)

Retrieves all properties using the v3 public API.

Authorizations:
bearerAuth
query Parameters
company_id
string
Example: company_id=7648486855465574556f452f306435785943443453673d3d

Valid company ID (required)

Responses

Response samples

Content type
application/json
{}

Rate Calendar

The RateCalendar API provides endpoints to manage and retrieve rate calendar information for properties.

All endpoints require authentication via Bearer Token.

Schema

modification (integer)

Possible values:

  • 1 → DERIVATION

  • 2 → RATE_CALENDAR

  • 3 → RESERVATION_CREATE

  • 4 → RESERVATION_UPDATE

  • 5 → RESERVATION_CANCEL

  • 6 → BULK_UPDATE

  • 7 → AUTOCLOSE

  • 8 → RMT

  • 9 → ICAL

  • 10 → COPY

  • 11 → INITIAL_SYNC

  • 12 → AUTOPILOT

price_variation (integer)

Possible values:

  • 1 → EXACT

  • 2 → INCREMENT

  • 3 → PERCENT

Field Descriptions

  • room_type_id (integer)
    Identifier for the room type to which the rate applies.

  • availability (integer)
    Number of available units for the period.

  • auto_availability (boolean-like, 0 or 1)
    Whether availability is managed automatically.

  • min_stay (integer, nullable)
    Minimum stay requirement in nights. Range: 1 to 999.

  • max_stay (integer, nullable)
    Maximum stay limit in nights. Range: 1 to 999.

  • cta (boolean-like, 0 or 1)
    Close to arrival flag.

  • ctd (boolean-like, 0 or 1)
    Close to departure flag.

  • stop_sell (boolean-like, 0 or 1)
    Stop sell flag.

  • price_variation (integer)
    Price variation type (refer to the schema for possible values)

  • amount (numeric, nullable)
    Rate amount (price).

  • weekdays (array, nullable)
    Optional list of weekdays to apply the rate.

  • modification (integer)
    Type of modification applied in bulk create (refer to the schema for possible values)

Get Rate Calendar

Retrieves a collection of rate calendar data with detailed information about prices, availability, and booking restrictions.

The maximum limit of records is 500.

Returns a collection of rate calendar entries with:

  • Rate information (amount, availability)

  • Date ranges

  • Room type details

  • Restrictions (min_stay, max_stay, cta, ctd, stop_sell)

  • Cut-off information

Authorizations:
bearerAuth
query Parameters
from
string
Example: from=2025-01-01

Start date of the range (inclusive). Format: YYYY-MM-DD

to
string
Example: to=2025-12-31

End date of the range (inclusive). Format: YYYY-MM-DD

limit
string
Example: limit=400

Maximum number of results to return. The default or maximum is defined by the API.

offset
string
Example: offset=5

Number of items to skip, used for pagination.

property_id
string
Example: property_id=

ID of the property to filter results for

room_type_id
string
Example: room_type_id=

ID of the room type (combination of unit category and rate plan)

unit_category_id
string
Example: unit_category_id=

ID of the unit category to filter associated room types

rate_plan_id
string
Example: rate_plan_id=

ID of the rate plan to filter associated room types

guests
string
Example: guests=

Number of guests to match rate availability

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": [ ]
}

Get RMS Rate Calendar Data

Retrieves rate calendar data specifically formatted for Revenue Management Systems (RMS).

This endpoint is optimized for external integrations and returns raw rate data.

Returns:

  • Date-based rate information

  • Room type associations

  • Property filtering support

  • Format optimized for RMS integrations

Authorizations:
bearerAuth
query Parameters
from
string
Example: from=2025-01-01

Start date of the range (inclusive). Format: YYYY-MM-DD

to
string
Example: to=2025-06-30

End date of the range (inclusive). Must be after 'from'. Format: YYYY-MM-DD

property_ids[]
string
Example: property_ids[]=

Optional. Filter by one or more property IDs. Send as array.

room_type_ids[]
string
Example: room_type_ids[]=33393

Optional. Filter by one or more room type IDs (unit category + rate plan). Send as array.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": [ ]
}

Bulk Create Rate Calendar Entries

Creates multiple rate calendar entries in bulk for efficient mass updates. Supports various modification types.

Request Body

Array of rate calendar objects with the following fields:

Field Type Description Notes
room_type_id integer Identifier of the room type Required
start_date string Start date of the rate period (YYYY-MM-DD) Required
end_date string End date of the rate period (YYYY-MM-DD) Required
amount integer Rate amount in cents (e.g., 10000 = 100.00) Required
availability integer Number of available units Optional
min_stay integer Minimum stay requirement Optional
max_stay integer Maximum stay limit Optional
cta boolean Close to arrival flag Optional, accepts 0 or 1
ctd boolean Close to departure flag Optional, accepts 0 or 1
stop_sell boolean Stop sell flag Optional, accepts 0 or 1
auto_availability boolean Auto availability flag Optional, accepts 0 or 1
weekdays array Days of the week affected (1 Monday, 2 Tuesday, etc.) Optional
modification string Type of modification, defaults to BULK_UPDATE Optional

Response

Returns an array with the processed rate calendar entries confirming creation or update.

Notes

  • Boolean flags (auto_availability, cta, ctd, stop_sell) accept 0 or 1.
  • The modification field defaults to 6 (BULK_UPDATE) if not specified.
  • Typical HTTP responses:
    • 200 OK — Success
    • 401 Unauthorized — Missing or invalid token
    • 422 Unprocessable Entity — Validation errors
    • 500 Internal Server Error — Server issues
Authorizations:
bearerAuth
Request Body schema: application/json
Array
amount
number
auto_availability
number
availability
number
cta
number
ctd
number
end_date
string
max_stay
number
min_stay
number
room_type_id
number
start_date
string
stop_sell
number
weekdays
Array of numbers

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": [ ]
}

Reservations

Here you will find the APIs related to retrieving reservations in CiaoBooking.

Schema

status (integer)

  • 1 → CANCELED

  • 2 → CONFIRMED

  • 3 → PENDING

guest_status (integer)

Possible values:

  • 0 → NOT ARRIVED

  • 1 → ARRIVED

  • 2 → LEFT

type (integer)

  • 1 → RESERVATION

  • 2 → OPTION

  • 3 → BLOCK DATES

payment_method (integer)

  • 0 → UNKNOWN

  • 1 → CREDIT CARD

  • 2 → BANK TRANSFER

  • 3 → PREPAID

  • 4 → CASH

  • 5 → UPON ARRIVAL

is_split (integer)

  • 0 → NOT SPLITTED

  • 1 → SPLITTED

  • 2 → MOVED

is_checkin_completed (integer)

  • 0 → TO DO

  • 1 → COMPLETED

  • 2 → VERIFIED

Field Descriptions

  • amount – Total base price of the room(s).

  • cleaning_fee – Additional cleaning fee applied to the reservation.

  • extras – Total cost of all extras included in the reservation.

  • city_tax – Expected amount of city tax to be collected.

  • total_gross – Sum of amount, cleaning_fee, and extras.

  • guests – Total number of guests requiring a bed. This includes children.

  • children – Number of children included in the reservation.

  • infants – Number of infants. Not included in the guests count.

  • meal_plan – Type of meal plan selected for the reservation:

    • 0 → ROOM_ONLY

    • 1 → BREAKFAST

    • 2 → HALF_BOARD

    • 3 → FULL_BOARD

    • 4 → ALL_INCLUSIVE

Get All Reservations

Retrieves a public collection of reservations.

The API request must include either the from and to query parameters or the updated_at parameter.

It is recommended to use the from and to parameters for the initial data pull. Subsequently, use the updated_at parameter to fetch only the changes (differences) since the last API call by passing the timestamp of the previous request.

The maximum number of reservations returned per API call is limited to 200.

Notes

  • Returns only reservations that are not split or moved split reservations

  • All dates filter based on the start_date field

  • Pagination supported with limit and offset

  • Maximum limit is 200 records per request

  • The response includes comprehensive reservation details with related entities

Error Responses

  • 403 Forbidden — User lacks EXTERNAL_API role

  • 422 Validation Error — Missing or invalid parameters (e.g., missing from and to, invalid date format, or limit > 200)

Authorizations:
bearerAuth
query Parameters
from
string
Example: from=2025-01-01

Start date for filtering reservations (inclusive). Format: YYYY-MM-DD

to
string
Example: to=2025-06-18

End date for filtering reservations (inclusive). Format: YYYY-MM-DD

updated_at
string
Example: updated_at=

Filter reservations updated since this timestamp (ISO 8601 or Unix timestamp)

status
string
Example: status=

Filter by reservation status (e.g., confirmed, cancelled).

limit
string
Example: limit=10

Maximum number of results to return (default 200, max 200)

offset
string
Example: offset=1

Number of results to skip for pagination

property_id
string
Example: property_id=142321

Filter by specific property ID

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": [ ]
}

Create Reservation

Creates a new reservation in the system. Supports full reservation details, including client and pricing information.

Request Body Parameters

Required Parameters

Field Type Description
type integer 1 = RESERVATION, 2 = OPTION, 3 = BLOCK
property_id integer ID of the property
room_type_id integer ID of the room type
start_date string Check-in date (format: Y-m-d)
end_date string Check-out date (format: Y-m-d)
guests integer Number of guests (minimum: 1)

Client Information

Option 1 – Existing Client

Field Type Description
client_id integer ID of the existing client

Option 2 – New Client

Field Type Description
client object Client data object
company_id integer ID of the company
name string Full name
email string Email address

Pricing

Option 1 – Total Amount

Field Type Description
amount number Total reservation amount

Option 2 – Daily Breakdown

Field Type Description
amount_details array Daily amounts list
date string Date (Y-m-d)
amount number Amount for the date
discount number Discount for the date

Optional Parameters

Reservation Details

Field Type Description
property_id integer Auto-detected if not provided
unit_id integer ID of the specific unit
source_id integer Source of reservation (defaults to PMS)
quantity integer Number of identical reservations (default: 1)
res_id string External ID (auto-generated if not set)
type integer 1 = RESERVATION, 2 = OPTION, 3 = BLOCK
status integer 1 = CANCELED, 2 = CONFIRMED, 3 = PENDING
currency string Currency code
arrival_time string Format: H:i
checkout_time string Format: H:i
expired_at string Required if type is OPTION (Y-m-d H:i:s)
payment_method integer Payment method code
meal_plan integer Meal plan code
children integer Default: 0
infants integer Default: 0

Financial Info

Field Type Description
amount_promotions number Promotional discounts
city_tax number City tax
cleaning_fee number Cleaning fee
extras number Extra charges
ota_fee number OTA fees
discount number Total discount

Extras and Notes

Field Type Description
ref string Reservation reference
color string Color code
pin string Access PIN
flight_number string Flight number
ota_note string OTA notes
internal_note string Internal notes
service_note string Service notes
is_ciaobooking boolean Defaults to false
is_hidden boolean Defaults to false

Extras Array (amount_extras)

Field Type Description
name string Extra service name
amount number Price of extra
vat_percent number VAT applied to extra
property_extra_id integer ID from property_extras table

Control Flags

Field Type Description
confirm boolean If true, triggers confirmation events
skip_messages boolean If true, suppresses guest notifications
skip_notifications boolean If true, disables all notifications
Authorizations:
bearerAuth
Request Body schema: application/json
amount
string
amount_extras
Array of any
cleaning_fee
string
client_id
number
company_id
number
currency
string
end_date
string
extras
string
guests
number
is_refundable
number
meal_plan
number
property_id
number
room_type_id
number
start_date
string
type
number
unit_category_id
number
unit_id
number

Responses

Request samples

Content type
application/json
{
  • "amount": "190.00",
  • "amount_extras": [ ],
  • "cleaning_fee": "20.00",
  • "client_id": 1007109,
  • "company_id": 1359,
  • "currency": "EUR",
  • "end_date": "2025-07-01",
  • "extras": "5.00",
  • "guests": 2,
  • "is_refundable": 0,
  • "meal_plan": 0,
  • "property_id": 142321,
  • "room_type_id": 33393,
  • "start_date": "2025-06-29",
  • "type": 1,
  • "unit_category_id": 7156,
  • "unit_id": 146663
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": [ ]
}

Get Reservation by ID

Retrieves the details of a specific reservation.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1255558

ID of the reservation to cancel (Required)

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": [ ]
}

Update Reservation

Updates an existing reservation by ID.

Request Body Parameters

Required Parameters

These fields must be included in the request body:

Field Type Description
id integer ID of the reservation
property_id integer ID of the property
room_type_id integer ID of the room type
start_date string Check-in date (format: Y-m-d)
end_date string Check-out date (format: Y-m-d)
type integer Reservation type
status integer Reservation status
client_id integer ID of the client (or provide client object instead)
amount number Total reservation amount
is_checkin_completed integer Status of check-in

Client Information

Option 1 – Existing Client

Field Type Description
client_id integer ID of the existing client

Option 2 – New Client

Field Type Description
client object Client data object
company_id integer ID of the company
name string Full name
email string Email address

Pricing

Option 1 – Total Amount

Field Type Description
amount number Total reservation amount

Option 2 – Daily Breakdown

Field Type Description
amount_details array Daily pricing breakdown
date string Date (Y-m-d)
amount number Daily amount
discount number Daily discount

Optional Parameters

Reservation Details

Field Type Description
unit_id integer Specific unit ID
source_id integer Source of reservation (defaults to PMS)
quantity integer Number of identical reservations (default: 1)
res_id string External ID (auto-generated if not set)
currency string Currency code
arrival_time string Format: H:i
checkout_time string Format: H:i
expired_at string Required for OPTION type (Y-m-d H:i:s)
payment_method integer Payment method code
meal_plan integer Meal plan code
children integer Default: 0
infants integer Default: 0

Financial Information

Field Type Description
amount_promotions number Promotional discounts
city_tax number City tax
cleaning_fee number Cleaning fee
extras number Extra charges
ota_fee number OTA fees
discount number Total discount

Extras and Notes

Field Type Description
ref string Reservation reference
color string Reservation color
pin string Access PIN
flight_number string Flight number
ota_note string OTA notes
internal_note string Internal notes
service_note string Service-related notes
is_ciaobooking boolean Defaults to false
is_hidden boolean Defaults to false

Extras Array (amount_extras)

Field Type Description
name string Extra service name
amount number Price of the extra
vat_percent number VAT applied to the extra
property_extra_id integer ID from property_extras table

Control Flags

Field Type Description
confirm boolean If true, triggers confirmation workflow
skip_messages boolean If true, skips guest notifications
skip_notifications boolean If true, disables all notifications

Error Responses

Code Meaning Description
403 Forbidden User lacks EXTERNAL_API role or permission
404 Not Found Reservation with given ID not found
422 Unprocessable Entity Validation failed (e.g., missing fields, wrong formats)
409 Conflict Unit not available for the specified dates

Notes

  • If type = 2 (OPTION), then expired_at is required.

  • If client object is passed, a new client will be created.

  • confirm: true triggers relevant notifications.

  • System recalculates total_gross, to_pay, and taxes automatically.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1255558

ID of the reservation to cancel (Required)

Request Body schema: application/json
amount
string
cleaning_fee
string
client_id
number
end_date
string
extras
string
guests
number
id
number
is_checkin_completed
number
property_id
number
room_type_id
number
start_date
string
status
number
type
number

Responses

Request samples

Content type
application/json
{
  • "amount": "190.00",
  • "cleaning_fee": "60.00",
  • "client_id": 1007109,
  • "end_date": "2025-07-01",
  • "extras": "15.00",
  • "guests": 4,
  • "id": 1255575,
  • "is_checkin_completed": 0,
  • "property_id": 142321,
  • "room_type_id": 33393,
  • "start_date": "2025-06-29",
  • "status": 2,
  • "type": 1
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": [ ]
}

Delete Reservation

Cancels a reservation by ID. This is a soft delete operation — the reservation is marked as canceled, but not permanently removed from the database.

Request Body Parameters (JSON)

Name Type Default Description
delete_related boolean false If true, cancels all related reservations with the same res_id that are not already canceled
internal_note string – Adds an internal note to the reservation
skip_messages boolean false If true, no cancellation notifications will be sent
skip_channels boolean false If true, skips channel manager (OTA) updates
force boolean false If true, forces cancellation even if restrictions exist

Use Cases

  • Simple Cancellation — Cancel a single reservation

  • Group Cancellation — Cancel all related reservations with delete_related: true

  • Silent Cancellation — Suppress guest notifications with skip_messages: true

  • Channel-Specific Cancellation — Prevent OTA updates with skip_channels: true

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 1255558

ID of the reservation to cancel (Required)

Request Body schema: application/json
delete_related
boolean
force
boolean
internal_note
string
skip_channels
boolean
skip_messages
boolean

Responses

Request samples

Content type
application/json
{
  • "delete_related": true,
  • "force": false,
  • "internal_note": "Canceled due to guest no-show.",
  • "skip_channels": true,
  • "skip_messages": true
}

Response samples

Content type
application/json
{
  • "data": true,
  • "meta": [ ]
}