DEV Community: Stan

I rebuilt my open-source salon booking template: one page instead of a wizard

Stan — Thu, 29 Oct 2026 08:39:49 +0000

In June I posted how I built a salon booking site in a weekend from an open-source Next.js template called Haar. Since then I've rebuilt almost all of it: the design, the booking flow, checkout, accounts and how it talks to the API. This post is the new version, with the code that matters and the parts I changed my mind about.

If you just want to click around: live demo · GitHub (MIT).

The wizard was the wrong shape

The first Haar booked like most booking widgets do: pick a service, next, pick a stylist, next, pick a day, next, pick a time, next, pay. Each step hid the thing you needed to decide the previous one. You chose a stylist before you knew whether she had anything on Thursday, and you didn't see the price with your options until the end.

People don't book a salon that way. They think "balayage, Thursday afternoon, ideally with Astrid, but whoever's free is fine". So the new booking page is one page. Numbered sections (service, stylist, day and time, finishing touches) unlock in order, and an appointment card on the right fills itself in as you go, with the total.

The part I like most is "Any stylist" mode. Every time slot shows the faces of the stylists who are free at that time, and when you pick a slot you pick the person right there, or "no preference, choose for me". You never hit a dead end where your stylist has no time that day.

All of it is one availability call

The availability logic (who can do this service, at which location, for how long, around existing bookings and days off) isn't in the template. It's an API call, made from a Next.js route handler so the key never reaches the browser. This is the template's real route, trimmed a little:

// app/api/availability/route.ts
import '@/lib/opencals';
import { ProductService } from '@opencals/storefront-sdk';
import { NextRequest, NextResponse } from 'next/server';

export async function GET(request: NextRequest) {
  const p = request.nextUrl.searchParams;
  const productId = p.get('productId');
  const date = p.get('date');
  if (!productId || !date) {
    return NextResponse.json({ error: 'productId and date are required' }, { status: 400 });
  }

  const { data } = await ProductService.getCurrentAvailabilities({
    path: { productId },
    query: {
      date,
      timezone: p.get('timezone') ?? undefined,
      staffMemberId: p.get('staffMemberId') ?? undefined, // leave out for "Any stylist"
      locationId: p.get('locationId') ?? undefined,
      // when rescheduling, the appointment's own slot must not block itself
      excludeAppointmentId: p.get('excludeAppointmentId') ?? undefined,
    },
    throwOnError: true,
  });
  return NextResponse.json(data ?? []);
}

excludeAppointmentId is easy to miss: when a customer reschedules, their current booking would otherwise block the slots around it. Passing the appointment's own id lets it move to the slot next door.

Deep links work too: /booking/balayage?date=2026-11-12&staff=…&location=… opens the page with those sections already filled, which is handy for "book again" emails and Instagram links.

One change you should copy: a private key and the buyer's IP

The June version used a public storefront key (sfk_). The template calls the API from its own server, so it now uses a private key (spk_) and forwards each visitor's IP:

// lib/opencals.ts
import { setupOpencals } from '@opencals/storefront-sdk';
import { nextBuyerIp } from '@opencals/storefront-sdk/next';

setupOpencals({
  baseUrl: process.env.OPENCALS_API_URL ?? 'https://api.opencals.com',
  apiKey: process.env.OPENCALS_API_KEY, // spk_…
  buyerIp: nextBuyerIp,
});

Without the IP forwarding, every visitor's sign-in, cart and checkout request looks like it comes from your Vercel function, so they all share one rate limit. With nextBuyerIp, the API counts each visitor separately. You create the key in the Opencals dashboard under Users → your user → API Keys; on Vercel, leave the allowed-IPs list empty.

Reserving holds the chair

When you press Reserve, the appointment goes into a cart and the card flips to "Held for you" with a countdown. Nobody else can take that slot while it's held, and if checkout takes longer, there's an Extend button next to the timer. I wrote separately about why holds are the hard part of preventing double bookings, if you want the database side of it.

Checkout is three numbered sections next to the stack of appointment cards: your details, a few questions the salon sets, and payment. The payment options are card through Stripe (including Apple Pay and Google Pay), pay at the salon, bank transfer, or free bookings.

Accounts without passwords

Customers can now sign in with a 6-digit code sent by email (a password still works), and links in booking emails sign them straight in. The account page is a "salon diary": the next visit with a countdown, past and upcoming appointments, orders as receipts, and reschedule or cancel where the salon allows it.

Mobile first, for real this time

On a phone, the appointment card becomes a sticky "Your card · $80" bar at the bottom that opens as a sheet, and checkout gets a sticky pay bar.

Deploy it

Create a free dev store at app.opencals.com and choose the HAAR Salon dataset when asked. It seeds the same services, stylists and locations as the demo.
Create a private storefront key (spk_) under Users → your user → API Keys.
Click Deploy with Vercel in the README and set two variables: OPENCALS_API_KEY (your spk_ key) and AUTH_SECRET (any random string).

Locally it's the usual:

git clone https://github.com/letsopencals/template-haar.git
cd template-haar
npm install
cp .env.example .env   # OPENCALS_API_KEY=spk_… and AUTH_SECRET=…
npm run dev

All the salon copy (name, hero, team, hours, contact) lives in lib/site-config.ts, and colours and fonts are CSS variables in app/globals.css, so a rebrand for a client is mostly those two files.

What to know before you build on it

The template is MIT; Opencals isn't open source. The engine behind the API (availability, carts, checkout, accounts) is our hosted service. What's open is the templates, the @opencals/storefront-sdk package and our Agent Skills.
The dev store is free and has every feature, but it's in test mode. It can't take real payments until you switch the store to production (pricing).
Deposits and no-show fees are still in beta on the Opencals side.

It's a series now

Haar was the first template. There are now ten, all on the same SDK, each built around how that kind of business actually books:

Frisor: barbershop, dark editorial design
Clear Care: medical clinic, department-first booking
Alba: dental group, a tooth-chart "Smile Check" and a chair-time planner
VOLT: padel and squash clubs, a live court grid
NOIR Drive: car rental by the day, with chauffeur packages
Fluently: language school, group classes with live seats
Lumbung Sidemen: villa rental, nightly stays
Tensile: reformer Pilates timetable with beds left
Gable: coworking, desks, rooms and booths on one day sheet

I'll write one of these posts per template, about the booking problem each one had to solve, so follow the series if that's useful. And if there's a business type you'd want next, tell me in the comments. Tattoo studios and day spas are high on my list.

— Stan, building Opencals

Prevent Double Booking: System Design That Holds (2026)

Stan — Thu, 29 Oct 2026 07:22:30 +0000

Originally published on opencals.com. The original stays updated; check it for the latest version.

The bug report always reads the same way. Two customers booked the 10:30 with the same stylist, both got a confirmation email, and the salon found out when both of them walked in. The code that let it happen looks perfectly reasonable: check whether the slot is free, and if it is, insert the booking.

That check-then-insert is the whole problem. Run it twice at the same moment and both checks see an empty slot, because neither insert has committed yet. It doesn't need heavy traffic, either. Two people on a Sunday evening tapping the same slot within a few hundred milliseconds of each other is enough, and a booking page that shows "only 2 slots left this week" makes that collision more likely, not less.

This is the system design I'd use to make double booking impossible rather than unlikely. Most of it lives in the database, which is where it belongs.

Double booking is a race between two "is this free?" reads, so no amount of checking in application code fixes it. Make the database refuse the second write: in PostgreSQL, an exclusion constraint on a time range per staff member or room; in MySQL, a row lock on the staff member before you check. Treat group classes as a seat counter updated with a conditional UPDATE, and treat a hold during checkout as a real row with an expiry, because the database can't expire it for you. The last gap is payment: a card can succeed after the hold has gone, so confirming a booking has to be idempotent and able to refund.

The availability check is a read, and reads don't lock anything

Here's the sequence with two requests, A and B, both for Lena at 10:30 on Thursday:

A: SELECT ... WHERE staff = lena AND overlaps(10:30–11:30)  -> 0 rows
B: SELECT ... WHERE staff = lena AND overlaps(10:30–11:30)  -> 0 rows
A: INSERT booking (lena, 10:30–11:30)                        -> ok
B: INSERT booking (lena, 10:30–11:30)                        -> ok

Under PostgreSQL's default isolation level, READ COMMITTED, that interleaving is completely legal. Each statement sees data committed before it started, and nothing that A did is visible to B until A commits. MySQL's InnoDB default, REPEATABLE READ, doesn't save you either, because a plain SELECT reads a snapshot and takes no locks.

The first fix most people reach for is a unique index on (staff_id, starts_at). It catches two bookings that start at exactly 10:30. It does nothing for a 10:00–11:00 colour and a 10:30–11:30 cut, which overlap by half an hour and start at different times. Appointments are intervals, and a uniqueness check on a point can't see an interval.

So the rule I'd hold to: the availability endpoint is a cache of the truth, and it's allowed to be wrong for a second. The write is where correctness lives, and the write has to be able to fail.

Let Postgres refuse the overlapping insert

PostgreSQL has had the right tool for this since 9.0, and range types since 9.2: an exclusion constraint. It's a generalised unique constraint where you choose the operator. "Equal staff member and overlapping time range" is exactly the rule you want.

CREATE EXTENSION IF NOT EXISTS btree_gist;

CREATE TABLE booking (
  id         uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  staff_id   uuid NOT NULL,
  during     tstzrange NOT NULL,
  status     text NOT NULL DEFAULT 'confirmed',
  CONSTRAINT no_overlap_per_staff
    EXCLUDE USING gist (staff_id WITH =, during WITH &&)
    WHERE (status <> 'cancelled')
);

btree_gist is there so a plain uuid column can sit in a GiST index next to the range. The WHERE clause means cancelled bookings stop blocking the slot without being deleted. The PostgreSQL range-types documentation uses almost this exact example with meeting rooms, which is a good sign you're using the feature for what it was built for.

Now replay the race. B's insert either fails immediately or, if A hasn't committed yet, waits for A and then fails. It fails with SQLSTATE 23P01, exclusion_violation, which your code catches and turns into the message the customer actually needs: that slot just went, here are the next three.

If you're on PostgreSQL 18, there's a shorter spelling. A primary key or unique constraint can now end with WITHOUT OVERLAPS, as in UNIQUE (staff_id, during WITHOUT OVERLAPS), and the CREATE TABLE docs say it behaves like the equivalent EXCLUDE USING GIST. The partial WHERE for cancelled rows isn't available on that form, so I'd still write the explicit EXCLUDE.

Two details that bite later. Store the range as half-open, [10:30, 11:30), so a booking ending at 11:30 and one starting at 11:30 don't conflict; that's the default for tstzrange. And if a service needs ten minutes of clean-up after it, put the buffer inside the range you constrain. A buffer that only exists in the availability code is a buffer the database will happily let someone book into.

A booking usually occupies more than one thing

A massage needs a therapist and a treatment room. A podcast session needs a studio and, sometimes, an engineer. Constrain only the person and you'll double-book the room.

What's worked for me is splitting "the booking" from "what it occupies":

CREATE TABLE allocation (
  booking_id   uuid NOT NULL REFERENCES booking(id),
  resource_id  uuid NOT NULL,          -- a staff member, room, chair or bike
  during       tstzrange NOT NULL,
  active       boolean NOT NULL DEFAULT true,
  EXCLUDE USING gist (resource_id WITH =, during WITH &&) WHERE (active)
);

One constraint covers every kind of resource. Creating a massage booking inserts one booking row and two allocation rows in a single transaction, so either both the therapist and the room are free or nothing is written. It also lets each allocation have its own range, which matters when the room needs fifteen minutes to turn over and the therapist doesn't.

Seats in a class are a counter, not an overlap

An exclusion constraint answers "can these two things coexist?" A yoga class with twelve mats is the wrong question for it: twelve bookings for the same class are supposed to overlap. What you need there is a count that can't pass a ceiling.

The cleanest version I know is a conditional update on the class session itself:

UPDATE class_session
   SET seats_taken = seats_taken + $2
 WHERE id = $1
   AND seats_taken + $2 <= capacity
RETURNING seats_taken;

If it returns a row, you got the seats; insert the booking in the same transaction. If it returns nothing, the class is full. Two concurrent requests for the last mat can't both win, because in PostgreSQL's READ COMMITTED mode the second UPDATE waits for the first to commit and then re-checks the WHERE clause against the new row. The same shape works in MySQL.

The thing I'd avoid is SELECT count(*) followed by an insert. That's check-then-insert again, wearing a different hat.

Without exclusion constraints: lock the person, then look

MySQL has no exclusion constraints, and neither do most databases that aren't PostgreSQL. You can still make the race impossible; you just have to serialise it yourself. Lock a row that every booking for that resource must touch, then do your overlap check, then insert:

START TRANSACTION;
SELECT id FROM staff WHERE id = ? FOR UPDATE;      -- one at a time per staff member

SELECT COUNT(*) FROM booking
 WHERE staff_id = ? AND status <> 'cancelled'
   AND starts_at < ? AND ends_at > ?;              -- requested end, requested start

-- insert only if the count was 0
INSERT INTO booking (staff_id, starts_at, ends_at) VALUES (?, ?, ?);
COMMIT;

The FOR UPDATE on the staff row means two bookings for Lena queue behind each other while bookings for Marco carry on in parallel. For a service business that's no real cost: a busy salon takes a few hundred bookings a day, not a few hundred a second. For multi-resource bookings, lock every resource row involved, always in the same order (sort by id), or two transactions will deadlock each other.

The other options are worth knowing and I'd pick them less often. SERIALIZABLE isolation in PostgreSQL will detect the conflict and abort one transaction with SQLSTATE 40001, but then every booking path needs a retry loop, and that's easy to forget in the one code path nobody tests. Pre-generating slot rows with a unique key works well when every service is the same length on a fixed grid, like 30-minute tennis courts, and falls apart as soon as a 45-minute and a 60-minute service share a calendar.

Holds expire, and constraints can't tell time

Now add payment. Between choosing 10:30 and the card going through, the slot has to be reserved for this customer, or the second customer can buy it while the first is typing a card number. So the hold is a booking row with status = 'held' and an expiry time, and the exclusion constraint treats it exactly like a confirmed booking. Good.

The trap: you can't put hold_expires_at > now() into the constraint's WHERE clause. PostgreSQL requires that predicate to be immutable, and now() isn't. The constraint can't know a hold has lapsed, so an expired hold keeps blocking the slot until something removes it.

I'd handle that in two places. A sweeper job that cancels expired holds every minute or so keeps the calendar clean. And the booking transaction clears any expired hold that overlaps the requested range before inserting, so a customer never loses a slot to someone who closed their tab nine minutes ago:

UPDATE booking SET status = 'cancelled'
 WHERE staff_id = $1 AND status = 'held'
   AND hold_expires_at < now()
   AND during && $2;

INSERT INTO booking (staff_id, during, status, hold_expires_at)
VALUES ($1, $2, 'held', now() + interval '10 minutes');

If two customers do this at the same moment, both cancel the stale hold, one insert wins, and the other gets 23P01. The constraint is still the referee.

How long should the hold be? Long enough for a checkout with 3-D Secure on a phone, short enough that abandoned carts don't make the shop look full. Ten minutes is a common default; give the frontend a way to extend it once checkout has actually started rather than making the initial hold longer.

The card can succeed after the hold is gone

This is the case I see teams find in production. The customer reaches the bank's 3-D Secure page, gets distracted, comes back eleven minutes later and approves. The hold expired at ten. Someone else booked 10:30 at minute ten and a half. Stripe now tells you the payment succeeded.

There's no locking trick that makes this go away, because the payment provider doesn't know about your locks. What you can do is make the confirm step honest:

UPDATE booking SET status = 'confirmed', hold_expires_at = NULL
 WHERE id = $1 AND status = 'held'
RETURNING id;

If that returns the row, confirm and send the email. If it returns nothing, the hold was swept, and you refund automatically and tell the customer straight away, with the next free slots in the same message. It's a bad moment for them, and it's still much better than a confirmation email for a chair someone else is sitting in.

The same statement makes your payment webhook safe to receive twice, which it will be: Stripe says outright that an endpoint can get the same event more than once. The second delivery finds no held row and does nothing. Use an idempotency key on the call that creates the charge too; Stripe stores the first response for a key and returns it on retries, and can prune keys once they're 24 hours old, so generate one per checkout attempt, not per customer.

Where a Redis lock fits, and where it doesn't

A short-lived lock in Redis (SET key value NX PX 5000) on lena:2026-11-12 can stop two requests from even attempting the same slot, and it's a reasonable way to keep a slow availability computation from running twice. It is not a replacement for the constraint. A lock with a timeout can expire while the process holding it is paused in garbage collection, and then two writers believe they hold it at once. Martin Kleppmann's 2016 essay on distributed locking walks through that failure and why it needs fencing tokens; for a booking system the fencing token is, in effect, the database constraint. Keep the constraint, and treat any lock in front of it as a performance optimisation.

Shopify's inventory counts units, not hours

If you sell appointments through Shopify, the platform's own guard against overselling is inventory: a variant with a quantity of one can't be bought twice. That's exactly right for a t-shirt and the wrong shape for time. An appointment product doesn't have a quantity that means anything; the same "60-minute massage" variant is sold forty times a week, each one for a different interval, and Shopify's cart has no notion that two of those carts hold the same Thursday at 10:30.

So on Shopify, the overlap check has to live in the booking app, and the hold has to survive Shopify's checkout, which the app doesn't control. I went through what Shopify actually permits inside checkout in the article on embedding booking in Shopify checkout; the short form is to ask any booking app what holds the slot while the customer pays, and what happens if that hold expires mid-checkout.

What we do, and the parts we don't do yet

Opencals is a hosted booking engine, so if you build on it, none of the SQL above is yours to maintain. On the Storefront API, you create the appointment for the chosen slot and put it into a cart. Carts expire on their own, there's a cart extend endpoint that adds five minutes (the "extend once checkout has started" pattern from above), and starting checkout validates the cart's items before a payment is created. On Shopify, the slot is held from the moment it goes into the cart for a window the merchant sets, and a Shopify checkout validation function refuses to complete the order if that hold has expired, so the customer is told to rebook inside Shopify's own checkout rather than by an email afterwards. The Opencals for Shopify page shows that message as it appears.

Now the limits, because they affect how you'd design around us.

Webhooks aren't live. The webhooks guide lists the planned appointment and order events and says plainly that they're not yet available. If you mirror bookings into your own database today, you're polling the API, and your copy can lag behind ours.
Opencals isn't open source, so you can't read our locking code. What's open is the client side: the MIT-licensed Next.js templates such as Haar and the @opencals/storefront-sdk package on npm.
The free tier is a development store in test mode. It's the right place to try the race yourself with two browsers, but it won't take a real payment until you switch it to production.

If you're building this yourself instead, my advice is narrow: write the constraint before you write the availability endpoint. Availability is where the interesting algorithm lives, and it's tempting to start there, but the constraint is the part that stops the salon from finding out about your bug when two customers walk in. Once the database refuses the second booking, the rest is a matter of telling the customer nicely. For the rest of what a booking system asks of you after this, the developer's guide to booking systems covers reschedule links, refunds and reminders.

Frequently asked questions

How do you prevent double booking in a database?

Make the database reject the second booking instead of checking first in application code. In PostgreSQL, add an exclusion constraint such as EXCLUDE USING gist (staff_id WITH =, during WITH &&) on a tstzrange column, with the btree_gist extension installed. In MySQL, lock the staff member's row with SELECT ... FOR UPDATE, check for overlaps, then insert in the same transaction.

Why doesn't a unique index stop double bookings?

A unique index on staff and start time only catches two bookings that start at exactly the same moment. Appointments are intervals: a 10:00 to 11:00 booking and a 10:30 to 11:30 booking overlap but have different start times, so the index allows both.

What is the race condition in a booking system?

Two requests check availability at the same moment, both see the slot as free because neither has committed its insert yet, and both insert. It's called check-then-act, and it happens under default isolation levels in both PostgreSQL and MySQL.

How do you handle capacity for group classes?

Use a conditional update on the class session, for example UPDATE class_session SET seats_taken = seats_taken + 1 WHERE id = $1 AND seats_taken + 1 <= capacity. If no row comes back, the class is full. Concurrent requests for the last seat can't both succeed, because the second update waits and then re-checks the condition.

How long should a booking hold last during checkout?

Long enough for a card payment with 3-D Secure on a phone, and short enough that abandoned carts don't make the calendar look full. Around ten minutes is a common default, with an extension once checkout has actually started. Opencals' Storefront API, for example, has a cart extend endpoint that adds five minutes.

Is a Redis lock enough to prevent double booking?

No. A lock with a timeout can expire while the process holding it is paused, and then two writers think they hold it. Use Redis locks to avoid duplicate work if you like, but keep a database constraint as the final check.

Built a full salon booking website in a weekend — here's the stack

Stan — Tue, 23 Jun 2026 06:08:00 +0000

Update, October 2026: Haar has since been rebuilt almost from scratch: one-page booking instead of a wizard, "Any stylist" time slots, held chairs, passwordless accounts and a private API key. The current walkthrough, with new screenshots and code, is here: I rebuilt my open-source salon booking template. The post below describes the June version.

The thing nobody warns you about with booking sites

A booking website looks like a weekend project until you actually try to build one. The UI is easy — a service list, a calendar, a "Book now" button. Then you hit the real question: is this slot actually available?

That answer isn't a row in a calendar table. It depends on which staff member can do this service, which location they're at, how long the service runs, whether they're already booked, days off, buffers between appointments, and — for classes — how many seats are left. Get it slightly wrong and you double-book a stylist, which is a great way to lose a customer on day one.

I did not want to build that engine again. I've built scheduling logic before and it's the kind of thing that's "done" five times before it's actually done. So this time I let something else own the hard part and spent my weekend on the parts users actually see.

The stack

Layer	Choice	Why
Framework	Next.js 15 (App Router)	Server components for the data fetches, fast deploys to Vercel
Language	TypeScript	The API responses are typed end-to-end via the SDK
Styling	Tailwind CSS	The template ships with it; rebranding is mostly editing tokens
Booking backend	Opencals Storefront API	Availability, staff, locations, cart, Stripe checkout, customer accounts
Payments	Stripe (through the API)	No payments backend of my own to build or maintain
UI	Claude (Opus 4.8)	I described the screens; it wrote the React + Tailwind components against the typed SDK
Hosting	Vercel	`git push` and it's live

The part I want to be honest about: the Opencals Storefront API is the reason this was a weekend and not a month. It's the booking infrastructure behind Opencals (a service-commerce platform I work on), exposed as a plain REST API with a typed TypeScript SDK. Services, availability, staff, locations, cart, checkout, customer self-service — all endpoints I'd otherwise have had to design, build, and debug myself. With the scheduling logic owned by the API and a small typed surface to write against, Claude handled most of the UI components cleanly.

Step 1 — Clone the template

I didn't start from create-next-app. There's an open-source salon template — Haar — that already wires the whole flow to the API (announcement post · docs):

git clone https://github.com/letsopencals/template-haar.git
cd template-haar
npm install

It's template-haar — Next.js 15, TypeScript, Tailwind, MIT license. Services (with variants), staff, multi-location, real-time availability, add-ons, Stripe checkout, and customer accounts are all already connected. There's a live demo if you want to click through it first. My weekend was mostly rebranding and tweaking, not plumbing.

Step 2 — Create a store, seed it with Haar data, and deploy

This is the part that makes it fast. The template reads everything from one Opencals store, identified by a Storefront API key — and you can have a live, populated store in three steps, no code required:

Create a free Dev Store in the Opencals dashboard.
Choose the "HAAR Salon" seed dataset when prompted. It's built specifically for this template — it pre-loads the exact services, staff, and locations from the live demo, so your store isn't empty and the cloned site renders real content from the very first load.
Create a Storefront API Key under Settings → API Keys (it starts with sfk_).

Then deploy: hit Deploy with Vercel in the README, paste your sfk_ key when Vercel asks for the environment variable, and it builds in about two minutes. That's a working booking site before you've written a line of code.

Running it locally instead? Drop the key into .env.local:

OPENCALS_API_KEY=sfk_your_key_here

Keep the key server-side — it identifies your store and not recommended to ship to the browser. The quickstart covers it in more detail.

Step 3 — Listing services and fetching availability

The whole booking flow is seven typed calls (list services → pick staff → fetch slots → create appointment → cart → add-ons → checkout), and with the @opencals/storefront-sdk each one is basically a one-liner. You initialize the SDK once and the key stays server-side:

npm install @opencals/storefront-sdk

// lib/opencals.ts — run once, server-side only
import { setupOpencals } from "@opencals/storefront-sdk";

setupOpencals({
  apiKey: process.env.OPENCALS_API_KEY, // sfk_… from Settings → API Keys
});

Then the two calls that drive the whole front page — the service menu and real-time slots:

import "@/lib/opencals";
import { ProductService } from "@opencals/storefront-sdk";

// 1. List the bookable services (your menu)
const { data } = await ProductService.list({ query: { take: 50 } });
const services = data!.data; // Product[] — title, price, duration, staffMembers…

// 2. Real-time availability for one service on a given day
const { data: slots } = await ProductService.getCurrentAvailabilities({
  path: { productId: services[0].id },
  query: {
    date: "2026-07-01",
    timezone: "America/New_York", // slots come back converted for display
  },
});

That getCurrentAvailabilities call is the part I was dreading building. It already accounts for which staff can do the service, at which location, for how long, and what's already booked — pass an optional staffMemberId and it filters to one person. I render the slots and move on with my life.

From there it's create the appointment, drop it in a cart, optionally attach add-ons, and check out through Stripe. The full sequence is documented step by step in the Build a booking page guide, so I won't paste all seven here.

Step 4 — Customer accounts (the part I almost skipped)

I assumed self-service rescheduling would be the thing I'd cut for v1. It wasn't — the API handles customer auth (JWTs) and the account actions, so the template already had a customer portal where someone can log in, see their bookings, and reschedule or cancel without emailing the salon. For a real salon that's the difference between a booking tool and a front desk that never sleeps.

Step 5 — Make it yours

Rebranding is one file. Everything salon-specific — name, tagline, logo, hero, team, hours, contact, social — lives in lib/site-config.ts, and the brand colors are CSS custom properties in app/globals.css. Edit those and Haar stops looking like Haar.

@theme {
  --color-accent: #E8530E;   /* your brand color */
  --font-display: 'Playfair Display', Georgia, serif;
  --font-body: 'Inter', system-ui, sans-serif;
}

You already deployed in Step 2, so a rebrand is just editing that config and pushing — Vercel redeploys on every commit. That's the weekend.

What you actually get

A real Next.js booking website, not a calendar embed
Real-time availability across multiple staff and locations
Add-ons, Stripe checkout, and deposits without a payments backend
Customer accounts with self-service reschedule/cancel
One codebase you can rebrand per client — MIT, no royalties (relevant if you're an agency)

Try it without committing

You don't need an account to look around. The interactive API reference lets you browse every endpoint in the browser, no key required. If you want to build:

🧬 Clone the template: github.com/letsopencals/template-haar · live demo
📖 Template write-up + docs: the Haar announcement · Haar docs
🚀 Quickstart (5 min): opencals.com/docs/quickstart
📦 SDK: @opencals/storefront-sdk

This is Part 1 of a series where I rebuild the whole thing piece by piece — next up, the API calls in full, then Stripe deposits, then rendering availability in React the right way. If you build something with it, drop a comment — I read all of them and I'm curious what verticals people try beyond salons.

— Stan, building Opencals