> ## Documentation Index
> Fetch the complete documentation index at: https://docs.recepai.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /guests/checkout

> Check out a guest and move them to departure history.

## Endpoint

```
POST https://app.recepai.ai/api/pms/v1/{slug}/guests/checkout
```

Checks out an in-house guest. The guest is removed from the active roster and moved to the hotel's departure history. All guest notes, activity logs, and conversation history are preserved.

## Headers

| Header            | Required | Description                                                                                 |
| ----------------- | -------- | ------------------------------------------------------------------------------------------- |
| `Authorization`   | Yes      | `Bearer pms_live_xxx` or `Bearer pms_test_xxx`                                              |
| `Content-Type`    | Yes      | `application/json`                                                                          |
| `Idempotency-Key` | Yes      | Unique key for this request (1–255 chars). See [Idempotency](/api/pms/testing#idempotency). |

## Request Body

```json theme={null}
{
  "pmsGuestId": "RES-2026-001",
  "checkoutTime": "2026-02-22T11:30:00Z"
}
```

| Field          | Type   | Required | Description                                                                                                     |
| -------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------- |
| `pmsGuestId`   | string | **Yes**  | The guest to check out (your PMS identifier)                                                                    |
| `checkoutTime` | string | No       | Actual checkout timestamp in ISO 8601 format (`YYYY-MM-DDTHH:mm:ssZ`). Defaults to the current time if omitted. |

## Response: Success (200)

```json theme={null}
{
  "status": "checked_out",
  "guestId": "abc123-def456",
  "pmsGuestId": "RES-2026-001",
  "roomNumber": "305",
  "stayDuration": {
    "checkIn": "2026-02-18",
    "checkOut": "2026-02-22"
  },
  "requestId": "req_i9j0k1l2"
}
```

## Response: Already Checked Out (200)

If the guest has already been checked out (or was never checked in via the PMS API), the endpoint returns a **200 OK** — not an error:

```json theme={null}
{
  "status": "already_checked_out",
  "pmsGuestId": "RES-2026-001",
  "message": "Guest was already checked out or not found",
  "requestId": "req_i9j0k1l2"
}
```

<Info>
  **This is intentionally idempotent.** Checkout requests should be safe to retry without causing errors. If your PMS sends a checkout event twice (e.g., due to a network retry), the second request simply confirms the guest is already gone — no error, no side effects.
</Info>

## What Happens on Checkout

When a guest is checked out:

1. The guest is removed from the active in-house roster
2. The guest appears in the hotel's **Departures** section
3. All notes, service requests, and activity logs remain linked to the guest record
4. The hotel dashboard updates in real time via server-sent events
5. The AI receptionist no longer considers this guest as in-house

## Example: cURL

```bash theme={null}
curl -X POST https://app.recepai.ai/api/pms/v1/grand-hotel/guests/checkout \
  -H "Authorization: Bearer pms_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: checkout_RES2026001_20260222" \
  -d '{
    "pmsGuestId": "RES-2026-001",
    "checkoutTime": "2026-02-22T11:30:00Z"
  }'
```