# clndr.pro

---

# Introduction

clndr.pro hosts booking pages. A host sets their weekly hours, a guest picks an open slot, and the meeting shows up in the host's dashboard (and on their Google Calendar with a Meet link, when the page has Meet links turned on). These docs cover running that booking flow inside your own site, so guests never leave it for `www.clndr.pro/ada/intro-call`.

This is a complete booking form in a React app:

```tsx title="app/book/booking-widget.tsx"
'use client';

import { ClndrProvider, BookingInline } from '@clndr-pro/react';

export function BookingWidget() {
  return (
    <ClndrProvider publishableKey={process.env.NEXT_PUBLIC_CLNDR_PUBLISHABLE_KEY!}>
      <BookingInline slug="intro-call" />
    </ClndrProvider>
  );
}
```

It fetches the page, lets the guest pick a date and a slot, asks the host's questions, and books. The [quickstart](/quickstart) gets it running in a Next.js app.

## Pick a way in

| You want | Use | Key |
| --- | --- | --- |
| A booking widget on a site you don't write code for (Webflow, WordPress, plain HTML) | [Embed script](/embed/script) | None |
| A booking page in an iframe, nothing else | [Iframe embed](/embed/iframe) | None |
| The booking form inside your React or Next.js app, in your own components | [`@clndr-pro/react`](/react/components) | Publishable |
| Your own booking UI, or bookings flowing into your backend | [REST API](/api-reference) or [`@clndr-pro/sdk`](/sdk) | Publishable in the browser, secret on the server |

[Choose an integration](/integration-options) compares them properly, including what each one can't do.

## What the API covers

From any key you can read your booking pages, the questions they ask, and the open slots on a given day, and you can create bookings. From a secret key on your server you can also list bookings, confirm the ones waiting for approval, and cancel them.

Creating or editing booking pages, availability and access codes happens in the [dashboard](https://www.clndr.pro/booking), not the API. There are no outbound webhooks yet: your code hears about new bookings from the embed's browser events, from your own booking handler, or by [polling the API](/tutorials/sync-bookings).

## Building with Claude Code

Every page here is also plain Markdown (add `.md` to the URL), the whole site is indexed at [`/llms.txt`](/llms.txt), and there's an MCP server and a Claude Code skill. [Docs for AI tools](/ai/tools) has the setup. If you just want it done, paste this into Claude Code from the root of your project:

<Prompt title="Add clndr.pro booking to this project">

```text
Add clndr.pro booking to this project.

Read these first. They are Markdown pages written for coding agents:
- https://docs.clndr.pro/llms.txt (index of every docs page)
- https://docs.clndr.pro/integration-options.md
- https://docs.clndr.pro/nextjs.md for a Next.js app, otherwise https://docs.clndr.pro/react/components.md or, for a site without React, https://docs.clndr.pro/embed/script.md

Facts to rely on:
- API base URL: https://www.clndr.pro/api/v1. Always the www host: the bare domain redirects and the redirect drops the Authorization header.
- Packages: @clndr-pro/react (components and hooks, browser) and @clndr-pro/sdk (typed client, mainly server). Use @clndr-pro/react 0.2.1+ and @clndr-pro/sdk 0.1.5+. With older versions, pass baseUrl "https://www.clndr.pro".
- Import @clndr-pro/react only from files marked 'use client'.
- Publishable key (clndr_pk_...) goes in NEXT_PUBLIC_CLNDR_PUBLISHABLE_KEY. It is browser-safe and can read booking pages and slots and create bookings.
- Secret key (clndr_sk_...) goes in CLNDR_SECRET_KEY. Server only. It can also list, confirm and cancel bookings. Never import it into client code.

Steps:
1. Look at the project: framework and router, styling (Tailwind? shadcn/ui under components/ui?), and where a booking page fits. Tell me what you found and which integration you'll use before you change files.
2. Ask me for the booking page slug. Ask for my clndr.pro username too if you pick an embed.
3. Add the env vars to .env.example with placeholder values and tell me to put the real keys in .env.local.
4. Build it with the project's existing components and styles.
5. Run the type checker and the build, and fix what breaks.
```

</Prompt>

[Prompts for Claude Code](/ai/claude-code) has more specific ones: a shadcn booking widget, an approvals screen, syncing bookings to a database.

## Where things are

| | |
| --- | --- |
| Dashboard | [www.clndr.pro](https://www.clndr.pro/dashboard): **Booking pages**, **Availability** for hours, **API keys** |
| API base URL | `https://www.clndr.pro/api/v1` |
| npm packages | [`@clndr-pro/react`](https://www.npmjs.com/package/@clndr-pro/react), [`@clndr-pro/sdk`](https://www.npmjs.com/package/@clndr-pro/sdk) |
| OpenAPI 3.1 spec | [`docs.clndr.pro/openapi.json`](/openapi.json) |
| SDK source | [github.com/devsForFun/clndr-pro-sdk](https://github.com/devsForFun/clndr-pro-sdk) |
| Help | [hello@devsforfun.com](mailto:hello@devsforfun.com) |

---

# Quickstart

By the end of this page a guest can open `/book` on your Next.js site, pick a slot, and book a meeting that shows up under **Meetings** in your clndr.pro dashboard. You need a clndr.pro account and a Next.js 14+ app using the App Router.

<Steps>
<Step title="Set your hours">

In the dashboard, open [**Availability**](https://www.clndr.pro/availability) and set the hours you take meetings. Slots only exist inside these hours, so a page with no availability shows no times at all.

Connect Google Calendar when the dashboard asks. clndr.pro then keeps your existing events off the slot list and can add Meet links to bookings. It works without Google too: bookings still land in **Meetings**.

</Step>
<Step title="Create a booking page">

Open [**Booking pages**](https://www.clndr.pro/booking), choose **New booking page**, and note its **Link**, the slug at the end of its URL. A page at `www.clndr.pro/ada/intro-call` has the slug `intro-call`.

Leave **Confirmation** on *Instant* for now, so test bookings confirm immediately. *Needs approval* is covered in [How booking works](/concepts#booking-types).

</Step>
<Step title="Create a publishable key">

Open [**API keys**](https://www.clndr.pro/api-keys), choose **Create API Key**, pick **Publishable key** and give it a name like "Marketing site". Copy the key: it starts with `clndr_pk_` and is shown once.

A publishable key is meant to sit in browser code. It can read your booking pages and slots and create bookings, nothing else. [API keys](/api-keys) explains the two key types.

</Step>
<Step title="Install the React package">

```bash
npm install @clndr-pro/react
```

Then put the key in `.env.local`:

```bash title=".env.local"
NEXT_PUBLIC_CLNDR_PUBLISHABLE_KEY=clndr_pk_...
```

<Warning>
Use `@clndr-pro/react` 0.2.1 or later. Earlier versions call `https://clndr.pro`, which redirects to `www` and loses the key on the way, so every request fails with `401 Missing API key`. If you're stuck on an older version, pass `baseUrl="https://www.clndr.pro"` to `ClndrProvider`.
</Warning>

</Step>
<Step title="Add the provider">

`ClndrProvider` holds the API client every component and hook uses. It's a client component, so give it its own file instead of turning your root layout into one:

```tsx title="app/providers.tsx"
'use client';

import { ClndrProvider } from '@clndr-pro/react';

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <ClndrProvider publishableKey={process.env.NEXT_PUBLIC_CLNDR_PUBLISHABLE_KEY!}>
      {children}
    </ClndrProvider>
  );
}
```

```tsx title="app/layout.tsx" {1,7}
import { Providers } from './providers';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}
```

</Step>
<Step title="Render the booking form">

```tsx title="app/book/page.tsx"
import { BookingWidget } from './booking-widget';

export const metadata = { title: 'Book a call' };

export default function BookPage() {
  return (
    <main className="mx-auto max-w-xl px-4 py-12">
      <BookingWidget />
    </main>
  );
}
```

```tsx title="app/book/booking-widget.tsx"
'use client';

import { BookingInline } from '@clndr-pro/react';

export function BookingWidget() {
  return (
    <BookingInline
      slug="intro-call"
      onBooked={(bookingId) => console.log('booked', bookingId)}
    />
  );
}
```

Replace `intro-call` with your slug. The page itself stays a Server Component; only the widget runs in the browser.

</Step>
<Step title="Book a test meeting">

Run `npm run dev`, open [localhost:3000/book](http://localhost:3000/book), pick a date and a time, and confirm with your own email address. You'll get the confirmation email, and the meeting appears under [**Meetings**](https://www.clndr.pro/meetings).

</Step>
</Steps>

## Make it look like your site

The form ships with plain, unstyled markup. Hand it your own `Button`, `Input` and `Label` and it renders with them:

```tsx title="app/book/booking-widget.tsx"
'use client';

import { BookingInline } from '@clndr-pro/react';
import { Button } from '@/components/ui/button';
import { Input } from '@/components/ui/input';
import { Label } from '@/components/ui/label';

export function BookingWidget() {
  return (
    <BookingInline
      slug="intro-call"
      components={{ Button, Input, Label }}
      classNames={{
        root: 'space-y-6',
        heading: 'text-2xl font-semibold',
        muted: 'text-sm text-muted-foreground',
        slotGrid: 'mt-4 grid grid-cols-3 gap-2',
      }}
    />
  );
}
```

[Styling and slots](/react/styling) lists every slot and class name. To design the whole flow yourself (a calendar, grouped time slots, your own form), use the hooks instead: the [shadcn booking widget](/tutorials/shadcn-booking-widget) tutorial builds one.

## Next

- Keep the guest's details off the browser-to-clndr.pro path with [a server action](/tutorials/server-actions).
- Approve or decline requests from your own admin screen: [Approve bookings in your admin](/tutorials/approvals-dashboard).
- Something not working? [Troubleshooting](/troubleshooting) covers the usual suspects: `401`, empty slot lists, and dates a day off.

---

# Choose an integration

There are five ways to put a clndr.pro booking page on your site. They trade the same two things against each other: how much of the booking UI you own, and how much code you write. The first two show the hosted UI, the one guests see at `www.clndr.pro/{username}/{slug}`. The other three render inside your own app.

| | Embed script | Iframe | React components | React hooks | Server SDK / REST |
| --- | --- | --- | --- | --- | --- |
| Guest sees | clndr.pro's booking UI, inline, in a modal or behind a floating button | clndr.pro's booking UI in a frame | A booking form rendered by your app | Whatever you build | Whatever you build |
| Styling | `theme`, `primaryColor`, hide the header | Same as the script, via query params | Your own `Button`, `Input`, `Label`… plus class names on every element | All of it | All of it |
| Key | None | None | Publishable | Publishable | Secret (server) |
| You hear about bookings from | `onBookingSuccessful` | `postMessage` events | `onBooked(bookingId)` | The return value of `create()` | Your own handler; [polling](/tutorials/sync-bookings) for everything else |
| Private pages | Pass the access code | Pass the access code (`?c=`) | Works with the owner's key | Works with the owner's key | Works with the owner's key |
| Needs | One `<script>` tag | One `<iframe>` | React 18+ | React 18+ | Any server runtime |

## Embed script

One script tag, then `Clndr.inline(...)`, `Clndr.modal(...)` or `Clndr.floatingButton(...)`. The script creates an iframe, sizes it to its content, and calls you back when a booking goes through. It's the right call for WordPress, Webflow, Squarespace or a static HTML page, and for React apps that want clndr.pro's own UI rather than their own.

You can't change the form's layout or fonts, only the theme and the accent colour. [Embed script](/embed/script) has the full API.

## Iframe

The script's iframe without the script: `https://www.clndr.pro/embed/{username}/{slug}`. Use it where you can't run JavaScript, like a CMS that strips `<script>` tags. You size the frame yourself, or listen for the resize events the page sends. See [Iframe embed](/embed/iframe).

## React components

`@clndr-pro/react` ships `<BookingInline>`, `<BookingForm>` and `<BookingModal>`: the full flow from date picker to confirmation, in your React tree. Pass it your design system's `Button`, `Input`, `Label` and `Card` and it renders with them, so it matches the rest of your app. The flow itself (date input, slot grid, form) is fixed. [Components](/react/components) and [Styling and slots](/react/styling) cover it.

## React hooks

`useBookingPage`, `useAvailableSlots` and `useCreateBooking` give you the data and the booking call, and nothing else. Use them when the flow itself should look different: a month calendar instead of a date input, slots grouped by morning and afternoon, a multi-step dialog. The [shadcn booking widget](/tutorials/shadcn-booking-widget) tutorial builds one end to end. See [Hooks](/react/hooks).

## Server SDK and REST

`@clndr-pro/sdk` (or plain HTTP against `https://www.clndr.pro/api/v1`) with a secret key, from a server action, route handler or backend job. Three reasons to go here:

- **Guest details stay on your server.** The browser posts to your own endpoint, you validate it (add a captcha, check the email against your CRM), and your server books. [Book through a server action](/tutorials/server-actions) shows the pattern.
- **You manage bookings.** Only a secret key can list, confirm and cancel. See [Approve bookings in your admin](/tutorials/approvals-dashboard).
- **You don't run React.** The [plain JavaScript](/tutorials/vanilla-js) tutorial calls the API with `fetch` and a publishable key.

## Private and team pages

On clndr.pro itself, a `private` page asks for an access code and a `team` page needs a signed-in team member. The embed and the iframe go through those same checks. Pass the code with `accessCode` or `?c=`, and expect team pages not to load inside an iframe: browsers don't send clndr.pro's sign-in cookie to a third-party frame.

The API works differently. An API key belongs to the page's owner, so it can read and book every page on that account, private or not. If you render a private page with the React components or the API, your site becomes the gate. That's often what you want (the page is private on clndr.pro because it belongs behind your members' login), but it's your decision to make, and clndr.pro won't make it for you.

## If in doubt

```mermaid title="Which integration?"
flowchart TD
  A{Does the site run React?} -->|No| B{Can it run a script tag?}
  B -->|Yes| S[Embed script]
  B -->|No| I[Iframe]
  A -->|Yes| C{Should the booking UI match the app?}
  C -->|clndr.pro's UI is fine| S
  C -->|Same components, same flow| R[React components]
  C -->|A different flow| H[React hooks]
  A -.-> D{Need to read, approve or cancel bookings?}
  D -->|Yes| K[Server SDK with a secret key]
```

For a Next.js or React app, start with `<BookingInline>` and your own components. It takes ten minutes ([quickstart](/quickstart)), and you can move to the hooks later without changing keys or env vars. Anywhere else, start with the [embed script](/embed/script).

The approaches combine. A common setup is `<BookingInline>` on the marketing site with a publishable key, plus a secret key on the server that copies new bookings into your CRM.

---

# API keys

Every API request carries a key, and the key decides two things: whose booking pages and bookings the request can see, and what it can do with them. Each key belongs to the clndr.pro account that created it. A key can't reach another account's pages, so if your site shows booking pages for three people, each of them creates a key (or you use the [embed](/embed/script), which needs none).

## Two types

| | Secret | Publishable |
| --- | --- | --- |
| Prefix | `clndr_sk_` | `clndr_pk_` |
| Lives in | Your server: env vars, a secrets manager | Browser bundles, mobile apps, HTML |
| Env var we use in these docs | `CLNDR_SECRET_KEY` | `NEXT_PUBLIC_CLNDR_PUBLISHABLE_KEY` |
| Rate limit | 300 requests per 60 s | 120 requests per 60 s |
| Read booking pages and questions | Yes | Yes |
| Read open slots | Yes | Yes |
| Create bookings | Yes | Yes |
| List and read bookings (guest names, emails, answers) | Yes | No |
| Confirm and cancel bookings | Yes | No |

In scope terms: publishable keys hold `booking_pages:read`, `booking_pages:slots` and `bookings:create`. Secret keys hold those plus `bookings:read` and `bookings:write`. A request outside a key's scopes gets `403 API key is missing required scope(s): …`. The dashboard gives every key its type's full set; narrower custom scopes aren't available yet.

## Create a key

<Steps>
<Step title="Open API Keys">
Sign in at [www.clndr.pro](https://www.clndr.pro/dashboard) and open [**API keys**](https://www.clndr.pro/api-keys) in the sidebar.
</Step>
<Step title="Choose the type and a name">
Choose **Create API Key**, pick **Secret key** or **Publishable key**, and name it after where it will be used: "Marketing site", "CRM sync job". The name is only shown to you.
</Step>
<Step title="Copy it now">
The full key is shown once. clndr.pro stores a hash and the first 16 characters (for example `clndr_sk_4f1c2a9`), so a lost key can't be recovered, only replaced.
</Step>
</Steps>

You can create five keys an hour.

## Where keys go

The rule is the prefix. A `clndr_sk_` key never reaches a browser; a `clndr_pk_` key can go anywhere.

In Next.js, only variables that start with `NEXT_PUBLIC_` are copied into client bundles, at build time. That makes the naming do the work:

```bash title=".env.local"
# Server only. Read it in server components, server actions, route handlers.
CLNDR_SECRET_KEY=clndr_sk_...

# Inlined into the browser bundle. Safe, and visible to anyone.
NEXT_PUBLIC_CLNDR_PUBLISHABLE_KEY=clndr_pk_...
```

Don't put a secret key in a `NEXT_PUBLIC_` variable, and don't read `process.env.CLNDR_SECRET_KEY` in a file marked `'use client'`. Next.js leaves non-public variables out of client code, so that read gives you `undefined` in the browser: the SDK throws ``Clndr: `apiKey` is required`` when you build the client, and a hand-written `fetch` gets `401`. Adding `import 'server-only'` to the file that builds your secret-key client turns the mistake into a build error instead.

Because public variables are baked in at build time, changing `NEXT_PUBLIC_CLNDR_PUBLISHABLE_KEY` needs a rebuild, not just a restart.

### On Vercel

```bash
vercel env add CLNDR_SECRET_KEY production
vercel env add NEXT_PUBLIC_CLNDR_PUBLISHABLE_KEY production
```

Run them again with `preview` and `development` if those environments call clndr.pro too. You can use the same keys everywhere, or create separate ones so revoking a leaked preview key doesn't touch production.

## What each key exposes

A **publishable key** is public the moment you deploy it: anyone can read it from your page source. With it they can list every booking page on your account (including inactive and private ones), read their questions and open slots, and book those open slots, the same as a guest on your site could. Bookings made with a publishable key must match a slot the API is offering right now, so the key can't drop meetings outside your hours or past the page's `max_days_ahead`. They can't see who booked, change a booking, or touch your pages or availability. If a private page shouldn't be discoverable at all, keep it off accounts whose publishable keys you ship, or book it through your server with the secret key instead.

A **secret key** reads every booking on the account: guest names, email addresses, times and answers. It can also confirm and cancel bookings. It can't edit booking pages, availability, access codes or account settings; those exist only in the dashboard.

## Rotate a key

Rotation doesn't need downtime, because two keys can be active at once:

1. Create a new key of the same type.
2. Put it in your env vars and deploy.
3. Check the old key's **Last used** date in the dashboard. Once it stops moving, choose **Revoke** on it.

**Revoke** switches a key off and keeps it in the list, so you can still see when it was last used. Requests with it get `401 API key has been revoked`. **Delete** removes it entirely; requests then get `401 Invalid API key`. Revoke first, delete later.

Keys don't expire. The API honours an expiry date on a key, but the dashboard has no way to set one yet.

## If a secret key leaks

Revoke it in the dashboard straight away; it stops working on the next request. Then create a replacement, deploy it, and look through [**Meetings**](https://www.clndr.pro/meetings) for bookings that were cancelled or confirmed without you. The key never had access to your account itself, so there's no password to change.

If it was committed to git, revoking is what protects you. Rewriting history doesn't remove copies that were already pulled or forked.

## Sending the key

Use either header. They're equivalent:

```http
Authorization: Bearer clndr_sk_...
x-clndr-key: clndr_sk_...
```

Always send requests to `https://www.clndr.pro/api/v1`. The bare `clndr.pro` host redirects to `www`, and HTTP clients strip `Authorization` when a redirect changes host, so the request arrives without a key and fails with `401 Missing API key`.

---

# How booking works

Four things make up every booking: a **booking page** (what can be booked), the host's **availability** (when), the **slots** clndr.pro derives from those two, and the **booking** a guest makes in one of them. This page explains each one well enough that the API's answers stop surprising you.

## Booking pages

A booking page is one bookable meeting type: "30-minute intro call", "Portfolio review". Hosts create them under [**Booking pages**](https://www.clndr.pro/booking) in the dashboard, and the API can read them but not create or edit them.

| Field | Dashboard label | What it does |
| --- | --- | --- |
| `slug` | Link | Identifies the page in URLs and API paths. Unique per account. |
| `duration_minutes` | Duration (minutes) | The length of every slot, 1 to 480. |
| `booking_type` | Confirmation | `direct` (*Instant*) or `approval` (*Needs approval*). See [Booking types](#booking-types). |
| `buffer_time_minutes` | Buffer time between bookings | The gap between one generated slot and the next. |
| `max_days_ahead` | Bookable up to | How far out guests can book. Later days have no slots. |
| `visibility` | Page Visibility | `public`, `private` or `team`. See [Private and team pages](#private-and-team-pages). |
| `availability_set_id` | Hours | Which of the host's schedules applies. Empty means all of them. |
| `auto_generate_meet_link` | Add a Google Meet link | Confirmed bookings get a Google Calendar event with a Meet link. |
| `show_on_profile` | List on your public profile | Lists the page at `www.clndr.pro/{username}`. |
| `is_active` | | Inactive pages still appear in List booking pages, but can't be fetched, have no slots and can't be booked. |

`description` is Markdown the host writes. Render it as Markdown: the React components already do.

## Availability

A host's availability is a set of weekly rules: "Monday 09:00–12:00", "Monday 14:00–17:30", "Thursday 09:00–12:00". A day can have several windows. Hosts can keep several sets (say "Office hours" and "Evenings") and point each booking page at one of them, or at none, in which case every set counts.

The times are wall-clock times in the host's timezone, the `timezone` on their profile (an IANA name such as `Europe/London`). "09:00" means 09:00 where the host is, through daylight-saving changes. There are no one-off exceptions or holidays yet; a host blocks a day by putting an event in their calendar.

## Slots

[List open slots](/api-reference/operations/listSlots) returns the slots a guest can book on one day. clndr.pro builds them like this:

1. Take the host's calendar day for the `date` you asked for. `date=2026-10-15` means 15 October **in the host's timezone**.
2. For each availability window that day, place a slot at the window's start, then the next one `duration_minutes + buffer_time_minutes` later, until a slot would run past the window's end.
3. Drop slots that overlap a pending or confirmed booking, or an event on the host's calendar. Google Calendar events count once they've synced into clndr.pro. Only events that start and end within that day are checked, so an overnight or multi-day event doesn't block the day.
4. Drop slots that have already started, and return nothing at all for days past `max_days_ahead`.

Every slot comes back as a UTC `start` and `end`:

```json
{ "data": [{ "start": "2026-10-15T08:00:00.000Z", "end": "2026-10-15T08:30:00.000Z" }] }
```

To book one, send `start` and `end` back unchanged as `startTime` and `endTime`.

## Timezones, worked through

The host is in London, with Thursday availability 09:00–12:00 and a 30-minute page with a 10-minute buffer. On Thursday 15 October 2026 London is on summer time, UTC+1.

| Slot (host, London) | `start` (UTC) | Guest in New York (UTC−4) | Guest in Tokyo (UTC+9) |
| --- | --- | --- | --- |
| 09:00–09:30 | `08:00Z` | 04:00 Thu | 17:00 Thu |
| 09:40–10:10 | `08:40Z` | 04:40 Thu | 17:40 Thu |
| 10:20–10:50 | `09:20Z` | 05:20 Thu | 18:20 Thu |
| 11:00–11:30 | `10:00Z` | 06:00 Thu | 19:00 Thu |

The next slot would be 11:40–12:10, which runs past 12:00, so there isn't one.

Now move the window to 15:00–17:00 London. The last slots are 23:00 and 23:40 Thursday for the Tokyo guest, and 00:20 **Friday**. One call for the host's Thursday returned a slot on the guest's Friday. Two rules keep this sane in your UI:

- Format every time in the guest's timezone (`Intl.DateTimeFormat` with no `timeZone`, or `toLocaleTimeString()`, does that in a browser).
- If you show a calendar in the guest's time, group slots by their local date rather than by the `date` you requested. For a full week, request each day and merge the results.

## Bookings

A booking is a guest's claim on a slot. Create one with [Create a booking](/api-reference/operations/createBooking), from a publishable or a secret key. clndr.pro checks that the time doesn't overlap another pending or confirmed booking for the host. A taken time fails with `409`; fetch the slots again and let the guest pick another.

A publishable key can only book a slot the slots endpoint is offering right now: anyone can copy that key out of your page, so a booking made with it must be in the future, inside the host's hours, within `max_days_ahead`, at the page's duration. When it isn't (a taken slot included), the message is `This time slot is not available. Fetch the slots again and pick another.` A secret key, which only your server holds, can book any time that doesn't overlap another booking; a taken time there reads `This time slot is no longer available. Please pick another.`

One guest email address gets five booking attempts per clock hour (`429` past that; it resets at the top of the hour).

### Booking types

```mermaid title="Booking lifecycle"
stateDiagram-v2
  [*] --> confirmed: direct page
  [*] --> pending: approval page
  pending --> confirmed: host confirms
  pending --> cancelled: host declines
  confirmed --> cancelled: host cancels
```

**Direct** pages (*Instant* in the dashboard) confirm on the spot. The guest gets a confirmation email from clndr.pro, the host gets a new-booking email, and if the page auto-generates Meet links, a Google Calendar event is created on the host's calendar and Google sends the guest an invite.

**Approval** pages create a `pending` booking. The host gets a booking-request email. The guest gets nothing yet, so tell them in your UI that their request was sent, not that they're booked. The slot is held: no one else can book it while it's pending.

The host then confirms or declines, in the dashboard under [**Meetings**](https://www.clndr.pro/meetings) or through [Confirm or cancel a booking](/api-reference/operations/updateBooking). The two paths notify differently:

| | Dashboard | API (`PATCH` / `DELETE`) |
| --- | --- | --- |
| Confirm | Confirmation email to the guest, plus the Google event and Meet link if enabled | Google event and Meet link if enabled (Google sends the invite); no clndr.pro email |
| Cancel | Cancellation email to the guest; the Google event is deleted | The Google event is deleted and Google tells the guest; no clndr.pro email |

If you confirm or cancel through the API on a page without Meet links, nobody hears about it unless you email the guest yourself. clndr.pro doesn't send reminder emails yet.

### Google Calendar status

`sync_status` on a booking records whether its Google Calendar event was created: `synced`, `failed` (with the reason in `sync_failure_reason`, often `Google Calendar is not connected`), or `not_synced` when no event was needed. It's written when the guest books and when the host confirms or cancels in the dashboard. Confirming or cancelling through the API (`PATCH`, `DELETE`) doesn't update it, so after those, look at `google_calendar_event_id` and `google_meet_link` instead. A failed Google call never blocks the booking itself.

## Questions and answers

Each page can ask guests questions, returned with the page by [Get a booking page](/api-reference/operations/getBookingPage), in `order_index` order.

| `question_type` | Render as |
| --- | --- |
| `text` | A single-line text input |
| `email` | An email input |
| `phone` | A `tel` input |
| `textarea` | A multi-line text area |
| `select` | A dropdown of `options` |
| `checkbox` | A checkbox; send its answer as text, such as `Yes` |

The dashboard creates the first four; `select` and `checkbox` exist in the data model for pages set up other ways.

Send answers as `responses: [{ questionId, answer }]`, with every answer as a string. Two things the API leaves to you: it doesn't reject a booking that skips a question marked `is_required`, so enforce that in your form; and every `questionId` must belong to the page, because one unknown id means none of that booking's answers are saved. Only send ids from the page you fetched.

## Private and team pages

`visibility` controls who can open the hosted page at `www.clndr.pro/{username}/{slug}`:

- **public**: anyone with the link.
- **private**: visitors need an access code. With **Ask visitors for a code** on, the page asks for one; with it off, the page looks like it doesn't exist. Hosts create codes on the page's edit screen. They look like `K7Q2-M9XD-4TPA-8WNE`, are case-insensitive, and expire after a period you choose. A link with the code (`?c=K7Q2-M9XD-4TPA-8WNE`) opens the page directly.
- **team**: only signed-in members of the chosen team can book.

These checks protect the hosted page and the embeds. API keys skip them, because a key acts as the page's owner: it lists, reads and books private and team pages like any other. See [Choose an integration](/integration-options#private-and-team-pages) for what that means for your site.

---

# Embed script

`embed.js` puts the hosted booking page inside your site. It renders the page in an iframe, grows the frame to fit its content, and tells your code when a booking goes through. No API key, no build step: it works anywhere you can paste HTML.

You need the page's link, `username/slug`. For `www.clndr.pro/ada/intro-call` that's `ada/intro-call`.

## Inline

```html title="index.html"
<div id="booking"></div>

<script>
  function mountBooking() {
    Clndr.inline({
      elementOrSelector: '#booking',
      link: 'ada/intro-call',
      config: { theme: 'auto' },
    });
  }
</script>
<script src="https://www.clndr.pro/embed.js" async onload="mountBooking()"></script>
```

Call `Clndr` from the script's `onload`, as above. A plain `<script>` placed after an `async` one can run first, before `window.Clndr` exists, and throw `Clndr is not defined`.

<Warning>
Load the script from `https://www.clndr.pro`, with the `www`. The script builds the iframe's URL from its own origin and only trusts messages from that origin. Loaded from `clndr.pro`, the frame ends up on `www.clndr.pro` after a redirect, its messages are ignored, and the frame never resizes or reports bookings.
</Warning>

## Modal

`Clndr.modal()` opens the booking page in an overlay straight away, so call it from a click:

```html title="index.html"
<button type="button" onclick="Clndr.modal({ link: 'ada/intro-call' })">Book a call</button>

<script src="https://www.clndr.pro/embed.js" async></script>
```

The guest closes it with the × button, the Escape key or a click outside. After a successful booking it closes by itself 2.5 seconds later, once the guest has seen the confirmation.

## Floating button

A fixed button in a corner of every page, which opens the modal:

```html title="footer code"
<script>
  function mountBookingButton() {
    Clndr.floatingButton({
      link: 'ada/intro-call',
      buttonText: 'Book a call',
      position: 'bottom-right',
    });
  }
</script>
<script src="https://www.clndr.pro/embed.js" async onload="mountBookingButton()"></script>
```

Put it in your site-wide footer code so it shows on every page.

## Options

All three functions take `link` and an optional `config`.

<ParamField body="elementOrSelector" type="string | Element" required>
`inline` only. A CSS selector or a DOM element to append the iframe to. Throws if nothing matches.
</ParamField>

<ParamField body="link" type="string" required>
`username/slug` of the booking page. Throws if it isn't two segments.
</ParamField>

<ParamField body="buttonText" type="string" default="Book a meeting">
`floatingButton` only.
</ParamField>

<ParamField body="position" type="'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'" default="bottom-right">
`floatingButton` only. The button sits 24px from the two edges.
</ParamField>

<ParamField body="config.theme" type="'light' | 'dark' | 'auto'">
`auto` follows the guest's system setting.
</ParamField>

<ParamField body="config.hideEventTypeDetails" type="boolean" default="false">
Hides the host's name, the page title, the duration and the description, for when your page already shows them.
</ParamField>

<ParamField body="config.primaryColor" type="string">
Any CSS colour, used for buttons and highlights: `'#9A5A16'`, `'rgb(74 78 143)'`.
</ParamField>

<ParamField body="config.prefill" type="{ name?: string; email?: string }">
Fills in the guest's name and email, for signed-in visitors.
</ParamField>

<ParamField body="config.accessCode" type="string">
Required for `private` pages: the embed has no code prompt of its own, and without the code it shows "Booking page not found".
</ParamField>

<ParamField body="config.onBookingSuccessful" type="(payload) => void">
Called once a booking is made. See [Events](#events).
</ParamField>

<ParamField body="config.onRouteChanged" type="(payload) => void">
Called when the booking page loads, with `{ path: '/embed/ada/intro-call' }`.
</ParamField>

Each function returns a handle. `inline` returns `{ iframe, destroy }`, `modal` returns `{ destroy }`, and `floatingButton` returns `{ button, destroy }`. `destroy()` removes what was added and stops listening for its events. On a floating button it removes the button but leaves an open modal alone.

## Events

```js
Clndr.inline({
  elementOrSelector: '#booking',
  link: 'ada/intro-call',
  config: {
    onBookingSuccessful({ meetingId, startTime, endTime }) {
      // meetingId is the booking's id; the times are UTC ISO strings.
      window.dataLayer?.push({ event: 'booking_made', meetingId });
      window.location.href = '/thanks?at=' + encodeURIComponent(startTime);
    },
  },
});
```

`onBookingSuccessful` fires for approval pages too, when the request is sent. To act on the host's decision, use a secret key on your server: [Sync bookings to your database](/tutorials/sync-bookings) shows how.

Under the hood these are `postMessage` events from the iframe. The script handles the resizing for you; [Iframe embed](/embed/iframe#events) lists the raw messages.

## In Next.js or React

If you'd rather render the booking form with your own components, use [`@clndr-pro/react`](/react/components) instead. To keep clndr.pro's own UI, load the script with `next/script`:

```tsx title="components/clndr-embed.tsx"
'use client';

import Script from 'next/script';
import { useEffect, useRef } from 'react';

type Handle = { destroy(): void };

declare global {
  interface Window {
    Clndr?: {
      inline(options: { elementOrSelector: Element | string; link: string; config?: Record<string, unknown> }): Handle;
    };
  }
}

export function ClndrEmbed({ link }: { link: string }) {
  const container = useRef<HTMLDivElement>(null);
  const handle = useRef<Handle | null>(null);

  function mount() {
    if (!container.current || !window.Clndr || handle.current) return;
    handle.current = window.Clndr.inline({
      elementOrSelector: container.current,
      link,
      config: { theme: 'auto' },
    });
  }

  useEffect(() => {
    mount(); // the script may already be loaded from a previous page
    return () => {
      handle.current?.destroy();
      handle.current = null;
    };
  }, [link]);

  return (
    <>
      <Script src="https://www.clndr.pro/embed.js" strategy="afterInteractive" onReady={mount} />
      <div ref={container} />
    </>
  );
}
```

`onReady` runs once the script loads and again on every remount, and `destroy()` on unmount stops a client-side navigation from leaving a second frame behind.

## WordPress, Webflow and other builders

- **WordPress**: add a **Custom HTML** block where the booking page should go and paste the inline snippet. For a floating button on every page, paste that snippet into your theme's footer or a header-and-footer plugin.
- **Webflow**: drop a **Code Embed** element on the page for the inline snippet. For the floating button, use **Site settings → Custom code → Footer code**.
- **Anything else**: if it accepts an HTML block with scripts, the snippets work unchanged. If it strips scripts, use the [iframe](/embed/iframe).

## Content Security Policy

If your site sends a CSP header, allow the script and the frame:

```text title="Content-Security-Policy"
script-src 'self' https://www.clndr.pro;
frame-src https://www.clndr.pro;
```

The snippets above use an inline `onload` attribute. Under a strict CSP that blocks inline handlers, move `mountBooking` into a script file of your own and attach the listener there: `document.querySelector('script[src$="/embed.js"]').addEventListener('load', mountBooking)`.

## Limits

- The embed shows clndr.pro's UI: you can change the theme and the accent colour, not the layout or the fonts.
- `team` pages don't load inside the frame, because browsers don't send clndr.pro's sign-in cookie to a third-party iframe.

---

# Iframe embed

Every booking page has an embeddable version at:

```text
https://www.clndr.pro/embed/{username}/{slug}
```

It's the same booking flow as the hosted page, without clndr.pro's header and footer, and it allows framing from any site. This is what the [embed script](/embed/script) creates for you. Use the iframe directly when you can't run scripts, or when you want full control of the frame.

```html title="index.html"
<iframe
  src="https://www.clndr.pro/embed/ada/intro-call?theme=auto"
  title="Book a call with Ada"
  style="width: 100%; min-height: 640px; border: 0"
></iframe>
```

## Query parameters

<ParamField query="theme" type="'light' | 'dark' | 'auto'">
`auto` follows the guest's system setting.
</ParamField>

<ParamField query="hideEventTypeDetails" type="'1'">
Hides the host's name, the page title, the duration and the description.
</ParamField>

<ParamField query="primaryColor" type="string">
Any CSS colour for buttons and highlights. URL-encode it: `#9A5A16` becomes `%239A5A16`.
</ParamField>

<ParamField query="name" type="string">
Prefills the guest's name.
</ParamField>

<ParamField query="email" type="string">
Prefills the guest's email.
</ParamField>

<ParamField query="c" type="string">
An access code, for `private` pages. Without it a private page shows "Booking page not found".
</ParamField>

Build the URL with `URLSearchParams` so names and colours are encoded properly:

```js
const src = new URL('https://www.clndr.pro/embed/ada/intro-call');
src.search = new URLSearchParams({ theme: 'dark', primaryColor: '#E0913D', email: 'grace@example.com' }).toString();
```

## Sizing

The page's height changes as the guest moves from the date picker to the slots to the form. The frame can't know that by itself, so either give it a fixed height (640px fits the date and slot steps on most screens) or listen for the page's resize messages:

```html title="index.html"
<iframe id="clndr" src="https://www.clndr.pro/embed/ada/intro-call" title="Book a call"
        style="width: 100%; min-height: 600px; border: 0" scrolling="no"></iframe>

<script>
  window.addEventListener('message', (event) => {
    if (event.origin !== 'https://www.clndr.pro') return;
    const frame = document.getElementById('clndr');
    if (event.source !== frame.contentWindow) return;
    if (event.data?.type === '__clndr:resize') {
      frame.style.height = event.data.payload.height + 'px';
    }
  });
</script>
```

Check `event.origin` on every message. The embed posts to `*`, so any page that frames it receives the messages, and you should only trust the ones that come from clndr.pro.

## Events

The embed posts `{ type, payload }` messages to its parent window:

| `type` | `payload` | Sent when |
| --- | --- | --- |
| `__clndr:resize` | `{ height: number }` | On load, and whenever the content's height changes |
| `__clndr:route_changed` | `{ path: string }` | When the booking page loads, for example `/embed/ada/intro-call` |
| `__clndr:booking_successful` | `{ meetingId?: string, startTime: string, endTime: string }` | After the guest books; times are UTC ISO strings |

```js
window.addEventListener('message', (event) => {
  if (event.origin !== 'https://www.clndr.pro') return;
  if (event.data?.type === '__clndr:booking_successful') {
    const { meetingId, startTime } = event.data.payload;
    console.log('Booked', meetingId, 'for', new Date(startTime).toLocaleString());
  }
});
```

On approval pages `booking_successful` means the request was sent; the booking is `pending` until the host confirms it.

## Private and team pages

A `private` page needs its access code in `c`. Anyone who can read your page's HTML can read that code too, so treat an embedded access code as shared with your site's visitors.

`team` pages don't work inside an iframe. They need the guest to be signed in to clndr.pro, and browsers don't send clndr.pro's cookies to a frame on another site. Link to the hosted page instead.

## Quirks worth knowing

- A `select` question shows as a plain text input in the embed, a `phone` question as a text input, and a `checkbox` question as a checkbox whose answer is always saved empty. If a page uses `select` or `checkbox` questions, render the form yourself with [`@clndr-pro/react`](/react/components).
- The embed asks for slots by the guest's local midnight, and clndr.pro answers with the host's day that contains that moment. When the guest and the host are many hours apart, the times under a date can fall on the day before or after it in the guest's time. The [API](/api-reference/operations/listSlots) takes a host-timezone date and leaves out past slots, so custom integrations don't have this problem.

---

# Next.js App Router

The [quickstart](/quickstart) puts one booking form on one page. This guide is the setup you keep: both keys in the right places, a URL for each of your booking pages with real titles in search results, and a server route for the bookings that come in. It assumes Next.js 15 or 16 with the App Router; the [Pages Router](#pages-router) section at the end covers the older setup.

## Two keys, two sides of the boundary

| Key | Env var | Used by | Can |
| --- | --- | --- | --- |
| Publishable `clndr_pk_…` | `NEXT_PUBLIC_CLNDR_PUBLISHABLE_KEY` | `@clndr-pro/react` in the browser | Read pages and slots, create bookings |
| Secret `clndr_sk_…` | `CLNDR_SECRET_KEY` | `@clndr-pro/sdk` in Server Components, route handlers, server actions | Everything above, plus list, confirm and cancel bookings |

```bash
npm install @clndr-pro/react @clndr-pro/sdk server-only
```

`@clndr-pro/react` already depends on the SDK. Installing `@clndr-pro/sdk` directly lets server code import it without pulling in React components, and `server-only` turns an accidental client import of your secret key into a build error.

```bash title=".env.local"
NEXT_PUBLIC_CLNDR_PUBLISHABLE_KEY=clndr_pk_...
CLNDR_SECRET_KEY=clndr_sk_...
```

On Vercel, add both under **Settings → Environment Variables** (or run `vercel env add CLNDR_SECRET_KEY`). `NEXT_PUBLIC_` values are inlined into the JavaScript bundle at build time, so redeploy after changing the publishable key. Never give the secret key a `NEXT_PUBLIC_` prefix.

<Warning>
Use `@clndr-pro/react` 0.2.1+ and `@clndr-pro/sdk` 0.1.5+. Older versions send requests to `https://clndr.pro`, which redirects to `www` and drops the key, so every call fails with `401 Missing API key`. If you can't upgrade, pass `baseUrl="https://www.clndr.pro"` to `ClndrProvider` and `baseUrl: 'https://www.clndr.pro'` to `new Clndr()`.
</Warning>

## The browser side

`ClndrProvider` creates the browser client from the publishable key. Give it its own client file and wrap your layout's children, so the layout stays a Server Component:

```tsx title="app/providers.tsx"
'use client';

import { ClndrProvider } from '@clndr-pro/react';

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <ClndrProvider publishableKey={process.env.NEXT_PUBLIC_CLNDR_PUBLISHABLE_KEY!}>
      {children}
    </ClndrProvider>
  );
}
```

```tsx title="app/layout.tsx"
import { Providers } from './providers';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}
```

If only one section of the site books meetings, put `<Providers>` in that section's layout (`app/book/layout.tsx`) instead of the root.

Everything from `@clndr-pro/react` (components, hooks, `ClndrProvider`) runs in the browser. Import it from files that start with `'use client'`. From 0.2.1 the package marks itself as client code, so importing `BookingInline` straight into a Server Component also works, but a small client wrapper works on every version and is the only place you can pass function props like `onBooked`.

## The server side

One module owns the secret key:

```ts title="lib/clndr.ts"
import 'server-only';
import { Clndr } from '@clndr-pro/sdk';

if (!process.env.CLNDR_SECRET_KEY) {
  throw new Error('Set CLNDR_SECRET_KEY (a clndr_sk_ key) in .env.local');
}

/** Server-only client. The secret key never reaches the browser bundle. */
export const clndr = new Clndr(process.env.CLNDR_SECRET_KEY);
```

Import `clndr` from Server Components, route handlers and server actions. If a client component ever imports `lib/clndr.ts`, even indirectly, `server-only` fails the build.

## A page for every booking page

`app/book/[slug]/page.tsx` serves `/book/intro-call`, `/book/demo` and so on. The server reads the booking page with the secret key to set the `<title>` and meta description, so search engines and link previews see "Intro call with Ada Lovelace" instead of a loading spinner. The form itself is the client widget, which fetches slots live.

```tsx title="app/book/[slug]/page.tsx"
import type { Metadata } from 'next';
import { notFound } from 'next/navigation';
import { cache } from 'react';
import { ClndrError } from '@clndr-pro/sdk';
import { clndr } from '@/lib/clndr';
import { BookingWidget } from './booking-widget';

// Re-render each booking page at most every 5 minutes. Slots aren't part of
// this HTML (the widget fetches them live), so only the title and
// description can be up to 5 minutes stale.
export const revalidate = 300;

// One API call per request, shared by generateMetadata and the page.
const getBookingPage = cache(async (slug: string) => {
  try {
    return await clndr.bookingPages.get(slug);
  } catch (err) {
    if (err instanceof ClndrError && err.status === 404) return null;
    throw err;
  }
});

export async function generateStaticParams() {
  const pages = await clndr.bookingPages.list();
  return pages.filter((p) => p.is_active && p.visibility === 'public').map((p) => ({ slug: p.slug }));
}

function summary(markdown: string | null, fallback: string) {
  const text = markdown?.replace(/[#*_`>[\]()]/g, '').replace(/\s+/g, ' ').trim();
  return text ? text.slice(0, 160) : fallback;
}

export async function generateMetadata({ params }: { params: Promise<{ slug: string }> }): Promise<Metadata> {
  const { slug } = await params;
  const page = await getBookingPage(slug);
  if (!page) return {};
  const { bookingPage, userProfile } = page;
  const host = userProfile.full_name ?? userProfile.username;
  return {
    title: `${bookingPage.title} with ${host}`,
    description: summary(bookingPage.description, `Book ${bookingPage.duration_minutes} minutes with ${host}.`),
  };
}

export default async function BookingPage({ params }: { params: Promise<{ slug: string }> }) {
  const { slug } = await params;
  const page = await getBookingPage(slug);
  // Your key can read your private and team pages too. Only show public ones.
  if (!page || page.bookingPage.visibility !== 'public') notFound();

  return (
    <main className="mx-auto max-w-2xl px-4 py-12">
      <BookingWidget slug={slug} />
    </main>
  );
}
```

```tsx title="app/book/[slug]/booking-widget.tsx"
'use client';

import { BookingInline } from '@clndr-pro/react';
import { Button } from '@/components/ui/button';
import { Input } from '@/components/ui/input';
import { Label } from '@/components/ui/label';
import { Textarea } from '@/components/ui/textarea';

export function BookingWidget({ slug }: { slug: string }) {
  return (
    <BookingInline
      slug={slug}
      components={{ Button, Input, Label, Textarea }}
      classNames={{
        root: 'space-y-6',
        heading: 'text-2xl font-semibold tracking-tight',
        muted: 'text-sm text-muted-foreground',
        label: 'mb-2 block',
        dateInput: 'w-full',
        slotGrid: 'mt-4 grid grid-cols-3 gap-2',
        slotButton: 'bg-background text-foreground border hover:bg-accent hover:text-accent-foreground',
        card: 'space-y-4 rounded-xl border p-6',
        buttonSecondary: 'bg-secondary text-secondary-foreground hover:bg-secondary/80',
        error: 'text-sm text-destructive',
      }}
    />
  );
}
```

Three things this page relies on:

- **The visibility check is yours to make.** The API hands your key every page on your account, including `private` pages (which need an access code on clndr.pro) and `team` pages. The hosted page enforces those rules. Your site doesn't, unless you check `visibility` as above.
- **`generateStaticParams` runs at build time**, so `CLNDR_SECRET_KEY` has to exist in the build environment. Pages you create later still work: `dynamicParams` defaults to `true`, so a new slug renders on its first request and is cached from then on.
- **`revalidate` keeps the API calls down.** A secret key gets 300 requests a minute, and a statically generated page calls the API once per revalidation, not once per visitor.

<Note>
With `cacheComponents` turned on (Next.js 16), route segment options like `revalidate` aren't available. Move the API call into an async function marked `'use cache'` that calls `cacheLife('minutes')`, and call it from the page and `generateMetadata` in place of `cache()`.
</Note>

## A route handler for your admin

Anything that reads bookings needs the secret key and returns guest names and emails, so it lives on the server behind your own auth check:

```ts title="app/api/bookings/route.ts"
import { NextResponse } from 'next/server';
import { clndr } from '@/lib/clndr';
import { auth } from '@/auth'; // your auth library

const STATUSES = ['pending', 'confirmed', 'cancelled'] as const;
type Status = (typeof STATUSES)[number];

/** GET /api/bookings?status=pending — for your own admin screens only. */
export async function GET(request: Request) {
  // This returns guest names and emails. Never ship it without an auth check.
  const session = await auth();
  if (session?.user?.role !== 'admin') {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }

  const param = new URL(request.url).searchParams.get('status');
  const status = STATUSES.includes(param as Status) ? (param as Status) : undefined;

  const bookings = await clndr.bookings.list({ status, limit: 100 });
  return NextResponse.json({ bookings });
}
```

For confirming and declining from a screen, server actions are less code than a route handler: [Approve bookings in your admin](/tutorials/approvals-dashboard) builds one. To keep guest details off the browser-to-clndr.pro path entirely, book through [a server action](/tutorials/server-actions) instead of `BookingInline`.

## What you can skip

You don't need middleware or `proxy.ts` changes: the API accepts cross-origin requests from any site. You don't need a `next.config` entry either, since the packages ship compiled JavaScript.

If your site sends a Content-Security-Policy, the browser has to reach the API: add `https://www.clndr.pro` to `connect-src`. If you also use the [iframe](/embed/iframe) or [script](/embed/script) embed, add it to `frame-src`, and to `script-src` for the script.

## Pages Router

The same pieces, with `_app.tsx` holding the provider and `getStaticProps` doing the server work. There's no `'use client'` to manage: page components render in the browser after hydration, and the data functions never ship to it.

```tsx title="pages/_app.tsx"
import type { AppProps } from 'next/app';
import { ClndrProvider } from '@clndr-pro/react';

export default function App({ Component, pageProps }: AppProps) {
  return (
    <ClndrProvider publishableKey={process.env.NEXT_PUBLIC_CLNDR_PUBLISHABLE_KEY!}>
      <Component {...pageProps} />
    </ClndrProvider>
  );
}
```

```tsx title="pages/book/[slug].tsx"
import type { GetStaticPaths, GetStaticProps } from 'next';
import Head from 'next/head';
import { BookingInline } from '@clndr-pro/react';
import { Clndr, ClndrError } from '@clndr-pro/sdk';

type Props = { slug: string; title: string };

// getStaticProps and getStaticPaths only run on the server, so the secret key stays there.
const clndr = new Clndr(process.env.CLNDR_SECRET_KEY!);

export const getStaticPaths: GetStaticPaths = async () => {
  const pages = await clndr.bookingPages.list();
  return {
    paths: pages.filter((p) => p.is_active && p.visibility === 'public').map((p) => ({ params: { slug: p.slug } })),
    fallback: 'blocking',
  };
};

export const getStaticProps: GetStaticProps<Props, { slug: string }> = async ({ params }) => {
  try {
    const { bookingPage } = await clndr.bookingPages.get(params!.slug);
    if (bookingPage.visibility !== 'public') return { notFound: true };
    return { props: { slug: bookingPage.slug, title: bookingPage.title }, revalidate: 300 };
  } catch (err) {
    if (err instanceof ClndrError && err.status === 404) return { notFound: true };
    throw err;
  }
};

export default function BookPage({ slug, title }: Props) {
  return (
    <>
      <Head>
        <title>{title}</title>
      </Head>
      <main style={{ maxWidth: 640, margin: '48px auto', padding: 16 }}>
        <BookingInline slug={slug} />
      </main>
    </>
  );
}
```

<Prompt title="Set up clndr.pro in this Next.js app">

```text
Set up clndr.pro booking in this Next.js app, following https://docs.clndr.pro/nextjs.md (read it first).

- Install @clndr-pro/react (0.2.1+), @clndr-pro/sdk (0.1.5+) and server-only.
- Add NEXT_PUBLIC_CLNDR_PUBLISHABLE_KEY and CLNDR_SECRET_KEY to .env.example with placeholders. Don't touch .env.local; tell me to fill it in.
- Create app/providers.tsx ('use client', ClndrProvider with the publishable key) and wrap the root layout's children with it. Keep the layout a Server Component.
- Create lib/clndr.ts with import 'server-only' and a Clndr client built from CLNDR_SECRET_KEY.
- Create app/book/[slug]/page.tsx: generateStaticParams from clndr.bookingPages.list() (active, public pages only), generateMetadata from clndr.bookingPages.get(slug), notFound() for a 404 ClndrError or a non-public page, revalidate = 300. Render a 'use client' BookingWidget that uses BookingInline with this project's own Button/Input/Label/Textarea components if it has them (components/ui).
- If the site sets a Content-Security-Policy, add https://www.clndr.pro to connect-src.
- Run the type checker and the build and fix what breaks. List the files you changed.
```

</Prompt>

---

# Components

`@clndr-pro/react` has one provider and three components. The components are the same booking flow in different wrappers, so most of this page is about one of them.

```bash
npm install @clndr-pro/react
```

Everything here runs in the browser: import it from a file with `'use client'` at the top. The [Next.js guide](/nextjs) shows where those files go.

## ClndrProvider

Creates the API client the components and hooks use, and passes it down through React context.

```tsx title="app/providers.tsx"
'use client';

import { ClndrProvider } from '@clndr-pro/react';

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <ClndrProvider publishableKey={process.env.NEXT_PUBLIC_CLNDR_PUBLISHABLE_KEY!}>
      {children}
    </ClndrProvider>
  );
}
```

| Prop | Type | |
| --- | --- | --- |
| `publishableKey` | `string` | A `clndr_pk_` key. Required unless you pass `client`. |
| `client` | `Clndr` | An already-built client. Takes priority over `publishableKey`. |
| `baseUrl` | `string` | API host. Defaults to `https://www.clndr.pro` from 0.2.1. Only needed on older versions, or against a local clndr.pro. |
| `children` | `ReactNode` | |

The provider throws if it gets neither `publishableKey` nor `client`, and every component or hook throws `useClndr must be used inside <ClndrProvider>` when there's no provider above it.

### Your own client

Pass `client` when you need control over how requests are made: a custom `fetch` for logging or tests, or a different base URL. Build it once, outside the component. The provider memoises on the client's identity, so a new `Clndr` on every render recreates the context each time.

```tsx title="components/debug-booking.tsx"
'use client';

import { Clndr, ClndrProvider, BookingInline } from '@clndr-pro/react';

// Built once at module scope: ClndrProvider memoises on the client's identity.
const client = new Clndr({
  apiKey: process.env.NEXT_PUBLIC_CLNDR_PUBLISHABLE_KEY!,
  fetch: (input, init) => {
    console.debug('clndr request', input);
    return fetch(input, init);
  },
});

export function DebugBooking() {
  return (
    <ClndrProvider client={client}>
      <BookingInline slug="intro-call" />
    </ClndrProvider>
  );
}
```

### Several accounts on one site

A key belongs to one clndr.pro account, and a slug is only unique within an account. To book with two people who each have their own account, give each section its own provider. Components use the nearest one.

```tsx
<ClndrProvider publishableKey={process.env.NEXT_PUBLIC_CLNDR_KEY_ADA!}>
  <BookingInline slug="intro-call" />
</ClndrProvider>

<ClndrProvider publishableKey={process.env.NEXT_PUBLIC_CLNDR_KEY_GRACE!}>
  <BookingInline slug="intro-call" />
</ClndrProvider>
```

## BookingInline and BookingForm

`BookingInline` renders `BookingForm` and nothing else; use whichever name reads better in your code. Both take the same props.

```tsx title="app/book/booking-widget.tsx"
'use client';

import { BookingInline } from '@clndr-pro/react';

export function BookingWidget() {
  return <BookingInline slug="intro-call" onBooked={(id) => console.log('booked', id)} />;
}
```

| Prop | Type | |
| --- | --- | --- |
| `slug` | `string` | The booking page's slug. Required. |
| `prefill` | `{ name?: string; email?: string }` | Initial values for the guest's name and email. The guest can still edit them. |
| `onBooked` | `(bookingId: string) => void` | Called after the booking is created, with its `id`. |
| `components` | `ComponentSlots` | Your own `Button`, `Input`, `Label` and other elements. See [Styling and slots](/react/styling). |
| `classNames` | `ClassNameMap` | Class names for each part. See [Styling and slots](/react/styling). |

### What the guest sees

1. While the page loads: "Loading…". If the slug doesn't exist on the key's account, or the page is inactive, the API's error message ("Booking page not found").
2. The page title, then the host's name and the duration ("Ada Lovelace · 30 min"), then the page description rendered as Markdown.
3. A date input from today on, capped at `max_days_ahead` days from now when the page sets a limit.
4. After a date is picked, the open times for that day as buttons, in the guest's local time. "No available slots for this date." when there are none.
5. After a time is picked, a form: name, email, and the host's questions in their order. Required questions are marked with `*` and use the browser's `required` validation.
6. **Confirm** creates the booking. If that fails (someone else took the time, say), the API's message appears above the buttons. **Back** returns to the times.
7. A success card. *Direct* pages say "Booking confirmed" and that a confirmation email is coming. *Approval* pages say the request was submitted and the guest will hear once it's approved (the heading reads "Request sent" from 0.2.1; 0.2.0 says "Booking confirmed" for both).

Question types map to inputs like this from 0.2.1: `textarea` gets a text area, `email` an email input, `phone` a `tel` input, `select` a `<select>` with the question's options, `checkbox` a checkbox whose answer is "Yes" or "No". In 0.2.0 everything except `textarea` and `email` renders as a plain text input. The dashboard only creates `text`, `email`, `phone` and `textarea` questions today, so this mostly matters for `phone`.

The API doesn't check that required questions were answered; the form's `required` attributes do. If you build your own form, validate them yourself.

### After booking: onBooked

`onBooked` fires once, with the new booking's id, after the API returns it. The success card renders at the same moment. Common uses:

```tsx
'use client';

import { useRouter } from 'next/navigation';
import { BookingInline } from '@clndr-pro/react';

export function BookingWidget() {
  const router = useRouter();
  return (
    <BookingInline
      slug="intro-call"
      onBooked={(bookingId) => {
        // Send your analytics event here, then move on.
        router.push(`/thanks?booking=${bookingId}`);
      }}
    />
  );
}
```

The id is all the browser gets. To show booking details on the thanks page, read the booking on your server with a secret key ([Get a booking](/api-reference/operations/getBooking)): a publishable key can't read bookings, by design.

### Prefill from your own user

If the guest is signed in to your site, pass what you know. Read the user on the server and hand plain values to the client component:

```tsx title="app/onboarding/book-with-account.tsx"
'use client';

import { BookingInline } from '@clndr-pro/react';

export function BookWithAccount({ user }: { user: { name: string; email: string } }) {
  return <BookingInline slug="onboarding-call" prefill={{ name: user.name, email: user.email }} />;
}
```

```tsx title="app/onboarding/page.tsx"
import { getCurrentUser } from '@/lib/auth'; // your auth library
import { BookWithAccount } from './book-with-account';

export default async function OnboardingPage() {
  const user = await getCurrentUser();
  return <BookWithAccount user={{ name: user.name, email: user.email }} />;
}
```

## BookingModal

The same flow in a fixed-position overlay. It closes on Escape and on a click outside the panel, and closes itself 2.5 seconds after a successful booking so the guest sees the confirmation first.

```tsx title="components/book-button.tsx"
'use client';

import { useState } from 'react';
import { BookingModal } from '@clndr-pro/react';

export function BookButton() {
  const [open, setOpen] = useState(false);
  return (
    <>
      <button type="button" onClick={() => setOpen(true)}>
        Book a call
      </button>
      <BookingModal slug="intro-call" open={open} onOpenChange={setOpen} />
    </>
  );
}
```

Every `BookingInline` prop, plus:

| Prop | Type | |
| --- | --- | --- |
| `open` | `boolean` | Whether the modal is showing. Required. |
| `onOpenChange` | `(open: boolean) => void` | Called with `false` on Escape, an outside click, and after a booking. Required. |
| `overlayClassName` | `string` | Replaces the built-in overlay styles (a 50% black backdrop, centred panel). |
| `contentClassName` | `string` | Replaces the built-in panel styles (white, 8px radius, 560px wide). |

The built-in styles are inline and fixed: the panel stays white in dark mode until you pass `contentClassName`. It also doesn't trap focus or lock page scroll. If your site has a design system, render `BookingForm` inside your own dialog instead: [Booking dialog with shadcn](/tutorials/shadcn-booking-dialog) shows how, with a drawer on phones.

## Types

The package re-exports the SDK's types and classes, so one import covers a component file:

```ts
import {
  Clndr,
  ClndrError,
  type Booking,
  type BookingPage,
  type BookingPageDetail,
  type BookingQuestion,
  type CreateBookingInput,
  type TimeSlot,
  type UserProfile,
  type BookingFormProps,
  type BookingModalProps,
  type ComponentSlots,
  type ClassNameMap,
} from '@clndr-pro/react';
```

[Data types](/types) describes every field. For a flow these components can't express (a month calendar, slots grouped by morning and afternoon, a multi-step wizard), use the [hooks](/react/hooks).

---

# Hooks

The hooks are the data layer under `BookingForm`, exposed so you can draw your own booking UI. They need a [`ClndrProvider`](/react/components#clndrprovider) above them and, like everything in `@clndr-pro/react`, run only in `'use client'` files.

| Hook | Wraps | Returns |
| --- | --- | --- |
| `useBookingPage(slug)` | [Get a booking page](/api-reference/operations/getBookingPage) | `{ data, status, error, isLoading }` |
| `useAvailableSlots(slug, date)` | [List open slots](/api-reference/operations/listSlots) | `{ slots, status, error, isLoading, refetch }` |
| `useCreateBooking()` | [Create a booking](/api-reference/operations/createBooking) | `{ create, data, status, error, isLoading }` |
| `useClndr()` | The provider's client | `Clndr` |

`status` is `'idle' | 'loading' | 'success' | 'error'` everywhere. The hooks don't cache between components or retry; each one is a `useEffect` around one SDK call.

## useBookingPage

```ts
function useBookingPage(slug: string | null): {
  data: BookingPageDetail | null; // { bookingPage, userProfile, questions }
  status: 'idle' | 'loading' | 'success' | 'error';
  error: Error | null;
  isLoading: boolean;
};
```

Fetches the page, its host's profile and its questions. Pass `null` to skip fetching (while you don't know the slug yet). It refetches when `slug` changes, and keeps the previous page in `data` until the new one arrives.

```tsx
const { data: page, error } = useBookingPage('intro-call');

if (error) return <p>{error.message}</p>; // "Booking page not found" for a bad slug
if (!page) return <Spinner />;

const { bookingPage, userProfile, questions } = page;
```

Given a slug, the hook starts in `status: 'loading'`, so checking `isLoading` works from the first render. Checking "no data and no error", as above, works too, and also covers `@clndr-pro/react` 0.2.0, which started in `idle` and could show a not-found state for a frame.

## useAvailableSlots

```ts
function useAvailableSlots(slug: string | null, date: Date | null): {
  slots: TimeSlot[]; // [{ start, end }], UTC ISO strings
  status: 'idle' | 'loading' | 'success' | 'error';
  error: Error | null;
  isLoading: boolean;
  refetch: () => void; // ask again for the same slug and day
};
```

Fetches the open slots for one day. `date` is sent as its local calendar date (`2026-10-15`), and the API reads that as the host's calendar day, in the host's timezone. The slots that come back are UTC instants; format them for the guest with `Intl.DateTimeFormat` or `toLocaleTimeString`. When host and guest are far apart, some of the host's day can fall on the guest's previous or next date, so group by the guest's date if you show dates next to times. Past slots and days beyond the page's `max_days_ahead` come back empty. Slots are sorted by start time.

The hook refetches when `slug` changes, when `date` points at a different instant, and when you call `refetch()`. It compares the date's timestamp, not the object, so building `new Date(...)` during render is fine. While a request is in flight `slots` still holds the previous list, so render from `isLoading` first. `error` is cleared each time a new request starts.

**Build dates from local parts.** A date picker's `Date` (shadcn's `Calendar`, react-day-picker) is already local midnight. From an `<input type="date">`, split the string: `new Date('2026-10-15')` is UTC midnight, which is still the 14th for anyone west of UTC.

```ts
/** `YYYY-MM-DD` from <input type="date"> → a Date at local midnight. */
function parseLocalDate(value: string) {
  const [y, m, d] = value.split('-').map(Number);
  return new Date(y, m - 1, d);
}
```

<Note>
Upgrading from `@clndr-pro/react` 0.2.0? Its `useAvailableSlots` had no `refetch`, skipped a request that matched the previous slug and day, and could sit on `loading` forever under React Strict Mode (every `next dev`) when a component mounted with a date already set. It also sent a `Date` as a full UTC timestamp, which the API reads as "the host's day containing this instant", one day off for many timezone pairs. 0.2.1 (with SDK 0.1.5) fixes all of that.
</Note>

## useCreateBooking

```ts
function useCreateBooking(): {
  create: (input: CreateBookingInput) => Promise<Booking>;
  data: Booking | null;
  status: 'idle' | 'loading' | 'success' | 'error';
  error: ClndrError | Error | null;
  isLoading: boolean;
};

interface CreateBookingInput {
  bookingPageId: string; // page.bookingPage.id
  guestName: string;
  guestEmail: string;
  startTime: string;     // a slot's `start`, unchanged
  endTime: string;       // the same slot's `end`
  responses?: Array<{ questionId: string; answer: string }>;
}
```

`create` both updates the hook's state and returns (or throws) the result, so you can `await` it in a submit handler. Catch the rejection: the error is on `error` too, and an uncaught rejection in an event handler only ends up in the console (`<BookingForm>` catches its own).

```tsx
const { create, data: booking, error, isLoading } = useCreateBooking();

async function onSubmit() {
  try {
    await create({
      bookingPageId: page.bookingPage.id,
      guestName: name,
      guestEmail: email,
      startTime: slot.start,
      endTime: slot.end,
      responses: [{ questionId: questions[0].id, answer: topic }],
    });
  } catch {
    // shown from `error`
  }
}

if (booking) {
  return <p>{booking.status === 'pending' ? 'Request sent' : "You're booked"}</p>;
}
```

The returned `Booking` is `confirmed` on *direct* pages and `pending` on *approval* pages; on direct pages with Meet links on it already carries `google_meet_link`. It doesn't include the answers.

Send each answer once, only for questions on this page. One unknown `questionId` and none of the answers are saved (the booking still is). Skip questions the guest left blank, and check required ones before you call `create`: the API doesn't.

## useClndr

```ts
function useClndr(): Clndr;
```

The provider's client, for calls the other hooks don't cover. With a publishable key that's `bookingPages.list()`, `bookingPages.get()`, `bookingPages.getSlots()` and `bookings.create()`; the [TypeScript SDK](/sdk) page documents each. A page picker, for example:

```tsx title="components/booking-page-list.tsx"
'use client';

import { useEffect, useState } from 'react';
import { useClndr, type BookingPage } from '@clndr-pro/react';

export function BookingPageList({ onPick }: { onPick: (slug: string) => void }) {
  const clndr = useClndr();
  const [pages, setPages] = useState<BookingPage[] | null>(null);

  useEffect(() => {
    clndr.bookingPages
      .list()
      .then((all) => setPages(all.filter((p) => p.is_active && p.visibility === 'public')))
      .catch(() => setPages([]));
  }, [clndr]);

  if (!pages) return <p>Loading…</p>;
  return (
    <ul>
      {pages.map((p) => (
        <li key={p.id}>
          <button type="button" onClick={() => onPick(p.slug)}>
            {p.title} · {p.duration_minutes} min
          </button>
        </li>
      ))}
    </ul>
  );
}
```

`list()` returns every page on the account, inactive and private ones included, so filter before showing it to guests.

## A minimal custom flow

All three hooks together, unstyled, in one component:

```tsx title="components/minimal-booking.tsx"
'use client';

import { useState, type FormEvent } from 'react';
import { useAvailableSlots, useBookingPage, useCreateBooking, type TimeSlot } from '@clndr-pro/react';

/** `YYYY-MM-DD` from <input type="date"> → a Date at local midnight. */
function parseLocalDate(value: string) {
  const [y, m, d] = value.split('-').map(Number);
  return new Date(y, m - 1, d);
}

export function MinimalBooking({ slug }: { slug: string }) {
  const { data: page, error: pageError } = useBookingPage(slug);
  const [day, setDay] = useState('');
  const date = day ? parseLocalDate(day) : null;
  const { slots, isLoading: loadingSlots } = useAvailableSlots(slug, date);
  const [slot, setSlot] = useState<TimeSlot | null>(null);
  const { create, data: booking, error, isLoading } = useCreateBooking();

  if (pageError) return <p>{pageError.message}</p>;
  if (!page) return <p>Loading…</p>;
  if (booking) return <p>{booking.status === 'pending' ? 'Request sent.' : 'Booked!'} Check your inbox.</p>;

  async function book(e: FormEvent<HTMLFormElement>) {
    e.preventDefault();
    if (!slot || !page) return;
    const form = new FormData(e.currentTarget);
    await create({
      bookingPageId: page.bookingPage.id,
      guestName: String(form.get('name')),
      guestEmail: String(form.get('email')),
      startTime: slot.start,
      endTime: slot.end,
    }).catch(() => {}); // the hook's `error` has the message
  }

  return (
    <div>
      <h2>{page.bookingPage.title}</h2>
      <input type="date" value={day} onChange={(e) => { setDay(e.target.value); setSlot(null); }} />
      {loadingSlots ? <p>Loading times…</p> : null}
      <div>
        {slots.map((s) => (
          <button key={s.start} type="button" aria-pressed={slot?.start === s.start} onClick={() => setSlot(s)}>
            {new Date(s.start).toLocaleTimeString([], { hour: 'numeric', minute: '2-digit' })}
          </button>
        ))}
      </div>
      {slot ? (
        <form onSubmit={book}>
          <input name="name" placeholder="Name" required />
          <input name="email" type="email" placeholder="Email" required />
          <button disabled={isLoading}>{isLoading ? 'Booking…' : 'Book'}</button>
          {error ? <p role="alert">{error.message}</p> : null}
        </form>
      ) : null}
    </div>
  );
}
```

It skips the host's questions and doesn't refetch a taken slot; the [shadcn booking widget](/tutorials/shadcn-booking-widget) tutorial handles both and adds a calendar.

## A slot someone else just took

Two guests can pick the same time. The second `create` fails with a `ClndrError` with status `409`. With a publishable key (the usual case in the browser) the message is usually "This time slot is not available. Fetch the slots again and pick another.", because the API checks the slot is still open before booking; "This time slot is no longer available. Please pick another." means both requests passed that check at the same moment. Every other failure is a `ClndrError` too, with the API's message:

```ts
import { ClndrError } from '@clndr-pro/react';

function isSlotTaken(err: unknown) {
  return err instanceof ClndrError && (err.status === 409 || /no longer available|not available/i.test(err.message));
}
```

| `err.status` | Likely cause |
| --- | --- |
| `400` | A missing field, a bad email address, or a timestamp that doesn't parse |
| `409` | Slot taken, or not an open slot (message above) |
| `401` | Missing or revoked key, or requests going to `https://clndr.pro` instead of `www` |
| `403` | The page isn't on this key's account |
| `429` | The key's rate limit, or the guest's email used its 5 booking attempts this clock hour; `err.data` has the message, the `Retry-After` header isn't exposed |

After a taken slot, clear the picked slot and ask for a fresh list with `refetch()`:

```tsx
const { slots, refetch } = useAvailableSlots(slug, date);

// in the submit handler's catch:
if (isSlotTaken(err)) {
  setSlot(null);
  refetch();
}
```

`ClndrError` has `message`, `status` (the HTTP status) and `data` (the parsed response body, `{ error: string }`). [Errors and rate limits](/errors) lists every message the API sends.

---

# Styling and slots

`BookingForm`, `BookingInline` and `BookingModal` ship plain HTML with a `clndr-*` class on every part and no CSS at all. Two props change that:

- `components` swaps the elements themselves: your `Button`, `Input`, `Label`.
- `classNames` swaps the class on each part.

Use both with a component library, `classNames` alone with Tailwind, or neither and write CSS against the default classes.

## Slots: the components prop

| Slot | Default | Renders |
| --- | --- | --- |
| `Root` | `<div>` | The outer wrapper, in every state |
| `Card` | `<div>` | The details form, and the success message |
| `Heading` | `<h2>` | The page title, and the success heading |
| `Muted` | `<div>` | Host and duration, the picked time, loading and empty messages |
| `Error` | `<div>` | Load and booking errors |
| `Button` | `<button>` | Every button: time slots, **Back** and **Confirm** |
| `Input` | `<input>` | The date input, name, email, and `text` / `email` / `phone` questions |
| `Textarea` | `<textarea>` | `textarea` questions |
| `Select` | `<select>` | `select` questions, with the options as `<option>` children. 0.2.1+ |
| `Label` | `<label>` | Every field label |
| `MarkdownRenderer` | Lazy-loaded `react-markdown` | The page description. Gets `{ content, className }`. |

Each slot receives the native props for its element (`className`, `onClick`, `value`, `htmlFor`, …), so any component that forwards them works. The checkbox for `checkbox` questions is always a native `<input type="checkbox">`: design-system `Input`s are text fields.

One `Button` slot covers three kinds of button, told apart only by class. To make time slots outlined while **Confirm** stays solid, give them different `classNames` (below) rather than different components.

## Class names: the classNames prop

A class you pass **replaces** the default for that part; it isn't appended. Pass `input: 'w-full'` and the `clndr-input` class is gone from inputs.

| Key | Default | On |
| --- | --- | --- |
| `root` | `clndr-root` | `Root` |
| `heading` | `clndr-heading` | `Heading` |
| `muted` | `clndr-muted` | `Muted` |
| `error` | `clndr-error` | `Error` |
| `description` | `clndr-description` | The wrapper `MarkdownRenderer` draws |
| `label` | `clndr-label` | Every `Label` |
| `dateInput` | `clndr-date-input` | The date `Input` |
| `slotGrid` | `clndr-slot-grid` | The `<div>` around the time buttons |
| `slotButton` | `clndr-slot-btn` | Each time `Button` |
| `card` | `clndr-card` | `Card` |
| `input` | `clndr-input` | Name, email and question `Input`s |
| `textarea` | `clndr-textarea` | `Textarea` |
| `select` | same as `input` | `Select`. 0.2.1+ |
| `checkbox` | `clndr-checkbox` | Checkbox questions. 0.2.1+ |
| `buttonSecondary` | `clndr-btn clndr-btn-secondary` | **Back** |
| `buttonPrimary` | `clndr-btn clndr-btn-primary` | **Confirm** |

`slotButtonSelected` (`clndr-slot-btn--selected`) is in the type but nothing uses it yet: picking a time moves straight on to the form, so there's no selected state to draw. The row holding **Back** and **Confirm** has an inline `display: flex; gap: 8px` you can't override from `classNames`.

## shadcn/ui

With shadcn's `Button`, `Input`, `Label` and `Textarea`, the form matches the rest of a shadcn app, including dark mode:

```bash
npx shadcn@latest add button input label textarea
```

```tsx title="components/booking/shadcn-booking-form.tsx"
'use client';

import { BookingForm, type BookingFormProps } from '@clndr-pro/react';
import { Button } from '@/components/ui/button';
import { Input } from '@/components/ui/input';
import { Label } from '@/components/ui/label';
import { Textarea } from '@/components/ui/textarea';

/** The SDK's booking flow, drawn with your shadcn components. */
export function ShadcnBookingForm(props: Omit<BookingFormProps, 'components' | 'classNames'>) {
  return (
    <BookingForm
      {...props}
      components={{ Button, Input, Label, Textarea }}
      classNames={{
        root: 'space-y-5',
        heading: 'text-lg font-semibold',
        muted: 'text-sm text-muted-foreground',
        label: 'mb-2 block',
        dateInput: 'w-full',
        slotGrid: 'mt-4 grid grid-cols-3 gap-2',
        slotButton: 'bg-background text-foreground border hover:bg-accent hover:text-accent-foreground',
        card: 'space-y-4',
        buttonSecondary: 'bg-secondary text-secondary-foreground hover:bg-secondary/80',
        error: 'text-sm text-destructive',
        description: 'text-sm text-muted-foreground',
      }}
    />
  );
}
```

shadcn's `Button` renders its default (solid) variant here, because the slot can't pick a variant. The `slotButton` and `buttonSecondary` classes turn that into outline and secondary looks: shadcn merges class names with `tailwind-merge`, so `bg-background` wins over the variant's `bg-primary`. If your `Button` doesn't merge classes, wrap it instead: `Button: (props) => <Button variant="outline" {...props} />` makes every button outlined.

From 0.2.1 you can pass a `Select` slot too. shadcn's `Select` is a Radix component with a different API from `<select>` (`onValueChange`, no `<option>` children), so it doesn't fit the slot directly; a styled native select does. `classNames.select` takes `input`'s classes by default, which is usually what you want.

<Tip>
For a calendar, times grouped by day, or a layout these slots can't reach, drop down to the hooks: the [shadcn booking widget](/tutorials/shadcn-booking-widget) tutorial builds one with shadcn's `Calendar`.
</Tip>

## Plain CSS

Without Tailwind, keep the default classes and style them. This stylesheet gives a clean, neutral form; change the variables at the top to match your site:

```css title="styles/clndr.css"
.clndr-root {
  --clndr-fg: #18181b;
  --clndr-muted: #71717a;
  --clndr-border: #e4e4e7;
  --clndr-bg: #ffffff;
  --clndr-accent: #2563eb;
  --clndr-danger: #dc2626;
  --clndr-radius: 8px;

  display: grid;
  gap: 1.25rem;
  max-width: 36rem;
  color: var(--clndr-fg);
  font: inherit;
}

@media (prefers-color-scheme: dark) {
  .clndr-root {
    --clndr-fg: #fafafa;
    --clndr-muted: #a1a1aa;
    --clndr-border: #3f3f46;
    --clndr-bg: #18181b;
  }
}

.clndr-heading { margin: 0; font-size: 1.5rem; font-weight: 600; line-height: 1.25; }
.clndr-muted { color: var(--clndr-muted); font-size: 0.875rem; }
.clndr-error { color: var(--clndr-danger); font-size: 0.875rem; }
.clndr-description { font-size: 0.9375rem; line-height: 1.6; }
.clndr-description a { color: var(--clndr-accent); }

.clndr-label { display: block; margin-bottom: 0.375rem; font-size: 0.875rem; font-weight: 500; }

.clndr-input,
.clndr-textarea,
.clndr-date-input {
  box-sizing: border-box;
  width: 100%;
  padding: 0.5rem 0.75rem;
  border: 1px solid var(--clndr-border);
  border-radius: var(--clndr-radius);
  background: var(--clndr-bg);
  color: inherit;
  font: inherit;
}
.clndr-textarea { min-height: 6rem; resize: vertical; }

.clndr-input:focus-visible,
.clndr-textarea:focus-visible,
.clndr-date-input:focus-visible,
.clndr-btn:focus-visible,
.clndr-slot-btn:focus-visible {
  outline: 2px solid var(--clndr-accent);
  outline-offset: 2px;
}

.clndr-slot-grid {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(6rem, 1fr));
  gap: 0.5rem;
  margin-top: 1rem;
}

.clndr-slot-btn {
  padding: 0.5rem;
  border: 1px solid var(--clndr-border);
  border-radius: var(--clndr-radius);
  background: var(--clndr-bg);
  color: inherit;
  font: inherit;
  cursor: pointer;
}
.clndr-slot-btn:hover { border-color: var(--clndr-accent); color: var(--clndr-accent); }

.clndr-card {
  display: grid;
  gap: 1rem;
  padding: 1.25rem;
  border: 1px solid var(--clndr-border);
  border-radius: calc(var(--clndr-radius) + 4px);
}

.clndr-btn {
  padding: 0.625rem 1rem;
  border: 1px solid transparent;
  border-radius: var(--clndr-radius);
  font: inherit;
  font-weight: 600;
  cursor: pointer;
}
.clndr-btn-primary { flex: 1; background: var(--clndr-accent); color: #fff; }
.clndr-btn-secondary { background: transparent; border-color: var(--clndr-border); color: inherit; }
.clndr-btn:disabled { opacity: 0.6; cursor: progress; }

.clndr-checkbox { width: 1rem; height: 1rem; accent-color: var(--clndr-accent); }
```

Import it once (`import './clndr.css'` in a client component, or from your global stylesheet) and render the form with no `classNames` at all.

## The description

Hosts write booking page descriptions in Markdown, and the form renders them: headings, lists, links (opened in a new tab), tables, code. The renderer, `react-markdown` with `remark-gfm`, loads in its own chunk the first time a description appears, so pages without one never download it.

Its elements carry shadcn/Tailwind classes (`text-primary`, `bg-muted`, `border-border`, `text-muted-foreground`), so they pick up a shadcn theme. Two catches:

- **Tailwind only generates classes it finds in your source**, and it skips `node_modules`. Unless your own code uses the same utilities, tell Tailwind to scan the package. In Tailwind v4, add this to the CSS file that imports Tailwind:

  ```css title="app/globals.css"
  @source "../node_modules/@clndr-pro/react/dist";
  ```

  In Tailwind v3, add `'./node_modules/@clndr-pro/react/dist/**/*.{js,mjs}'` to `content`.
- **Without Tailwind** the classes do nothing and the description renders as plain HTML; style it through `.clndr-description` like the stylesheet above.

To use your own renderer (MDX, a `prose` component you already have), pass `MarkdownRenderer`. Yours is bundled normally and the built-in chunk is never requested:

```tsx title="components/booking/booking-with-markdown.tsx"
'use client';

import Markdown from 'react-markdown';
import { BookingInline } from '@clndr-pro/react';

export function WithOwnMarkdown() {
  return (
    <BookingInline
      slug="intro-call"
      components={{
        MarkdownRenderer: ({ content, className }) => (
          <div className={className}>
            <Markdown>{content}</Markdown>
          </div>
        ),
      }}
      classNames={{ description: 'prose prose-sm dark:prose-invert max-w-none' }}
    />
  );
}
```

The `prose` classes come from `@tailwindcss/typography`. Without the plugin, use your own typography classes.

## Dark mode

The form has no colours of its own, so it follows whatever you give it: shadcn components and tokens switch with your `.dark` class, and the plain-CSS example switches on `prefers-color-scheme` (swap that media query for your own dark selector if you have a toggle). The exception is `BookingModal`'s built-in white panel; pass `contentClassName` and `overlayClassName` to restyle it, or [use your own dialog](/tutorials/shadcn-booking-dialog).

---

# shadcn booking widget

`BookingInline` is one fixed flow: a date input, a list of times, a form. This tutorial builds the version you'd design yourself, with shadcn/ui: a month calendar beside the open times, times grouped under the guest's own dates, every question type drawn with the right shadcn input, skeletons while things load, and a recovery path when someone books the slot first.

It uses the [hooks](/react/hooks) for data and nothing else from the SDK, so every pixel is yours to change. The finished files are at the [end of the page](#the-finished-files).

<Prompt title="Build a custom shadcn booking widget">

```text
Build a custom clndr.pro booking widget in this project with shadcn/ui, following https://docs.clndr.pro/tutorials/shadcn-booking-widget.md (read it first, and https://docs.clndr.pro/react/hooks.md for the hook details).

- Use the hooks from @clndr-pro/react 0.2.1+ (useBookingPage, useAvailableSlots, useCreateBooking) inside 'use client' files. If there's no ClndrProvider yet, set one up as in https://docs.clndr.pro/nextjs.md.
- Add whichever of these shadcn components the project doesn't have: calendar button card input label textarea skeleton alert select checkbox. Install react-markdown for the page description.
- Match this project's existing styling and components where they differ from stock shadcn.
- Build the Date for useAvailableSlots from local parts (a date picker's Date is fine; never new Date('YYYY-MM-DD')). Show times in the guest's timezone, grouped by the guest's local date.
- Render every question type (text, email, phone, textarea, select, checkbox) and check required answers before submitting.
- When a booking fails because the slot was taken (HTTP 409), call refetch() from useAvailableSlots and tell the guest.
- Ask me for the booking page slug and where the widget should go. Run the type checker and the build when you're done.
```

</Prompt>

## Before you start

You need a Next.js app with shadcn/ui and a [`ClndrProvider`](/nextjs#the-browser-side) holding your publishable key, and `@clndr-pro/react` 0.2.1 or later: earlier versions ask for the wrong day for many timezones. Add the shadcn components this widget uses, and `react-markdown` for the booking page's description:

```bash
npx shadcn@latest add calendar button card input label textarea skeleton alert select checkbox
npm install react-markdown
```

<Steps>
<Step title="Load the page">

`useBookingPage` returns the page, its host and its questions. Until the page arrives there's no data and no error; show skeletons then, and an error only when `pageError` is set.

```tsx
const { data: page, error: pageError } = useBookingPage(slug);

if (!page) {
  return pageError ? (
    <Alert variant="destructive">
      <AlertTitle>This booking page isn't available</AlertTitle>
      <AlertDescription>{pageError.message}</AlertDescription>
    </Alert>
  ) : (
    <Card>{/* skeletons */}</Card>
  );
}
```

The description is Markdown written by the host, so render it with `react-markdown`. The arbitrary-variant classes (`[&_ul]:list-disc`) style the generated lists and links without the typography plugin.

</Step>
<Step title="Pick a day">

shadcn's `Calendar` (react-day-picker) hands you a `Date` at local midnight, which is exactly what `useAvailableSlots` wants. Disable days before today and after the page's booking window:

```tsx
const today = startOfToday();
const lastDay = bookingPage.max_days_ahead ? addDays(today, bookingPage.max_days_ahead) : undefined;

<Calendar
  mode="single"
  selected={date}
  onSelect={(day) => {
    setDate(day);
    setSlot(null);
    setNotice(null);
  }}
  disabled={lastDay ? [{ before: today }, { after: lastDay }] : { before: today }}
  className="rounded-md border"
/>
```

`date` lives in state. The hook compares the day's timestamp, so it fetches again only when the guest picks a different day.

</Step>
<Step title="Show the open times">

`useAvailableSlots` is called once, at the top of the widget, so the list survives while the guest fills in the form ("Change" goes straight back to it) and the submit handler can call its `refetch()` after a failed booking. A small `SlotPicker` component only draws what it returns:

```tsx
const { slots, status: slotsStatus, error: slotsError, refetch: refetchSlots } = useAvailableSlots(slug, date ?? null);

<SlotPicker slots={slots} status={slotsStatus} error={slotsError} onPick={setSlot} />
```

The API returns the **host's** day, as UTC timestamps. Format them with the guest's locale and timezone, and group by the guest's date: when host and guest are hours apart, a host's Tuesday can start on the guest's Monday evening.

```tsx
const days = useMemo(() => {
  const byDay = new Map<string, TimeSlot[]>();
  for (const slot of slots) {
    const day = dayFormat.format(new Date(slot.start));
    byDay.set(day, [...(byDay.get(day) ?? []), slot]);
  }
  return [...byDay];
}, [slots]);
```

Show the skeleton for anything but `status === 'success'`, which also covers the moment between picking a day and the request starting. An empty list means the host has no free time that day, so say so.

</Step>
<Step title="Ask the host's questions">

Each question has a `question_type`. `QuestionField` maps them to shadcn inputs: `textarea` to `Textarea`, `select` to `Select` with the question's `options`, `checkbox` to `Checkbox` with the answer `"Yes"` or `"No"`, `phone` to a `tel` input, the rest to `Input`.

The API doesn't enforce `is_required`, so the widget checks before submitting:

```tsx
function isAnswered(question: BookingQuestion, value: string | undefined) {
  if (question.question_type === 'checkbox') return value === 'Yes';
  return !!value?.trim();
}

const missing = questions.filter((q) => q.is_required && !isAnswered(q, answers[q.id]));
```

Send only answered questions, as `{ questionId, answer }` pairs. An unknown `questionId` makes the API drop every answer for that booking, so never send ids from another page.

</Step>
<Step title="Book, and recover from a taken slot">

`create` from `useCreateBooking` posts the booking. Pass the slot's `start` and `end` unchanged. If two guests pick the same time, the second gets an HTTP 409: with a publishable key the message is usually "This time slot is not available. Fetch the slots again and pick another." (the check also matches the message text). The widget clears the picked slot, calls `refetchSlots()`, and tells the guest:

```tsx
try {
  await create({
    bookingPageId: bookingPage.id,
    guestName: name,
    guestEmail: email,
    startTime: slot.start,
    endTime: slot.end,
    responses: Object.entries(answers)
      .filter(([, answer]) => answer.trim() !== '')
      .map(([questionId, answer]) => ({ questionId, answer })),
  });
} catch (err) {
  if (isSlotTaken(err)) {
    setSlot(null);
    refetchSlots();
    setNotice('Someone booked that time a moment ago. Pick another one.');
  }
}
```

Other errors (the guest's email used its 5 booking attempts this clock hour, the page was switched off) land on the hook's `error`, and the form shows the API's message.

</Step>
<Step title="Say what happened">

The booking that comes back has `status: 'confirmed'` on *direct* pages and `'pending'` on *approval* pages. Those need different words: a pending guest has not got a meeting yet, and clndr.pro won't email them until the host approves.

```tsx
<CardTitle>{booking.status === 'pending' ? 'Request sent' : "You're booked"}</CardTitle>
```

Direct pages with Meet links turned on return the link straight away in `google_meet_link`.

</Step>
<Step title="Put it on a page">

```tsx title="app/book/page.tsx"
import { BookingWidget } from '@/components/booking/booking-widget';

export const metadata = { title: 'Book a call' };

export default function BookPage() {
  return (
    <main className="mx-auto max-w-4xl px-4 py-12">
      <BookingWidget slug="intro-call" />
    </main>
  );
}
```

The page stays a Server Component; `BookingWidget` is the client boundary.

</Step>
</Steps>

## The finished files

```tsx title="components/booking/booking-widget.tsx"
'use client';

import { useMemo, useState, type FormEvent } from 'react';
import Markdown from 'react-markdown';
import {
  ClndrError,
  useAvailableSlots,
  useBookingPage,
  useCreateBooking,
  type BookingQuestion,
  type TimeSlot,
} from '@clndr-pro/react';
import { Alert, AlertDescription, AlertTitle } from '@/components/ui/alert';
import { Button } from '@/components/ui/button';
import { Calendar } from '@/components/ui/calendar';
import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
import { Input } from '@/components/ui/input';
import { Label } from '@/components/ui/label';
import { Skeleton } from '@/components/ui/skeleton';
import { QuestionField } from './question-field';

const timeFormat = new Intl.DateTimeFormat(undefined, { hour: 'numeric', minute: '2-digit' });
const dayFormat = new Intl.DateTimeFormat(undefined, { weekday: 'long', month: 'long', day: 'numeric' });

function startOfToday() {
  const now = new Date();
  return new Date(now.getFullYear(), now.getMonth(), now.getDate());
}

function addDays(date: Date, days: number) {
  return new Date(date.getFullYear(), date.getMonth(), date.getDate() + days);
}

/** Someone else booked the slot between fetching and submitting. */
function isSlotTaken(err: unknown) {
  return err instanceof ClndrError && (err.status === 409 || /no longer available|not available/i.test(err.message));
}

function isAnswered(question: BookingQuestion, value: string | undefined) {
  if (question.question_type === 'checkbox') return value === 'Yes';
  return !!value?.trim();
}

export function BookingWidget({ slug }: { slug: string }) {
  const { data: page, error: pageError } = useBookingPage(slug);
  const { create, data: booking, error: createError, isLoading: submitting } = useCreateBooking();

  const [date, setDate] = useState<Date | undefined>();
  // Called here, not inside SlotPicker, so the list survives while the guest
  // fills in the form and submit() can refetch it after a taken slot.
  const { slots, status: slotsStatus, error: slotsError, refetch: refetchSlots } = useAvailableSlots(slug, date ?? null);
  const [slot, setSlot] = useState<TimeSlot | null>(null);
  const [name, setName] = useState('');
  const [email, setEmail] = useState('');
  const [answers, setAnswers] = useState<Record<string, string>>({});
  const [notice, setNotice] = useState<string | null>(null);

  // No page and no error yet: still loading.
  if (!page) {
    return pageError ? (
      <Alert variant="destructive">
        <AlertTitle>This booking page isn't available</AlertTitle>
        <AlertDescription>{pageError.message}</AlertDescription>
      </Alert>
    ) : (
      <Card>
        <CardHeader className="gap-3">
          <Skeleton className="h-6 w-48" />
          <Skeleton className="h-4 w-32" />
        </CardHeader>
        <CardContent>
          <Skeleton className="h-72 w-full" />
        </CardContent>
      </Card>
    );
  }

  const { bookingPage, userProfile, questions } = page;
  const host = userProfile.full_name ?? userProfile.username;

  if (booking) {
    const start = new Date(booking.start_time);
    return (
      <Card>
        <CardHeader>
          <CardTitle>{booking.status === 'pending' ? 'Request sent' : "You're booked"}</CardTitle>
          <CardDescription>
            {bookingPage.title} with {host}, {dayFormat.format(start)} at {timeFormat.format(start)}.
          </CardDescription>
        </CardHeader>
        <CardContent className="text-sm text-muted-foreground">
          {booking.status === 'pending'
            ? `${host} confirms requests by hand. You'll get an email at ${booking.guest_email} once it's approved.`
            : `A confirmation is on its way to ${booking.guest_email}.`}
          {booking.google_meet_link ? (
            <p className="mt-3">
              <a className="font-medium text-foreground underline underline-offset-4" href={booking.google_meet_link}>
                Join with Google Meet
              </a>
            </p>
          ) : null}
        </CardContent>
      </Card>
    );
  }

  const today = startOfToday();
  const lastDay = bookingPage.max_days_ahead ? addDays(today, bookingPage.max_days_ahead) : undefined;

  async function submit(e: FormEvent) {
    e.preventDefault();
    if (!slot) return;
    const missing = questions.filter((q) => q.is_required && !isAnswered(q, answers[q.id]));
    if (missing.length > 0) {
      setNotice(`Please answer: ${missing.map((q) => q.question_text).join(', ')}`);
      return;
    }
    setNotice(null);
    try {
      await create({
        bookingPageId: bookingPage.id,
        guestName: name,
        guestEmail: email,
        startTime: slot.start,
        endTime: slot.end,
        responses: Object.entries(answers)
          .filter(([, answer]) => answer.trim() !== '')
          .map(([questionId, answer]) => ({ questionId, answer })),
      });
    } catch (err) {
      if (isSlotTaken(err)) {
        setSlot(null);
        refetchSlots();
        setNotice('Someone booked that time a moment ago. Pick another one.');
      }
      // Anything else is on `createError` and shown below the form.
    }
  }

  return (
    <Card>
      <CardHeader>
        <CardTitle className="text-xl">{bookingPage.title}</CardTitle>
        <CardDescription>
          {host} · {bookingPage.duration_minutes} min
        </CardDescription>
        {bookingPage.description ? (
          <div className="mt-2 space-y-2 text-sm text-muted-foreground [&_a]:underline [&_ol]:list-decimal [&_ol]:pl-5 [&_strong]:text-foreground [&_ul]:list-disc [&_ul]:pl-5">
            <Markdown>{bookingPage.description}</Markdown>
          </div>
        ) : null}
      </CardHeader>

      <CardContent className="grid gap-6 md:grid-cols-[auto_1fr]">
        <Calendar
          mode="single"
          selected={date}
          onSelect={(day) => {
            setDate(day);
            setSlot(null);
            setNotice(null);
          }}
          disabled={lastDay ? [{ before: today }, { after: lastDay }] : { before: today }}
          className="rounded-md border"
        />

        <div className="min-w-0">
          {notice ? (
            <Alert className="mb-4">
              <AlertDescription>{notice}</AlertDescription>
            </Alert>
          ) : null}

          {!date ? (
            <p className="text-sm text-muted-foreground">Pick a day to see open times.</p>
          ) : !slot ? (
            <SlotPicker slots={slots} status={slotsStatus} error={slotsError} onPick={setSlot} />
          ) : (
            <form onSubmit={submit} className="grid gap-4">
              <div className="flex items-center justify-between gap-2 rounded-md border px-3 py-2 text-sm">
                <span>
                  {dayFormat.format(new Date(slot.start))}, {timeFormat.format(new Date(slot.start))}
                </span>
                <Button type="button" variant="ghost" size="sm" onClick={() => setSlot(null)}>
                  Change
                </Button>
              </div>

              <div className="grid gap-2">
                <Label htmlFor="guest-name">Name</Label>
                <Input id="guest-name" required autoComplete="name" value={name} onChange={(e) => setName(e.target.value)} />
              </div>
              <div className="grid gap-2">
                <Label htmlFor="guest-email">Email</Label>
                <Input
                  id="guest-email"
                  type="email"
                  required
                  autoComplete="email"
                  value={email}
                  onChange={(e) => setEmail(e.target.value)}
                />
              </div>

              {questions.map((question) => (
                <QuestionField
                  key={question.id}
                  question={question}
                  value={answers[question.id] ?? ''}
                  onChange={(value) => setAnswers((a) => ({ ...a, [question.id]: value }))}
                />
              ))}

              {createError && !isSlotTaken(createError) ? (
                <Alert variant="destructive">
                  <AlertTitle>Couldn't book that</AlertTitle>
                  <AlertDescription>{createError.message}</AlertDescription>
                </Alert>
              ) : null}

              <Button type="submit" disabled={submitting}>
                {submitting ? 'Booking…' : bookingPage.booking_type === 'approval' ? 'Request this time' : 'Book'}
              </Button>
            </form>
          )}
        </div>
      </CardContent>
    </Card>
  );
}

/**
 * Open times for one day, grouped by the guest's own calendar date. The day
 * the API returns is the host's day, so near midnight some slots can fall on
 * the guest's previous or next date.
 */
function SlotPicker({
  slots,
  status,
  error,
  onPick,
}: {
  slots: TimeSlot[];
  status: 'idle' | 'loading' | 'success' | 'error';
  error: Error | null;
  onPick: (slot: TimeSlot) => void;
}) {
  const timeZone = useMemo(() => Intl.DateTimeFormat().resolvedOptions().timeZone, []);

  const days = useMemo(() => {
    const byDay = new Map<string, TimeSlot[]>();
    for (const slot of slots) {
      const day = dayFormat.format(new Date(slot.start));
      byDay.set(day, [...(byDay.get(day) ?? []), slot]);
    }
    return [...byDay];
  }, [slots]);

  if (status === 'error') {
    return (
      <Alert variant="destructive">
        <AlertTitle>Couldn't load times</AlertTitle>
        <AlertDescription>{error?.message}</AlertDescription>
      </Alert>
    );
  }

  if (status !== 'success') {
    return (
      <div className="grid grid-cols-3 gap-2">
        {Array.from({ length: 9 }, (_, i) => (
          <Skeleton key={i} className="h-9" />
        ))}
      </div>
    );
  }

  if (days.length === 0) {
    return <p className="text-sm text-muted-foreground">No open times that day. Try another one.</p>;
  }

  return (
    <div className="grid gap-4">
      {days.map(([day, daySlots]) => (
        <section key={day} className="grid gap-2">
          <h3 className="text-sm font-medium">{day}</h3>
          <div className="grid grid-cols-3 gap-2 sm:grid-cols-4">
            {daySlots.map((slot) => (
              <Button key={slot.start} variant="outline" onClick={() => onPick(slot)}>
                {timeFormat.format(new Date(slot.start))}
              </Button>
            ))}
          </div>
        </section>
      ))}
      <p className="text-xs text-muted-foreground">Times are in {timeZone.replace(/_/g, ' ')}.</p>
    </div>
  );
}
```

```tsx title="components/booking/question-field.tsx"
'use client';

import type { BookingQuestion } from '@clndr-pro/react';
import { Checkbox } from '@/components/ui/checkbox';
import { Input } from '@/components/ui/input';
import { Label } from '@/components/ui/label';
import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select';
import { Textarea } from '@/components/ui/textarea';

interface QuestionFieldProps {
  question: BookingQuestion;
  value: string;
  onChange: (value: string) => void;
}

/** One of the host's questions, rendered with the right shadcn input for its type. */
export function QuestionField({ question, value, onChange }: QuestionFieldProps) {
  const id = `question-${question.id}`;
  const label = (
    <Label htmlFor={id}>
      {question.question_text}
      {question.is_required ? <span className="text-muted-foreground"> *</span> : null}
    </Label>
  );

  switch (question.question_type) {
    case 'textarea':
      return (
        <div className="grid gap-2">
          {label}
          <Textarea id={id} value={value} onChange={(e) => onChange(e.target.value)} rows={4} />
        </div>
      );

    case 'select':
      return (
        <div className="grid gap-2">
          {label}
          <Select value={value} onValueChange={onChange}>
            <SelectTrigger id={id} className="w-full">
              <SelectValue placeholder="Choose one" />
            </SelectTrigger>
            <SelectContent>
              {(question.options ?? []).map((option) => (
                <SelectItem key={option} value={option}>
                  {option}
                </SelectItem>
              ))}
            </SelectContent>
          </Select>
        </div>
      );

    case 'checkbox':
      return (
        <div className="flex items-center gap-3">
          <Checkbox
            id={id}
            checked={value === 'Yes'}
            onCheckedChange={(checked) => onChange(checked === true ? 'Yes' : 'No')}
          />
          {label}
        </div>
      );

    default:
      return (
        <div className="grid gap-2">
          {label}
          <Input
            id={id}
            type={question.question_type === 'email' ? 'email' : question.question_type === 'phone' ? 'tel' : 'text'}
            autoComplete={question.question_type === 'phone' ? 'tel' : undefined}
            value={value}
            onChange={(e) => onChange(e.target.value)}
          />
        </div>
      );
  }
}
```

## Where to take it

- **Your copy.** Every string is in the component: the button says "Request this time" on approval pages and "Book" otherwise.
- **Prefill.** If guests are signed in to your site, initialise `name` and `email` from your user.
- **Several pages.** List them with `useClndr().bookingPages.list()` (filter on `is_active` and `visibility`) and pass the chosen slug in.
- **Keep guest data on your server.** Swap `useCreateBooking` for a [server action](/tutorials/server-actions) that books with your secret key; the rest of the widget stays as it is.

---

# Booking dialog with shadcn

A booking form doesn't need its own page. This tutorial puts a **Book a call** button in your site header: on a laptop it opens a shadcn `Dialog`, on a phone a bottom `Drawer`, and after the guest books it shows the confirmation for a couple of seconds and closes.

The form inside is the SDK's `BookingForm` drawn with your shadcn components, so there's no booking logic to write. If you built the [custom widget](/tutorials/shadcn-booking-widget), drop that in instead; the dialog part doesn't change.

<Prompt title="Add a Book a call dialog to my header">

```text
Add a "Book a call" button to this site's header that opens a clndr.pro booking form, following https://docs.clndr.pro/tutorials/shadcn-booking-dialog.md (read it first).

- Use @clndr-pro/react 0.2.1+ and BookingForm with this project's Button/Input/Label/Textarea components. If there's no ClndrProvider yet, add one as in https://docs.clndr.pro/nextjs.md.
- Desktop (min-width 768px): shadcn Dialog. Phones: shadcn Drawer. Add whichever of dialog, drawer, button, input, label, textarea the project is missing.
- Keep an accessible title and description on the dialog (visually hidden is fine).
- Close it 2.5 seconds after onBooked fires.
- Ask me for the booking page slug and the button label. Run the type checker and the build when you're done.
```

</Prompt>

## Before you start

You need shadcn/ui, a [`ClndrProvider`](/nextjs#the-browser-side) with your publishable key, and these components:

```bash
npx shadcn@latest add dialog drawer button input label textarea
```

<Steps>
<Step title="Draw the form with shadcn">

Wrap `BookingForm` once with your components and classes, so the dialog and the drawer render the same thing. [Styling and slots](/react/styling) explains each key.

```tsx title="components/booking/booking-form-shadcn.tsx"
'use client';

import { BookingForm, type BookingFormProps } from '@clndr-pro/react';
import { Button } from '@/components/ui/button';
import { Input } from '@/components/ui/input';
import { Label } from '@/components/ui/label';
import { Textarea } from '@/components/ui/textarea';

/** The SDK's booking flow, drawn with your shadcn components. */
export function ShadcnBookingForm(props: Omit<BookingFormProps, 'components' | 'classNames'>) {
  return (
    <BookingForm
      {...props}
      components={{ Button, Input, Label, Textarea }}
      classNames={{
        root: 'space-y-5',
        heading: 'text-lg font-semibold',
        muted: 'text-sm text-muted-foreground',
        label: 'mb-2 block',
        dateInput: 'w-full',
        slotGrid: 'mt-4 grid grid-cols-3 gap-2',
        slotButton: 'bg-background text-foreground border hover:bg-accent hover:text-accent-foreground',
        card: 'space-y-4',
        buttonSecondary: 'bg-secondary text-secondary-foreground hover:bg-secondary/80',
        error: 'text-sm text-destructive',
        description: 'text-sm text-muted-foreground',
      }}
    />
  );
}
```

</Step>
<Step title="Know when you're on a phone">

A dialog centred on a 390px screen leaves the date input and the keyboard fighting for space; a drawer from the bottom is the native pattern there. This hook reports whether a media query matches, and returns `false` on the server so the first render is stable:

```ts title="hooks/use-media-query.ts"
import { useSyncExternalStore } from 'react';

/** `true` while the media query matches. `false` during server rendering. */
export function useMediaQuery(query: string) {
  return useSyncExternalStore(
    (onChange) => {
      const list = window.matchMedia(query);
      list.addEventListener('change', onChange);
      return () => list.removeEventListener('change', onChange);
    },
    () => window.matchMedia(query).matches,
    () => false,
  );
}
```

</Step>
<Step title="The button, the dialog and the drawer">

```tsx title="components/booking/book-call-button.tsx"
'use client';

import { useState } from 'react';
import { Button } from '@/components/ui/button';
import {
  Dialog,
  DialogContent,
  DialogDescription,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from '@/components/ui/dialog';
import {
  Drawer,
  DrawerContent,
  DrawerDescription,
  DrawerHeader,
  DrawerTitle,
  DrawerTrigger,
} from '@/components/ui/drawer';
import { useMediaQuery } from '@/hooks/use-media-query';
import { ShadcnBookingForm } from './booking-form-shadcn';

export function BookCallButton({ slug, label = 'Book a call' }: { slug: string; label?: string }) {
  const [open, setOpen] = useState(false);
  const isDesktop = useMediaQuery('(min-width: 768px)');

  // Leave the confirmation on screen for a moment, then close.
  const onBooked = () => setTimeout(() => setOpen(false), 2500);

  if (isDesktop) {
    return (
      <Dialog open={open} onOpenChange={setOpen}>
        <DialogTrigger asChild>
          <Button>{label}</Button>
        </DialogTrigger>
        <DialogContent className="max-h-[90dvh] overflow-y-auto sm:max-w-lg">
          <DialogHeader className="sr-only">
            <DialogTitle>{label}</DialogTitle>
            <DialogDescription>Pick a time that works for you.</DialogDescription>
          </DialogHeader>
          <ShadcnBookingForm slug={slug} onBooked={onBooked} />
        </DialogContent>
      </Dialog>
    );
  }

  return (
    <Drawer open={open} onOpenChange={setOpen}>
      <DrawerTrigger asChild>
        <Button>{label}</Button>
      </DrawerTrigger>
      <DrawerContent>
        <DrawerHeader className="sr-only">
          <DrawerTitle>{label}</DrawerTitle>
          <DrawerDescription>Pick a time that works for you.</DrawerDescription>
        </DrawerHeader>
        <div className="max-h-[80dvh] overflow-y-auto px-4 pb-6">
          <ShadcnBookingForm slug={slug} onBooked={onBooked} />
        </div>
      </DrawerContent>
    </Drawer>
  );
}
```

Things worth knowing about this component:

- **Radix needs a title.** `Dialog` and `Drawer` warn without a `DialogTitle` and `DialogDescription`. `BookingForm` already shows the page title as a heading, so the dialog's own header is `sr-only`: screen readers announce it, nobody sees it twice.
- **Closing resets the form.** shadcn's `DialogContent` and `DrawerContent` unmount when closed, so the next open starts at the date picker again. That also means the booking page is fetched again on each open.
- **The delay is for the guest.** `onBooked` fires as the success message appears. Closing at once would hide it; 2.5 seconds is long enough to read "Booking confirmed" or "Request sent".
- **Long forms scroll inside.** `max-h-[90dvh] overflow-y-auto` keeps the **Confirm** button reachable when a page asks several questions.

</Step>
<Step title="Put it in the header">

`BookCallButton` is a client component; your header can stay a Server Component and render it like any other element:

```tsx title="components/site/site-header.tsx"
import Link from 'next/link';
import { BookCallButton } from '@/components/booking/book-call-button';

export function SiteHeader() {
  return (
    <header className="sticky top-0 z-40 border-b bg-background/80 backdrop-blur">
      <div className="mx-auto flex h-14 max-w-5xl items-center justify-between px-4">
        <Link href="/" className="font-semibold">
          Acme Studio
        </Link>
        <nav className="flex items-center gap-4 text-sm">
          <Link href="/work">Work</Link>
          <Link href="/pricing">Pricing</Link>
          <BookCallButton slug="intro-call" />
        </nav>
      </div>
    </header>
  );
}
```

</Step>
</Steps>

## Variations

- **Several pages, one button.** Show a short list first (`useClndr().bookingPages.list()`, filtered on `is_active` and `visibility === 'public'`), then render the form for the chosen slug in the same dialog.
- **Prefill.** Pass `prefill={{ name, email }}` through `ShadcnBookingForm` when the visitor is signed in.
- **No shadcn Drawer.** Drop the `isDesktop` branch and keep the `Dialog`: on phones it still works, just less comfortably.
- **No design system at all.** `BookingModal` is the built-in version of this: a fixed overlay with Escape, outside-click and auto-close after booking. See [Components](/react/components#bookingmodal).

---

# Book through a server action

With `@clndr-pro/react`, the guest's browser calls clndr.pro directly with a publishable key. That's the fastest route, but your server never sees the booking happen. Route it through a server action instead and you get a place to:

- check a captcha or rate-limit by IP before anything reaches clndr.pro,
- write the lead to your CRM or database in the same request,
- keep every key off the client: the page below ships no clndr.pro key at all.

The trade: you render the slot picker yourself. This tutorial builds `/book` in a Next.js 15 or 16 App Router app with a day picker, a slot list, the host's questions and a confirmation screen. It assumes shadcn/ui and [zod](https://zod.dev):

```bash
npm install @clndr-pro/sdk server-only zod
npx shadcn@latest add button input label textarea
```

```bash title=".env.local"
CLNDR_SECRET_KEY=clndr_sk_...
```

```mermaid title="One booking, end to end"
sequenceDiagram
  participant G as Guest's browser
  participant N as Your Next.js server
  participant C as clndr.pro API
  G->>N: GET /book?date=2026-10-15
  N->>C: GET /booking-pages/intro-call, /slots?date=2026-10-15
  C-->>N: page, questions, open slots
  N-->>G: HTML with the slot list
  G->>N: submit form (server action)
  N->>N: validate, captcha, your own checks
  N->>C: GET /slots again (still open?)
  N->>C: POST /bookings (secret key)
  C-->>N: 201 booking
  N-->>G: confirmation screen
```

## The client

One module owns the key. `server-only` makes any import of it from a client component a build error.

```ts title="lib/clndr.ts"
import 'server-only';
import { Clndr } from '@clndr-pro/sdk';

export const clndr = new Clndr(process.env.CLNDR_SECRET_KEY!);

/** The booking page this site books into. */
export const BOOKING_SLUG = 'intro-call';
```

## The page

A Server Component loads the booking page and the slots for the day in `?date=`. Days are calendar days in the host's timezone, because that's how the slots endpoint reads `date`.

```tsx title="app/book/page.tsx"
import Link from 'next/link';
import { clndr, BOOKING_SLUG } from '@/lib/clndr';
import { BookingForm } from './booking-form';

export const metadata = { title: 'Book a call' };

/** YYYY-MM-DD for `date` as seen in `timeZone`. */
function dayIn(timeZone: string, date = new Date()) {
  return new Intl.DateTimeFormat('en-CA', { timeZone, year: 'numeric', month: '2-digit', day: '2-digit' }).format(date);
}

function addDays(ymd: string, n: number) {
  const [y, m, d] = ymd.split('-').map(Number);
  return new Date(Date.UTC(y, m - 1, d + n)).toISOString().slice(0, 10);
}

function dayLabel(ymd: string) {
  return new Date(`${ymd}T12:00:00Z`).toLocaleDateString('en-US', {
    weekday: 'short',
    month: 'short',
    day: 'numeric',
    timeZone: 'UTC',
  });
}

export default async function BookPage({ searchParams }: { searchParams: Promise<{ date?: string }> }) {
  const { bookingPage, userProfile, questions } = await clndr.bookingPages.get(BOOKING_SLUG);

  const today = dayIn(userProfile.timezone ?? 'UTC');
  const horizon = Math.min(bookingPage.max_days_ahead || 14, 14);
  const days = Array.from({ length: horizon }, (_, i) => addDays(today, i));

  const { date: requested } = await searchParams;
  const date = requested && days.includes(requested) ? requested : days[0];
  const slots = await clndr.bookingPages.getSlots(BOOKING_SLUG, date);

  return (
    <main className="mx-auto max-w-2xl space-y-8 px-4 py-12">
      <header className="space-y-1">
        <h1 className="text-2xl font-semibold">{bookingPage.title}</h1>
        <p className="text-sm text-muted-foreground">
          {userProfile.full_name ?? userProfile.username} · {bookingPage.duration_minutes} min
        </p>
      </header>

      <nav aria-label="Pick a day" className="flex gap-2 overflow-x-auto pb-1">
        {days.map((d) => (
          <Link
            key={d}
            href={`/book?date=${d}`}
            scroll={false}
            aria-current={d === date ? 'date' : undefined}
            className="shrink-0 rounded-md border px-3 py-2 text-sm aria-[current=date]:border-primary aria-[current=date]:font-medium"
          >
            {dayLabel(d)}
          </Link>
        ))}
      </nav>

      {/* key: a new day remounts the form, clearing the picked slot */}
      <BookingForm key={date} date={date} slots={slots} questions={questions} />
    </main>
  );
}
```

`max_days_ahead` caps the strip, and slots that already started on `today` aren't returned, so the first pill can legitimately be empty in the evening.

## The action

The action validates the form, re-checks that the slot is still open (someone may have taken it while the guest typed), and books. Errors come back as state for the form to show.

```ts title="app/book/actions.ts"
'use server';

import { revalidatePath } from 'next/cache';
import { z } from 'zod';
import { ClndrError } from '@clndr-pro/sdk';
import { clndr, BOOKING_SLUG } from '@/lib/clndr';

export type BookingState =
  | { status: 'idle' }
  | { status: 'error'; message?: string; fieldErrors?: Record<string, string>; values?: Record<string, string> }
  | { status: 'success'; bookingType: 'direct' | 'approval'; startTime: string; guestEmail: string };

const schema = z.object({
  date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
  slot: z.string().regex(/^[^|]+\|[^|]+$/, 'Pick a time.'),
  guestName: z.string().trim().min(1, 'Enter your name.').max(120),
  guestEmail: z.string().trim().email('Enter a valid email address.'),
});

const TAKEN = 'That time was just taken. Pick another one.';

export async function bookSlot(_prev: BookingState, formData: FormData): Promise<BookingState> {
  const values = Object.fromEntries(
    [...formData.entries()].filter((e): e is [string, string] => typeof e[1] === 'string'),
  );

  const parsed = schema.safeParse(values);
  if (!parsed.success) {
    const fieldErrors: Record<string, string> = {};
    for (const issue of parsed.error.issues) fieldErrors[String(issue.path[0])] ??= issue.message;
    return { status: 'error', fieldErrors, values };
  }
  const { date, slot, guestName, guestEmail } = parsed.data;
  const [startTime, endTime] = slot.split('|');

  // Your own gate goes here: verify a Turnstile/hCaptcha token, rate-limit by
  // IP (headers().get('x-forwarded-for')) with Upstash or your database,
  // reject disposable email domains, …

  const { bookingPage, questions } = await clndr.bookingPages.get(BOOKING_SLUG);

  // The API doesn't enforce required questions, so this form does.
  const responses: { questionId: string; answer: string }[] = [];
  const fieldErrors: Record<string, string> = {};
  for (const q of questions) {
    const raw = formData.get(`q:${q.id}`);
    const answer = q.question_type === 'checkbox' ? (raw ? 'Yes' : '') : typeof raw === 'string' ? raw.trim() : '';
    if (answer) responses.push({ questionId: q.id, answer });
    else if (q.is_required) fieldErrors[`q:${q.id}`] = 'This one is required.';
  }
  if (Object.keys(fieldErrors).length) return { status: 'error', fieldErrors, values };

  // Still open? Compare instants, not strings.
  const open = await clndr.bookingPages.getSlots(BOOKING_SLUG, date);
  const stillOpen = open.some(
    (s) => Date.parse(s.start) === Date.parse(startTime) && Date.parse(s.end) === Date.parse(endTime),
  );
  if (!stillOpen) return { status: 'error', message: TAKEN, values };

  try {
    await clndr.bookings.create({
      bookingPageId: bookingPage.id,
      guestName,
      guestEmail,
      startTime,
      endTime,
      responses,
    });
  } catch (err) {
    if (err instanceof ClndrError) {
      if (err.message.startsWith('This time slot')) return { status: 'error', message: TAKEN, values };
      if (err.status === 429 || err.message.startsWith('Too many')) {
        return { status: 'error', message: 'Too many booking attempts from this email. Try again after the top of the hour.', values };
      }
      console.error('clndr.pro booking failed', err.status, err.message);
    } else {
      console.error('clndr.pro booking failed', err);
    }
    return { status: 'error', message: "We couldn't book that time. Please try again.", values };
  }

  // Booked. Write the lead to your CRM here if you keep one.
  revalidatePath('/book');
  return { status: 'success', bookingType: bookingPage.booking_type, startTime, guestEmail };
}
```

The two `startsWith` checks match the API's messages for a taken slot and for a guest email over its hourly limit. [Errors and rate limits](/errors) lists them all.

## The form

A client component renders slots and questions, posts to the action with `useActionState`, and shows either the errors or the confirmation. Times are formatted in the guest's own timezone, which only the browser knows, so those labels skip hydration checks.

```tsx title="app/book/booking-form.tsx"
'use client';

import { useActionState } from 'react';
import type { BookingQuestion, TimeSlot } from '@clndr-pro/sdk';
import { Button } from '@/components/ui/button';
import { Input } from '@/components/ui/input';
import { Label } from '@/components/ui/label';
import { Textarea } from '@/components/ui/textarea';
import { bookSlot, type BookingState } from './actions';

const time = (iso: string) => new Date(iso).toLocaleTimeString([], { hour: 'numeric', minute: '2-digit' });
const when = (iso: string) =>
  new Date(iso).toLocaleString([], { weekday: 'long', month: 'long', day: 'numeric', hour: 'numeric', minute: '2-digit' });

export function BookingForm({ date, slots, questions }: { date: string; slots: TimeSlot[]; questions: BookingQuestion[] }) {
  const [state, action, pending] = useActionState<BookingState, FormData>(bookSlot, { status: 'idle' });

  if (state.status === 'success') {
    return (
      <div role="status" className="space-y-2 rounded-lg border p-6">
        <h2 className="text-lg font-semibold">
          {state.bookingType === 'approval' ? 'Request sent' : "You're booked"}
        </h2>
        <p className="text-sm text-muted-foreground" suppressHydrationWarning>
          {when(state.startTime)}.{' '}
          {state.bookingType === 'approval'
            ? `You'll get an email at ${state.guestEmail} once it's approved.`
            : `A confirmation is on its way to ${state.guestEmail}.`}
        </p>
      </div>
    );
  }

  const err = state.status === 'error' ? state : undefined;
  const value = (name: string) => err?.values?.[name];
  const fieldError = (name: string) => {
    const message = err?.fieldErrors?.[name];
    return message ? <p className="text-sm text-destructive">{message}</p> : null;
  };

  return (
    <form action={action} className="space-y-6">
      <input type="hidden" name="date" value={date} />

      <fieldset className="space-y-3">
        <legend className="text-sm font-medium">Time</legend>
        {slots.length === 0 ? (
          <p className="text-sm text-muted-foreground">No open times this day. Try another one.</p>
        ) : (
          <div className="grid grid-cols-3 gap-2 sm:grid-cols-4">
            {slots.map((s) => {
              const v = `${s.start}|${s.end}`;
              return (
                <label
                  key={s.start}
                  className="cursor-pointer rounded-md border px-3 py-2 text-center text-sm has-[:checked]:border-primary has-[:checked]:bg-primary has-[:checked]:text-primary-foreground has-[:focus-visible]:ring-2"
                >
                  <input type="radio" name="slot" value={v} defaultChecked={value('slot') === v} required className="sr-only" />
                  <span suppressHydrationWarning>{time(s.start)}</span>
                </label>
              );
            })}
          </div>
        )}
        {fieldError('slot')}
      </fieldset>

      <div className="grid gap-4 sm:grid-cols-2">
        <div className="space-y-2">
          <Label htmlFor="guestName">Name</Label>
          <Input id="guestName" name="guestName" autoComplete="name" defaultValue={value('guestName')} required />
          {fieldError('guestName')}
        </div>
        <div className="space-y-2">
          <Label htmlFor="guestEmail">Email</Label>
          <Input id="guestEmail" name="guestEmail" type="email" autoComplete="email" defaultValue={value('guestEmail')} required />
          {fieldError('guestEmail')}
        </div>
      </div>

      {questions.map((q) => {
        const name = `q:${q.id}`;
        const required = q.is_required ?? false;
        return (
          <div key={q.id} className="space-y-2">
            {q.question_type === 'checkbox' ? (
              <label className="flex items-center gap-2 text-sm">
                <input type="checkbox" name={name} defaultChecked={!!value(name)} required={required} />
                {q.question_text}
              </label>
            ) : (
              <>
                <Label htmlFor={name}>
                  {q.question_text}
                  {required ? ' *' : ''}
                </Label>
                {q.question_type === 'textarea' ? (
                  <Textarea id={name} name={name} defaultValue={value(name)} required={required} />
                ) : q.question_type === 'select' ? (
                  <select
                    id={name}
                    name={name}
                    defaultValue={value(name) ?? ''}
                    required={required}
                    className="h-9 w-full rounded-md border bg-transparent px-3 text-sm"
                  >
                    <option value="">Choose…</option>
                    {(q.options ?? []).map((o) => (
                      <option key={o} value={o}>
                        {o}
                      </option>
                    ))}
                  </select>
                ) : (
                  <Input
                    id={name}
                    name={name}
                    type={q.question_type === 'email' ? 'email' : q.question_type === 'phone' ? 'tel' : 'text'}
                    defaultValue={value(name)}
                    required={required}
                  />
                )}
              </>
            )}
            {fieldError(name)}
          </div>
        );
      })}

      {err?.message ? (
        <p role="alert" className="text-sm text-destructive">
          {err.message}
        </p>
      ) : null}

      <Button type="submit" disabled={pending || slots.length === 0} className="w-full">
        {pending ? 'Booking…' : 'Book it'}
      </Button>
    </form>
  );
}
```

Returning `values` from the action matters: React resets a form after its action runs, and the inputs fall back to their `defaultValue`. Without it, a typo in the email would wipe the whole form.

## Try it

Open `/book`, pick a day and a time, and submit. Then try the failure paths: submit with an empty name, or book the same slot from two tabs. The second tab gets "That time was just taken" and a fresh slot list after it picks another day. The booking shows up under [**Meetings**](https://www.clndr.pro/meetings) in the dashboard.

<Prompt title="Book through a Next.js server action">

```text
Build a /book page in this Next.js App Router project that books clndr.pro meetings through a server action, so the browser never calls clndr.pro and no clndr.pro key reaches the client.

Read first: https://docs.clndr.pro/tutorials/server-actions.md and https://docs.clndr.pro/sdk.md

Facts:
- @clndr-pro/sdk 0.1.5+; client in lib/clndr.ts with `import 'server-only'` and new Clndr(process.env.CLNDR_SECRET_KEY!). Never use NEXT_PUBLIC_ for the secret key.
- API base is https://www.clndr.pro/api/v1 (the SDK default from 0.1.5).
- clndr.bookingPages.get(slug) -> { bookingPage, userProfile, questions }. clndr.bookingPages.getSlots(slug, 'YYYY-MM-DD') -> [{ start, end }]; the date is a calendar day in the host's timezone (userProfile.timezone) and past slots are excluded.
- clndr.bookings.create({ bookingPageId, guestName, guestEmail, startTime, endTime, responses: [{ questionId, answer }] }). Send slot start/end unchanged. booking_type 'approval' means the booking is pending, so say "Request sent", not "Booked".
- The API doesn't enforce required questions: validate in the action. Re-check the slot is still in getSlots() right before create. Errors throw ClndrError { status, message }; a taken slot's message starts with "This time slot".

Steps:
1. Ask me for the booking page slug. Check whether shadcn/ui and zod are set up; use them if so.
2. Create lib/clndr.ts, app/book/page.tsx (server component: day strip from ?date=, slots), app/book/actions.ts ('use server', zod validation, required questions, slot re-check, create, revalidatePath) and app/book/booking-form.tsx ('use client', useActionState, slot radios, the page's questions by question_type, success screen). Return submitted values on error so the form keeps them.
3. Add CLNDR_SECRET_KEY to .env.example and tell me to set it in .env.local.
4. Run the type checker and build; fix what breaks.

Done when: no file under a 'use client' boundary imports lib/clndr.ts, slot times show in the guest's local timezone, and a taken slot shows a clear message instead of a crash.
```

</Prompt>

---

# Approve bookings in your admin

On a booking page set to *Needs approval*, every booking starts as `pending` and waits for the host. The clndr.pro dashboard has an approve button, but if your team already works in your own admin, the decision can live there. This page builds `/admin/bookings`: a table of pending requests with the guest's answers, an **Approve** button, and a **Decline** dialog that takes a reason.

Everything here runs on your server with the secret key. You'll need shadcn/ui and, for the emails at the end, [Resend](https://resend.com) or any mail API:

```bash
npm install @clndr-pro/sdk server-only resend
npx shadcn@latest add table badge button dialog label textarea
```

```bash title=".env.local"
CLNDR_SECRET_KEY=clndr_sk_...
RESEND_API_KEY=re_...
```

## Who can see this page

The secret key can read every guest's name, email and answers, and confirm or cancel any booking. Whatever renders this page is as privileged as the key, so put it behind your own auth before it goes anywhere near production. The helper below lets you in during `next dev` and nowhere else until you wire it up:

```ts title="lib/auth.ts"
import 'server-only';
import { notFound } from 'next/navigation';

/** Swap the body for your real check: Auth.js, Clerk, Supabase, a session cookie… */
export async function requireAdmin() {
  if (process.env.NODE_ENV === 'development') return;
  notFound();
}
```

```ts title="lib/clndr.ts"
import 'server-only';
import { Clndr } from '@clndr-pro/sdk';

export const clndr = new Clndr(process.env.CLNDR_SECRET_KEY!);
```

## Tell the guest yourself

Approving through the API confirms the booking, and if the page creates Meet links it also creates the Google Calendar event, and Google sends the guest an invite. clndr.pro doesn't send its own confirmation email for API approvals, and a declined request that never had a calendar event produces no email at all. So the admin sends them:

```ts title="lib/notify.ts"
import 'server-only';
import { Resend } from 'resend';

const resend = new Resend(process.env.RESEND_API_KEY);
const FROM = 'Ada Lovelace <bookings@example.com>';

function when(iso: string, timeZone: string) {
  return new Date(iso).toLocaleString('en-US', {
    timeZone,
    weekday: 'long',
    month: 'long',
    day: 'numeric',
    hour: 'numeric',
    minute: '2-digit',
    timeZoneName: 'short',
  });
}

export async function sendApproved(to: string, name: string, start: string, timeZone: string) {
  await resend.emails.send({
    from: FROM,
    to,
    subject: `Confirmed: ${when(start, timeZone)}`,
    text: `Hi ${name},\n\nYour call on ${when(start, timeZone)} is confirmed. See you then.`,
  });
}

export async function sendDeclined(to: string, name: string, start: string, timeZone: string, reason?: string) {
  await resend.emails.send({
    from: FROM,
    to,
    subject: `About your request for ${when(start, timeZone)}`,
    text: `Hi ${name},\n\nI can't make ${when(start, timeZone)}.${reason ? `\n\n${reason}` : ''}\n\nYou're welcome to pick another time.`,
  });
}
```

## The actions

Two server actions, both re-checking auth, since a server action is a public endpoint whatever page renders it. Both also read the booking first and act only while it's still `pending`: `PATCH` doesn't look at the current status, so approving a request the host already declined in the dashboard would confirm it again.

```ts title="app/admin/bookings/actions.ts"
'use server';

import { revalidatePath } from 'next/cache';
import { clndr } from '@/lib/clndr';
import { requireAdmin } from '@/lib/auth';
import { sendApproved, sendDeclined } from '@/lib/notify';

/** Someone may have handled it in the dashboard since the page loaded. */
async function stillPending(id: string) {
  const booking = await clndr.bookings.get(id);
  return booking.status === 'pending';
}

export async function approveBooking(id: string, timeZone: string) {
  await requireAdmin();
  if (await stillPending(id)) {
    const booking = await clndr.bookings.update(id, { status: 'confirmed' });

    // With a Meet link, Google has already sent the guest a calendar invite.
    if (!booking.google_meet_link) {
      await sendApproved(booking.guest_email, booking.guest_name, booking.start_time, timeZone);
    }
  }
  revalidatePath('/admin/bookings');
}

export async function declineBooking(id: string, timeZone: string, formData: FormData) {
  await requireAdmin();
  if (await stillPending(id)) {
    const reason = String(formData.get('reason') ?? '').trim() || undefined;
    const booking = await clndr.bookings.update(id, { status: 'cancelled', reason });

    await sendDeclined(booking.guest_email, booking.guest_name, booking.start_time, timeZone, reason);
  }
  revalidatePath('/admin/bookings');
}
```

`reason` is stored on the booking as `cancellation_reason`. The clndr.pro dashboard doesn't display it, which is why the decline email carries it. Cancelling also frees the slot: pending bookings hold their time until someone decides.

## The page

The list endpoint doesn't include answers, so the page reads each pending booking once more for its `meeting_responses`, and each booking page once for its question text. That's `2 + pages + pending` requests per load, well inside the secret key's 300 a minute for a normal queue. If yours runs to hundreds, load answers on a detail page instead.

```tsx title="app/admin/bookings/page.tsx"
import { clndr } from '@/lib/clndr';
import { requireAdmin } from '@/lib/auth';
import { Badge } from '@/components/ui/badge';
import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from '@/components/ui/table';
import { approveBooking } from './actions';
import { DeclineButton } from './decline-button';
import { SubmitButton } from './submit-button';

export const dynamic = 'force-dynamic';
export const metadata = { title: 'Booking requests' };

type Answer = { question_id: string; answer: string };

export default async function BookingRequestsPage() {
  await requireAdmin();

  const [pending, pages] = await Promise.all([
    clndr.bookings.list({ status: 'pending', limit: 100 }),
    clndr.bookingPages.list(),
  ]);
  // The API returns the latest start first; put the next decision on top.
  pending.sort((a, b) => Date.parse(a.start_time) - Date.parse(b.start_time));

  const pageById = new Map(pages.map((p) => [p.id, p]));
  const slugs = [...new Set(pending.map((b) => pageById.get(b.booking_page_id)?.slug))].filter(
    (s): s is string => !!s,
  );

  const [details, answers] = await Promise.all([
    // get() 404s for an inactive page; its requests still list, just without question text.
    Promise.all(slugs.map((slug) => clndr.bookingPages.get(slug).catch(() => null))),
    Promise.all(
      pending.map(async (b) => {
        const full = (await clndr.bookings.get(b.id)) as unknown as { meeting_responses?: Answer[] };
        return full.meeting_responses ?? [];
      }),
    ),
  ]);

  const questionText = new Map<string, string>();
  for (const d of details) for (const q of d?.questions ?? []) questionText.set(q.id, q.question_text);
  const timeZone = details.find(Boolean)?.userProfile.timezone ?? 'UTC';

  const when = (iso: string) =>
    new Date(iso).toLocaleString('en-US', {
      timeZone,
      weekday: 'short',
      month: 'short',
      day: 'numeric',
      hour: 'numeric',
      minute: '2-digit',
    });

  return (
    <main className="mx-auto max-w-5xl space-y-6 px-4 py-10">
      <div>
        <h1 className="text-2xl font-semibold">Booking requests</h1>
        <p className="text-sm text-muted-foreground">
          {pending.length === 0 ? 'Nothing waiting on you.' : `${pending.length} waiting. Times in ${timeZone}.`}
        </p>
      </div>

      {pending.length > 0 ? (
        <Table>
          <TableHeader>
            <TableRow>
              <TableHead>Guest</TableHead>
              <TableHead>When</TableHead>
              <TableHead>Answers</TableHead>
              <TableHead className="text-right">Decision</TableHead>
            </TableRow>
          </TableHeader>
          <TableBody>
            {pending.map((b, i) => {
              const past = Date.parse(b.start_time) < Date.now();
              return (
                <TableRow key={b.id} className="align-top">
                  <TableCell>
                    <div className="font-medium">{b.guest_name}</div>
                    <a href={`mailto:${b.guest_email}`} className="text-sm text-muted-foreground underline-offset-4 hover:underline">
                      {b.guest_email}
                    </a>
                  </TableCell>
                  <TableCell className="whitespace-nowrap">
                    <div>{when(b.start_time)}</div>
                    <div className="text-sm text-muted-foreground">{pageById.get(b.booking_page_id)?.title}</div>
                    {past ? <Badge variant="destructive" className="mt-1">Time has passed</Badge> : null}
                  </TableCell>
                  <TableCell className="max-w-sm">
                    {answers[i].length === 0 ? (
                      <span className="text-sm text-muted-foreground">No answers</span>
                    ) : (
                      <dl className="space-y-2 text-sm">
                        {answers[i].map((a) => (
                          <div key={a.question_id}>
                            <dt className="text-muted-foreground">{questionText.get(a.question_id) ?? 'Removed question'}</dt>
                            <dd className="whitespace-pre-wrap">{a.answer}</dd>
                          </div>
                        ))}
                      </dl>
                    )}
                  </TableCell>
                  <TableCell>
                    <div className="flex justify-end gap-2">
                      <DeclineButton id={b.id} guestName={b.guest_name} timeZone={timeZone} />
                      {past ? null : (
                        <form action={approveBooking.bind(null, b.id, timeZone)}>
                          <SubmitButton>Approve</SubmitButton>
                        </form>
                      )}
                    </div>
                  </TableCell>
                </TableRow>
              );
            })}
          </TableBody>
        </Table>
      ) : null}
    </main>
  );
}
```

## The buttons

A submit button that disables itself while its form's action runs:

```tsx title="app/admin/bookings/submit-button.tsx"
'use client';

import { useFormStatus } from 'react-dom';
import { Button } from '@/components/ui/button';

export function SubmitButton({ children, ...props }: React.ComponentProps<typeof Button>) {
  const { pending } = useFormStatus();
  return (
    <Button type="submit" size="sm" disabled={pending} {...props}>
      {pending ? 'Saving…' : children}
    </Button>
  );
}
```

And the decline dialog. Write the reason as if the guest will read it, because they will:

```tsx title="app/admin/bookings/decline-button.tsx"
'use client';

import { useState } from 'react';
import { Button } from '@/components/ui/button';
import {
  Dialog,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from '@/components/ui/dialog';
import { Label } from '@/components/ui/label';
import { Textarea } from '@/components/ui/textarea';
import { declineBooking } from './actions';
import { SubmitButton } from './submit-button';

export function DeclineButton({ id, guestName, timeZone }: { id: string; guestName: string; timeZone: string }) {
  const [open, setOpen] = useState(false);

  return (
    <Dialog open={open} onOpenChange={setOpen}>
      <DialogTrigger asChild>
        <Button variant="outline" size="sm">
          Decline
        </Button>
      </DialogTrigger>
      <DialogContent>
        <form
          action={async (formData) => {
            await declineBooking(id, timeZone, formData);
            setOpen(false);
          }}
        >
          <DialogHeader>
            <DialogTitle>Decline {guestName}'s request?</DialogTitle>
            <DialogDescription>They'll get an email with your note, and the time opens up again.</DialogDescription>
          </DialogHeader>
          <div className="space-y-2 py-4">
            <Label htmlFor={`reason-${id}`}>Note to the guest (optional)</Label>
            <Textarea id={`reason-${id}`} name="reason" placeholder="I'm travelling that week. Could you pick a time after the 20th?" />
          </div>
          <DialogFooter>
            <Button type="button" variant="ghost" onClick={() => setOpen(false)}>
              Keep it
            </Button>
            <SubmitButton variant="destructive">Decline</SubmitButton>
          </DialogFooter>
        </form>
      </DialogContent>
    </Dialog>
  );
}
```

## Check it

Book a test meeting on an approval page from its public URL, then open `/admin/bookings` under `next dev`. The request is there with your answers. Approve it: it disappears from the table, turns *Confirmed* under **Meetings** in the clndr.pro dashboard, and either Google's invite or your email arrives. Decline a second one and look for the note in your inbox.

A booking someone already handled in the dashboard is skipped by the `stillPending` check and drops off the list on reload. If an action throws (a deleted booking returns `404`, say), Next.js shows your nearest `error.tsx`. Add one under `app/admin/` with a "Reload" button and you're covered.

<Prompt title="Build an approvals screen for clndr.pro bookings">

```text
Add an admin page at /admin/bookings to this Next.js App Router project that lists pending clndr.pro bookings and lets me approve or decline them.

Read first: https://docs.clndr.pro/tutorials/approvals-dashboard.md and https://docs.clndr.pro/sdk.md

Facts:
- @clndr-pro/sdk 0.1.5+, server only: lib/clndr.ts with `import 'server-only'` and new Clndr(process.env.CLNDR_SECRET_KEY!). Never NEXT_PUBLIC_ for the secret key.
- clndr.bookings.list({ status: 'pending', limit }) returns latest start_time first, max 200, no cursor. It doesn't include answers: clndr.bookings.get(id) adds meeting_responses: [{ question_id, answer }] (not in the SDK's Booking type, so cast). Question text comes from clndr.bookingPages.get(slug).questions; map booking_page_id to slug with clndr.bookingPages.list().
- Approve: clndr.bookings.update(id, { status: 'confirmed' }). Decline: clndr.bookings.update(id, { status: 'cancelled', reason }). PATCH doesn't check the current status, so in each action call clndr.bookings.get(id) first and do nothing unless status === 'pending' (otherwise a booking the host already declined in the dashboard gets confirmed again).
- API approvals don't send clndr.pro's confirmation email; Google invites the guest only when the page creates Meet links (booking.google_meet_link is set after confirming). Declining a pending booking sends nothing. So send our own emails.
- Secret key budget: 300 requests per minute.

Steps:
1. Find how this project does auth and admin checks, and how it sends email. Tell me what you'll use. If there's no admin check, create requireAdmin() that only allows NODE_ENV=development and tell me to replace it.
2. Build the page (server component, shadcn Table if available), server actions for approve and decline (each calls requireAdmin), a decline dialog with an optional note, and pending-state submit buttons.
3. Send the guest an email on approve (when there's no Meet link) and on decline, using the project's email setup.
4. Add the env vars to .env.example. Run the type checker and build; fix what breaks.

Done when: the secret key is only imported by server files, both actions check admin access, past requests can't be approved, and times show in the host's timezone with the zone named.
```

</Prompt>

---

# Sync bookings to your database

clndr.pro doesn't send webhooks yet. If you want bookings in your own database (for a CRM, a reporting dashboard, or to join them against your users), you pull them. Two signals cover it:

1. **The booking form tells you.** `<BookingInline onBooked>` and the embed's `onBookingSuccessful` fire in the guest's browser the moment a booking succeeds. Post the id to your server and store it straight away.
2. **A cron job catches everything else.** Status changes made in the clndr.pro dashboard, approvals, cancellations by the host, bookings made on the hosted page: none of those reach your site. A job that lists bookings every ten minutes does.

```mermaid title="Two paths into your table"
sequenceDiagram
  participant G as Guest's browser
  participant S as Your server
  participant C as clndr.pro API
  participant D as Your database
  G->>C: create booking (BookingInline / embed)
  C-->>G: booking id
  G->>S: POST /api/clndr/booked { bookingId }
  S->>C: GET /bookings/{id} (secret key)
  S->>D: upsert
  loop every 10 minutes
    S->>C: GET /bookings?status=pending|confirmed|cancelled
    S->>D: upsert rows whose updated_at moved
  end
```

The examples use [Drizzle](https://orm.drizzle.team) on Postgres. The SQL at the end does the same without an ORM.

## The table

Store the fields you'll query, plus clndr.pro's `updated_at`, which changes on every status change and tells you whether your copy is stale.

```ts title="db/schema.ts"
import { pgTable, text, timestamp, uuid } from 'drizzle-orm/pg-core';

export const clndrBookings = pgTable('clndr_bookings', {
  id: uuid('id').primaryKey(), // clndr.pro's booking id
  bookingPageId: uuid('booking_page_id').notNull(),
  guestName: text('guest_name').notNull(),
  guestEmail: text('guest_email').notNull(),
  startTime: timestamp('start_time', { withTimezone: true }).notNull(),
  endTime: timestamp('end_time', { withTimezone: true }).notNull(),
  status: text('status').notNull(), // pending | confirmed | cancelled
  meetLink: text('meet_link'),
  cancellationReason: text('cancellation_reason'),
  clndrUpdatedAt: timestamp('clndr_updated_at', { withTimezone: true }).notNull(),
  syncedAt: timestamp('synced_at', { withTimezone: true }).notNull().defaultNow(),
});
```

## The sync

`upsertBookings` writes any bookings whose `updated_at` is newer than your copy and hands each change to a hook. `syncBookings` lists all three statuses (200 each, the API's maximum) and upserts them.

```ts title="lib/clndr-sync.ts"
import 'server-only';
import { and, gt, inArray, sql } from 'drizzle-orm';
import { ClndrError } from '@clndr-pro/sdk';
import { db } from '@/db';
import { clndrBookings } from '@/db/schema';
import { clndr } from '@/lib/clndr';

/** The API's booking row; the SDK's Booking type leaves some of these out. */
export type ApiBooking = {
  id: string;
  booking_page_id: string;
  guest_name: string;
  guest_email: string;
  start_time: string;
  end_time: string;
  status: 'pending' | 'confirmed' | 'cancelled' | 'completed';
  google_meet_link: string | null;
  cancellation_reason: string | null;
  updated_at: string;
};

const STATUSES = ['pending', 'confirmed', 'cancelled'] as const;

/** Your side effects: post to Slack, update the CRM, email the team. */
async function onBookingChange(booking: ApiBooking, previousStatus: string | null) {
  if (previousStatus === null) console.log('new booking', booking.id, booking.status);
  else if (previousStatus !== booking.status) console.log('status', booking.id, previousStatus, '→', booking.status);
}

export async function upsertBookings(bookings: ApiBooking[]) {
  if (bookings.length === 0) return 0;

  const before = new Map(
    (
      await db
        .select({ id: clndrBookings.id, status: clndrBookings.status, updatedAt: clndrBookings.clndrUpdatedAt })
        .from(clndrBookings)
        .where(inArray(clndrBookings.id, bookings.map((b) => b.id)))
    ).map((r) => [r.id, r]),
  );

  const changed = bookings.filter((b) => {
    const prev = before.get(b.id);
    return !prev || prev.updatedAt.getTime() < Date.parse(b.updated_at);
  });
  if (changed.length === 0) return 0;

  await db
    .insert(clndrBookings)
    .values(
      changed.map((b) => ({
        id: b.id,
        bookingPageId: b.booking_page_id,
        guestName: b.guest_name,
        guestEmail: b.guest_email,
        startTime: new Date(b.start_time),
        endTime: new Date(b.end_time),
        status: b.status,
        meetLink: b.google_meet_link,
        cancellationReason: b.cancellation_reason,
        clndrUpdatedAt: new Date(b.updated_at),
      })),
    )
    .onConflictDoUpdate({
      target: clndrBookings.id,
      set: {
        status: sql`excluded.status`,
        startTime: sql`excluded.start_time`,
        endTime: sql`excluded.end_time`,
        meetLink: sql`excluded.meet_link`,
        cancellationReason: sql`excluded.cancellation_reason`,
        clndrUpdatedAt: sql`excluded.clndr_updated_at`,
        syncedAt: sql`now()`,
      },
    });

  for (const b of changed) await onBookingChange(b, before.get(b.id)?.status ?? null);
  return changed.length;
}

export async function syncBookings() {
  const lists = await Promise.all(STATUSES.map((status) => clndr.bookings.list({ status, limit: 200 })));
  const fetched = lists.flat() as unknown as ApiBooking[];

  // Each list holds the 200 latest start times, so an upcoming booking can drop
  // out of view in a busy calendar. Look up any upcoming booking we hold as
  // pending/confirmed that didn't show up under that status this time.
  const seen = new Set(fetched.map((b) => b.id));
  const ours = await db
    .select({ id: clndrBookings.id })
    .from(clndrBookings)
    .where(and(inArray(clndrBookings.status, ['pending', 'confirmed']), gt(clndrBookings.startTime, new Date())));

  for (const { id } of ours.filter((r) => !seen.has(r.id)).slice(0, 50)) {
    try {
      fetched.push((await clndr.bookings.get(id)) as unknown as ApiBooking);
    } catch (err) {
      if (!(err instanceof ClndrError && err.status === 404)) throw err;
    }
  }

  return { fetched: fetched.length, changed: await upsertBookings(fetched) };
}
```

## Run it every ten minutes

A route handler for the cron, refusing anyone without the secret:

```ts title="app/api/cron/clndr-sync/route.ts"
import { syncBookings } from '@/lib/clndr-sync';

export const dynamic = 'force-dynamic';
export const maxDuration = 60;

export async function GET(request: Request) {
  const secret = process.env.CRON_SECRET;
  if (!secret || request.headers.get('authorization') !== `Bearer ${secret}`) {
    return new Response('Unauthorized', { status: 401 });
  }
  return Response.json(await syncBookings());
}
```

```json title="vercel.json"
{
  "crons": [{ "path": "/api/cron/clndr-sync", "schedule": "*/10 * * * *" }]
}
```

Set `CRON_SECRET` in your Vercel project's environment variables and Vercel sends it as the bearer token on every cron call. Vercel's Hobby plan only runs crons once a day; on Hobby, or off Vercel, call the same URL from any scheduler (a GitHub Actions `schedule`, a system crontab) with `Authorization: Bearer $CRON_SECRET`.

### The request budget

One run costs 3 list calls plus at most 50 lookups. At six runs an hour that's about 18 requests an hour in a quiet month, against a secret key limit of 300 a minute. You can poll every minute if you need to; the rest of your server-side traffic shares the same limit.

### What polling can't see

Each status list is capped at 200 bookings, sorted by start time, latest first, with no cursor. Past 200 upcoming bookings in one status, the nearest ones fall below the cut, which is what the lookup step patches, 50 at a time. At that volume, lean on the instant path below and treat the cron as a backstop. A booking cancelled long after its start time can also fall out of the cancelled list. Your copy then keeps its last known status, which for a past meeting is usually what you want anyway.

## Store bookings the moment they happen

When the booking happens on your own site, don't wait for the cron. The form hands you the booking id in the browser; post it to a route that fetches the booking with the secret key and upserts it. Fetching by id, instead of trusting the browser's payload, means nobody can write made-up bookings into your table: an id from another account just 404s.

```ts title="app/api/clndr/booked/route.ts"
import { ClndrError } from '@clndr-pro/sdk';
import { clndr } from '@/lib/clndr';
import { upsertBookings, type ApiBooking } from '@/lib/clndr-sync';

export async function POST(request: Request) {
  const { bookingId } = (await request.json().catch(() => ({}))) as { bookingId?: unknown };
  if (typeof bookingId !== 'string') return new Response('bookingId required', { status: 400 });

  try {
    const booking = await clndr.bookings.get(bookingId);
    await upsertBookings([booking as unknown as ApiBooking]);
  } catch (err) {
    if (err instanceof ClndrError && err.status === 404) return new Response('Unknown booking', { status: 404 });
    throw err;
  }
  return new Response(null, { status: 204 });
}
```

Then call it from whichever form you use:

<Tabs>
<Tab title="React component">

```tsx title="app/book/booking-widget.tsx"
'use client';

import { BookingInline } from '@clndr-pro/react';

export function BookingWidget() {
  return (
    <BookingInline
      slug="intro-call"
      onBooked={(bookingId) => {
        void fetch('/api/clndr/booked', {
          method: 'POST',
          headers: { 'content-type': 'application/json' },
          body: JSON.stringify({ bookingId }),
        });
      }}
    />
  );
}
```

</Tab>
<Tab title="Embed script">

```html
<div id="booking"></div>

<script>
  function mountBooking() {
    Clndr.inline({
      elementOrSelector: '#booking',
      link: 'ada/intro-call',
      config: {
        onBookingSuccessful: (payload) => {
          if (!payload.meetingId) return;
          fetch('/api/clndr/booked', {
            method: 'POST',
            headers: { 'content-type': 'application/json' },
            body: JSON.stringify({ bookingId: payload.meetingId }),
          });
        },
      },
    });
  }
</script>
<script src="https://www.clndr.pro/embed.js" async onload="mountBooking()"></script>
```

Call `Clndr` from the script's `onload`, as on [Embed script](/embed/script): an inline call can run before `embed.js` has loaded.

</Tab>
</Tabs>

If the guest closes the tab before that request goes out, the cron picks the booking up on its next run.

## Without Drizzle

The same upsert in SQL, guarded so an older copy never overwrites a newer one:

```sql
create table if not exists clndr_bookings (
  id                  uuid primary key,
  booking_page_id     uuid not null,
  guest_name          text not null,
  guest_email         text not null,
  start_time          timestamptz not null,
  end_time            timestamptz not null,
  status              text not null,
  meet_link           text,
  cancellation_reason text,
  clndr_updated_at    timestamptz not null,
  synced_at           timestamptz not null default now()
);

insert into clndr_bookings
  (id, booking_page_id, guest_name, guest_email, start_time, end_time, status, meet_link, cancellation_reason, clndr_updated_at)
values
  ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)
on conflict (id) do update set
  status              = excluded.status,
  start_time          = excluded.start_time,
  end_time            = excluded.end_time,
  meet_link           = excluded.meet_link,
  cancellation_reason = excluded.cancellation_reason,
  clndr_updated_at    = excluded.clndr_updated_at,
  synced_at           = now()
where clndr_bookings.clndr_updated_at < excluded.clndr_updated_at;
```

<Prompt title="Sync clndr.pro bookings into my database">

```text
Keep a copy of my clndr.pro bookings in this project's database: a polling cron plus an instant update when a booking is made on our site.

Read first: https://docs.clndr.pro/tutorials/sync-bookings.md and https://docs.clndr.pro/types.md

Facts:
- No webhooks. Poll GET /bookings with the SECRET key (server only): @clndr-pro/sdk 0.1.5+, clndr.bookings.list({ status, limit: 200 }) per status (pending, confirmed, cancelled). Max 200, no cursor, sorted by start_time latest first.
- Booking rows are snake_case and include updated_at (changes on every status change) and cancellation_reason; the SDK's Booking type doesn't declare those, so use a local type.
- clndr.bookings.get(id) for single bookings; an id from another account is a 404 (ClndrError status 404).
- Secret key limit: 300 requests per minute.
- The booking form gives the id in the browser: BookingInline onBooked(bookingId), or the embed's onBookingSuccessful({ meetingId }).

Steps:
1. Find this project's database and ORM and its scheduler (Vercel Cron? something else?). Tell me what you'll use.
2. Add a clndr_bookings table (migration in this project's style) keyed by clndr.pro's booking id, with clndr_updated_at.
3. Write upsertBookings (skip rows whose updated_at hasn't moved, call an onBookingChange hook) and syncBookings (three status lists + look up upcoming pending/confirmed rows that didn't appear, max 50 per run).
4. Add a cron route protected by a CRON_SECRET bearer token and schedule it every 10 minutes, and a POST route that takes { bookingId }, fetches it with the secret key and upserts it. Wire our booking form's success callback to that route.
5. Add the env vars to .env.example. Run the type checker and build; fix what breaks.

Done when: running the sync twice in a row changes nothing the second time, the cron route rejects requests without the secret, and the secret key is never imported into client code.
```

</Prompt>

---

# Plain JavaScript

No React, no bundler, no SDK: one HTML file that loads a booking page, shows the open times for a day, asks the host's questions and books. Use it on a static site, inside a CMS that accepts custom HTML, or as a reference for porting the flow to Vue, Svelte or anything else.

If you'd rather not write the form at all, the [embed script](/embed/script) drops clndr.pro's own booking page onto any site with two lines.

## The file

Save this as `book.html`, put your publishable key and slug in the three constants at the top of the script, and open it in a browser. It talks to the API directly; there's no server of yours involved.

```html title="book.html"
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Book a call</title>
    <style>
      body { font: 16px/1.5 system-ui, sans-serif; margin: 0; color: #18181b; }
      main { max-width: 34rem; margin: 3rem auto; padding: 0 1rem; display: grid; gap: 1rem; }
      h1 { margin: 0; font-size: 1.5rem; }
      .muted { color: #71717a; font-size: 0.875rem; margin: 0; }
      .description { white-space: pre-line; }
      label { display: grid; gap: 0.25rem; font-size: 0.875rem; font-weight: 500; }
      input, select, textarea { font: inherit; padding: 0.5rem 0.75rem; border: 1px solid #d4d4d8; border-radius: 8px; }
      #slots { display: grid; grid-template-columns: repeat(auto-fill, minmax(6rem, 1fr)); gap: 0.5rem; }
      #slots button, form button { font: inherit; padding: 0.5rem; border: 1px solid #d4d4d8; border-radius: 8px; background: #fff; cursor: pointer; }
      #slots button[aria-pressed="true"] { border-color: #2563eb; color: #2563eb; }
      form { display: grid; gap: 0.75rem; }
      form button[type="submit"] { background: #18181b; color: #fff; border-color: #18181b; }
      .check { display: flex; gap: 0.5rem; align-items: center; }
      #status:empty { display: none; }
    </style>
  </head>
  <body>
    <main>
      <div>
        <h1 id="title">Loading…</h1>
        <p class="muted" id="meta"></p>
      </div>
      <p class="description" id="description"></p>

      <label>
        Day
        <input id="day" type="date" disabled />
      </label>
      <div id="slots" role="group" aria-label="Open times"></div>

      <form id="details" hidden>
        <p class="muted" id="picked"></p>
        <label>Name <input name="name" required autocomplete="name" /></label>
        <label>Email <input name="email" type="email" required autocomplete="email" /></label>
        <div id="questions"></div>
        <button type="submit">Book</button>
      </form>

      <p id="status" role="status"></p>
    </main>

    <script type="module">
      const API = 'https://www.clndr.pro/api/v1'; // always www
      const KEY = 'clndr_pk_...'; // a publishable key: fine in page source
      const SLUG = 'intro-call';

      const $ = (id) => document.getElementById(id);
      const time = new Intl.DateTimeFormat(undefined, { hour: 'numeric', minute: '2-digit' });
      const longDate = new Intl.DateTimeFormat(undefined, { weekday: 'long', month: 'long', day: 'numeric' });

      async function api(path, body) {
        const res = await fetch(API + path, {
          method: body ? 'POST' : 'GET',
          headers: { Authorization: `Bearer ${KEY}`, ...(body ? { 'Content-Type': 'application/json' } : {}) },
          body: body ? JSON.stringify(body) : undefined,
        });
        const json = await res.json().catch(() => ({}));
        if (!res.ok) throw Object.assign(new Error(json.error ?? `HTTP ${res.status}`), { status: res.status });
        return json.data;
      }

      const ymd = (d) =>
        `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;

      let page; // { bookingPage, userProfile, questions }
      let picked = null; // { start, end }

      // 1. The booking page: title, host, description, questions.
      try {
        page = await api(`/booking-pages/${encodeURIComponent(SLUG)}`);
      } catch (err) {
        $('title').textContent = 'This booking page isn’t available';
        $('meta').textContent = err.message;
        throw err;
      }

      const { bookingPage, userProfile, questions } = page;
      document.title = bookingPage.title;
      $('title').textContent = bookingPage.title;
      $('meta').textContent = `${userProfile.full_name ?? userProfile.username} · ${bookingPage.duration_minutes} min`;
      // Markdown from the host: shown as text. Use a Markdown library to render it.
      $('description').textContent = bookingPage.description ?? '';

      const today = new Date();
      $('day').min = ymd(today);
      if (bookingPage.max_days_ahead) {
        $('day').max = ymd(new Date(today.getFullYear(), today.getMonth(), today.getDate() + bookingPage.max_days_ahead));
      }
      $('day').disabled = false;

      // 2. The host's questions, built with DOM APIs (never innerHTML with host text).
      for (const q of questions) {
        const label = document.createElement('label');
        let field;
        if (q.question_type === 'textarea') {
          field = document.createElement('textarea');
          field.rows = 4;
        } else if (q.question_type === 'select') {
          field = document.createElement('select');
          field.append(new Option('Choose one', ''), ...(q.options ?? []).map((o) => new Option(o, o)));
        } else {
          field = document.createElement('input');
          field.type = { email: 'email', phone: 'tel', checkbox: 'checkbox' }[q.question_type] ?? 'text';
          if (q.question_type === 'checkbox') label.className = 'check';
        }
        field.name = `q:${q.id}`;
        field.required = !!q.is_required;
        label.append(`${q.question_text}${q.is_required ? ' *' : ''}`, field);
        $('questions').append(label);
      }

      // 3. Open times for the picked day. The API reads YYYY-MM-DD as the host's day.
      async function loadSlots() {
        picked = null;
        $('details').hidden = true;
        $('slots').replaceChildren();
        if (!$('day').value) return;
        $('status').textContent = 'Loading times…';
        try {
          const slots = await api(`/booking-pages/${encodeURIComponent(SLUG)}/slots?date=${$('day').value}`);
          $('status').textContent = slots.length ? '' : 'No open times that day. Try another one.';
          for (const slot of slots) {
            const button = document.createElement('button');
            button.type = 'button';
            button.textContent = time.format(new Date(slot.start)); // the guest's local time
            button.setAttribute('aria-pressed', 'false');
            button.addEventListener('click', () => pick(slot, button));
            $('slots').append(button);
          }
        } catch (err) {
          $('status').textContent = err.message;
        }
      }

      function pick(slot, button) {
        picked = slot;
        for (const b of $('slots').children) b.setAttribute('aria-pressed', String(b === button));
        $('picked').textContent = `${longDate.format(new Date(slot.start))}, ${time.format(new Date(slot.start))}`;
        $('details').hidden = false;
      }

      $('day').addEventListener('change', loadSlots);

      // 4. Book it.
      $('details').addEventListener('submit', async (event) => {
        event.preventDefault();
        if (!picked) return;
        const form = new FormData(event.currentTarget);
        const responses = questions
          .map((q) => {
            const answer =
              q.question_type === 'checkbox' ? (form.get(`q:${q.id}`) ? 'Yes' : 'No') : String(form.get(`q:${q.id}`) ?? '').trim();
            return { questionId: q.id, answer };
          })
          .filter((r) => r.answer !== '');

        const submit = event.currentTarget.querySelector('[type="submit"]');
        submit.disabled = true;
        $('status').textContent = 'Booking…';
        try {
          const booking = await api('/bookings', {
            bookingPageId: bookingPage.id,
            guestName: String(form.get('name')),
            guestEmail: String(form.get('email')),
            startTime: picked.start,
            endTime: picked.end,
            responses,
          });
          $('details').hidden = true;
          $('slots').replaceChildren();
          $('status').textContent =
            booking.status === 'pending'
              ? `Request sent. ${userProfile.full_name ?? userProfile.username} will confirm by email.`
              : `You're booked. A confirmation is on its way to ${booking.guest_email}.`;
        } catch (err) {
          if (/no longer available|not available/i.test(err.message) || err.status === 409) {
            await loadSlots();
            $('status').textContent = 'Someone booked that time a moment ago. Pick another one.';
          } else {
            $('status').textContent = err.message;
          }
        } finally {
          submit.disabled = false;
        }
      });
    </script>
  </body>
</html>
```

## How it works

**Requests.** `api()` sends the key as `Authorization: Bearer clndr_pk_…` and unwraps the `data` field every successful response has. On failure it throws an `Error` carrying the API's own `error` message and the HTTP `status`. The API sends `Access-Control-Allow-Origin: *`, so this works from any origin, `file://` pages included.

**The day.** `<input type="date">` gives `YYYY-MM-DD`, and the API reads that as a calendar day in the **host's** timezone. Pass the string as it is. The times that come back are UTC timestamps, and `Intl.DateTimeFormat` with an `undefined` locale formats them in the guest's own locale and timezone. Today's past times and days beyond the page's booking window come back empty, and the `min`/`max` on the input keep guests inside that window.

**Questions.** Each `question_type` gets the closest native input: `textarea`, a `select` built from `options`, a `checkbox` (answered "Yes" or "No"), `tel` for `phone`, `email`, or text. Required questions use the browser's `required` validation, which matters: the API accepts bookings with unanswered questions. Every piece of text from the host goes in through `textContent`, never `innerHTML`.

**Booking.** The `POST /bookings` body uses camelCase (`bookingPageId`, `guestEmail`, `startTime`) while responses use snake_case (`guest_email`). `startTime` and `endTime` are the slot's `start` and `end`, untouched. The response's `status` is `confirmed` for *direct* pages and `pending` for *approval* pages, and the message changes to match.

**A taken slot.** If another guest booked the same time first, the API answers `409`. With a publishable key the message is usually "This time slot is not available. Fetch the slots again and pick another." The script treats any `409` as a taken slot, reloads that day's times and asks the guest to pick again.

## Making it yours

- **Styling.** The `<style>` block is the whole design; replace it with your site's.
- **The description** is Markdown, shown here as plain text with line breaks kept. To render it, run it through a Markdown library such as `marked` plus a sanitiser such as DOMPurify, since the host's text then becomes HTML.
- **Several booking pages.** `GET /booking-pages` lists every page on the key's account, including inactive and private ones. Filter on `is_active` and `visibility === 'public'` before offering them. See [List booking pages](/api-reference/operations/listBookingPages).
- **Rate limits.** A publishable key gets 120 requests a minute, shared by every visitor using it. Each guest costs about three to five: the page, a slot list per day they look at, the booking. A page with heavy traffic should load the booking page once on your server and cache it.

## Keep the key publishable

This file ships the key to every visitor, which is what publishable keys are for: they can read your pages and slots and create bookings, nothing else. Never put a secret `clndr_sk_` key in a page like this. Anything that lists, confirms or cancels bookings belongs on a server; see the [TypeScript SDK](/sdk).

<Prompt title="Port the plain-JavaScript booking form">

```text
Add a clndr.pro booking form to this site without React, following https://docs.clndr.pro/tutorials/vanilla-js.md (read it first; the API reference is https://docs.clndr.pro/api-reference).

- Use fetch against https://www.clndr.pro/api/v1 (always www) with a publishable key (clndr_pk_...) in an Authorization: Bearer header. Never use a secret key in browser code.
- Load GET /booking-pages/{slug}, GET /booking-pages/{slug}/slots?date=YYYY-MM-DD (the host's calendar day), then POST /bookings with bookingPageId, guestName, guestEmail, startTime and endTime copied from the slot, and responses as [{ questionId, answer }].
- Insert host-written text with textContent, never innerHTML. Show times with Intl.DateTimeFormat in the guest's timezone.
- On a 409 (the slot was taken or isn't open any more), reload that day's slots and ask the guest to pick again. Show "Request sent" instead of "booked" when the booking comes back pending.
- Match the site's existing markup and styles. Ask me for the booking page slug and which page this goes on, and leave a clearly marked placeholder for the publishable key.
```

</Prompt>

---

# TypeScript SDK

`@clndr-pro/sdk` is a thin, typed wrapper over the [REST API](/api-reference). It has no dependencies and uses the runtime's own `fetch`, so the same import works in Node, Edge functions, Bun, Deno and browsers. `@clndr-pro/react` is built on it and re-exports the `Clndr` class, but on a server you only need this package.

```bash
npm install @clndr-pro/sdk
```

<Warning>
Use 0.1.5 or later. Earlier versions default to `https://clndr.pro`, which redirects to `www` and drops your key (every call fails with `401 Missing API key`), and their CommonJS entry point is missing, so `require('@clndr-pro/sdk')` throws. On an older version, pass `baseUrl: 'https://www.clndr.pro'` and import it as ESM.
</Warning>

## Create a client

On a server, use your secret key. Keep the client in one module and mark it server-only, so a stray import from a client component fails the build instead of shipping the key:

```ts title="lib/clndr.ts"
import 'server-only';
import { Clndr } from '@clndr-pro/sdk';

export const clndr = new Clndr(process.env.CLNDR_SECRET_KEY!);
```

`server-only` is a separate npm package (`npm install server-only`). Next.js turns any client-side import of it into a build error.

In a browser, use a publishable key. If you're in React, let [`ClndrProvider`](/react/components#clndrprovider) create the client for you. Elsewhere:

```ts
import { Clndr } from '@clndr-pro/sdk';

const clndr = new Clndr({ apiKey: 'clndr_pk_...' });
```

### Options

The constructor takes the key on its own, or an options object:

<ParamField body="apiKey" type="string" required>
A secret (`clndr_sk_…`) or publishable (`clndr_pk_…`) key. The constructor throws if it's empty.
</ParamField>

<ParamField body="baseUrl" type="string" default="https://www.clndr.pro">
The clndr.pro origin, without `/api/v1`. Trailing slashes are stripped. Change it only to point at a local or self-hosted instance.
</ParamField>

<ParamField body="fetch" type="typeof fetch">
A `fetch` implementation to use instead of the global one. Handy for tests, request logging, or adding a timeout.
</ParamField>

`clndr.keyType` is `'publishable'` when the key starts with `clndr_pk_` and `'secret'` otherwise. It's read from the prefix, not checked with the server.

## Booking pages

### `bookingPages.list()`

```ts
list(): Promise<BookingPage[]>
```

Every booking page on the key's account, newest first: `GET /booking-pages` ([reference](/api-reference/operations/listBookingPages)). Inactive and private pages are included, so filter before showing the list to guests:

```ts
const pages = (await clndr.bookingPages.list()).filter((p) => p.is_active && p.visibility === 'public');
```

### `bookingPages.get(slug)`

```ts
get(slug: string): Promise<BookingPageDetail>
```

One active page, its host's public profile and its questions: `GET /booking-pages/{slug}` ([reference](/api-reference/operations/getBookingPage)). Throws a `ClndrError` with status `404` when the slug doesn't exist on the account or the page is inactive.

```ts
const { bookingPage, userProfile, questions } = await clndr.bookingPages.get('intro-call');
console.log(bookingPage.id, userProfile.timezone, questions.length);
```

### `bookingPages.getSlots(slug, date)`

```ts
getSlots(slug: string, date: string | Date): Promise<TimeSlot[]>
```

Open slots on one day: `GET /booking-pages/{slug}/slots?date=` ([reference](/api-reference/operations/listSlots)). The day is a calendar day in the **host's** timezone.

- A string is sent as is. Pass `YYYY-MM-DD`.
- A `Date` is turned into its local calendar date (`getFullYear`, `getMonth`, `getDate`) and sent as `YYYY-MM-DD`. Build it with `new Date(2026, 9, 15)`, not `new Date('2026-10-15')`: the second form is UTC midnight, which is still the 14th in the Americas.

```ts
const slots = await clndr.bookingPages.getSlots('intro-call', '2026-10-15');
// [{ start: '2026-10-15T08:00:00.000Z', end: '2026-10-15T08:30:00.000Z' }, …]
```

Slots that have already started aren't returned, and days beyond the page's `max_days_ahead` come back empty.

## Bookings

### `bookings.create(input)`

```ts
create(input: CreateBookingInput): Promise<Booking>
```

`POST /bookings` ([reference](/api-reference/operations/createBooking)). Works with either key type. Pass a slot's `start` and `end` unchanged:

```ts
const booking = await clndr.bookings.create({
  bookingPageId: bookingPage.id,
  guestName: 'Grace Hopper',
  guestEmail: 'grace@example.com',
  startTime: slots[0].start,
  endTime: slots[0].end,
  responses: [{ questionId: questions[0].id, answer: 'Moving our sales demos over.' }],
});

booking.status; // 'confirmed' on a direct page, 'pending' on an approval page
```

The returned booking doesn't include the answers. Read them back with `bookings.get`.

### `bookings.list(params?)`

```ts
list(params?: { status?: 'pending' | 'confirmed' | 'cancelled'; limit?: number }): Promise<Booking[]>
```

`GET /bookings` ([reference](/api-reference/operations/listBookings)). Secret keys only. Sorted by `start_time`, latest first. `limit` defaults to 50 and is capped at 200; there's no cursor.

```ts
const pending = await clndr.bookings.list({ status: 'pending', limit: 100 });
```

### `bookings.get(id)`

```ts
get(id: string): Promise<Booking>
```

`GET /bookings/{id}` ([reference](/api-reference/operations/getBooking)). Secret keys only. The response also carries `meeting_responses`, the guest's answers, which the SDK's `Booking` type doesn't declare. [Data types](/types#bookingwithresponses) has an interface to cast to.

### `bookings.update(id, patch)`

```ts
update(id: string, patch: { status: 'confirmed' | 'cancelled'; reason?: string }): Promise<Booking>
```

`PATCH /bookings/{id}` ([reference](/api-reference/operations/updateBooking)). Secret keys only. Approve a pending booking with `{ status: 'confirmed' }`, decline with `{ status: 'cancelled', reason }`.

Confirming through the API creates the Google Calendar event and Meet link if the page uses Meet links, and Google emails the guest the invite. clndr.pro doesn't send its own confirmation email for API confirmations, so on pages without Meet links, tell the guest yourself. [Approve bookings in your admin](/tutorials/approvals-dashboard) shows how.

### `bookings.cancel(id)`

```ts
cancel(id: string): Promise<{ success: true }>
```

`DELETE /bookings/{id}` ([reference](/api-reference/operations/cancelBooking)). Secret keys only. Cancels the booking and deletes its Google Calendar event; Google tells the guest. Unlike `update`, it never stores a reason.

## Errors

Any non-2xx response throws a `ClndrError`. Its `message` is the API's `error` string, `status` is the HTTP status, and `data` is the parsed response body.

```ts title="lib/book.ts"
import 'server-only';
import { ClndrError, type CreateBookingInput } from '@clndr-pro/sdk';
import { clndr } from '@/lib/clndr';

export async function book(input: CreateBookingInput) {
  try {
    return { booking: await clndr.bookings.create(input) };
  } catch (err) {
    if (!(err instanceof ClndrError)) throw err; // network failure, timeout, …

    switch (err.status) {
      case 400:
        // A malformed request: missing field, bad email, unparseable time.
        return { error: err.message };
      case 409:
        // The slot was taken (or, with a publishable key, isn't an open slot).
        // Refetch the slots and let the guest pick another.
        return { error: 'That time was just taken. Pick another.' };
      case 401:
      case 403:
        // Revoked key, missing scope, page on another account. Your bug, not the guest's.
        console.error('clndr.pro key problem:', err.message);
        return { error: 'Booking is unavailable right now.' };
      case 429:
        // The key's per-minute limit, or this guest email's 5 attempts this clock hour.
        return { error: 'Too many attempts. Try again later.' };
      default:
        return { error: 'Something went wrong. Please try again.' };
    }
  }
}
```

Network errors and timeouts aren't wrapped: you get whatever your `fetch` throws, usually a `TypeError`. [Errors and rate limits](/errors) lists every message the API sends.

## Runtimes

Node 18 and later, Vercel and Cloudflare edge runtimes, Bun, Deno and modern browsers: anywhere with a global `fetch`. From 0.1.5 the package ships both ESM (`import`) and CommonJS (`require`) builds, with type definitions for each.

## Testing

Pass a `fetch` that answers from fixtures, and nothing touches the network:

```ts title="booking.test.ts"
import { describe, expect, it } from 'vitest';
import { Clndr } from '@clndr-pro/sdk';

function fakeFetch(routes: Record<string, unknown>): typeof fetch {
  return async (input) => {
    const href = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
    const body = routes[new URL(href).pathname];
    return body === undefined
      ? new Response(JSON.stringify({ error: 'Booking page not found' }), { status: 404 })
      : new Response(JSON.stringify(body), { status: 200, headers: { 'content-type': 'application/json' } });
  };
}

describe('slots', () => {
  it('returns the API data', async () => {
    const clndr = new Clndr({
      apiKey: 'clndr_sk_test',
      fetch: fakeFetch({
        '/api/v1/booking-pages/intro-call/slots': {
          data: [{ start: '2026-10-15T08:00:00.000Z', end: '2026-10-15T08:30:00.000Z' }],
        },
      }),
    });
    await expect(clndr.bookingPages.getSlots('intro-call', '2026-10-15')).resolves.toHaveLength(1);
  });
});
```

The same hook adds a timeout in production: `fetch: (url, init) => fetch(url, { ...init, signal: AbortSignal.timeout(8000) })`.

## Without the SDK

Every method above is one HTTP request with a bearer token. From a terminal:

```bash
export CLNDR_KEY=clndr_sk_...
export CLNDR_API=https://www.clndr.pro/api/v1

# Booking pages and slots (any key)
curl -H "Authorization: Bearer $CLNDR_KEY" "$CLNDR_API/booking-pages"
curl -H "Authorization: Bearer $CLNDR_KEY" "$CLNDR_API/booking-pages/intro-call"
curl -H "Authorization: Bearer $CLNDR_KEY" "$CLNDR_API/booking-pages/intro-call/slots?date=2026-10-15"

# Create a booking (any key)
curl -X POST "$CLNDR_API/bookings" \
  -H "Authorization: Bearer $CLNDR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bookingPageId": "8b6f2c1e-4a1d-4f0b-9a63-2f0c5d7e9b14",
    "guestName": "Grace Hopper",
    "guestEmail": "grace@example.com",
    "startTime": "2026-10-15T08:40:00.000Z",
    "endTime": "2026-10-15T09:10:00.000Z"
  }'

# Read, confirm and cancel bookings (secret key)
curl -H "Authorization: Bearer $CLNDR_KEY" "$CLNDR_API/bookings?status=pending&limit=20"
curl -H "Authorization: Bearer $CLNDR_KEY" "$CLNDR_API/bookings/c3a7e5d1-2b9f-4c6e-8a1d-7f4b0e2c9a58"
curl -X PATCH "$CLNDR_API/bookings/c3a7e5d1-2b9f-4c6e-8a1d-7f4b0e2c9a58" \
  -H "Authorization: Bearer $CLNDR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "cancelled", "reason": "Travelling that week." }'
curl -X DELETE -H "Authorization: Bearer $CLNDR_KEY" \
  "$CLNDR_API/bookings/c3a7e5d1-2b9f-4c6e-8a1d-7f4b0e2c9a58"
```

Success bodies are wrapped in `data` (except `DELETE`, which returns `{ "success": true }`), and errors are `{ "error": "…" }`. The [API reference](/api-reference) has the full schemas, and [`/openapi.json`](/openapi.json) is the spec to generate a client in another language.

---

# Data types

Response objects are database rows, so their fields are snake_case (`duration_minutes`, `guest_email`). Request bodies are camelCase (`bookingPageId`, `guestEmail`). Every success response wraps its payload in `data`; every error is an [`ApiError`](#apierror). Timestamps are ISO 8601 strings in UTC.

The interfaces below describe the full API responses. `@clndr-pro/sdk` exports narrower versions of some of them, listed in [What the SDK types cover](#what-the-sdk-types-cover), so you can copy these into your project when you need the extra fields.

## Enums

```ts title="types/clndr.ts"
/** `direct`: confirmed on the spot. `approval`: `pending` until the host decides. */
export type BookingType = 'direct' | 'approval';

/**
 * Who can open the hosted page at www.clndr.pro/{username}/{slug}.
 * API keys see all of their owner's pages regardless.
 */
export type Visibility = 'public' | 'private' | 'team';

/** The dashboard creates text, email, textarea and phone; select comes with `options`. */
export type QuestionType = 'text' | 'email' | 'textarea' | 'phone' | 'select' | 'checkbox';

/** `completed` is reserved; nothing sets it today. */
export type BookingStatus = 'pending' | 'confirmed' | 'cancelled' | 'completed';

/**
 * Whether the booking's Google Calendar event was created, as recorded when
 * the guest booked or the host acted in the dashboard. PATCH/DELETE through
 * the API don't update it: check google_calendar_event_id after those.
 */
export type SyncStatus = 'not_synced' | 'pending' | 'synced' | 'failed';
```

## BookingPageSummary

An item of [List booking pages](/api-reference/operations/listBookingPages).

```ts title="types/clndr.ts"
export interface BookingPageSummary {
  /** Send as `bookingPageId` when you create a booking. */
  id: string;
  /** Unique per account: lowercase letters, digits and hyphens. */
  slug: string;
  title: string;
  /** Markdown written by the host. Render it as Markdown. */
  description: string | null;
  /** Length of every slot, 1–480. */
  duration_minutes: number;
  booking_type: BookingType;
  /** How far ahead guests can book. `null` = no limit. */
  max_days_ahead: number | null;
  /** Gap between consecutive slots. */
  buffer_time_minutes: number | null;
  visibility: Visibility;
  /** Confirmed bookings get a Google Calendar event with a Meet link. */
  auto_generate_meet_link: boolean | null;
  /** Inactive pages are listed but can't be read, offer no slots and can't be booked. */
  is_active: boolean | null;
  created_at: string;
}
```

## BookingPage

The full row returned inside [`BookingPageDetail`](#bookingpagedetail).

```ts title="types/clndr.ts"
export interface BookingPage extends BookingPageSummary {
  /** The host's clndr.pro account id. */
  user_id: string;
  updated_at: string;
  /** The availability schedule the page uses. `null` = all of the host's schedules. */
  availability_set_id: string | null;
  /** The team allowed to book a `team` page. */
  allowed_team_id: string | null;
  /** Whether the hosted page asks visitors of a private page for an access code. */
  show_access_code_prompt: boolean;
  /** Whether the page is listed on www.clndr.pro/{username}. */
  show_on_profile: boolean;
}
```

## UserProfile

The host's public profile.

```ts title="types/clndr.ts"
export interface UserProfile {
  /** 3–30 characters: lowercase letters, digits, `_` and `-`. */
  username: string;
  full_name: string | null;
  bio: string | null;
  avatar_url: string | null;
  /** IANA timezone the host's availability is defined in, e.g. "Europe/London". */
  timezone: string;
}
```

`timezone` is also the timezone the `date` parameter of [List open slots](/api-reference/operations/listSlots) is read in.

## BookingQuestion

A question the host asks every guest.

```ts title="types/clndr.ts"
export interface BookingQuestion {
  /** Send as `responses[].questionId`. */
  id: string;
  question_text: string;
  question_type: QuestionType;
  /** Choices for a `select` question; `null` otherwise. */
  options: string[] | null;
  /** Collect an answer before submitting. The API doesn't enforce it. */
  is_required: boolean | null;
  /** Show questions in ascending order. */
  order_index: number;
}
```

## BookingPageDetail

[Get a booking page](/api-reference/operations/getBookingPage) returns this. It's everything a booking form needs.

```ts title="types/clndr.ts"
export interface BookingPageDetail {
  bookingPage: BookingPage;
  userProfile: UserProfile;
  /** Active questions, sorted by `order_index`. */
  questions: BookingQuestion[];
}
```

The three keys are camelCase because they're the API's own envelope; the objects inside are rows, so their fields are snake_case.

## TimeSlot

An item of [List open slots](/api-reference/operations/listSlots).

```ts title="types/clndr.ts"
export interface TimeSlot {
  /** UTC with milliseconds, e.g. "2026-10-15T08:40:00.000Z". */
  start: string;
  /** `start` plus the page's `duration_minutes`. */
  end: string;
}
```

Book a slot by sending `start` and `end` back unchanged as `startTime` and `endTime`.

## Booking

A meeting on the host's calendar, as returned by [Create a booking](/api-reference/operations/createBooking), [List bookings](/api-reference/operations/listBookings) and [Confirm or cancel a booking](/api-reference/operations/updateBooking).

```ts title="types/clndr.ts"
export interface Booking {
  id: string;
  booking_page_id: string;
  /** The host. */
  user_id: string;
  guest_name: string;
  guest_email: string;
  /** Postgres timestamps, e.g. "2026-10-15T08:40:00+00:00". Parse with `new Date()`. */
  start_time: string;
  end_time: string;
  status: BookingStatus;
  cancellation_reason: string | null;
  reminder_sent: boolean | null;
  /** Set once a Meet link exists: at booking time on direct pages, at confirmation on approval pages. */
  google_meet_link: string | null;
  google_calendar_event_id: string | null;
  google_calendar_id: string | null;
  /** Not updated by PATCH/DELETE through the API; see SyncStatus. */
  sync_status: SyncStatus;
  last_synced_at: string | null;
  /** Why the Google event couldn't be created, e.g. "Google Calendar is not connected". */
  sync_failure_reason: string | null;
  created_at: string;
  /** Changes on every status change: use it to detect updates when you sync. */
  updated_at: string;
}
```

`start_time`, `created_at` and the other row timestamps arrive in Postgres's format (`+00:00`) while slot times use `Z` with milliseconds. They're the same instant: compare with `Date.parse()`, never as strings.

## BookingWithResponses

[Get a booking](/api-reference/operations/getBooking) adds the guest's answers.

```ts title="types/clndr.ts"
export interface BookingResponse {
  question_id: string;
  answer: string;
}

export interface BookingWithResponses extends Booking {
  meeting_responses: BookingResponse[];
}
```

The SDK's `bookings.get()` is typed as returning `Booking`, so cast the result to read the answers:

```ts
import type { BookingWithResponses } from '@/types/clndr';

const booking = (await clndr.bookings.get(id)) as unknown as BookingWithResponses;
for (const r of booking.meeting_responses) console.log(r.question_id, r.answer);
```

Match `question_id` against the page's `questions[].id` to show the question text next to each answer.

## CreateBookingInput

The body of [Create a booking](/api-reference/operations/createBooking).

```ts title="types/clndr.ts"
export interface CreateBookingInput {
  /** `id` of one of your booking pages. */
  bookingPageId: string;
  guestName: string;
  /** Confirmation emails go here. */
  guestEmail: string;
  /** A slot's `start`, unchanged. */
  startTime: string;
  /** The same slot's `end`. */
  endTime: string;
  /**
   * Answers, one per answered question. Leave out skipped questions. Every
   * `questionId` must belong to this page: one unknown id and none are saved.
   */
  responses?: Array<{ questionId: string; answer: string }>;
}
```

Answers are always strings. For a `checkbox` question send something readable like `"Yes"`; for `select`, send the chosen option.

## UpdateBookingInput

The body of [Confirm or cancel a booking](/api-reference/operations/updateBooking).

```ts title="types/clndr.ts"
export interface UpdateBookingInput {
  status: 'confirmed' | 'cancelled';
  /** Stored as `cancellation_reason`. Omitting it clears any earlier reason. */
  reason?: string;
}
```

## ApiError

Every non-2xx response body.

```ts title="types/clndr.ts"
export interface ApiError {
  /** A sentence you can log, e.g. "Booking page not found". */
  error: string;
}
```

The SDK throws it as a `ClndrError` with `message` set to `error`, `status` set to the HTTP status and `data` set to this body. [Errors and rate limits](/errors) lists the messages.

## What the SDK types cover

`@clndr-pro/sdk` (and `@clndr-pro/react`, which re-exports them) ships these types:

| SDK type | Matches | Differences |
| --- | --- | --- |
| `BookingPage` | [`BookingPageSummary`](#bookingpagesummary) | Used for both `list()` and `get()`. On `get()`, the extra [`BookingPage`](#bookingpage) fields are present at runtime but not typed. `max_days_ahead`, `buffer_time_minutes`, `auto_generate_meet_link` and `is_active` are typed as never `null`. |
| `BookingQuestion` | [`BookingQuestion`](#bookingquestion) | `is_required` typed as `boolean`. |
| `UserProfile` | [`UserProfile`](#userprofile) | `timezone` typed as `string \| null`. |
| `BookingPageDetail` | [`BookingPageDetail`](#bookingpagedetail) | Same shape. |
| `TimeSlot` | [`TimeSlot`](#timeslot) | Same. |
| `Booking` | [`Booking`](#booking) | Declares `id`, `booking_page_id`, `user_id`, `guest_name`, `guest_email`, `start_time`, `end_time`, `status` (without `completed`), `google_meet_link` and `created_at`. The other fields arrive but aren't typed. |
| `CreateBookingInput` | [`CreateBookingInput`](#createbookinginput) | Same. |
| `ClndrError` | [`ApiError`](#apierror) | A class: `message`, `status`, `data`. |

If you'd rather generate types than copy them, the OpenAPI spec is at [`/openapi.json`](/openapi.json):

```bash
npx openapi-typescript https://docs.clndr.pro/openapi.json -o types/clndr-api.d.ts
```

That gives you `components['schemas']['Booking']` and friends, plus typed paths for clients like `openapi-fetch`.

---

# Errors and rate limits

When a request fails, the API answers with a non-2xx status and a JSON body holding one human-readable message:

```json
{ "error": "API key is missing required scope(s): bookings:read" }
```

Branch on the status code. The messages are written for people and may get clearer over time, so log them and show them, but don't match on their exact text.

## Status codes

| Status | Means | Retry? |
| --- | --- | --- |
| `400` | The request is malformed | No, change the request |
| `401` | The key is missing, unknown, revoked or expired | No, fix the key |
| `403` | The key lacks a scope, or the page belongs to another account | No |
| `404` | No such booking page or booking on this key's account | No |
| `409` | The slot can't be booked: taken, or not an open slot | Not the same slot. Fetch the slots again and book another. |
| `429` | Rate limited: the key's per-minute limit, or the guest email's hourly booking limit | Yes, after `Retry-After` seconds (key limit) or at the top of the next hour (guest limit) |
| `500` | Failed on clndr.pro's side | Yes, with backoff |

## Authentication errors

Every endpoint can return these.

| Status | `error` | Cause |
| --- | --- | --- |
| `401` | ``Missing API key. Send `Authorization: Bearer <key>` or `x-clndr-key` header.`` | No key arrived. Usually a request to `clndr.pro` instead of `www.clndr.pro`: the redirect drops the header. |
| `401` | `Invalid API key` | The key doesn't exist: a typo, a truncated paste, or a deleted key. |
| `401` | `API key has been revoked` | The key was revoked in the dashboard. |
| `401` | `API key has expired` | The key had an expiry date and it has passed. |
| `403` | `API key is missing required scope(s): bookings:read` | A publishable key on a secret-only endpoint. The message names the missing scopes. |
| `429` | `Rate limit exceeded. This publishable key allows 120 requests per 60s window.` | See [Rate limits](#rate-limits). |

## Endpoint errors

| Endpoint | Status | `error` |
| --- | --- | --- |
| [Get a booking page](/api-reference/operations/getBookingPage) | `404` | `Booking page not found` (wrong slug, or the page is inactive) |
| [List open slots](/api-reference/operations/listSlots) | `400` | ``Missing required `date` query param (YYYY-MM-DD)`` |
| | `400` | `` `date` must be YYYY-MM-DD or an ISO 8601 timestamp `` |
| | `404` | `Booking page not found` |
| [Create a booking](/api-reference/operations/createBooking) | `400` | `Invalid JSON body` |
| | `400` | `Missing required fields: bookingPageId, guestName, guestEmail, startTime, endTime` |
| | `400` | `` `guestEmail` must be a valid email address `` |
| | `400` | ``` `startTime` and `endTime` must be ISO 8601 timestamps, with `endTime` after `startTime` ``` |
| | `400` | ``` `responses` must be an array of { questionId, answer } ``` |
| | `400` | `Booking page not found` (the page is inactive) |
| | `403` | `This booking page does not belong to the API key owner` |
| | `409` | `This time slot is not available. Fetch the slots again and pick another.` (publishable key, and the time isn't an open slot right now) |
| | `409` | `This time slot is no longer available. Please pick another.` (another booking took it first) |
| | `429` | `Too many booking requests. Please try again later.` (this guest email used its 5 booking attempts for the current clock hour; no `Retry-After`, resets at the top of the hour) |
| | `500` | `Failed to create meeting` or `An unexpected error occurred` (failed on clndr.pro's side; check whether the booking exists before retrying, see [Retrying](#retrying)) |
| [Get a booking](/api-reference/operations/getBooking), [cancel](/api-reference/operations/cancelBooking) | `404` | `Booking not found` |
| [Confirm or cancel a booking](/api-reference/operations/updateBooking) | `400` | `Invalid JSON body` |
| | `400` | `` `status` must be "confirmed" or "cancelled" `` |
| | `404` | `Booking not found` |

A `500` carries a short message such as `Failed to fetch bookings` or `Failed to update booking`.

## In the SDK

`@clndr-pro/sdk` throws a `ClndrError` for any non-2xx response. It carries the message, the status and the parsed body:

```ts title="lib/book.ts"
import { Clndr, ClndrError } from '@clndr-pro/sdk';

const clndr = new Clndr(process.env.CLNDR_SECRET_KEY!);

try {
  await clndr.bookings.create(input);
} catch (err) {
  if (err instanceof ClndrError && err.status === 409) {
    // Someone else took the slot: refetch slots and let the guest pick again.
  } else {
    throw err;
  }
}
```

`err.status` is the HTTP status, `err.message` is the API's `error`, and `err.data` is the whole response body. Network failures (DNS, timeouts) aren't wrapped: they reject with whatever `fetch` threw. The React hooks expose the same error object as `error`.

## Rate limits

Each key gets a fixed 60-second window:

| Key | Requests per 60 s |
| --- | --- |
| Secret | 300 |
| Publishable | 120 |

The count is per key, not per visitor: every guest on your site shares your publishable key's 120 requests a minute. A booking flow costs about one request per date the guest looks at, plus two (page and booking), so this covers a busy site. If you outgrow it, move slot lookups to your server and cache them for a minute.

A `429` comes with these headers:

| Header | Value |
| --- | --- |
| `Retry-After` | Seconds until the window resets |
| `X-RateLimit-Limit` | 300 or 120 |
| `X-RateLimit-Remaining` | `0` |
| `X-RateLimit-Reset` | When the window resets, in Unix seconds |

Successful responses don't include them, so you can't watch your remaining budget; back off when you get a `429`.

Two other limits apply to bookings specifically: one guest email address gets five booking attempts per clock hour, counting attempts that then fail (a `429` without `Retry-After`; it resets at the top of the hour), and each account can create five API keys an hour in the dashboard.

## Retrying

`GET` requests are safe to retry. So are `PATCH` and `DELETE` on a booking, with two details: a `PATCH` without `reason` clears any `cancellation_reason` already stored, so resend the same `reason`; and `PATCH` doesn't check the current status, so confirming retries are safe but a stale "confirm" after the host declined confirms the booking again.

`POST /bookings` isn't. If a create times out, the booking may exist. Retrying the same slot then fails with a `409`, which might be your own first attempt. From a server, look for the booking (`clndr.bookings.list({ status: 'confirmed' })` or `'pending'`, matching `guest_email` and `start_time`) before telling the guest anything. In the browser, show the guest a neutral message and refetch the slots.

A small wrapper that honours `Retry-After` on idempotent requests:

```ts title="lib/clndr-fetch.ts"
const BASE = 'https://www.clndr.pro/api/v1';

export async function clndrGet<T>(path: string, key: string, attempts = 3): Promise<T> {
  for (let attempt = 1; ; attempt++) {
    const res = await fetch(BASE + path, { headers: { Authorization: `Bearer ${key}` } });
    if (res.ok) return (await res.json()) as T;

    const retryable = res.status === 429 || res.status >= 500;
    if (!retryable || attempt === attempts) {
      const body = await res.json().catch(() => ({}));
      throw new Error(`${res.status} ${body.error ?? res.statusText}`);
    }

    const wait = Number(res.headers.get('Retry-After')) || 2 ** attempt;
    await new Promise((resolve) => setTimeout(resolve, wait * 1000));
  }
}
```

---

# Prompts for Claude Code

Each prompt below is a complete brief. Open Claude Code at the root of the project you want to change, paste one, and answer the questions it comes back with (usually your booking page's slug, sometimes your clndr.pro username). The prompts tell the agent which docs pages to read, spell out the facts it tends to get wrong, and end with a "done when" list it should check before stopping.

They assume:

- you have a clndr.pro account with at least one booking page and some [availability](https://www.clndr.pro/availability),
- you'll create the key yourself under [**API keys**](https://www.clndr.pro/api-keys) and put it in `.env.local`. The prompts never ask for the key's value, and you shouldn't paste it in,
- Claude Code can fetch URLs. If it can't, install the [skill](/ai/tools#the-claude-code-skill) first; it carries the same facts offline.

Not sure which one you need? Start with the first. It looks at the project and picks.

## Any project

<Prompt title="Add clndr.pro booking to this project">

```text
Add clndr.pro booking to this project.

Read these first. They are Markdown pages written for coding agents:
- https://docs.clndr.pro/llms.txt (index of every docs page)
- https://docs.clndr.pro/integration-options.md
- https://docs.clndr.pro/nextjs.md for a Next.js app, otherwise https://docs.clndr.pro/react/components.md or, for a site without React, https://docs.clndr.pro/embed/script.md

Facts to rely on:
- API base URL: https://www.clndr.pro/api/v1. Always the www host: the bare domain redirects and the redirect drops the Authorization header.
- Packages: @clndr-pro/react (components and hooks, browser) and @clndr-pro/sdk (typed client, mainly server). Use @clndr-pro/react 0.2.1+ and @clndr-pro/sdk 0.1.5+. With older versions, pass baseUrl "https://www.clndr.pro".
- Import @clndr-pro/react only from files marked 'use client'.
- Publishable key (clndr_pk_...) goes in NEXT_PUBLIC_CLNDR_PUBLISHABLE_KEY. It is browser-safe and can read booking pages and slots and create bookings.
- Secret key (clndr_sk_...) goes in CLNDR_SECRET_KEY. Server only. It can also list, confirm and cancel bookings. Never import it into client code.

Steps:
1. Look at the project: framework and router, styling (Tailwind? shadcn/ui under components/ui?), and where a booking page fits. Tell me what you found and which integration you'll use before you change files.
2. Ask me for the booking page slug. Ask for my clndr.pro username too if you pick an embed.
3. Add the env vars to .env.example with placeholder values and tell me to put the real keys in .env.local.
4. Build it with the project's existing components and styles.
5. Run the type checker and the build, and fix what breaks.
```

</Prompt>

## Next.js

<Prompt title="Drop-in booking page with shadcn components">

```text
Add a /book page to this Next.js App Router app that shows my clndr.pro booking form, rendered with this project's own shadcn/ui components.

Read first: https://docs.clndr.pro/quickstart.md, https://docs.clndr.pro/nextjs.md and https://docs.clndr.pro/react/styling.md

Facts:
- Install @clndr-pro/react 0.2.1 or later. It talks to https://www.clndr.pro by default.
- ClndrProvider takes publishableKey={process.env.NEXT_PUBLIC_CLNDR_PUBLISHABLE_KEY!}. Put it in its own app/providers.tsx ('use client') and wrap {children} in app/layout.tsx with it. Don't make the root layout a client component.
- <BookingInline slug="..." /> renders the whole flow: date, slots, the host's questions, confirmation. Import it only from a 'use client' file; keep app/book/page.tsx a Server Component that renders that client file.
- Restyle it with components={{ Button, Input, Label, Textarea }} (pass the shadcn components) and classNames={{ root, heading, muted, slotGrid, slotButton, ... }} (Tailwind classes). The full slot and className list is in react/styling.md.
- The page's description is Markdown; it renders automatically.

Steps:
1. Check that shadcn/ui is set up (components.json, components/ui). Add button, input, label and textarea with the shadcn CLI if missing.
2. Ask me for the booking page slug.
3. Create app/providers.tsx, update app/layout.tsx, create app/book/page.tsx and app/book/booking-widget.tsx.
4. Map the slots to our components and theme tokens so it matches the rest of the site in light and dark mode.
5. Add NEXT_PUBLIC_CLNDR_PUBLISHABLE_KEY to .env.example; tell me to set it in .env.local. Run the type checker and build; fix what breaks.

Done when: /book renders without hydration warnings, every @clndr-pro/react import sits in a 'use client' file, and the form uses our Button and Input.
```

</Prompt>

<Prompt title="Custom booking widget with shadcn/ui and the hooks">

```text
Build a custom booking widget for my clndr.pro booking page in this project, using shadcn/ui and the @clndr-pro/react hooks instead of the built-in form: a calendar, open times for the picked day, the host's questions, and a confirmation state.

Read first: https://docs.clndr.pro/tutorials/shadcn-booking-widget.md, https://docs.clndr.pro/react/hooks.md and https://docs.clndr.pro/concepts.md

Facts:
- @clndr-pro/react 0.2.1+. Hooks need <ClndrProvider publishableKey={process.env.NEXT_PUBLIC_CLNDR_PUBLISHABLE_KEY!}> above them, in a 'use client' file.
- useBookingPage(slug) -> { data: { bookingPage, userProfile, questions } | null, isLoading, error }.
- useAvailableSlots(slug, date: Date | null) -> { slots: [{ start, end }], isLoading, error, refetch }. The date is read as a calendar day in the HOST's timezone (userProfile.timezone). Build it as new Date(year, monthIndex, day), never new Date('YYYY-MM-DD').
- useCreateBooking() -> { create, isLoading, error, data }. create({ bookingPageId: bookingPage.id, guestName, guestEmail, startTime: slot.start, endTime: slot.end, responses: [{ questionId, answer }] }). Send slot times unchanged.
- Show slot times in the guest's local timezone. Past slots are already excluded; days past bookingPage.max_days_ahead return no slots, so disable them in the calendar.
- question_type is text | email | textarea | phone | select (with options) | checkbox. The API doesn't enforce is_required: validate in the form.
- booking_type 'approval' means the booking is pending: say "Request sent", not "Booked". A taken slot fails with HTTP 409 (message starts "This time slot"): call refetch() from useAvailableSlots.
- bookingPage.description is Markdown.

Steps:
1. Check shadcn/ui is set up; add calendar, button, card, input, label, textarea and skeleton if missing.
2. Ask me for the booking page slug and where the widget should live.
3. Build the widget as one 'use client' component with loading skeletons, an empty state for days with no times, inline errors and a success state.
4. Add NEXT_PUBLIC_CLNDR_PUBLISHABLE_KEY to .env.example. Run the type checker and build; fix what breaks.

Done when: it works with the keyboard, looks right in light and dark mode and at 375px wide, and a booking made with it shows up under Meetings in the clndr.pro dashboard.
```

</Prompt>

<Prompt title='A "Book a call" button that opens a dialog'>

```text
Add a "Book a call" button to this site's header that opens my clndr.pro booking form in a shadcn/ui Dialog, without leaving the page.

Read first: https://docs.clndr.pro/tutorials/shadcn-booking-dialog.md and https://docs.clndr.pro/react/components.md

Facts:
- @clndr-pro/react 0.2.1+, imported only from 'use client' files. ClndrProvider with publishableKey={process.env.NEXT_PUBLIC_CLNDR_PUBLISHABLE_KEY!} must be above the button (app/providers.tsx wrapping {children} in the root layout).
- Render <BookingForm slug="..." components={{ Button, Input, Label, Textarea }} onBooked={...} /> inside the Dialog. Use the project's shadcn Dialog rather than the package's BookingModal, so focus trapping, escape and styling match the site.
- onBooked(bookingId) fires after a successful booking. Keep the confirmation visible for a moment, then close the dialog.
- The form fetches the booking page when it mounts, so render it only while the dialog is open.

Steps:
1. Find the site header/navbar component and check shadcn/ui (add dialog and button if missing).
2. Ask me for the booking page slug and the button label.
3. Build a 'use client' BookCallButton and put it in the header. Make the dialog scroll on small screens.
4. Add NEXT_PUBLIC_CLNDR_PUBLISHABLE_KEY to .env.example. Run the type checker and build; fix what breaks.

Done when: the dialog opens from the keyboard, closes on Escape, and the header stays a Server Component if it was one.
```

</Prompt>

<Prompt title="Book through a server action">

```text
Build a /book page in this Next.js App Router project that books clndr.pro meetings through a server action, so the browser never calls clndr.pro and no clndr.pro key reaches the client.

Read first: https://docs.clndr.pro/tutorials/server-actions.md and https://docs.clndr.pro/sdk.md

Facts:
- @clndr-pro/sdk 0.1.5+; client in lib/clndr.ts with `import 'server-only'` and new Clndr(process.env.CLNDR_SECRET_KEY!). Never use NEXT_PUBLIC_ for the secret key.
- clndr.bookingPages.get(slug) -> { bookingPage, userProfile, questions }. clndr.bookingPages.getSlots(slug, 'YYYY-MM-DD') -> [{ start, end }]; the date is a calendar day in the host's timezone and past slots are excluded.
- clndr.bookings.create({ bookingPageId, guestName, guestEmail, startTime, endTime, responses }) with slot start/end unchanged. booking_type 'approval' -> "Request sent".
- The API doesn't enforce required questions. Re-check the slot is still in getSlots() right before create. Errors throw ClndrError { status, message }.

Steps: follow the tutorial's structure (lib/clndr.ts, app/book/page.tsx, app/book/actions.ts with zod, app/book/booking-form.tsx with useActionState). Ask me for the slug first. Add CLNDR_SECRET_KEY to .env.example. Run the type checker and build; fix what breaks.

Done when: no 'use client' file imports lib/clndr.ts, slot times show in the guest's timezone, and a taken slot shows a clear message.
```

</Prompt>

## Server side

<Prompt title="Approvals screen in my admin">

```text
Add an admin page at /admin/bookings that lists pending clndr.pro bookings with the guest's answers and lets me approve or decline them.

Read first: https://docs.clndr.pro/tutorials/approvals-dashboard.md and https://docs.clndr.pro/types.md

Facts:
- Secret key, server only: lib/clndr.ts with `import 'server-only'`, new Clndr(process.env.CLNDR_SECRET_KEY!) from @clndr-pro/sdk 0.1.5+.
- clndr.bookings.list({ status: 'pending', limit }) (latest start first, max 200). clndr.bookings.get(id) adds meeting_responses [{ question_id, answer }] (not in the SDK type: cast). Question text: clndr.bookingPages.get(slug).questions.
- Approve: clndr.bookings.update(id, { status: 'confirmed' }). Decline: update(id, { status: 'cancelled', reason }).
- API approvals send no clndr.pro email; Google invites the guest only when the page makes Meet links. Declines send nothing. We send our own emails.

Steps: find the project's auth and email setup and tell me what you'll use; protect the page and both server actions; build the table, approve button and decline dialog; send the emails; update .env.example; run the type checker and build.

Done when: the secret key is only in server files, both actions check admin access, and past requests can't be approved.
```

</Prompt>

<Prompt title="Sync bookings into my database">

```text
Keep a copy of my clndr.pro bookings in this project's database with a polling cron and an instant update when a booking is made on our site.

Read first: https://docs.clndr.pro/tutorials/sync-bookings.md and https://docs.clndr.pro/types.md

Facts:
- No webhooks. Poll with the secret key on the server: clndr.bookings.list({ status, limit: 200 }) for pending, confirmed and cancelled. Max 200, no cursor, latest start_time first.
- Rows are snake_case and include updated_at and cancellation_reason (not in the SDK type: use a local type). clndr.bookings.get(id) returns 404 for ids outside my account.
- Secret key limit: 300 requests per minute.
- BookingInline's onBooked(bookingId) and the embed's onBookingSuccessful({ meetingId }) give the id in the browser.

Steps: find the database, ORM and scheduler and tell me what you'll use; add a clndr_bookings table keyed by the clndr.pro id; write an idempotent upsert keyed on updated_at with a change hook; add a CRON_SECRET-protected cron route every 10 minutes and a POST route that fetches one booking by id; wire our booking form's success callback to it; update .env.example; run the type checker and build.

Done when: a second sync run changes nothing, the cron route rejects requests without the secret, and the secret key is never in client code.
```

</Prompt>

## Sites without React

<Prompt title="Embed booking on a WordPress, Webflow or HTML site">

```text
Embed my clndr.pro booking page on this site. It isn't a React app, so use the embed script.

Read first: https://docs.clndr.pro/embed/script.md and https://docs.clndr.pro/embed/iframe.md

Facts:
- No API key is needed. The booking link is "username/slug", the last two parts of the hosted page URL (www.clndr.pro/ada/intro-call -> "ada/intro-call").
- Load https://www.clndr.pro/embed.js (always the www host: from the bare domain the iframe's messages are ignored and auto-resize stops working). It defines window.Clndr. Call it only after the script has loaded.
- Clndr.inline({ elementOrSelector, link, config }), Clndr.modal({ link, config }), Clndr.floatingButton({ link, buttonText, position: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left', config }). Each returns an object with destroy().
- config: theme ('light' | 'dark' | 'auto'), hideEventTypeDetails, primaryColor (any CSS colour), prefill { name, email }, accessCode (for private pages), onBookingSuccessful(payload { meetingId, startTime, endTime }), onRouteChanged.
- The inline iframe resizes itself to its content.
- Fallback without JavaScript: <iframe src="https://www.clndr.pro/embed/{username}/{slug}?theme=auto"> with a min-height.

Steps:
1. Work out how this site is built (static HTML, a template engine, WordPress theme, Webflow export) and where custom HTML goes. Tell me before changing anything.
2. Ask me for the booking link (username/slug) and whether I want it inline on a page, as a popup from an existing button, or as a floating button.
3. Add it, matching primaryColor and theme to the site's colours.
4. If I use analytics, fire an event from onBookingSuccessful.

Done when: the widget loads on a fresh page load, works on a 375px-wide screen, and there are no console errors.
```

</Prompt>

## Fix an existing integration

<Prompt title="Audit and upgrade my clndr.pro integration">

```text
Audit this project's clndr.pro integration and fix what's wrong. Look for every use of clndr.pro: @clndr/*, @clndr-pro/*, "clndr" in env vars, fetch calls to clndr.pro, embed scripts and iframes.

Read first: https://docs.clndr.pro/troubleshooting.md and https://docs.clndr.pro/llms.txt

Check and fix:
1. Package names: @clndr/sdk and @clndr/react never existed on npm. The packages are @clndr-pro/sdk and @clndr-pro/react.
2. Versions: upgrade to @clndr-pro/react 0.2.1+ and @clndr-pro/sdk 0.1.5+. Older versions default to https://clndr.pro, which redirects and drops the API key (401 "Missing API key"). Any hard-coded base URL must be https://www.clndr.pro (REST: https://www.clndr.pro/api/v1). Same for embed.js and iframe URLs.
3. Client boundaries: @clndr-pro/react imports only in 'use client' files; ClndrProvider in its own client providers file, not a client root layout.
4. Key leaks: the secret key (clndr_sk_..., CLNDR_SECRET_KEY) must never appear in client code, NEXT_PUBLIC_* variables, committed files or logs. Browser code uses the publishable key (clndr_pk_..., NEXT_PUBLIC_CLNDR_PUBLISHABLE_KEY). If a secret key is committed anywhere, stop and tell me so I can revoke it in the dashboard.
5. Slot dates: getSlots/useAvailableSlots read the date as a day in the host's timezone. Replace new Date('YYYY-MM-DD') with new Date(y, m - 1, d) or pass the 'YYYY-MM-DD' string to getSlots.
6. Field names: request bodies are camelCase (bookingPageId, guestEmail, startTime); responses are snake_case rows wrapped in { data }.
7. Approval pages: success copy must say the request was sent, not confirmed.

Then run the type checker and build. Report each finding with the file and line, what you changed, and anything you need me to do (revoke a key, set an env var in production).
```

</Prompt>

## Install the skill instead

If you integrate clndr.pro often, install the [clndr.pro skill](/ai/tools#the-claude-code-skill) once. Claude Code then loads the same facts on its own whenever a task mentions clndr.pro, and short requests ("put my intro call booking page on /book") work without a prompt from this page.

---

# Docs for AI tools

Coding agents do better with plain text than with a rendered page, so every page of these docs has a machine-readable twin. Pick the one that fits the tool you're using.

| You're using | Give it |
| --- | --- |
| Claude Code, every session in a project | [The clndr.pro skill](#the-claude-code-skill) |
| Any agent that can call MCP tools | [The docs MCP server](#mcp-server) |
| An agent that can fetch URLs | [`/llms.txt`](/llms.txt), then the paths it lists with `.md` appended |
| A chat window with a big context | [`/llms-full.txt`](/llms-full.txt), pasted or attached |
| A code generator, Postman, Insomnia | [`/openapi.json`](/openapi.json) |

## Markdown for every page

Add `.md` to any URL here and you get the page as Markdown: no navigation, no scripts, components flattened into plain blocks. Prompt cards keep their prompt as a fenced code block.

```text
https://docs.clndr.pro/index.md                                  ← the introduction
https://docs.clndr.pro/quickstart.md
https://docs.clndr.pro/tutorials/shadcn-booking-widget.md
https://docs.clndr.pro/api-reference/operations/createBooking.md ← one endpoint
```

The **Copy Markdown** button at the top of each guide page copies the same text (API reference pages have their `.md` URLs but no button). Next to it, the **Open** menu sends the page to ChatGPT, Claude, Perplexity, Grok or Google with "Read this page and help me understand it", installs the MCP server below into Cursor or VS Code, or copies a ready-made command for Claude Code, Codex, OpenCode or Antigravity.

## llms.txt

[`/llms.txt`](/llms.txt) follows the [llms.txt convention](https://llmstxt.org): a short Markdown index with one line per docs page (title, link, description) and one per API operation. The links are site-relative HTML paths such as `/quickstart` or `/api-reference/operations/listSlots`; add `.md` and the domain to fetch one as Markdown (`https://docs.clndr.pro/quickstart.md`). It's small enough for an agent to read first and decide which pages it needs.

[`/llms-full.txt`](/llms-full.txt) is the whole site in one file: every guide, tutorial and API operation, in nav order. Use it when you'd rather hand a model everything at once than let it fetch page by page.

Both are rebuilt with each deploy, so they always match the site.

## MCP server

`https://docs.clndr.pro/api/mcp` is a [Model Context Protocol](https://modelcontextprotocol.io) server over HTTP. It's read-only and needs no key: it serves these docs and nothing else, and has no access to your clndr.pro account.

| Tool | What it returns |
| --- | --- |
| `search` | Ranked matches across docs pages and API operations for a query |
| `get_doc` | One docs page's source, by slug (`quickstart`, `react/hooks`, …) |
| `list_operations` | Every API operation: operationId, method, path, summary, tag |
| `get_operation` | One operation's parameters, request body and responses, as Markdown |

<Tabs>
<Tab title="Claude Code">

```bash
claude mcp add --transport http clndr-docs https://docs.clndr.pro/api/mcp
```

Add `--scope project` to write it to the project's `.mcp.json` so everyone on the repo gets it.

</Tab>
<Tab title="Cursor">

```json title=".cursor/mcp.json"
{
  "mcpServers": {
    "clndr-docs": { "url": "https://docs.clndr.pro/api/mcp" }
  }
}
```

Or use **Open → Open in Cursor** on any page.

</Tab>
<Tab title="VS Code">

```json title=".vscode/mcp.json"
{
  "servers": {
    "clndr-docs": { "type": "http", "url": "https://docs.clndr.pro/api/mcp" }
  }
}
```

Or use **Open → Open in VS Code** on any page.

</Tab>
</Tabs>

## The Claude Code skill

A skill is a Markdown file Claude Code loads on its own whenever a task matches the skill's description. The clndr.pro skill holds what an agent most often gets wrong: the `www` base URL, which key goes where, `'use client'` boundaries, the slot `date` semantics, the endpoint table, and a checklist to run before calling the job done. It links back here for everything longer.

Install it into a project:

```bash
mkdir -p .claude/skills/clndr-pro && curl -fsSL https://docs.clndr.pro/skills/clndr-pro/SKILL.md -o .claude/skills/clndr-pro/SKILL.md
```

Or for every project on your machine:

```bash
mkdir -p ~/.claude/skills/clndr-pro && curl -fsSL https://docs.clndr.pro/skills/clndr-pro/SKILL.md -o ~/.claude/skills/clndr-pro/SKILL.md
```

Commit the project copy so your teammates get it too. Run the command again to update it. With the skill installed, a request as short as "add a clndr.pro booking page at /book" is enough; the [prompt library](/ai/claude-code) is for when you want a specific shape.

## OpenAPI spec

[`/openapi.json`](/openapi.json) is the OpenAPI 3.1 document the [API reference](/api-reference) is rendered from. It's served with `Access-Control-Allow-Origin: *`, so browser tools can load it directly.

```bash
# TypeScript types for every request and response
npx openapi-typescript https://docs.clndr.pro/openapi.json -o types/clndr-api.d.ts
```

In Postman or Insomnia, import it by URL and set the bearer token to your key. Each operation also carries `x-required-scopes` and `x-key-types`, which say which scope and which key type it needs.

## Keep keys out of the conversation

Agents read files, run commands and keep transcripts. Treat your keys accordingly:

- Put keys in `.env.local` and make sure it's in `.gitignore`. Tell the agent the variable name (`CLNDR_SECRET_KEY`), never the value. Every prompt on this site is written that way.
- Don't paste a key into a prompt, and don't ask an agent to print environment variables.
- Use a separate key for local development. A publishable key is enough to build and test any browser-side booking flow.
- Review diffs for `clndr_sk_` before you commit.

If a secret key does end up in a transcript, a log or a commit, revoke it under [**API keys**](https://www.clndr.pro/api-keys) and create a new one. Revoking takes effect on the next request.

---

# Troubleshooting

Find the symptom, check the cause, apply the fix. If none of these match, email [hello@devsforfun.com](mailto:hello@devsforfun.com) with the request URL, the status code, the `error` message and roughly when it happened. Never include the full key.

## Keys and requests

<AccordionGroup>

<Accordion title="401 Missing API key, but I am sending one">

The request went to `https://clndr.pro`, which redirects to `https://www.clndr.pro`. HTTP clients drop the `Authorization` header when a redirect changes host, so the key never arrives.

Use `https://www.clndr.pro/api/v1` everywhere. If it's the SDK, upgrade: `@clndr-pro/sdk` before 0.1.5 and `@clndr-pro/react` before 0.2.1 default to the bare domain. If you can't upgrade yet, set the base URL yourself:

```ts
new Clndr({ apiKey: process.env.CLNDR_SECRET_KEY!, baseUrl: 'https://www.clndr.pro' });
```

```tsx
<ClndrProvider publishableKey={key} baseUrl="https://www.clndr.pro">
```

The other cause is a hand-written `fetch` with an empty key: `process.env.X` was `undefined` (see the next entry), so the header said `Bearer undefined`, or wasn't set. The SDK doesn't get that far: `new Clndr({ apiKey: undefined })` throws ``Clndr: `apiKey` is required``, `new Clndr(undefined)` throws a `TypeError`, and `ClndrProvider` without a key throws ``ClndrProvider: either `publishableKey` or `client` is required``.

</Accordion>

<Accordion title="401 Invalid API key">

clndr.pro has no key with that value. Check, in order: the env var holds the whole key (they're 73 characters: `clndr_sk_` or `clndr_pk_` plus 64 hex characters); the deployment you're testing has the variable (Vercel keeps Production, Preview and Development separately); the key wasn't deleted in the dashboard.

In Next.js, a secret key read inside a `'use client'` file is always `undefined` (with the SDK that throws when the client is built, before any request), and a `NEXT_PUBLIC_` variable added after the last build isn't in the bundle until you rebuild.

</Accordion>

<Accordion title="401 API key has been revoked">

Someone revoked it under **API keys**. Create a new one and deploy it. Revoked keys can't be switched back on.

</Accordion>

<Accordion title="403 API key is missing required scope(s): bookings:read">

A publishable key called an endpoint only secret keys can use: listing, reading, confirming or cancelling bookings. Move that call to your server and use the secret key there. [Book through a server action](/tutorials/server-actions) and [Approve bookings in your admin](/tutorials/approvals-dashboard) show the shape.

</Accordion>

<Accordion title="403 This booking page does not belong to the API key owner">

The `bookingPageId` you sent belongs to a different clndr.pro account than the key. It happens when you copy a page id from one account and a key from another, or mix up staging and production keys. Fetch the page with the same key (`GET /booking-pages/{slug}`) and use its `bookingPage.id`.

</Accordion>

<Accordion title="404 Booking page not found">

Either the slug is wrong (it's the last part of the page's URL, lowercase, like `intro-call`) or the page is switched off. [List booking pages](/api-reference/operations/listBookingPages) shows every page on the account with its `slug` and `is_active`.

</Accordion>

<Accordion title="429 Rate limit exceeded">

The key used up its window: 300 requests a minute for a secret key, 120 for a publishable one, shared by everyone using that key. Wait `Retry-After` seconds. If a page fires a slots request on every render, fix the effect's dependencies; if traffic is genuinely high, fetch slots on your server and cache them briefly. See [Errors and rate limits](/errors#rate-limits).

</Accordion>

<Accordion title="CORS error in the browser console">

The API allows every origin, so a CORS error almost always hides something else. The usual one: the request went to `clndr.pro` and the browser refused to follow the redirect on a preflight. Use `https://www.clndr.pro`. If the URL is right, open the Network tab: a failed request that isn't from clndr.pro (an ad blocker, a proxy) shows up there.

</Accordion>

</AccordionGroup>

## Slots and dates

<AccordionGroup>

<Accordion title="The slot list is empty">

Go through these in order:

1. The host has no availability that weekday. Check [**Availability**](https://www.clndr.pro/availability), and check which **Hours** the booking page uses.
2. The day is past the page's **Bookable up to** limit.
3. The day is in the past, or it's today and every slot has started.
4. Bookings and calendar events fill the day. Synced Google Calendar events block slots like bookings do.
5. You asked for the wrong day. `date` is a day in the host's timezone, as `YYYY-MM-DD`.

</Accordion>

<Accordion title="Slots are a day off, or show at odd hours">

Two separate things cause this.

clndr.pro returns UTC times. Showing them without converting (slicing `"2026-10-15T08:00:00.000Z"` to `08:00`) puts every slot at its UTC time. Format them with `toLocaleTimeString()` or `Intl.DateTimeFormat`, which use the guest's timezone.

Separately, `date` means the host's day. A guest far from the host can see some of those slots fall on their previous or next day. That's correct; group slots by the guest's local date if you show a calendar. [How booking works](/concepts#timezones-worked-through) has a worked example.

Older SDKs add a third cause: before `@clndr-pro/sdk` 0.1.5, `getSlots(slug, date)` sent a `Date` as a full UTC timestamp, which can land on the neighbouring day. Upgrade, or pass the day as a `YYYY-MM-DD` string.

</Accordion>

<Accordion title="A booking failed with 409">

`This time slot is no longer available` means someone booked an overlapping time between your slots request and the guest's submit, or the guest double-submitted. `This time slot is not available` (publishable keys only, and what a publishable key usually gets for a taken slot too) means the `startTime`/`endTime` you sent isn't an open slot right now: it's in the past, beyond `max_days_ahead`, outside the host's hours, a different length than the page's duration, or no longer free. Send a slot's `start` and `end` exactly as the slots endpoint returned them.

Either way, fetch the slots again and let the guest pick. If the error came after a timed-out first attempt, the first attempt may have worked: see [Retrying](/errors#retrying).

</Accordion>

</AccordionGroup>

## React and Next.js

<AccordionGroup>

<Accordion title="createContext only works in Client Components">

A clndr.pro component or hook was imported into a Server Component. Import `@clndr-pro/react` only in files that start with `'use client'`, and keep `ClndrProvider` in its own client file rendered from your layout (see the [quickstart](/quickstart)). Versions before 0.2.1 also left the `'use client'` marker out of the published bundle, so upgrade.

</Accordion>

<Accordion title="require('@clndr-pro/sdk') fails with Cannot find module">

Versions before `@clndr-pro/sdk` 0.1.5 and `@clndr-pro/react` 0.2.1 pointed their CommonJS entry at a file that wasn't published. ES module imports (`import { Clndr } from '@clndr-pro/sdk'`) always worked. Upgrade, or switch the file to `import`.

</Accordion>

<Accordion title="useClndr must be used inside ClndrProvider">

The component isn't under the provider. Render `<Providers>` around `{children}` in `app/layout.tsx`, or wrap just the booking section in `ClndrProvider`.

</Accordion>

<Accordion title="The date picker and slot buttons are unstyled">

That's the default: the components ship plain HTML so they don't fight your CSS. Pass your own components and class names, as in [Styling and slots](/react/styling).

</Accordion>

</AccordionGroup>

## Embeds

<AccordionGroup>

<Accordion title="Clndr is not defined">

Your code ran before `embed.js` loaded. Call `Clndr` from the script's `onload` (or `onReady` with `next/script`), as in [Embed script](/embed/script#inline).

</Accordion>

<Accordion title="The embed never resizes or reports bookings, or stays blank">

Load the script and the iframe from `https://www.clndr.pro`. From the bare `clndr.pro` the frame ends up on another origin, so its messages are ignored: no resizing, no callbacks. A blank frame on a `team` page means the guest isn't signed in to clndr.pro inside the frame, which browsers block for third-party iframes; team pages can't be embedded.

</Accordion>

<Accordion title="The iframe doesn't resize">

Only the embed script, or your own message listener, resizes the frame. Check the listener compares `event.origin` with `https://www.clndr.pro` exactly, with the `www`. See [Sizing](/embed/iframe#sizing).

</Accordion>

<Accordion title="A private page says Booking page not found">

Private pages need their access code: `config.accessCode` in the script, `?c=` on the iframe URL. The code must belong to that page and not have expired.

</Accordion>

</AccordionGroup>

## Emails and calendar

<AccordionGroup>

<Accordion title="The guest didn't get a confirmation email">

On an approval page that's expected: the guest gets an email when the host confirms in the dashboard, not when they book. Confirming through the API sends no clndr.pro email (Google sends an invite if the page has Meet links). On a direct page, check the address on the booking under **Meetings**, then the guest's spam folder.

</Accordion>

<Accordion title="The booking has no Meet link">

Meet links need **Add a Google Meet link** on the booking page and the host's Google Calendar connected. For approval pages the link appears once the booking is confirmed. If it's on and still missing, read the booking's `sync_status` and `sync_failure_reason`: `Google Calendar is not connected` means the host needs to reconnect Google in the dashboard. Those two fields aren't updated when you confirm through the API, so for a booking you approved with `PATCH`, an empty `google_calendar_event_id` is the sign that no event was created.

</Accordion>

</AccordionGroup>

---

# API Reference

# clndr.pro API

The clndr.pro REST API puts your booking pages on your own site. List your booking pages, read the open time slots for a day, and create bookings from a browser or a server. From a server you can also list, confirm and cancel the bookings that come in.

**Base URL:** `https://www.clndr.pro/api/v1`

Use the `www` host. `https://clndr.pro` redirects to it, and HTTP clients drop the `Authorization` header when they follow a redirect to another host, so requests to the bare domain fail with `401 Missing API key`.

## Authentication

Send an API key with every request, as a bearer token or in the `x-clndr-key` header:

```http
Authorization: Bearer clndr_sk_4f1c…
```

Create keys in the clndr.pro dashboard under **API Keys**. A key belongs to the clndr.pro account that created it and only ever sees that account's booking pages and bookings. See [API keys](/api-keys) for rotation and storage.

| Key type | Prefix | Use it in | Default scopes |
| --- | --- | --- | --- |
| Secret | `clndr_sk_` | Your server only | `booking_pages:read` `booking_pages:slots` `bookings:create` `bookings:read` `bookings:write` |
| Publishable | `clndr_pk_` | Browsers and mobile apps | `booking_pages:read` `booking_pages:slots` `bookings:create` |

## Scopes

| Scope | Allows |
| --- | --- |
| `booking_pages:read` | List booking pages and read one with its questions |
| `booking_pages:slots` | Read open time slots |
| `bookings:create` | Create a booking on one of your pages |
| `bookings:read` | List and read bookings (guest names and emails included) |
| `bookings:write` | Confirm and cancel bookings |

A request without a required scope gets `403`. Publishable keys can never hold `bookings:read` or `bookings:write`.

## Errors

Errors return a JSON body with a human-readable message:

```json
{ "error": "Booking page not found" }
```

| Status | Meaning |
| --- | --- |
| `400` | The request is malformed: a missing field, invalid JSON, a bad email address or timestamp. The message names it. |
| `401` | The key is missing, unknown, revoked or expired. |
| `403` | The key lacks a scope, or the booking page belongs to another account. |
| `404` | No such booking page or booking for this key's account. |
| `409` | The slot is taken, or (with a publishable key) isn't one the slots endpoint offers. Fetch the slots again. |
| `429` | Rate limit hit: the key's per-minute limit (wait `Retry-After` seconds), or the guest email's 5 bookings an hour. |
| `500` | Something failed on our side. Retry with backoff. |

## Rate limits

Limits are per key, in fixed 60-second windows: **300 requests** for secret keys and **120** for publishable keys. A `429` carries `Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` (Unix seconds). Successful responses don't carry these headers.

Separately, one guest email address can create at most 5 bookings an hour.

## CORS

Every endpoint answers preflight requests with `Access-Control-Allow-Origin: *`, so a publishable key works from any origin.

## Dates and times

Timestamps are ISO 8601 in UTC, for example `2026-10-15T13:30:00.000Z`. Format them in the guest's timezone when you display them. A host's own timezone is `userProfile.timezone` on [Get a booking page](/api-reference/operations/getBookingPage).

## Field names

Request bodies use camelCase (`guestEmail`). Response objects are database rows and use snake_case (`guest_email`). The [TypeScript SDK](/sdk) has types for all of them.

# Booking pages

Booking pages, their questions and their open slots.

## List booking pages

`GET /booking-pages`

Returns every booking page on the key's account, newest first. The list includes inactive and private pages: check is_active (and visibility, if it matters to you) before you show a page to guests. Scope: booking_pages:read. Keys: secret and publishable.

**Responses:**

- `200`: Your booking pages. — `application/json`: object{data}
- `401`: The key is missing, unknown, revoked or expired. — `application/json`: object{error}
- `403`: The key doesn't have the scope this endpoint needs. — `application/json`: object{error}
- `429`: Too many requests from this key in the current 60-second window. — `application/json`: object{error}
- `500`: Something failed on our side. Retry with exponential backoff. — `application/json`: object{error}

## Get a booking page

`GET /booking-pages/{slug}`

Returns one active booking page with the host's public profile and the questions to ask guests. This is everything you need to render a booking form. Scope: booking_pages:read. Keys: secret and publishable.

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| slug | path | yes | string | The booking page's slug. |

**Responses:**

- `200`: The booking page, its host and its questions. — `application/json`: object{data}
- `401`: The key is missing, unknown, revoked or expired. — `application/json`: object{error}
- `403`: The key doesn't have the scope this endpoint needs. — `application/json`: object{error}
- `404`: No active booking page with this slug on the key's account. — `application/json`: object{error}
- `429`: Too many requests from this key in the current 60-second window. — `application/json`: object{error}
- `500`: Something failed on our side. Retry with exponential backoff. — `application/json`: object{error}

## List open slots

`GET /booking-pages/{slug}/slots`

Returns the slots a guest can book on one day, in start order. The date is a calendar day in the host's timezone (userProfile.timezone on the booking page), so a slot can fall on the previous or next day for a guest elsewhere: convert each start to the guest's timezone before you group or label it. A slot is offered when it sits inside the host's weekly availability and doesn't overlap a booking or a synced calendar event. Slots that have already started, and days beyond the page's max_days_ahead, are left out. Scope: booking_pages:slots. Keys: secret and publishable.

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| slug | path | yes | string | The booking page's slug. |
| date | query | yes | string | The day, as YYYY-MM-DD, in the host's timezone. A full ISO 8601 timestamp also works and means the host's day that contains that instant. |

**Responses:**

- `200`: Open slots for the day. Empty when the host has no availability that day. — `application/json`: object{data}
- `400`: date is missing or not a date. — `application/json`: object{error}
- `401`: The key is missing, unknown, revoked or expired. — `application/json`: object{error}
- `403`: The key doesn't have the scope this endpoint needs. — `application/json`: object{error}
- `404`: No active booking page with this slug on the key's account. — `application/json`: object{error}
- `429`: Too many requests from this key in the current 60-second window. — `application/json`: object{error}
- `500`: Something failed on our side. Retry with exponential backoff. — `application/json`: object{error}

# Bookings

Create bookings from any key; read, confirm and cancel them from a secret key.

## List bookings

`GET /bookings`

Returns bookings across all of the account's booking pages, latest start_time first. Responses include guest names and emails, so call this from your server only. Scope: bookings:read. Keys: secret.

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| status | query | no | enum("pending", "confirmed", "cancelled", "completed") | Only return bookings with this status. |
| limit | query | no | integer | How many bookings to return. Values above 200 are capped at 200. There's no cursor; narrow with status instead. |

**Responses:**

- `200`: Bookings, latest start time first. — `application/json`: object{data}
- `401`: The key is missing, unknown, revoked or expired. — `application/json`: object{error}
- `403`: The key doesn't have the scope this endpoint needs. — `application/json`: object{error}
- `429`: Too many requests from this key in the current 60-second window. — `application/json`: object{error}
- `500`: Something failed on our side. Retry with exponential backoff. — `application/json`: object{error}

## Create a booking

`POST /bookings`

Books a slot on one of your booking pages. Fetch the slots first and send the chosen slot's start and end unchanged. On a direct page the booking is confirmed straight away: the guest gets a confirmation email, the host is notified, and if the page creates Meet links a Google Calendar event is added and Google invites the guest. On an approval page the booking is pending: the host gets a request email and the guest hears nothing until the host confirms it with PATCH /bookings/{id}. With a publishable key, the start and end must match a slot that List open slots offers right now (future, inside the host's hours, within max_days_ahead), because anyone can copy that key from your page. A secret key, which only your server holds, can book any time that doesn't overlap another pending or confirmed booking, even outside the host's hours. One guest email address gets 5 booking attempts per clock hour. Scope: bookings:create. Keys: secret and publishable.

**Request body:**

- `application/json`: object{bookingPageId, guestName, guestEmail, startTime, endTime, responses}

**Responses:**

- `201`: The new booking. It doesn't include the guest's answers; read them with Get a booking. — `application/json`: object{data}
- `400`: A required field is missing, the body isn't JSON, guestEmail isn't an email address, the timestamps don't parse or end before they start, or responses isn't an array. — `application/json`: object{error}
- `401`: The key is missing, unknown, revoked or expired. — `application/json`: object{error}
- `403`: The key lacks bookings:create, or bookingPageId belongs to another account. — `application/json`: object{error}
- `409`: The slot can't be booked. With a publishable key the time isn't an open slot ("This time slot is not available. Fetch the slots again and pick another."); with any key, another booking got there first ("This time slot is no longer available. Please pick another."). Fetch the slots again and let the guest pick another. — `application/json`: object{error}
- `429`: Either the key's per-minute rate limit (with Retry-After and X-RateLimit headers), or this guest email has used its 5 booking attempts for the current clock hour ("Too many booking requests. Please try again later.", no headers; resets at the top of the hour). — `application/json`: object{error}
- `500`: Creating the booking failed on our side ("Failed to create meeting" or "An unexpected error occurred"). Check with List bookings whether it exists before you retry. — `application/json`: object{error}

## Get a booking

`GET /bookings/{id}`

Returns one booking with the guest's answers. Scope: bookings:read. Keys: secret.

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| id | path | yes | string | The booking's id. |

**Responses:**

- `200`: The booking and the guest's answers. — `application/json`: object{data}
- `401`: The key is missing, unknown, revoked or expired. — `application/json`: object{error}
- `403`: The key doesn't have the scope this endpoint needs. — `application/json`: object{error}
- `404`: No booking with this id on the key's account. — `application/json`: object{error}
- `429`: Too many requests from this key in the current 60-second window. — `application/json`: object{error}
- `500`: Something failed on our side. Retry with exponential backoff. — `application/json`: object{error}

## Confirm or cancel a booking

`PATCH /bookings/{id}`

Sets a booking's status to confirmed or cancelled, which is how you approve or decline pending bookings on approval pages. Confirming creates the Google Calendar event and Meet link when the page has auto_generate_meet_link and the booking has no event yet, and Google sends the guest the invite. clndr.pro doesn't send its own confirmation email for confirmations made through the API, so email the guest yourself when the page has no Meet link. Cancelling deletes the booking's Google Calendar event (Google tells the guest) and opens the slot up again. There's no status check: confirming a booking the host already declined confirms it again, so read it first if that matters. Scope: bookings:write. Keys: secret.

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| id | path | yes | string | The booking's id. |

**Request body:**

- `application/json`: object{status, reason}

**Responses:**

- `200`: The updated booking. — `application/json`: object{data}
- `400`: Invalid JSON, or status isn't confirmed or cancelled. — `application/json`: object{error}
- `401`: The key is missing, unknown, revoked or expired. — `application/json`: object{error}
- `403`: The key doesn't have the scope this endpoint needs. — `application/json`: object{error}
- `404`: No booking with this id on the key's account. — `application/json`: object{error}
- `429`: Too many requests from this key in the current 60-second window. — `application/json`: object{error}
- `500`: Something failed on our side. Retry with exponential backoff. — `application/json`: object{error}

## Cancel a booking

`DELETE /bookings/{id}`

Cancels a booking and deletes its Google Calendar event. The same as Confirm or cancel a booking with status: "cancelled", except that it never stores a reason. Scope: bookings:write. Keys: secret.

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| id | path | yes | string | The booking's id. |

**Responses:**

- `200`: The booking is cancelled. — `application/json`: object{success}
- `401`: The key is missing, unknown, revoked or expired. — `application/json`: object{error}
- `403`: The key doesn't have the scope this endpoint needs. — `application/json`: object{error}
- `404`: No booking with this id on the key's account. — `application/json`: object{error}
- `429`: Too many requests from this key in the current 60-second window. — `application/json`: object{error}
- `500`: Something failed on our side. Retry with exponential backoff. — `application/json`: object{error}

# Legacy

Endpoints kept for older integrations.

## List a user's profile pages (legacy)

`GET /embed/booking`

Kept for the original embed SDK. Returns any user's public profile and the active booking pages they show on it. Use List booking pages in new code. Scope: booking_pages:read. Keys: secret and publishable.

> **Deprecated.**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| username | query | yes | string | A clndr.pro username. |

**Responses:**

- `200`: The user's profile and the booking pages listed on it. Unlike every other endpoint, the body is not wrapped in data. — `application/json`: object{userProfile, bookingPages}
- `400`: username is missing. — `application/json`: object{error}
- `401`: The key is missing, unknown, revoked or expired. — `application/json`: object{error}
- `403`: The key doesn't have the scope this endpoint needs. — `application/json`: object{error}
- `404`: No such user. — `application/json`: object{error}
- `429`: Too many requests from this key in the current 60-second window. — `application/json`: object{error}

---

# Changelog

## Developer docs, and slot dates that mean what they say — 2026-10-10

**docs.clndr.pro is live.** Guides for the embed, `@clndr-pro/react`, `@clndr-pro/sdk` and the REST API, six tutorials (shadcn widgets, server actions, approvals, syncing bookings), an OpenAPI 3.1 spec at [`/openapi.json`](/openapi.json), and [prompts you can paste into Claude Code](/ai/claude-code). Every page is also Markdown at its own URL plus `.md`, indexed at [`/llms.txt`](/llms.txt), and there's an MCP server and a Claude Code skill: see [Docs for AI tools](/ai/tools).

**API: `GET /booking-pages/{slug}/slots`**

- `date=YYYY-MM-DD` now means that calendar day in the host's timezone. It used to be read as UTC midnight, so hosts west of UTC got the previous day's slots. Full ISO timestamps still work as before.
- Slots that have already started are no longer returned, and days past the page's `max_days_ahead` return an empty list.
- An unparseable `date` returns `400` instead of `500`.

**API: `POST /bookings`**

- Bookings made with a publishable key must match a slot the slots endpoint offers right now: future, inside the host's hours, within `max_days_ahead`. Anything else is a `409`. Secret keys can still book any time that doesn't overlap another booking.
- A taken slot is now `409` (was `400`), the guest-email limit `429` (was `400`), and failures on our side `500` (were `400`).
- Bad emails, unparseable or reversed timestamps, and a `responses` that isn't an array get a `400` that names the field.

**Slots.** A busy block that started inside a slot and ended with it (slot 9:00–10:00, meeting 9:30–10:00) was offered as free. Fixed for the API, the hosted page and the embed. Slots now come back sorted by start.

**Embed.** `https://www.clndr.pro/embed.js` loads on third-party pages. It used to redirect to the sign-in page, so `Clndr.inline`, `Clndr.modal` and `Clndr.floatingButton` never ran.

**Dashboard.** The API Keys page now names the real packages (`@clndr-pro/sdk` and `@clndr-pro/react`, not `@clndr/*`), shows an iframe embed snippet, tells you which env var each key belongs in, and links here.