Reservation Service
Overview
The Reservation Service serves as the primary mechanism for the Push Integration of successful booking transactions. This integration represents the proactive synchronization flow where the PMS sends reservation data, including guest profiles, room assignments, and financial ledgers directly to external systems.
By pushing these detailed booking records from the PMS, the platform ensures that the entire distribution ecosystem is automatically aligned with the property's internal bookings. This eliminates the need for manual reconciliation and guarantees that every partner system has the latest snapshot of the guest's itinerary and financial commitments.
Reservation Endpoint
API Specification
- HTTP Method:
POST - Secure URL Path:
{{external_base_url}}/api/reservation
Request Headers
x-api-key:{{api_key}}Authorization token assigned to the connecting system. The API key is provided by GuestPro.Content-Type:application/jsonExplicitly defines the payload structure.
Payload Construction and Schema Definition
Primary Request Body
The root object contains the administrative and source metadata for the booking.
reservation_id(String): Unique reference ID for idempotency check.reservation_no(String): Human-readable reservation reference number.reservation_group_id(String | Null): Reservation group ID (if any).agent_id(String): Name of the booking agent/channel (e.g., "Booking.com").agent_name(String): Name of the booking agent/channel (e.g., "Booking.com").segment_code(String | Null): Segment code (if any).source(String): Booking source (e.g., "Online Travel Agent").payment_type(String): Payment methodology (e.g., "Channel Collect").total_of_room(Number): Total rooms in this reservation.booking_status(String): Current lifecycle state:NEW,MODIFY, orCANCEL.currencycode(String): 3-letter ISO currency code (e.g., "IDR").created_at(DateTime): Creation timestamp (ISO-8601).updated_at(DateTime): Last update timestamp (ISO-8601).reservation_detail(Array): List of room details and nightly rate breakdowns.guest_profile(Array): List of guest contact information objects.payment(Array): List of payments (may be empty).
Reservation Detail Objects (reservation_detail)
id(String): Reservation detail ID.folio_no(Number): Folio number.room_type_id(String): Room type ID (mapped identifier).room_type_name(String): Room type name.room_name(String): Room label/number (e.g., 101).booking_status(String): Booking status at room level.reservation_status(String): Reservation status (e.g.,DEFINITE).adult(Number): Adult count.child(Number): Child count.infra(Number): Infant count.rate_id(String): Rate ID.arrival_date(Date): Check-in date inYYYY-MM-DD.departure_date(Date): Check-out date inYYYY-MM-DD.arrival_time(String): Arrival time (PMS-defined format).departure_time(String): Departure time (PMS-defined format).remark(String): Detail remark/notes (can be long).special_request(String): Special request (may contain HTML).total_room_rates(Number): Total room charge amount.total_include_product(Number): Total included products/add-ons.total_extra_charge(Number): Total extra charge amount.total_taxes_rates(Number): Total taxes for room rates.total_service_rates(Number): Total service for room rates.total_taxes_extra_charge(Number): Total taxes for extra charges.total_service_extra_charge(Number): Total service for extra charges.total_commission(Number): Total commission amount.nights(Number): Number of nights.open_availability(Number): Open availability flag.open_availability_start_date(String | Null): Open availability start date.open_availability_end_date(String | Null): Open availability end date.main_folio(String): Main folio ID.real_departure_date(Date): Actual departure date.reservation_folio(Object): Folio summary (total payment/POS).rates(Array): Nightly breakdown.
Reservation Folio Object (reservation_folio)
id(String): Folio ID.folio_no(Number): Folio number.total_payment(Number): Total payments.total_pos(Number): Total POS.
Rates Object (rates)
id(String): Rate line ID (per night).amount(Number): Amount (gross per PMS definition).dates(Date): Rate date inYYYY-MM-DD.name(String): Rate plan name.room_type_id(String): Room type ID for this rate line.rates_id(String): Rate plan/rate mapping ID.room_id(String): Room ID.net_rates(Number): Net rate.taxes_amount(Number): Taxes per night.service_amount(Number): Service per night.commission_amount(Number): Commission per night.total_pos(Number): POS total for this night.total_pos_taxes(Number): POS taxes.reservation_rates_type(String): Rate type (e.g.,ROOM_CHARGE).remark(String): Rate line remark (e.g., Room Charge).adult(Number): Adult count for this rate line.child(Number): Child count for this rate line.is_virtual_room(Number): Virtual room flag (0/1).
Guest Profile Object (guest_profile)
id(String): Guest profile ID.address(String | Null): Address.phone(String): Phone number.email(String): Email address.countrycode(String): Country code.first_name(String): First name.last_name(String): Last name.city(String): City.zipcode(String): Zip/postal code.
Expected System Responses
Successful Execution
The external system must respond with an HTTP 200 OK or 201 Created.
{
"status": "success",
"message": "Reservation b3b24f0b-179b-4e9a-afa4-e3a1ef882a48 has been successfully ingested."
}
Failure Execution
When the external system provides a response other than success codes (200, 201), the external system delivers the following error response structure.
{
"status": "error",
"message": "<<error_detail>>"
}
Full Request Body
{
"reservation_id": "8f708bc0-ebef-11f0-4d69ad00abaf",
"reservation_no": "jiwa-013738",
"reservation_date": "2026-01-07",
"agent_id": "2e5e-11ed-add0-350a581b5547",
"reservation_group_id": null,
"segment_code": null,
"agent_name": "Booking.com Pay at Agent 2",
"source": "Online Travel Agent",
"payment_type": "Channel Collect",
"total_of_room": 1,
"booking_status": "NEW",
"created_at": "2026-01-08T01:37:38+08:00",
"updated_at": "2026-02-19T15:50:26+08:00",
"currencycode": "IDR",
"reservation_detail": [
{
"id": "8fa96730-ebef-11f0-a33e",
"folio_no": 33867,
"room_type_id": "11ec-b26a-03aaaae40eb2",
"room_type_name": "Premier Room Rice Field View",
"room_name": "101",
"booking_status": "NEW",
"reservation_status": "DEFINITE",
"adult": 2,
"child": 0,
"infra": 0,
"rate_id": "0af63f80-4f1c6ca09b1e",
"arrival_date": "2026-03-17",
"departure_date": "2026-03-21",
"arrival_time": "00:00",
"departure_time": "00:00",
"remark": "smoking preference :: Non-Smoking | genius_rate : yes",
"special_request": "<p><strong>DOUBLE BED</strong></p>",
"total_room_rates": 4240743,
"total_include_product": 1000000,
"total_extra_charge": 0,
"total_taxes_rates": 357323.36,
"total_service_rates": 324839.42,
"total_commission": 1310186,
"nights": 4,
"open_availability": 0,
"main_folio": "8fa97320-1f90196e41ae",
"real_departure_date": "2026-03-21",
"reservation_folio": {
"id": "8fa97320-1f90196e41ae",
"folio_no": 33867,
"total_payment": 0,
"total_pos": 0
},
"rates": [
{
"id": "8fadad50-ebef-11f0-86c5",
"amount": 1020483,
"dates": "2026-03-17",
"name": "RBF - A'LA CARTE",
"net_rates": 1020483,
"taxes_amount": 63896.56,
"service_amount": 58087.78,
"commission_amount": 317620.81,
"reservation_rates_type": "ROOM_CHARGE",
"adult": 2,
"child": 0
},
{
"id": "8fd1c570-ebef-11f0-b717",
"amount": 1073420,
"dates": "2026-03-18",
"taxes_amount": 67505.90,
"service_amount": 61369.00
}
]
}
],
"guest_profile": [
{
"id": "8f70e7e0-ebef-11f0-bfdc",
"phone": "+48 724",
"email": "jtolwi@guest.com",
"countrycode": "and",
"first_name": "Ja",
"last_name": "Tski"
}
],
"payment": []
}