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

# Appointments overview

> Book one-time and recurring appointments, then charge or cancel them

Use the Appointments API when a customer books with a barber, or when a barber books on a customer's behalf. You can create one-time appointments and recurring series.

```mermaid theme={null}
sequenceDiagram
 participant Client
 participant API
 participant Barber

 Client->>API: List appointment openings
 API->>Client: Open slots
 Client->>API: Create appointment (idempotency key)
 API->>API: Check availability and conflicts
 API->>Client: Appointment pending or scheduled
 Barber->>API: Capture payment when service is done
 API->>Client: Payment captured
```

## What you do first

1. Check [appointment openings](/api-reference/appointments/list-appointment-openings) so you know the slot is free.
2. [Create an appointment](/api-reference/appointments/create-an-appointment) as the customer, or [create as a barber](/api-reference/appointments/create-an-appointment-as-a-barber) with cost and duration.
3. Send an [idempotency key](/api-reference/idempotency) on every create so a same-key retry can replay the first result instead of starting a second booking.
4. For a series, [create a recurring appointment](/api-reference/recurring-appointments/create-a-recurring-appointment) with frequency, start date, optional end date, and active status.

Each customer gets at most one recurring series per barber. Guile creates future visits in the background from the frequency and date range, they are **not** confirmed for you; the customer or barber still confirms each one. Without an end date, Guile creates appointments up to one year from the start date or today, whichever is later.

## States that matter

| Appointment state | What it means                                                    |
| ----------------- | ---------------------------------------------------------------- |
| `pending`         | Waiting on approval or confirmation; not a firm booked visit yet |
| `scheduled`       | Booked on the calendar; payment and cancel rules apply           |
| `canceled`        | Visit will not happen; do not authorize or capture for it        |
| `completed`       | Visit finished; capture or refund paths depend on payment state  |

| Payment state | What it means for the next call                                                                                  |
| ------------- | ---------------------------------------------------------------------------------------------------------------- |
| `pending`     | No successful hold or capture yet                                                                                |
| `authorized`  | Hold is in place; [capture](/api-reference/appointments/capture-an-appointment-payment) when the service is done |
| `paid`        | Money is recorded; use refund when you need money back                                                           |
| `failed`      | Last money attempt failed; fix the method before authorizing again                                               |

[Update a recurring appointment](/api-reference/recurring-appointments/update-a-recurring-appointment) to change frequency, dates, or active status. Deactivate it and no new appointments are created; ones already on the calendar stay. When you [delete a series](/api-reference/recurring-appointments/delete-a-recurring-appointment), send an `earliestDeletionDate` in the future so near-term visits stay. Delete a single visit and only that appointment goes away.

[List appointments](/api-reference/appointments/list-barber-appointments) with date ranges, payment states, payment methods, payment directions, and appointment states. [List recurring appointments](/api-reference/recurring-appointments/list-recurring-appointments) for a barber and filter by customer.

## When a call fails

Failures come back as problem documents. Open the `type` link for the cause, the fix, and whether retrying is safe. Always send idempotency keys on creates. When you delete a series, pick `earliestDeletionDate` so visits people already planned around stay put.

Customers and barbers can cancel. When a barber [cancels](/api-reference/appointments/cancel-an-appointment-as-a-barber), they can apply cancellation fees for late cancels or no-shows when the timing allows it.

## Related paths

* Appointments accept cards and external payments (cash or peer-to-peer tools like Venmo). [Authorize an appointment payment](/api-reference/appointments/authorize-an-appointment-payment) at booking and capture later, or charge immediately, [capture](/api-reference/appointments/capture-an-appointment-payment) when the service is done; [refund](/api-reference/appointments/refund-an-appointment-payment) with an optional reason code.
* Card-present collection lives under [Payments](/api-reference/Payments/overview).
* Refund requests live under [Refunds](/api-reference/Refunds/overview).
* [Date ranges](/api-reference/date-ranges): filter list calls by day.