> 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

Update an existing booking's status, notes, dates, room or exact bed, or check a guest in, via two dedicated endpoints. Availability and totals are revalidated; send only fields you want to change.

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

| What you want to change              | Endpoint                                          |
| ------------------------------------ | ------------------------------------------------- |
| Status (including check-in) or notes | `POST /api/v1/client/bookings/{bookingId}/update` |
| Dates, room, bed, or notes           | `PATCH /api/v1/client/bookings/{bookingId}`       |

Both endpoints require the `Idempotency-Key` header. See [Authentication](https://docs.hostelmate.co/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: `reserved`, `confirmed`, `paid`, `cancelled`, `noShow`, `waitlist`, `checkInPaid`. Case, spaces, `-` and `_` don't matter: `noShow`, `noshow`, `no_show` and `No-Show` all mean `noShow`. Responses always use the spelling listed here. |
| `notes`  | string | Internal notes for the booking.                                                                                                                                                                                                                                              |

Both fields are optional — send only the one(s) you want to update. `notes` can be up to 10,000 characters.

#### Checking a guest in

Send `"status": "checkInPaid"` to mark a guest as checked in. It's the same **Check In Paid** status your staff pick in the calendar, and the booking's `checked_in` becomes `true`. It means "checked in and fully paid", and the API doesn't check the payment for you, so send it once the guest has paid.

```json
{ "status": "checkInPaid" }
```

`checked_in` in the response can only be read. Sending it gets a `400` that points you to `checkInPaid`.

#### Bringing back a cancelled booking

Changing a cancelled booking to a status that holds a bed (`reserved`, `confirmed`, `paid` or `checkInPaid`) puts its nights back on their beds. If one of those beds has been booked or closed since the cancellation, you get a `409 availability_conflict` and nothing changes. Move the booking to a free bed first with the PATCH endpoint below, then change the status. `waitlist` and `noShow` don't hold a bed, so they are not checked.

#### Response (200 OK)

The full booking, the same as [Get Booking](https://docs.hostelmate.co/api-documentation/bookings/get.md) returns. Shortened here:

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

***

## Update Dates, Room, Bed, or Notes (Partial PATCH)

Use this endpoint to modify nightly dates, the assigned room or bed, or notes. Changing dates, room or bed re-checks availability. Changing dates 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, and a free bed in that room is picked for you.</td></tr><tr><td><code>bed</code></td><td>string</td><td>Put every night on this exact bed (a <code>stay_dates[].bed</code> id from <a href="https://docs.hostelmate.co/api-documentation/bookings/get.md">Get Booking</a>). The booking moves to that bed's room.</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 and at most 400, and each date can appear only once.
  * `date` must be a valid YYYY-MM-DD string.
  * A new night must fall between one year before and 1,095 days (3 years) after the property's today. Nights the booking already has are not checked, so you can still change an older booking.
  * `amount` must be a whole number in minor units, from 0 to 999999999 (9,999,999.99).
  * The server recomputes `total` from the provided dates.
* `notes` can be up to 10,000 characters.
* A request that breaks a rule gets a `400` and changes nothing.
* If `room` is provided, availability for the existing dates is re-validated.
* If `bed` is provided:
  * It must be a bed of this property, or you get a `404 bed_not_found`.
  * If you send `room` too, the bed must be in that room, or you get a `400`.
  * It must be free and open on every night of the booking (the new `booking.dates` when you send them), or you get a `409 availability_conflict`. A bed held only by a `waitlist`, `noShow` or cancelled booking counts as free, the same rule Hostel Mate uses when it gives a new booking a bed.

#### Example: put a booking on an exact bed

```json
{ "bed": "bb9c708a-2695-435f-a1eb-1bf61381ad77" }
```

***

#### 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>404</td><td><code>bed_not_found</code></td><td>The specified <code>bed</code> is not a bed of this property.</td></tr><tr><td>409</td><td><code>availability_conflict</code></td><td>New dates, room or bed 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>
