Booking Update

There are two endpoints for updating a booking, each handling different concerns:

What you want to change	Endpoint
Status or notes	POST /api/v1/client/bookings/{bookingId}/update
Dates, room, or notes	PATCH /api/v1/client/bookings/{bookingId}

Both endpoints require the Idempotency-Key header. See Authentication for details.

---

Update Status or Notes

Use this endpoint to change a booking's status or notes without modifying dates or room.

Endpoint

POST /api/v1/client/bookings/{bookingId}/update

Example curl

curl "https://api.hostelmate.co/api/v1/client/bookings/e7b7f6bb-6c0c-4e2c-9b3e-9c6f2a1c0a77/update" \
  -X POST \
  -H "X-API-Key: <your_api_key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <unique-uuid>" \
  -d '{
    "status": "paid",
    "notes": "Payment confirmed via wire transfer"
  }'

Request Payload

Field	Type	Description
status	string	New booking status. Allowed values: confirmed, paid, cancelled.
notes	string	Internal notes for the booking.

Both fields are optional — send only the one(s) you want to update.

Response (200 OK)

{
  "id": "e7b7f6bb-6c0c-4e2c-9b3e-9c6f2a1c0a77",
  "status": "paid",
  "total": 52000,
  "created": "2025-10-01T10:00:00Z",
  "updated": "2025-10-02T11:05:13Z"
}

---

Update Dates, Room, or Notes (Partial PATCH)

Use this endpoint to modify nightly dates, the assigned room, or notes. Changing dates or room re-checks availability and recomputes the total.

Endpoint

PATCH /api/v1/client/bookings/{bookingId}

Example curl

curl "https://api.hostelmate.co/api/v1/client/bookings/e7b7f6bb-6c0c-4e2c-9b3e-9c6f2a1c0a77" \
  -X PATCH \
  -H "X-API-Key: <your_api_key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <unique-uuid>" \
  -d '{
    "booking": {
      "dates": [
        { "date": "2025-12-19", "amount": 26000 },
        { "date": "2025-12-20", "amount": 26000 }
      ]
    }
  }'

This is a partial update. Send only the fields you want to change. Omitted fields are left unchanged.

Request Payload

Top-level Fields

Field	Type	Description
booking	object	Booking-level updates — new nightly dates/amounts.
room	string	Change to a different room UUID. Availability for existing dates is re-validated.
notes	string	Update internal notes for the booking.

Booking Object (updatable)

Field	Type	Description
dates	array	Replaces the full nightly pricing array. The server recomputes total as the sum of all amounts.

Dates Item

Field	Type	Description
date	string	Night date (YYYY-MM-DD).
amount	integer	Nightly amount in minor units (e.g., 26000 = 260.00).

Note on Amounts: All amount fields in the Booking API use integers in minor units. For example, to represent 100.00, send 10000. This is different from the Payments API, which uses decimal strings (e.g., "100.00").

Response (200 OK)

{
  "bookingId": "e7b7f6bb-6c0c-4e2c-9b3e-9c6f2a1c0a77",
  "status": "confirmed",
  "room": "7b9e2f12-34cd-4e89-bf45-4a18f5a8a1f0",
  "total": 52000,
  "dates": [
    { "date": "2025-12-19", "amount": 26000 },
    { "date": "2025-12-20", "amount": 26000 }
  ],
  "updated": "2025-10-02T11:05:13Z"
}

---

Validation Rules

• Only include the fields you want to change; missing fields are left as-is.

• If booking.dates is provided:

  • Must contain at least one item.

  • date must be a valid YYYY-MM-DD string.

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

  • The server recomputes total from the provided dates.

• If room is provided, availability for the existing dates is re-validated.

---

Error Codes

HTTP	Code	Description
400	bad_request	Invalid field(s), payload structure, or missing Idempotency-Key header.
404	booking_not_found	No booking found for the specified bookingId.
404	room_not_found	The specified room does not exist.
409	availability_conflict	New dates or room are not available.
422	pricing_mismatch	dates[].amount does not comply with rate rules.
500	server_error	Unexpected error.