Endpoint
POST https://app.recepai.ai/api/pms/v1/{slug}/guests/checkout
| 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. |
Request Body
{
"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)
{
"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:
{
"status": "already_checked_out",
"pmsGuestId": "RES-2026-001",
"message": "Guest was already checked out or not found",
"requestId": "req_i9j0k1l2"
}
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.
What Happens on Checkout
When a guest is checked out:
- The guest is removed from the active in-house roster
- The guest appears in the hotel’s Departures section
- All notes, service requests, and activity logs remain linked to the guest record
- The hotel dashboard updates in real time via server-sent events
- The AI receptionist no longer considers this guest as in-house
Example: cURL
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"
}'
