Developers / REST API

Reservory REST API

Supported public REST surface. All responses are JSON. CORS-enabled where indicated (anon endpoints). Mutating POSTs accept an Idempotency-Key header for safe client retries.

Tenant API keys support cancellation and check-in only on the operator routes listed here. Cancellation never refunds. Refunds and administrative actions require authorized dashboard sessions and are outside this SDK contract. GraphQL is unavailable.

Machine-readable spec: /api/openapi.json (OpenAPI 3.1, covers the public booking + payment surface). Import into Postman, Stoplight, or any SDK generator.

Auth at a glance

anon — no auth; CORS-open; rate-limited where relevant
signed token — HMAC token issued at booking-create or waiver-dispatch; passed as a header (X-Booking-Token) or URL segment
operator staff+/manager+/admin+ — Supabase JWT bearer; requireOperator enforces the role floor server-side

Booking

GET/api/widget/experience?tenant=&experience=anon

Widget bootstrap. Returns experience metadata and up to 40 available slots, filtered by capacity and business hours. Optional party_size must be an integer from 1 to 200; effective_party_size is at least the product minimum.

200 — { tenant_id, effective_party_size, experience, slots: [{ id, starts_at, ends_at, seats_remaining, price_cents, pricing_multiplier_bps }] }

404 — tenant_unavailable | experience_not_found | venue_unavailable

400 — missing_params | invalid_party_size

503 — product_configuration_unavailable | slots_lookup_failed | availability_unavailable

POST/api/bookings/holdanon

Acquire a 10-minute soft hold on N seats. Rate-limited 10/min/IP.

Body

{ slot_id, experience_id, seats }

200 — { hold_id, slot_id, expires_at, seats_remaining }

409 — hold_unavailable (reason: insufficient_capacity | already_held | ...)

Supports Idempotency-Key header. CORS-enabled.

POST/api/bookingsanon

Convert a hold into a booking. Returns a signed booking_token for the customer payment-intent route.

Body

{ hold_id, slot_id, experience_id, venue_id, customer:{email,first_name,last_name?,phone?}, guest_count, notes?, tickets?, form_responses?, form_session_token?, promo_code?, gift_card_code?, addons? }

201 — { booking_id, booking_token, waiver_url, payment_complete, promo_discount_cents, gift_card_applied_cents }

410 — hold_expired

409 — capacity_exceeded | slot_already_booked

Persist the key before sending. Completed identical requests replay; uncertain execution can require reconciliation. Never start another booking to bypass uncertainty.

GET/api/forms/checkout/[experienceId]anon

Read current published forms and session_token. Server/same-origin only; upload fields use hosted checkout.

GET/api/embed/bookings/[id]signed token

Read canonical booking status with X-Booking-Token. Only confirmed means booking completion.

POST/api/bookings/[id]/canceloperator manager+

Cancel a held / payment-pending / confirmed booking. Does NOT refund.

200 — { ok: true, id }

POST/api/bookings/[id]/check-inoperator staff+

Stamp checked_in_at + checked_in_by_user_id. Idempotent.

200 — { checked_in_at } or { already_checked_in: true, checked_in_at }

Payments

POST/api/embed/bookings/[id]/payment-intentsigned token

Customer-facing PI creation. Requires X-Booking-Token (HMAC issued at booking-create).

200 — { clientSecret, paymentIntentId, publishableKey }

202 — Pending operation; preserve the same key and check canonical booking status.

401 — invalid_booking_token

503 — stripe_not_configured | connected_account_not_ready

Webhook signatures

Outbound webhook deliveries include X-Reservory-Timestamp and X-Reservory-Signature: v1,<hex>. The signature is HMAC-SHA256 of `${timestamp}.${rawBody}` with your endpoint's signing secret. Reject deliveries older than 5 minutes to mitigate replay attacks.

Reservory REST API

Supported public REST surface. All responses are JSON. CORS-enabled where indicated (anon endpoints). Mutating POSTs accept an Idempotency-Key header for safe client retries.

Machine-readable spec: /api/openapi.json (OpenAPI 3.1, covers the public booking + payment surface). Import into Postman, Stoplight, or any SDK generator.

Booking

GET/api/widget/experience?tenant=&experience=anon

200 — { tenant_id, effective_party_size, experience, slots: [{ id, starts_at, ends_at, seats_remaining, price_cents, pricing_multiplier_bps }] }

404 — tenant_unavailable | experience_not_found | venue_unavailable

400 — missing_params | invalid_party_size

503 — product_configuration_unavailable | slots_lookup_failed | availability_unavailable

POST/api/bookings/holdanon

Acquire a 10-minute soft hold on N seats. Rate-limited 10/min/IP.

Body

{ slot_id, experience_id, seats }

200 — { hold_id, slot_id, expires_at, seats_remaining }

409 — hold_unavailable (reason: insufficient_capacity | already_held | ...)

Supports Idempotency-Key header. CORS-enabled.

POST/api/bookingsanon

Convert a hold into a booking. Returns a signed booking_token for the customer payment-intent route.

Body

{ hold_id, slot_id, experience_id, venue_id, customer:{email,first_name,last_name?,phone?}, guest_count, notes?, tickets?, form_responses?, form_session_token?, promo_code?, gift_card_code?, addons? }

201 — { booking_id, booking_token, waiver_url, payment_complete, promo_discount_cents, gift_card_applied_cents }

410 — hold_expired

409 — capacity_exceeded | slot_already_booked

Persist the key before sending. Completed identical requests replay; uncertain execution can require reconciliation. Never start another booking to bypass uncertainty.

GET/api/forms/checkout/[experienceId]anon

Read current published forms and session_token. Server/same-origin only; upload fields use hosted checkout.

GET/api/embed/bookings/[id]signed token

Read canonical booking status with X-Booking-Token. Only confirmed means booking completion.

POST/api/bookings/[id]/canceloperator manager+

Cancel a held / payment-pending / confirmed booking. Does NOT refund.

200 — { ok: true, id }

POST/api/bookings/[id]/check-inoperator staff+

Stamp checked_in_at + checked_in_by_user_id. Idempotent.

200 — { checked_in_at } or { already_checked_in: true, checked_in_at }

Payments

POST/api/embed/bookings/[id]/payment-intentsigned token

Customer-facing PI creation. Requires X-Booking-Token (HMAC issued at booking-create).

200 — { clientSecret, paymentIntentId, publishableKey }

202 — Pending operation; preserve the same key and check canonical booking status.

401 — invalid_booking_token

503 — stripe_not_configured | connected_account_not_ready