# Bookings & sessions

Create a complete booking or compose changes around an existing session. A booking can contain several sessions; actions on one session must preserve its siblings.

## Admission inputs and results

[Native booking admission](/api/docs#/Studio%20native%20checkout/v2CheckoutBooking) accepts email and explicit `sessions[]`. Supply service, concrete setup, local date/start, sold duration and every applicable [quote requirement](/api/docs/guides/v2/quotes): guests, recording seats, add-ons, file transfer, forms, invoice details and actual consent acceptance.

The write needs a persisted UUID and current session/client/payment authority, including conditional client creation authority. HTTP 202 returns real identities where applicable. Follow `resource_type` and `resource_id` to the current checkout or other returned resource. Availability/quote reads create no hold; admission rechecks current policy.

For [studio-collected money](/api/docs/guides/v2/payments), ordinary admission uses external checkouts with the same complete selection. Existing package rights instead use the owned-client rights/quote/redemption operations; a plan ID alone is not a usable right. A package session whose rounded length would end after studio-local midnight is refused with `422 crosses_midnight`; ending exactly at midnight is accepted.

## Published Tours

Use the published Tour offer, its availability and [Tour quote](/api/docs#/Studio%20native%20checkout/v2QuoteTour), then [Tour booking](/api/docs#/Studio%20native%20checkout/v2CheckoutTour) with the Tour ID in the path. Preserve setup-bound versus studio-wide roomless geometry. Tour guests use first name, last name and email; Tour consent is terms only. If phone is required, update the owned client profile first.

Tour `payment_source` defaults to `native`; `external` uses studio collection and its authority/readiness prerequisites. A positive external total returns a real external payable. A zero-total Tour uses its native no-Payment policy; do not fabricate a payable. Follow the returned resource type.

## Move a session in time

[Customer reschedule](/api/docs#/Studio%20booking%20aftercare/v2AftercareReschedule) changes local date and start time while retaining sold duration. Ordinary sessions keep their booked setup even if `setup_id` is supplied. That optional setup selection applies only to studio-tour sessions.

The [explicit staff reschedule](/api/docs#/Studio%20booking%20aftercare/v2AftercareStaffReschedule) has separate authority/policy; do not automatically retry a customer refusal through the staff route. A time move is not a commercial change to duration, setup or sold extras.

## Change the sold selection with an amendment

Read [amendment options](/api/docs#/Studio%20booking%20aftercare/v2AftercareStartAmendment), then [preview the full proposal](/api/docs#/Studio%20booking%20aftercare/v2AftercareAmendmentPreview). The proposal includes the service, setup, room, date/start, duration, recording seats, add-ons, file transfer, guests and form answers required by its exact schema. Supply payment source, credit choice and displayed consents.

[Accept the amendment](/api/docs#/Studio%20booking%20aftercare/v2AftercareAcceptAmendment) with that proposal and the preview's `expected_version`, plus financial/credit choices and consents. Retain the amendment ID and [read its current state](/api/docs#/Studio%20booking%20aftercare/v2AftercareAmendment). Price differences, credits, staff approval and fulfillment remain Podyx policy. A stale version requires another preview/customer decision, not a guessed replacement version.

Amendments have separate [withdrawal](/api/docs#/Studio%20booking%20aftercare/v2AftercareWithdrawAmendment), [staff approval](/api/docs#/Studio%20booking%20aftercare/v2AftercareApproveAmendment), [decline](/api/docs#/Studio%20booking%20aftercare/v2AftercareDeclineAmendment) and native payment operations. Each command has its own request UUID. An accepted proposal is not proof the changed session is fulfilled; inspect payment, approval and current session facts.

## Manage guests and paid add-ons

[List session guests](/api/docs#/Studio%20booking%20aftercare/v2AftercareGuests), then use the dedicated [invite](/api/docs#/Studio%20booking%20aftercare/v2AftercareInviteGuest), [update](/api/docs#/Studio%20booking%20aftercare/v2AftercareUpdateGuest) or [remove](/api/docs#/Studio%20booking%20aftercare/v2AftercareRemoveGuest) operation. Ordinary aftercare guest input uses `name` and its optional contact fields; do not reuse Tour guest input. Capacity and current session eligibility still apply. Invitation processing is not proof of email delivery.

[Quote add-on purchases](/api/docs#/Studio%20customer%20quotes/v2AddonQuote) against the relevant selection and use [session add-on purchase](/api/docs#/Studio%20booking%20aftercare/v2AftercareCreateAddon) with chosen quantities, payment source, credit choice and consents. Read the [add-on purchase resource](/api/docs#/Studio%20booking%20aftercare/v2AftercareAddon) and its actual payment/approval state. Native preparation/token/confirmation/retry and staff decision operations are separate. Paid extras keep their own tender and original booking payment pointers; do not overwrite them with an amendment payment.

## Cancel with the right scope

[Preview cancellation](/api/docs#/Studio%20booking%20aftercare/v2AftercareCancellationPreview) on the booking, supplying `slot_id` for one session. Submit the returned fingerprint as `expected_fingerprint` to [accept cancellation](/api/docs#/Studio%20external%20recovery/v2CancelBooking), retaining the same scope. Omitting session scope can affect the booking more broadly; do not omit it when the customer chose one session.

[Read the cancellation](/api/docs#/Studio%20external%20recovery/v2GetCancellation) for its frozen plan, collection sources and required actions. A live sibling retains its own extras/aftercare eligibility. Cancellation or staff decline can create a [refund obligation](/api/docs/guides/v2/payments) without executing the refund.

## Recovery and current state

Persist each command UUID and exact facts before sending. A timeout after any change is uncertain: [replay the original command](/api/docs/guides/v2/recovery), then read the returned resource. Do not create another amendment, add-on purchase or cancellation to discover the first result. Inspect booking/session, payment and approval facts separately.

## Example

Move an ordinary session in time, retaining its sold duration and setup:

```sh
curl "https://app.podyx.com/api/v2/sessions/$SESSION_ID/reschedules" \
  -H "Authorization: Bearer $PODYX_API_KEY" \
  -H "Idempotency-Key: $RESCHEDULE_UUID" \
  -H 'Content-Type: application/json' \
  --data '{"date":"2026-11-02","start_time":"11:00:00"}'
```

To change an ordinary setup or commercial selection, use amendment options → full preview → acceptance with its version. Reschedule cannot replace that policy.

A minimal ordinary native admission can use the following body when the current quote requires no other details. Replace every ID and confirm all displayed requirements first:

```json
{
  "email": "client@example.test",
  "sessions": [{
    "service_id": "<service-uuid>",
    "setup_id": "<setup-uuid>",
    "date": "2026-11-02",
    "start_time": "10:00:00",
    "duration_minutes": 45
  }],
  "consents": {"terms": true}
}
```

Send it to `POST /api/v2/bookings` with its own persisted UUID; external ordinary admission uses `POST /api/v2/external-checkouts`. A partial or stale selection can still be refused. Read the accepted resource rather than assuming the booking is paid or approved.