> ## 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](https://docs.anny.co/developers/guides/customer/checkout.md). For admin booking management, see [Admin Booking Lifecycle](https://docs.anny.co/developers/guides/admin/booking-lifecycle.md). For admin edits of a confirmed booking (resource, dates, fields, add-ons, sub-bookings), see [Admin Booking Edit](https://docs.anny.co/developers/guides/admin/booking-edit.md). For general conventions, see [JSON-API Conventions](https://docs.anny.co/developers/guides/json-api-conventions.md).

***

## 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. Quantity follows the same `always_apply` / `min_quantity` rules as checkout: customer `0` or omit floors to min when `always_apply` is `true`. See [Add-On](https://docs.anny.co/developers/models/add-ons.md).

### 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 |
| `400` — `service_and_resource_not_related` | The resource does not offer the chosen service | Send a linked resource/service pair. The API no longer swaps in another service. |
| `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 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.