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

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

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