> For the complete documentation index, see [llms.txt](https://docs.hostelmate.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hostelmate.co/api-documentation/bookings/update.md).

# 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>