Customer Booking Lifecycle

Manage bookings from the customer’s perspective — cancel, edit, personalize, and accept invitations. For creating bookings, see Order & Checkout Flow. For admin booking management, see Admin Booking Lifecycle. For general conventions, see JSON-API Conventions.

Prerequisites

A booking associated with the authenticated customer account, or
A booking number/code for unauthenticated lookup

Booking Statuses

Status	Meaning
`reserved`	Temporary hold (in cart, not yet completed)
`requested`	Submitted by customer, awaiting admin approval
`accepted`	Accepted and active
`invited`	Participant invited, not yet accepted
`rejected`	Request denied by admin. If payment already exists, the rejection results in a full refund.
`canceled`	Canceled by customer or admin. Refunds follow the configured cancellation policy.
`expired`	Expired because the booking was not checked in within the configured check-in window.

Looking Up Bookings

Request path documentation:

paths/public/bookings.yaml for GET /api/v1/bookings/by-number

By Booking Number

GET /api/v1/bookings/by-number?number={booking_number}

Accepts an optional hash parameter for terminal/kiosk authentication.

Cancelling a Booking

Request path documentation:

paths/public/bookings.yaml for GET /api/v1/bookings/{booking_id}/cancel

Step 1 — Preview Cancellation Terms

Before cancelling, check the cancellation policy:

GET /api/v1/bookings/{booking_id}/cancellation-preview

Returns the applicable cancellation fee based on how far in advance the cancellation is made. The response includes:

The fee percentage or amount
The refund amount
The deadline for the current fee tier

Step 2 — Cancel

GET /api/v1/bookings/{booking_id}/cancel

The cancellation can apply to a single booking or an entire recurring series, depending on the booking type. Refunds and invoice adjustments are handled automatically.

Accepting or Rejecting Invitations

When a participant is invited to a booking (status: invited):

Accept

POST /api/v1/bookings/{booking_id}/accept-invite

Updates the participant’s status to accepted.

Reject

POST /api/v1/bookings/{booking_id}/reject-invite

Removes the participant from the booking.

Personalization

Submit custom form data for a booking (e.g. dietary preferences, t-shirt size):

POST /api/v1/bookings/{booking_id}/personalization

{
  "field_uuid_1": "Vegetarian",
  "field_uuid_2": "L",
  "email": "jane@example.com"
}

The required fields are dynamic — they depend on the service’s CustomForm configuration. A CustomForm defines which fields are available and which are mandatory. Fetch the service’s custom form to discover the expected field UUIDs and types before submitting personalization data.

Editing an Accepted Booking

Edit Participants

POST /api/v1/bookings/{booking_id}/edit-participants

{
  "participants": [
    {
      "email": "jane@example.com",
      "name": "Jane Doe",
      "attending_virtually": false
    }
  ]
}

Field	Type	Description
`email`	string	Participant email (max 200 chars)
`name`	string	Participant display name
`can_edit`	boolean	Whether the participant can edit their own data
`attending_virtually`	boolean	Virtual attendance flag

Edit Service Options (Add-Ons)

Change add-on selections on an accepted booking:

POST /api/v1/bookings/{booking_id}/edit-service-options

{
  "addons": [
    { "add_on_id": "{add_on_uuid}", "quantity": 2 }
  ]
}

Note: This endpoint is only available when the service has canEditServiceOptions enabled.

Edit Booking Date/Time (Rebooking)

Change the date, time, or resource of an accepted booking:

POST /api/v1/bookings/{booking_id}/edit-booking-base-data

{
  "start_date": "2026-04-16T10:00:00+02:00",
  "end_date": "2026-04-16T11:00:00+02:00",
  "resource_id": "{new_resource_uuid}"
}

The new time is validated against availability. If the edit creates a price difference, the order is recalculated automatically. Each edit endpoint (edit-participants, edit-service-options, edit-booking-base-data) is self-contained — a successful response means the edit is applied. There is no separate “finish edit” endpoint.

Cancel an In-Progress Edit

If you started an edit but want to revert:

GET /api/v1/bookings/{booking_id}/cancel-edit-booking

Reverts the booking to its original state before the edit was initiated.

Instant Booking

Request path documentation:

paths/public/bookings.yaml for POST /api/v1/bookings/instant

Create and complete a booking immediately in a single request:

POST /api/v1/bookings/instant

{
  "start_date": "2026-04-15T09:00:00+02:00",
  "end_date": "2026-04-15T10:00:00+02:00",
  "resource_id": "{resource_uuid}",
  "service_id": "{service_uuid}"
}

This flow is documented in the customer API only. It requires an authenticated customer context and a service that supports instant bookings (controlled by the can_instant_book flag in the service’s meta configuration).

Common Errors

Error	Cause	Solution
`403` — unauthorized	Not the booking owner or participant	Verify customer account matches
`422` — booking not cancelable	Booking status doesn’t allow cancellation	Check status — only `accepted` and `requested` bookings can be cancelled
`422` — slot unavailable	Rebooking to an occupied time slot	Check availability before editing base data
`404` — booking not found	Invalid number or code	Verify the booking number/code

​Prerequisites

​Booking Statuses

​Looking Up Bookings

​By Booking Number

​Cancelling a Booking

​Step 1 — Preview Cancellation Terms

​Step 2 — Cancel

​Accepting or Rejecting Invitations

​Accept

​Reject

​Personalization

​Editing an Accepted Booking

​Edit Participants

​Edit Service Options (Add-Ons)

​Edit Booking Date/Time (Rebooking)

​Cancel an In-Progress Edit

​Instant Booking

​Common Errors

Prerequisites

Booking Statuses

Looking Up Bookings

By Booking Number

Cancelling a Booking

Step 1 — Preview Cancellation Terms

Step 2 — Cancel

Accepting or Rejecting Invitations

Accept

Reject

Personalization

Editing an Accepted Booking

Edit Participants

Edit Service Options (Add-Ons)

Edit Booking Date/Time (Rebooking)

Cancel an In-Progress Edit

Instant Booking

Common Errors