POST /guests/checkout

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.

Request body

{
  "pmsGuestId": "RES-2026-001"
}

Field	Type	Required	Description
`pmsGuestId`	string	Yes	The guest to check out (your PMS identifier)

Field reference

Field	Type	Required	Description
`pmsGuestId`	string	✅	The id you sent at check-in. Identifies which active guest to close.

Responses

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"
}

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 is not currently checked in (may have been manually checked out)",
  "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.

Side effects

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

Idempotency

This endpoint requires an Idempotency-Key header. Resending the same key within 24 hours replays the original response instead of repeating the operation, and a 4xx response does not consume the key. See Idempotency for the rules and the recommended key format.

Example

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"
  }'

Getting Started

Endpoints

Reference

POST /guests/checkout

Endpoint

Headers

Request body

Field reference

Responses

Success (200)

Already Checked Out (200)

Side effects

Idempotency

Example

​Endpoint

​Headers

​Request body

​Field reference

​Responses

​Success (200)

​Already Checked Out (200)

​Side effects

​Idempotency

​Example

Endpoint

Headers

Request body

Field reference

Responses

Success (200)

Already Checked Out (200)

Side effects

Idempotency

Example