Create Booking

POST

/properties/{tenant_id}/bookings

Create a new booking with customer information, room assignments, and optional payments. The booking will be created with status “confirmed” and assigned a unique booking code.

Scope Required: bookings:write

Body Parameters:

• “currency”: format: ISO 4217 currency code, example: VND,
• “checkin_date”: format: YYYY-MM-DD,
• “arrival_hour”: format: H:i,
• “checkout_date”: format: YYYY-MM-DD,
• “departure_hour”: format: H:i,
• “source_commission”: integer (min 0) or null,
• “notes”: format: string, max: 500 characters,
• “source_name”: format: string, example: trip,
• “occupancy_children”: format: integer, min: 0,
• “occupancy_adults”: format: integer, min: 1,
• “occupancy_infants”: format: integer, min: 0,
• “payment_collect”: string|null, one of: “property”, “ota”, “online”, "",

Customer (customer) object:

• “customer”: object, required, main guest information,
• “customer.name”: string, required, max: 50 characters,
• “customer.phone”: string|null,
• “customer.email”: string|null, valid email format, max: 255 characters,
• “customer.birthday”: string|null, format: YYYY-MM-DD,
• “customer.gender”: string|null, one of: “male”, “female”, “unknown”,
• “customer.company”: string|null,
• “customer.address”: string|null,
• “customer.ward”: string|null,
• “customer.city”: string|null,
• “customer.country”: string|null, ISO 3166-1 alpha-2 format (2 uppercase letters). Example: VN, US, JP, KR
• “customer.identity”: string|null,
• “customer.identity_issue_date”: string|null, format: YYYY-MM-DD,
• “customer.id_type”: string|null, one of: “identity_card”, “passport”, “other”,
• “customer.is_child”: boolean|null,
• “customer.notes”: string|null, max: 500 characters,

Booking rooms (booking_rooms) array:

• “booking_rooms”: array, required, at least 1 item,
• “booking_rooms[].room_type_id”: string, required, room type code (must exist and be active),
• “booking_rooms[].default_rate”: numeric|null, default room rate,
• “booking_rooms[].room_discount”: numeric, optional discount amount (default 0),
• “booking_rooms[].days_breakdown”: array|null, custom price per day,
• “booking_rooms[].days_breakdown[].day”: string, required with days_breakdown, format: YYYY-MM-DD,
• “booking_rooms[].days_breakdown[].price”: numeric, required with days_breakdown, daily price,

Payments (payments) array:

• “payments”: array|null, list of payment records to attach to booking,
• “payments[].amount”: numeric, required, min: 0,
• “payments[].notes”: string|null,
• “payments[].method”: string|null, one of system payment method (cash, bank_transfer, debt, atm_transfer, credit_card, apple_pay, pos, wechat_pay..v.v),
• “payments[].paid_at”: string|null, format: YYYY-MM-DD H:i:s,

Auto-cancel option:

• “auto_cancel”: boolean|null, default: true. If true and no payments provided, booking will be auto-cancelled after 16 minutes if unconfirmed.

Important Notes:

• Room availability is checked before booking creation
• Overlapping bookings for same room will be rejected
• Payment is optional - can be added later via Payment API
• For hourly bookings: set checkin_date = checkout_date and specify arrival_hour, departure_hour
• If no payments are provided and auto_cancel is true (default), the booking will be automatically cancelled after 16 minutes if it is still unconfirmed.
• Set auto_cancel to false to disable automatic cancellation for partners who manage confirmation externally.

Authorizations

• http

Parameters

Path Parameters

tenant_id

required

string

Request Body ^required

BookingCreateRequest

object

currency

string | null

<= 3 characters

checkin_date

required

string format: date

Example

2025-11-19

checkout_date

required

string format: date

Example

2025-11-21

arrival_hour

string | null

departure_hour

string | null

source_commission

integer | null

notes

string | null

<= 500 characters

discount_reason

Lý do giảm giá — tùy chọn.

string | null

<= 255 characters

payment_collect

string | null

Allowed values: property ota online ""

occupancy_children

integer | null

occupancy_adults

integer | null

>= 1

occupancy_infants

integer | null

source_name

required

string

auto_cancel

Auto-cancel option

boolean | null

customer

required

object

name

required

Customer validate

string

<= 50 characters

phone

string | null

email

string | null format: email

<= 255 characters

birthday

string | null format: date

Example

1990-05-15

gender

string | null

Allowed values: male female unknown

company

string | null

address

string | null

city

string | null

country

string | null

identity

string | null

identity_issue_date

string | null format: date

Example

2020-01-15

id_type

string | null

Allowed values: identity_card passport other

is_child

boolean | null

ward

string | null

<= 255 characters

notes

string | null

<= 500 characters

booking_rooms

required

Booking room validate

Array<object>

>= 1 items

object

room_type_id

required

string

rate_plan_id

string | null

default_rate

number | null

room_discount

number

days_breakdown

array | null

object

day

string format: date

price

number

payments

Payment validate

array | null

object

method

string | null

amount

required

number

paid_at

string | null format: date-time

Example

2025-11-19 16:54:00

notes

string | null

Responses

200

object

422

Validation error

object

message

required

Errors overview.

string

errors

required

A detailed description of each field that failed validation.

object

key

additional properties

Array<string>