Reservation lifecycle
Retrieve
GET /reservations/{reservation_id} returns the current representation only when it belongs to the selected organization. Unknown and cross-organization IDs both return reservation_not_found.
Keep Reservations in sync (reconciliation)
Reconciliation is the background sync that keeps your system aligned with Trutee after a Reservation is created. For example, a course may cancel a Reservation or mark it completed outside your integration. Because v1 does not send webhooks, periodically list Reservations changed since your last successful sync and apply those newer representations to your records.
List by course, play-date range, status, External Reference ID (external_reference_id), or updated_after. Every allocation in a grouped Reservation shares one course-local date, and the group matches when that shared date is inside the inclusive bounds. A cursor is scoped to the exact filters and limit.
Follow next_cursor until has_more is false without changing filters. Keep the first page’s fixed updated_through. After the last page, persist next_updated_after and use it as the next run’s updated_after. The one-millisecond overlap protects equal-timestamp boundaries; deduplicate by Reservation ID and updated_at.
Commit the new watermark only after every page succeeds. If a traversal fails, discard its cursor and restart from the last committed updated_after; never advance the watermark from a partial run. Choose a polling cadence that meets your guest-support needs while staying within the published read rate limit, and alert when repeated failures prevent a complete run.
Webhooks are deferred, so polling reconciliation is the v1 change-detection contract.
Cancel
Cancellation is atomic across the complete group and requires a new idempotency key.
If a fee is required, play started, the Reservation is not cancellable, or stored state cannot be safely released, the API does not partially cancel:
Contact the course when contact_course is true or the error directs you to do so. A later logical cancellation request with a new idempotency key succeeds and reports already_cancelled: true when the Reservation is already cancelled. A same-key retry replays the original response unchanged, so its already_cancelled value may remain false.
Cancel and rebook
Changes are not supported in place. Retrieve the Reservation, collect the requested change, and explain that replacement capacity is not guaranteed. Search replacement availability immediately before the guest confirms, then cancel the old Reservation and create the replacement with a new booking idempotency key and External Reference ID.
This is not an atomic replacement: the new offer can expire or lose capacity after cancellation succeeds. If cancellation is denied, do not book a replacement automatically because that can leave two active Reservations. If cancellation succeeds but replacement creation fails, stop automatic retries that would change the request, keep the guest informed, and contact the Inventory Course about recovery. Send messaging only for operations that returned success.

