# 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](/api-documentation/authentication.md) for details.

***

## Update Status or Notes

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

#### Endpoint

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

#### Example `curl`

```bash
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)

```json
{
  "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

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

#### Example `curl`

```bash
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**

<table><thead><tr><th width="104.3515625">Field</th><th width="92.70703125">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>booking</code></td><td>object</td><td>Booking-level updates — new nightly dates/amounts.</td></tr><tr><td><code>room</code></td><td>string</td><td>Change to a different room UUID. Availability for existing dates is re-validated.</td></tr><tr><td><code>notes</code></td><td>string</td><td>Update internal notes for the booking.</td></tr></tbody></table>

**Booking Object (updatable)**

<table><thead><tr><th width="104.3515625">Field</th><th width="92.70703125">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>dates</code></td><td>array</td><td>Replaces the full nightly pricing array. The server recomputes <code>total</code> as the sum of all amounts.</td></tr></tbody></table>

**Dates Item**

<table><thead><tr><th width="104.3515625">Field</th><th width="92.70703125">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>date</code></td><td>string</td><td>Night date (YYYY-MM-DD).</td></tr><tr><td><code>amount</code></td><td>integer</td><td>Nightly amount in minor units (e.g., <code>26000</code> = 260.00).</td></tr></tbody></table>

> **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)

```json
{
  "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

<table><thead><tr><th width="104.3515625">HTTP</th><th width="92.70703125">Code</th><th>Description</th></tr></thead><tbody><tr><td>400</td><td><code>bad_request</code></td><td>Invalid field(s), payload structure, or missing <code>Idempotency-Key</code> header.</td></tr><tr><td>404</td><td><code>booking_not_found</code></td><td>No booking found for the specified <code>bookingId</code>.</td></tr><tr><td>404</td><td><code>room_not_found</code></td><td>The specified <code>room</code> does not exist.</td></tr><tr><td>409</td><td><code>availability_conflict</code></td><td>New dates or room are not available.</td></tr><tr><td>422</td><td><code>pricing_mismatch</code></td><td><code>dates[].amount</code> does not comply with rate rules.</td></tr><tr><td>500</td><td><code>server_error</code></td><td>Unexpected error.</td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.hostelmate.co/api-documentation/bookings/update.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.