Reservations API
The Reservations API allows you to create, retrieve, update, and cancel reservations.
Authentication
All API requests require authentication via Bearer token.
curl -X GET https://api.hmpcloud.com/v1/reservations \
-H "Authorization: Bearer <access_token>" \
-H "X-Property-ID: prop_abc123"
Endpoints
List Reservations
GET /api/v1/reservations
Query Parameters:
| Parameter | Type | Description |
|---|---|---|
| arrival_from | date | Filter by arrival date (from) |
| arrival_to | date | Filter by arrival date (to) |
| departure_from | date | Filter by departure date (from) |
| departure_to | date | Filter by departure date (to) |
| status | string[] | Filter by status (CONFIRMED, CHECKED_IN, etc.) |
| source | string[] | Filter by booking source |
| guest_name | string | Search by guest name |
| confirmation_number | string | Search by confirmation number |
| cursor | string | Pagination cursor |
| limit | integer | Results per page (default: 20, max: 100) |
Example Request:
curl -X GET "https://api.hmpcloud.com/v1/reservations?arrival_from=2026-02-15&arrival_to=2026-02-20&status=CONFIRMED" \
-H "Authorization: Bearer <access_token>" \
-H "X-Property-ID: prop_abc123"
Response:
{
"data": [
{
"id": "res_xyz789",
"confirmation_number": "HTLABC20260215001",
"status": "CONFIRMED",
"source": "DIRECT",
"guest": {
"id": "guest_abc",
"name": "John Doe",
"email": "john@email.com"
},
"arrival_date": "2026-02-15",
"departure_date": "2026-02-18",
"nights": 3,
"rooms": [
{
"id": "resroom_123",
"room_type": {
"id": "rt_deluxe",
"name": "Deluxe Room"
},
"rate_plan": {
"id": "rp_bar",
"name": "Best Available Rate"
},
"adults": 2,
"children": 0,
"rate_per_night": 5000.00
}
],
"total_amount": 15000.00,
"paid_amount": 0.00,
"balance_due": 15000.00,
"special_requests": "High floor preferred",
"created_at": "2026-01-20T10:30:00Z",
"updated_at": "2026-01-20T10:30:00Z"
}
],
"pagination": {
"cursor": "eyJpZCI6MTAwfQ==",
"has_more": true
}
}
Get Reservation
GET /api/v1/reservations/:id
Example Request:
curl -X GET https://api.hmpcloud.com/v1/reservations/res_xyz789 \
-H "Authorization: Bearer <access_token>" \
-H "X-Property-ID: prop_abc123"
Create Reservation
POST /api/v1/reservations
Request Body:
{
"guest_id": "guest_abc123",
"arrival_date": "2026-02-15",
"departure_date": "2026-02-18",
"rooms": [
{
"room_type_id": "rt_deluxe",
"rate_plan_id": "rp_bar",
"adults": 2,
"children": 0
}
],
"source": "DIRECT",
"special_requests": "High floor preferred",
"payment_method": {
"type": "CREDIT_CARD",
"card_token": "tok_abc123"
}
}
Creating with New Guest:
{
"guest": {
"first_name": "John",
"last_name": "Doe",
"email": "john@email.com",
"phone": "+91-9876543210"
},
"arrival_date": "2026-02-15",
"departure_date": "2026-02-18",
"rooms": [
{
"room_type_id": "rt_deluxe",
"rate_plan_id": "rp_bar",
"adults": 2,
"children": 0
}
],
"source": "DIRECT"
}
Response: 201 Created
{
"data": {
"id": "res_xyz789",
"confirmation_number": "HTLABC20260215001",
"status": "CONFIRMED",
"guest": {
"id": "guest_abc",
"name": "John Doe"
},
"arrival_date": "2026-02-15",
"departure_date": "2026-02-18",
"total_amount": 15000.00,
"created_at": "2026-01-20T10:30:00Z"
}
}
Update Reservation
PUT /api/v1/reservations/:id
Request Body:
{
"arrival_date": "2026-02-16",
"departure_date": "2026-02-19",
"special_requests": "Late check-in requested"
}
Response: 200 OK
Cancel Reservation
POST /api/v1/reservations/:id/cancel
Request Body:
{
"reason": "Guest requested cancellation",
"waive_cancellation_fee": false
}
Response:
{
"data": {
"id": "res_xyz789",
"status": "CANCELLED",
"cancellation_fee": 5000.00,
"refund_amount": 0.00,
"cancelled_at": "2026-01-21T15:00:00Z"
}
}
Check Availability
POST /api/v1/availability
Request Body:
{
"arrival_date": "2026-02-15",
"departure_date": "2026-02-18",
"adults": 2,
"children": 0,
"rooms": 1
}
Response:
{
"data": {
"available": true,
"room_types": [
{
"id": "rt_standard",
"name": "Standard Room",
"available_count": 15,
"rates": [
{
"rate_plan_id": "rp_bar",
"rate_plan_name": "Best Available Rate",
"per_night": 4000.00,
"total": 12000.00,
"taxes": 2160.00,
"grand_total": 14160.00
}
]
},
{
"id": "rt_deluxe",
"name": "Deluxe Room",
"available_count": 8,
"rates": [
{
"rate_plan_id": "rp_bar",
"rate_plan_name": "Best Available Rate",
"per_night": 5500.00,
"total": 16500.00,
"taxes": 2970.00,
"grand_total": 19470.00
}
]
}
]
}
}
Reservation Status Values
| Status | Description |
|---|---|
| PENDING | Awaiting confirmation/payment |
| CONFIRMED | Reservation confirmed |
| CHECKED_IN | Guest has checked in |
| CHECKED_OUT | Guest has checked out |
| CANCELLED | Reservation cancelled |
| NO_SHOW | Guest did not arrive |
Source Values
| Source | Description |
|---|---|
| DIRECT | Phone, walk-in, direct booking |
| BOOKING_ENGINE | Website booking engine |
| OTA | Online Travel Agency |
| GDS | Global Distribution System |
| CORPORATE | Corporate booking |
| TRAVEL_AGENT | Travel agent booking |
Error Responses
Validation Error
{
"error": "validation_error",
"message": "Invalid request data",
"details": [
{
"field": "arrival_date",
"message": "Arrival date must be in the future"
}
]
}
Status: 400 Bad Request
Not Found
{
"error": "not_found",
"message": "Reservation not found"
}
Status: 404 Not Found
No Availability
{
"error": "no_availability",
"message": "No rooms available for the requested dates"
}
Status: 422 Unprocessable Entity