Booking Create

Create a Booking

Use this endpoint to create a new booking. To prevent duplicates, you must provide a unique booking.id (UUID v4) generated by your client. You must also provide either an existing guest.id or full guest details inside guest.

Endpoint

POST /api/v1/client/bookings

Example curl

curl "https://api.hostelmate.co/api/v1/client/bookings" \
  -X POST \
  -H "X-API-Key: <your_api_key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <unique-uuid>" \
  -d '{
    "booking": {
      "id": "e7b7f6bb-6c0c-4e2c-9b3e-9c6f2a1c0a77",
      "dates": [
        { "date": "2025-11-05", "amount": 25000 },
        { "date": "2025-11-06", "amount": 25000 },
        { "date": "2025-11-07", "amount": 25000 }
      ]
    },
    "room": "92b6f8b8-6ea2-4e0e-9b7b-3e2f9b6a7c2d",
    "guest": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "[email protected]",
      "phone": "[phone]",
      "country_code": "GB"
    },
    "notes": "Late arrival around 22:00"
  }'

Idempotency-Key is required on this endpoint. Omitting it returns 400 bad_request.

If guest.id is provided, the identity comes from that ID. If guest.id is not provided, guest.first_name, guest.last_name, and guest.email are required to create a new guest record. The guest.id here refers to an existing guest's guestId as returned by the Guests API — it is not the guest.id embedded in booking responses.

---

Request Payload

Top-level Fields

Field	Type	Description
booking	object	Booking info including a client-generated unique ID and nightly amounts.
room	string	The selected room or room type ID (UUID).
guest	object	Guest reference or full guest details (see “Guest Object”).
notes	string	Internal notes for the booking (optional).

Booking Object

Field	Type	Description
id	string	Required. Client-generated unique booking ID (UUID v4). Used to prevent duplicate processing.
dates	array	Array of nightly pricing items. The server computes total from the sum of these amounts.

Dates Item

Field	Type	Description
date	string	Night date (format: YYYY-MM-DD).
amount	integer	Nightly amount in minor units (e.g., fils/cents).

Guest Object

Field	Type	Description
id	string	Existing guest ID (UUID). If provided, this identifies the guest.
first_name	string	Required if id is not provided.
last_name	string	Required if id is not provided.
email	string	Required if id is not provided. Must be a valid email.
phone	string	Optional. E.164 format recommended (e.g., +447...).
country_code	string	Optional. ISO 3166-1 alpha-2 (e.g., GB).
address	object	Optional postal address (see below).

Address Object

Field	Type	Description
line1	string	Street line 1.
city	string	City.
postal_code	string	Postal/ZIP code.
country_code	string	ISO 3166-1 alpha-2 (e.g., GB).

---

Response (201 Created)

{
  "bookingId": "e7b7f6bb-6c0c-4e2c-9b3e-9c6f2a1c0a77",
  "status": "confirmed",
  "room": "92b6f8b8-6ea2-4e0e-9b7b-3e2f9b6a7c2d",
  "total": 75000,
  "dates": [
    { "date": "2025-11-05", "amount": 25000 },
    { "date": "2025-11-06", "amount": 25000 },
    { "date": "2025-11-07", "amount": 25000 }
  ],
  "guest": {
    "id": "f1b2c3d4-5678-49ab-9cde-112233445566",
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]"
  },
  "createdAt": "2025-10-02T09:20:17Z"
}

---

Validation Rules

• booking.id is required and must be a UUID v4. Re-using it with a different payload will be rejected.

• Provide either guest.id or (guest.first_name, guest.last_name, guest.email). Not both.

• dates[] must contain at least one item; date must be valid (YYYY-MM-DD).

• amount must be non-negative integer (minor units).

• The server computes total as the sum of dates[].amount.

---

Error Codes

HTTP	Code	Description
400	bad_request	Validation failed (e.g., missing required fields, malformed email, invalid dates).
404	room_not_found	The specified room does not exist.
409	booking_id_conflict	booking.id already used for a different payload.
409	availability_conflict	The selected room is no longer available for the requested dates.
422	guest_invalid	guest.id not found or guest fields invalid.
500	server_error	Unexpected error.