> ## 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](https://opencals.com/docs/ai-agents/overview.md#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](https://opencals.com/docs/guides/build-a-booking-page.md) — the same flow, walked through
* [Storefront SDK](https://opencals.com/docs/guides/storefront-sdk.md) — SDK setup and reference
* [opencals-build-booking-site skill](https://opencals.com/docs/ai-agents/build-booking-site-skill.md) — scaffold a whole site


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