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

# opencals-storefront-api skill

> The ground-truth Agent Skill for building on the Opencals API and @opencals/storefront-sdk — availability, carts, appointments, checkout, discounts, customer accounts, guests, custom durations, reschedule/cancel and rate limits.

The ground-truth reference skill. Install it whenever an agent writes, reviews or
debugs code against the Opencals API / `@opencals/storefront-sdk`. It carries the
real method names, argument shapes and enums copied from the generated SDK — so
the agent stops inventing APIs.

**Repo:** [github.com/letsopencals/skills](https://github.com/letsopencals/skills) ·
**Install:** [see the overview](/docs/ai-agents/overview#install)

## What it covers

A `SKILL.md` router plus focused reference files, loaded on demand:

| Reference              | Covers                                                                                                                                 |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `setup.md`             | `setupOpencals`, service classes, `X-Api-Version`, `OpencalsApiError`, the `throwOnError` gotcha                                       |
| `availability.md`      | `getCurrentAvailabilities` vs `getCurrentAvailabilitiesMerged`, the `duration` param, `excludeAppointmentId`, slot shape, grid fan-out |
| `custom-duration.md`   | `allowCustomDuration` / `maxDuration`, the quantity = duration-units pricing rule                                                      |
| `guests-attendees.md`  | `numberOfAttendees`, `attendees` / `maxAttendees`, `addGuest` / `removeGuest`                                                          |
| `cart-lifecycle.md`    | create/get, `X-Cart-Id`, `expiresAt`, `extendExpiration`, expiry countdown                                                             |
| `checkout.md`          | `saveCustomer` timing, billing vs delivery address, marketing consent, checkout questions, payment                                     |
| `auth-self-service.md` | password + passwordless + OAuth login, sessions, `SelfService` (profile, consent)                                                      |
| `reschedule-cancel.md` | `reschedule` / `cancel`, `rescheduleGap` / `cancelGap`, excluding the moved appointment                                                |
| `discounts.md`         | automatic vs code vs balance credit (`valueType: 'time'`), error codes                                                                 |
| `rate-limiting.md`     | 429 handling, exponential-backoff retry pattern, allowed origins, per-key throttling                                                   |
| `debugging.md`         | reading `OpencalsApiError`, the top recurring mistakes and how to spot them                                                            |

## When it triggers

Requests like "show available slots", "book an appointment", "apply a discount
code", "let customers reschedule", "add a guest", "collect a billing address",
"why am I getting a 429", "custom booking length", "customer login".

## Related

* [Build a booking page](/docs/guides/build-a-booking-page) — the same flow, walked through
* [Storefront SDK](/docs/guides/storefront-sdk) — SDK setup and reference
* [opencals-build-booking-site skill](/docs/ai-agents/build-booking-site-skill) — scaffold a whole site