> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anny.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Customer Booking Lifecycle

Manage bookings from the customer's perspective — cancel, edit, personalize, and accept invitations.

For creating bookings, see [Order & Checkout Flow](/developers/guides/customer/checkout). For admin booking management, see [Admin Booking Lifecycle](/developers/guides/admin/booking-lifecycle). For general conventions, see [JSON-API Conventions](/developers/guides/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

```http theme={null}
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:

```http theme={null}
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

```http theme={null}
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

```http theme={null}
POST /api/v1/bookings/{booking_id}/accept-invite
```

Updates the participant's status to `accepted`.

### Reject

```http theme={null}
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):

```http theme={null}
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

```http theme={null}
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:

```http theme={null}
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:

```http theme={null}
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:

```http theme={null}
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:

```http theme={null}
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                                           |