<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>DEV Community: Stan</title>
    <description>The latest articles on DEV Community by Stan (@stangineer).</description>
    <link>https://dev.to/stangineer</link>
    <image>
      <url>https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F3908650%2Fd574d054-942b-4f4f-8c04-81657d1f2719.jpg</url>
      <title>DEV Community: Stan</title>
      <link>https://dev.to/stangineer</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/stangineer"/>
    <language>en</language>
    <item>
      <title>Booking SDK: Typed TypeScript for Custom Booking Flows</title>
      <dc:creator>Stan</dc:creator>
      <pubDate>Wed, 18 Nov 2026 05:42:50 +0000</pubDate>
      <link>https://dev.to/stangineer/booking-sdk-typed-typescript-for-custom-booking-flows-28n8</link>
      <guid>https://dev.to/stangineer/booking-sdk-typed-typescript-for-custom-booking-flows-28n8</guid>
      <description>&lt;p&gt;&lt;em&gt;Originally published on &lt;a href="https://opencals.com/blog/booking-sdk" rel="noopener noreferrer"&gt;opencals.com&lt;/a&gt;. The original stays updated; check it for the latest version.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;Adding booking to an app looks like a weekend project until you start. Real-time availability across staff and locations, cart state that survives a page refresh, a payment flow that fails gracefully, booking statuses that move through their lifecycle — every piece is more nested and more stateful than it looks from the outside.&lt;/p&gt;

&lt;p&gt;A booking SDK is what turns that from raw HTTP plumbing into typed method calls. This is a look at what a booking SDK does, when it's worth using over the raw API, and how the Opencals storefront SDK is structured — with code you can actually run.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why a booking flow earns an SDK
&lt;/h2&gt;

&lt;p&gt;Plenty of APIs don't need an SDK. A booking API does, and the reason is the shape of the data. A single booking flow touches:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Availability:&lt;/strong&gt; nested slots computed across staff, hours, duration, capacity&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Cart state:&lt;/strong&gt; line items, quantities, selected times, held across steps&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Payment intents:&lt;/strong&gt; Stripe client secrets, confirmation, idempotency&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Booking status:&lt;/strong&gt; pending (held, awaiting payment or approval), scheduled, completed, canceled&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Wire that up with hand-rolled &lt;code&gt;fetch&lt;/code&gt; calls and you're maintaining a private, untyped copy of the API's mental model — one that silently drifts every time the backend adds a field. A typed SDK gives you autocomplete for every request, compile-time errors when a shape changes, and schemas for validating responses at the boundary. In a domain this nested, that's the difference between a booking flow you trust and one you babysit.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Key takeaway&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Use a booking SDK when the flow is stateful and the types are nested — availability, carts, and payments. Reach for the raw REST API for one-off scripts, server-to-server jobs, or non-JavaScript stacks.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  Install and set up
&lt;/h2&gt;

&lt;p&gt;The Opencals storefront SDK is a TypeScript package:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;npm install @opencals/storefront-sdk
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Initialize it once with your store API key. Keys are scoped to a single store. For server code use a private storefront key: it starts with &lt;code&gt;spk_&lt;/code&gt; and comes from the dashboard under Users → your user → API Keys. Keep it server-side, and forward each visitor's IP with the &lt;code&gt;buyerIp&lt;/code&gt; option so rate limits count per visitor, not per server.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// lib/opencals.ts — import it from server code&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;setupOpencals&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"@opencals/storefront-sdk"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;nextBuyerIp&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"@opencals/storefront-sdk/next"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="c1"&gt;// Next.js; elsewhere pass your own function&lt;/span&gt;

&lt;span class="nf"&gt;setupOpencals&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;apiKey&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nb"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="no"&gt;OPENCALS_API_KEY&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="c1"&gt;// spk_...&lt;/span&gt;
  &lt;span class="n"&gt;buyerIp&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;nextBuyerIp&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;throwOnError&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="c1"&gt;// failed calls throw OpencalsApiError instead of returning { error }&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;That's the whole setup. &lt;code&gt;setupOpencals&lt;/code&gt; configures one shared client, so the service classes below don't take a client argument: every call takes a single options object with &lt;code&gt;path&lt;/code&gt;, &lt;code&gt;query&lt;/code&gt;, &lt;code&gt;body&lt;/code&gt; and &lt;code&gt;headers&lt;/code&gt; as needed. The base URL (&lt;code&gt;https://api.opencals.com&lt;/code&gt;) is the default, and every route is typed. The full endpoint reference is at &lt;a href="https://api.opencals.com/docs/storefront" rel="noopener noreferrer"&gt;api.opencals.com/docs/storefront&lt;/a&gt; if you want to see the raw HTTP underneath.&lt;/p&gt;

&lt;h2&gt;
  
  
  The five things every booking flow does
&lt;/h2&gt;

&lt;p&gt;Almost every custom booking flow is the same five steps. Here's each one through the SDK (version 0.3.20, checked November 2026; the examples assume &lt;code&gt;throwOnError: true&lt;/code&gt;).&lt;/p&gt;

&lt;h3&gt;
  
  
  1. Load the service catalog
&lt;/h3&gt;

&lt;p&gt;Your services page is populated from the product catalog. It rarely changes, so cache it.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nc"&gt;ProductService&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"@opencals/storefront-sdk"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;data&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;page&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nc"&gt;ProductService&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;list&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;query&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;status&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"active"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;take&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;50&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;services&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;page&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;data&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="c1"&gt;// each service is typed: title, price, duration (seconds), variants, staff and locations&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h3&gt;
  
  
  2. Fetch real-time availability
&lt;/h3&gt;

&lt;p&gt;This is the endpoint that earns the platform. You ask for a service on a date, optionally narrowed to a staff member and a location; you get back the slots that are bookable right now — after existing bookings, working hours, buffers, and capacity are all accounted for.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nc"&gt;ProductService&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"@opencals/storefront-sdk"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;data&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;slots&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nc"&gt;ProductService&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;getCurrentAvailabilities&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;path&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;productId&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;query&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;date&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"2026-07-20"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;      &lt;span class="c1"&gt;// one day per call&lt;/span&gt;
    &lt;span class="n"&gt;staffMemberId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;           &lt;span class="c1"&gt;// optional — omit for "any available"&lt;/span&gt;
    &lt;span class="n"&gt;locationId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;              &lt;span class="c1"&gt;// optional&lt;/span&gt;
    &lt;span class="n"&gt;timezone&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"Europe/Warsaw"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="c1"&gt;// slots: [{ productId, fromDate, fromTime, toDate, toTime, staffMemberIds, attendees, maxAttendees }]&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;You render &lt;code&gt;slots&lt;/code&gt; straight into a calendar. You are not reconstructing availability logic on the client — the hard part stays on the server where it belongs. For "next free slot" buttons there's &lt;code&gt;ProductService.getNearestAvailability&lt;/code&gt;.&lt;/p&gt;

&lt;h3&gt;
  
  
  3. Create a cart and hold the slot
&lt;/h3&gt;

&lt;p&gt;A cart holds the selected slot while the customer finishes checkout. Every cart and checkout call names its cart in the &lt;code&gt;X-Cart-Id&lt;/code&gt; header; store the cart ID (an httpOnly cookie works) so the cart survives a page refresh.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nc"&gt;AppointmentService&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nc"&gt;CartService&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"@opencals/storefront-sdk"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;data&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;cart&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nc"&gt;CartService&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;createOrGet&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;headers&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="s2"&gt;"X-Cart-Id"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;savedCartId&lt;/span&gt; &lt;span class="o"&gt;??&lt;/span&gt; &lt;span class="s2"&gt;""&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nc"&gt;AppointmentService&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;create&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;body&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;slot&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="n"&gt;productId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;slot&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;productId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;fromDate&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;slot&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;fromDate&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;fromTime&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;slot&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;fromTime&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;toDate&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;slot&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;toDate&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;toTime&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;slot&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;toTime&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="c1"&gt;// times are UTC&lt;/span&gt;
    &lt;span class="n"&gt;numberOfAttendees&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;cartId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;cart&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;If two people try to hold the same slot at the same moment, one gets it and the other gets a clear error that the slot is being booked, so show that and let them pick another time.&lt;/p&gt;

&lt;h3&gt;
  
  
  4. Start checkout, pay, submit
&lt;/h3&gt;

&lt;p&gt;&lt;code&gt;CheckoutService.start&lt;/code&gt; attaches the customer and creates the payment. For card payments it returns a Stripe client secret, the publishable key and the connected account ID, so your app never stores a Stripe key. The browser confirms the payment with Stripe.js, then your server submits.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nc"&gt;CheckoutService&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"@opencals/storefront-sdk"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;cartHeaders&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="s2"&gt;"X-Cart-Id"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;cart&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;data&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;checkout&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nc"&gt;CheckoutService&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;start&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;headers&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;cartHeaders&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;body&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;provider&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"stripe"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;customer&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;kind&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"new"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;email&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;firstName&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;lastName&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="c1"&gt;// browser: loadStripe(checkout.publishableKey, { stripeAccount: checkout.stripeAccountId })&lt;/span&gt;
&lt;span class="c1"&gt;// → mount a Payment Element with checkout.clientSecret → stripe.confirmPayment(...)&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;data&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;result&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nc"&gt;CheckoutService&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;submit&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;headers&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;cartHeaders&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;body&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;stripePaymentIntentId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;paymentIntent&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The failure cases are named, so a retry doesn't have to guess. Submitting a card payment that isn't authorised returns &lt;code&gt;402 PAYMENT_NOT_AUTHORIZED&lt;/code&gt;: no order is placed and the cart is untouched, so the customer can try again. A second &lt;code&gt;start&lt;/code&gt; or &lt;code&gt;submit&lt;/code&gt; while one is still running returns &lt;code&gt;409 CHECKOUT_IN_PROGRESS&lt;/code&gt;, and starting a cart that already became an order returns &lt;code&gt;409 CART_ALREADY_CHECKED_OUT&lt;/code&gt; with that order's ID. Not every booking is confirmed on submit: a &lt;code&gt;pending&lt;/code&gt; appointment with &lt;code&gt;pendingReason&lt;/code&gt; set is awaiting payment or the store's approval, so label it that way rather than "Confirmed".&lt;/p&gt;

&lt;h3&gt;
  
  
  5. Customer self-service
&lt;/h3&gt;

&lt;p&gt;Viewing, rescheduling, and cancelling a customer's own bookings uses a second credential: a customer access token from Opencals' customer accounts (&lt;code&gt;AuthService.signIn&lt;/code&gt;, or &lt;code&gt;signUp&lt;/code&gt; for new customers), sent as a Bearer header. The store key stays on the server while a signed-in customer acts only on their own bookings.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nc"&gt;AppointmentService&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nc"&gt;AuthService&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"@opencals/storefront-sdk"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;data&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;session&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nc"&gt;AuthService&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;signIn&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;body&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;email&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;password&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;asCustomer&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nc"&gt;Authorization&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="sb"&gt;`Bearer ${session.accessToken}`&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;data&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;upcoming&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nc"&gt;AppointmentService&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;list&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;headers&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;asCustomer&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;query&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;status&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"scheduled"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"pending"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;orderBy&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"from"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;order&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"ASC"&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nc"&gt;AppointmentService&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;reschedule&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;headers&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;asCustomer&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;path&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;appointmentId&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;body&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;slot&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;newSlot&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="c1"&gt;// from getCurrentAvailabilities with excludeAppointmentId&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nc"&gt;AppointmentService&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;cancel&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;headers&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;asCustomer&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;path&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;appointmentId&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;body&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;notifyCustomer&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The five steps at a glance:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;1. Catalog:&lt;/strong&gt; ProductService.list() — populate services from page.data. Cache it.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;2. Availability:&lt;/strong&gt; ProductService.getCurrentAvailabilities({ path: { productId }, query: { date } }) — render the calendar from real bookable slots, one day per call.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;3. Cart:&lt;/strong&gt; CartService.createOrGet() with the X-Cart-Id header, then AppointmentService.create() with the slot and cartId to hold it.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;4. Checkout:&lt;/strong&gt; CheckoutService.start() for the Stripe client secret, stripe.confirmPayment() in the browser, then CheckoutService.submit().&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;5. Self-service:&lt;/strong&gt; AuthService.signIn() for a customer token, then AppointmentService.list(), reschedule() and cancel() with it.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Type safety and runtime validation
&lt;/h2&gt;

&lt;p&gt;Static types catch shape mismatches at compile time. But data crossing a network boundary can still surprise you at runtime, so the SDK also exports a Zod schema for every response type. Run the ones you care about with &lt;code&gt;safeParse&lt;/code&gt; at the boundary, and a malformed or unexpected payload fails loudly at the edge instead of leaking an &lt;code&gt;undefined&lt;/code&gt; three components deep into your UI.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;zProductListResponse&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"@opencals/storefront-sdk"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;parsed&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;zProductListResponse&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;safeParse&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;raw&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="n"&gt;parsed&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;success&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="nb"&gt;console&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;error&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;parsed&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;error&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;It also includes the small formatting helpers you'd otherwise rewrite on every project:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;formatPrice&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;formatDuration&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"@opencals/storefront-sdk"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="nf"&gt;formatPrice&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;45&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"USD"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;     &lt;span class="c1"&gt;// "$45.00"&lt;/span&gt;
&lt;span class="nf"&gt;formatPrice&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"USD"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;      &lt;span class="c1"&gt;// "Free"&lt;/span&gt;
&lt;span class="nf"&gt;formatDuration&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;5400&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;       &lt;span class="c1"&gt;// "1 hour 30 minutes"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Durations come back in seconds and prices as plain amounts in the store's currency (&lt;code&gt;45&lt;/code&gt; is $45.00, not cents), which is what the helpers expect. Check the output in your own locale before you ship; &lt;code&gt;formatPrice&lt;/code&gt; takes a locale as its third argument.&lt;/p&gt;

&lt;h2&gt;
  
  
  Using it with Next.js and React
&lt;/h2&gt;

&lt;p&gt;The SDK is framework-agnostic; it runs wherever JavaScript runs. The only real rule is credential placement.&lt;/p&gt;

&lt;p&gt;Keep the store API key on the server — route handlers, server actions, or server components. Fetch there, then pass typed data (or a customer token) down to the client. Never ship the private &lt;code&gt;spk_&lt;/code&gt; key to the browser. The &lt;a href="https://opencals.com/blog/add-booking-to-nextjs-app" rel="noopener noreferrer"&gt;Next.js booking tutorial&lt;/a&gt; walks through the whole flow this way, from services to checkout.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// app/api/availability/route.ts (Next.js route handler)&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="s2"&gt;"@/lib/opencals"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="c1"&gt;// the setupOpencals module from above&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nc"&gt;ProductService&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"@opencals/storefront-sdk"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nc"&gt;GET&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;req&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;Request&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;searchParams&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="no"&gt;URL&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;req&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;url&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;data&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;slots&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nc"&gt;ProductService&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;getCurrentAvailabilities&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;path&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;productId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;searchParams&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"productId"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;query&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="n"&gt;date&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;searchParams&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"date"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="c1"&gt;// YYYY-MM-DD&lt;/span&gt;
      &lt;span class="n"&gt;staffMemberId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;searchParams&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"staffMemberId"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;??&lt;/span&gt; &lt;span class="kc"&gt;undefined&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nc"&gt;Response&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;json&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;slots&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The client calls your route, not Opencals directly. That's the whole &lt;a href="https://opencals.com/blog/headless-booking-system" rel="noopener noreferrer"&gt;headless booking&lt;/a&gt; pattern: your frontend, your framework, your domain — the booking engine and payments handled underneath.&lt;/p&gt;

&lt;h2&gt;
  
  
  SDK or raw REST — which to reach for
&lt;/h2&gt;

&lt;p&gt;Both are supported; they're not competitors.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;SDK pros&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;SDK: typed methods, autocomplete, and compile-time safety across the whole flow&lt;/li&gt;
&lt;li&gt;SDK: Zod runtime validation and money/duration helpers included&lt;/li&gt;
&lt;li&gt;SDK: less boilerplate for the stateful cart-and-checkout sequence&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;strong&gt;Raw REST pros&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Raw REST: better for non-JavaScript stacks (Python, Go, PHP) — no SDK to depend on&lt;/li&gt;
&lt;li&gt;Raw REST: leaner for server-to-server jobs or one-off scripts&lt;/li&gt;
&lt;li&gt;Raw REST: nothing to update when you just need a single endpoint&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;If you're building a production booking experience in TypeScript, the SDK is the shorter path. If you're integrating from another language or writing a quick automation, the &lt;a href="https://opencals.com/blog/booking-api" rel="noopener noreferrer"&gt;REST API&lt;/a&gt; is right there with the same guarantees.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Note&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;The SDK and the website templates are open source and free; the Opencals platform underneath is a managed cloud service. You get open, inspectable client code running against an API you don't have to operate.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  Related reading
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;a href="https://opencals.com/blog/booking-api" rel="noopener noreferrer"&gt;&lt;strong&gt;Booking API guide&lt;/strong&gt;&lt;/a&gt;: The endpoint-level reference: auth model, core routes, and the full flow in raw REST.&lt;/li&gt;
&lt;li&gt;
&lt;a href="https://opencals.com/blog/headless-booking-system" rel="noopener noreferrer"&gt;&lt;strong&gt;Headless booking system&lt;/strong&gt;&lt;/a&gt;: The architecture for building a custom booking frontend on any stack.&lt;/li&gt;
&lt;li&gt;
&lt;a href="https://opencals.com/blog/add-booking-to-nextjs-app" rel="noopener noreferrer"&gt;&lt;strong&gt;Add booking to a Next.js app&lt;/strong&gt;&lt;/a&gt;: The full flow in a Next.js App Router project: services, slots, cart and checkout over the REST API.&lt;/li&gt;
&lt;li&gt;
&lt;a href="https://opencals.com/developers" rel="noopener noreferrer"&gt;&lt;strong&gt;Opencals for developers&lt;/strong&gt;&lt;/a&gt;: API docs, the OpenAPI spec, and how to get a storefront key.&lt;/li&gt;
&lt;li&gt;
&lt;a href="https://opencals.com/blog/build-a-booking-website" rel="noopener noreferrer"&gt;&lt;strong&gt;Build a booking website&lt;/strong&gt;&lt;/a&gt;: Deploy a free open-source template on your own domain in an afternoon.&lt;/li&gt;
&lt;li&gt;
&lt;a href="https://opencals.com/blog/open-source-booking-system" rel="noopener noreferrer"&gt;&lt;strong&gt;Open-source booking system&lt;/strong&gt;&lt;/a&gt;: What's open (SDK + templates) and what's managed (the platform), and why.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Frequently asked questions
&lt;/h2&gt;

&lt;h3&gt;
  
  
  What is a booking SDK?
&lt;/h3&gt;

&lt;p&gt;A booking SDK is a client library that wraps a booking platform's API in typed methods, so you can build a custom appointment flow — loading services, checking availability, adding to a cart, taking payment — without writing raw HTTP calls or guessing at request and response shapes. The Opencals storefront SDK is a TypeScript package (@opencals/storefront-sdk) that covers the full booking flow with type safety and runtime validation built in.&lt;/p&gt;

&lt;h3&gt;
  
  
  Why use an SDK instead of calling the REST API directly?
&lt;/h3&gt;

&lt;p&gt;You can call the REST API directly — the SDK is optional. But a booking flow has a lot of nested, stateful objects: availability slots, cart line items, payment intents, booking statuses. A typed SDK gives you autocomplete, compile-time errors when a shape changes, and runtime validation, which removes a whole class of bugs. For quick scripts or non-JS stacks, raw REST is fine; for a production TypeScript app, the SDK saves real time.&lt;/p&gt;

&lt;h3&gt;
  
  
  Does the booking SDK work with Next.js and React?
&lt;/h3&gt;

&lt;p&gt;Yes. The SDK is framework-agnostic — it runs anywhere JavaScript runs. In Next.js, keep the store API key server-side (route handlers, server actions, or server components) and pass only the data or a customer token to the client. In React, fetch on the server or in a data-loading hook and render from typed results. The SDK doesn't force a framework or a state library on you.&lt;/p&gt;

&lt;h3&gt;
  
  
  Is the Opencals booking SDK open source?
&lt;/h3&gt;

&lt;p&gt;The SDK and the website templates are open source and free to use; the Opencals platform itself (the booking engine, dashboard, and hosted infrastructure) is a managed cloud service, not open source. So you get open, inspectable client code and templates you own, running against a managed API you don't have to operate. The distinction matters if you're evaluating self-hosting versus a managed backend.&lt;/p&gt;

&lt;h3&gt;
  
  
  How do I authenticate with the booking SDK?
&lt;/h3&gt;

&lt;p&gt;There are two credentials. A private storefront key (prefix spk_, from the dashboard under Users → your user → API Keys) scopes all storefront calls to one store and must stay server-side. A customer access token, from Opencals' customer accounts via AuthService.signIn, is required for customer self-service endpoints like viewing, rescheduling, or cancelling their own bookings; send it as an Authorization: Bearer header on those calls. You initialize the SDK with the store key once; you attach the customer token per call.&lt;/p&gt;

&lt;h3&gt;
  
  
  Can the SDK handle payments?
&lt;/h3&gt;

&lt;p&gt;The SDK drives the checkout flow, and card payment is collected through Stripe. CheckoutService.start returns a Stripe client secret plus the publishable key and connected account ID, so your app stores no Stripe key; you confirm the payment with Stripe.js in the browser, then call CheckoutService.submit to place the order. An unauthorised card returns 402 PAYMENT_NOT_AUTHORIZED with the cart untouched, and a concurrent start or submit on the same cart returns 409 CHECKOUT_IN_PROGRESS, so retries are safe to handle. Manual methods such as bank transfer skip the Stripe step.&lt;/p&gt;

</description>
      <category>typescript</category>
      <category>javascript</category>
      <category>webdev</category>
      <category>api</category>
    </item>
    <item>
      <title>How to Add Booking to a Next.js App With a REST API (2026)</title>
      <dc:creator>Stan</dc:creator>
      <pubDate>Fri, 13 Nov 2026 05:44:57 +0000</pubDate>
      <link>https://dev.to/stangineer/how-to-add-booking-to-a-nextjs-app-with-a-rest-api-2026-3pi</link>
      <guid>https://dev.to/stangineer/how-to-add-booking-to-a-nextjs-app-with-a-rest-api-2026-3pi</guid>
      <description>&lt;p&gt;&lt;em&gt;Originally published on &lt;a href="https://opencals.com/blog/add-booking-to-nextjs-app" rel="noopener noreferrer"&gt;opencals.com&lt;/a&gt;. The original stays updated; check it for the latest version.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;Adding a booking page to a Next.js app looks like a weekend project until you start it. The UI is the easy part. The hard part is everything the calendar needs to know before it can show a single open slot: which staff are working, how long the service takes, what's already booked, how much buffer to leave between appointments, and whether two people can hold the same slot at once. That logic is where booking projects quietly turn into month-long ones.&lt;/p&gt;

&lt;p&gt;This guide takes the other path. Instead of building the scheduling engine yourself, you call a booking API for the availability, cart, and payment logic, and you keep full control of the Next.js frontend. I built &lt;a href="https://opencals.com/" rel="noopener noreferrer"&gt;Opencals&lt;/a&gt; as exactly that kind of API, so the code here uses it — but the shape of the problem is the same whichever backend you pick, and I'll flag the parts that are universal.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Key takeaway&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;The frontend of a booking flow is a few forms and a calendar grid. The backend is real-time availability across staff, services, and existing bookings — plus payments. Calling a booking API lets you own the first part and hand off the second.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  What "add booking" actually involves
&lt;/h2&gt;

&lt;p&gt;Before any code, it helps to name the pieces. A working booking flow has four moving parts, and most half-finished projects stall because they underestimated one of them.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;1. A service catalog&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;What can be booked — a 60-minute session, a color treatment, a group class — each with its own duration, price, and the staff who can deliver it. This is your booking homepage data.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;2. Real-time availability&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Given a service and a date range, which slots are actually open? This has to account for existing bookings, staff hours, buffer time, and multi-staff conflicts. It is the single hardest piece to build well.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;3. A cart and checkout&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Holding a slot while the customer enters details and pays, then confirming the booking only if payment succeeds. Slots are a scarce resource, so this needs to be race-safe.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;4. Post-booking management&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Confirmation, reminders, and letting customers reschedule or cancel without emailing you. Easy to skip on day one, painful to add later.&lt;/p&gt;

&lt;p&gt;If you build all four yourself, you're writing a scheduling engine. If you call an API, you're wiring four typed methods into React components. This guide does the second.&lt;/p&gt;

&lt;h2&gt;
  
  
  Prerequisites
&lt;/h2&gt;

&lt;p&gt;You need a Next.js 14+ app using the App Router, Node 18+, and a booking API key. With Opencals that's a private storefront key (prefixed &lt;code&gt;spk_&lt;/code&gt;), created in the dashboard under Users → your user → API Keys; any booking API will have an equivalent. Install the SDK:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;npm i @opencals/storefront-sdk
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Then set the key in your environment. Keep it server-side — a private storefront key can create real bookings, so it does not belong in client bundles.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="c"&gt;# .env.local&lt;/span&gt;
&lt;span class="nv"&gt;OPENCALS_API_KEY&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;spk_your_key_here
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Why server-side&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Anything that creates a booking or a payment should run in a Route Handler or Server Action, never in a client component. The browser calls your Next.js API routes; your routes call the booking API with the secret key. This is the same pattern you'd use for a Stripe secret key.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  Step 1 — Initialise the SDK once
&lt;/h2&gt;

&lt;p&gt;Create a small module that configures the client. &lt;code&gt;setupOpencals&lt;/code&gt; sets up the SDK's shared client, so you call it once and every service call after that uses the key. Import this module at the top of any server file that calls the API.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// lib/opencals.ts — import from server code only&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;setupOpencals&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"@opencals/storefront-sdk"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;nextBuyerIp&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"@opencals/storefront-sdk/next"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="nf"&gt;setupOpencals&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;apiKey&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nb"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="no"&gt;OPENCALS_API_KEY&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="c1"&gt;// spk_…&lt;/span&gt;
  &lt;span class="n"&gt;buyerIp&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;nextBuyerIp&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;throwOnError&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="c1"&gt;// failed calls throw OpencalsApiError instead of returning { error }&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;nextBuyerIp&lt;/code&gt; forwards each visitor's IP on sign-in, cart and checkout calls, so the API rate-limits per visitor instead of treating your server as one very busy customer. It skips GET requests on purpose, so your cached pages stay static.&lt;/p&gt;

&lt;p&gt;If you prefer raw &lt;code&gt;fetch&lt;/code&gt; over an SDK, the same call is a &lt;code&gt;GET&lt;/code&gt; with the key in an &lt;code&gt;X-Api-Key&lt;/code&gt; header — the SDK just gives you typed responses. Both work; typing saves you from guessing the shape of a nested availability object at 11pm.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;curl https://api.opencals.com/storefront/products \
 -H &lt;span class="s2"&gt;"X-Api-Key: spk_your_key"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  Step 2 — List services on a Server Component
&lt;/h2&gt;

&lt;p&gt;The App Router lets you fetch on the server and stream HTML, which is ideal for a service catalog — it's public data, good for SEO, and doesn't need to be interactive.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// app/book/page.tsx&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="s2"&gt;"@/lib/opencals"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nc"&gt;ProductService&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"@opencals/storefront-sdk"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nc"&gt;ServiceCard&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"./service-card"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;default&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nc"&gt;BookPage&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
 &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;data&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;page&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nc"&gt;ProductService&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;list&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;query&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;status&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"active"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;take&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;50&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;throwOnError&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
 &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

 &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;
 &lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;main&lt;/span&gt; &lt;span class="n"&gt;className&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;"grid gap-4"&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;
 &lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="n"&gt;page&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;data&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;map&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;service&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;
 &lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nc"&gt;ServiceCard&lt;/span&gt; &lt;span class="n"&gt;key&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="n"&gt;service&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="n"&gt;service&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="n"&gt;service&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;/&amp;gt;&lt;/span&gt;
 &lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;
 &lt;span class="o"&gt;&amp;lt;/&lt;/span&gt;&lt;span class="n"&gt;main&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;
 &lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The list comes back as &lt;code&gt;{ data, meta }&lt;/code&gt;, fully typed. Each service carries its &lt;code&gt;price&lt;/code&gt; (a plain amount in the store's currency: &lt;code&gt;45&lt;/code&gt; is $45.00, not cents), &lt;code&gt;duration&lt;/code&gt; (seconds), &lt;code&gt;beforeGap&lt;/code&gt;/&lt;code&gt;afterGap&lt;/code&gt; buffers and a &lt;code&gt;variants&lt;/code&gt; array, each variant with its own price and duration. &lt;code&gt;formatPrice&lt;/code&gt; and &lt;code&gt;formatDuration&lt;/code&gt; from the SDK turn those into display strings. You render, you don't compute.&lt;/p&gt;

&lt;h2&gt;
  
  
  Step 3 — Fetch real-time availability
&lt;/h2&gt;

&lt;p&gt;This is the endpoint that would have taken you weeks to write. You pass a service and a date, optionally a staff member or location, and you get back the slots that are open right now.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// app/api/availability/route.ts  (Route Handler)&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nc"&gt;NextRequest&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nc"&gt;NextResponse&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"next/server"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="s2"&gt;"@/lib/opencals"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nc"&gt;ProductService&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"@opencals/storefront-sdk"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nc"&gt;GET&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;req&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;NextRequest&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
 &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;searchParams&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="no"&gt;URL&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;req&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;url&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

 &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;data&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;slots&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nc"&gt;ProductService&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;getCurrentAvailabilities&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;path&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;productId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;searchParams&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"productId"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;query&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="n"&gt;date&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;searchParams&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"date"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="c1"&gt;// YYYY-MM-DD&lt;/span&gt;
      &lt;span class="n"&gt;staffMemberId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;searchParams&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"staffMemberId"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;??&lt;/span&gt; &lt;span class="kc"&gt;undefined&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;timezone&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"Europe/Warsaw"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="c1"&gt;// your store's timezone&lt;/span&gt;
 &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
 &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

 &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nc"&gt;NextResponse&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;json&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;slots&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Each slot is &lt;code&gt;{ fromDate, fromTime, toDate, toTime, staffMemberIds, attendees, maxAttendees }&lt;/code&gt;, and the list already leaves out times that are booked, outside staff hours, or too close to another appointment given the service's buffers. Your calendar component fetches this route when the user picks a date and renders whatever comes back — no client-side conflict math. For a month view, &lt;code&gt;getCurrentAvailabilitiesMerged&lt;/code&gt; returns the broad open windows so you can grey out full days.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;The universal part&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Every booking backend worth using exposes an availability endpoint like this. If a tool only gives you raw calendar events and expects you to compute open slots yourself, you haven't offloaded the hard part — you've just moved it. Availability calculation is the feature to evaluate first.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  Step 4 — Hold the slot with a cart
&lt;/h2&gt;

&lt;p&gt;A slot is a scarce resource. Between "customer clicked 2pm" and "customer paid," you don't want someone else grabbing it, and you don't want to create a real booking that might never be paid for. A cart holds the slot for a short window: you create (or reuse) a cart, then create the appointment inside it.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// app/api/cart/route.ts&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nc"&gt;NextRequest&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nc"&gt;NextResponse&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"next/server"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;cookies&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"next/headers"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="s2"&gt;"@/lib/opencals"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nc"&gt;AppointmentService&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nc"&gt;CartService&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"@opencals/storefront-sdk"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nc"&gt;POST&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;req&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;NextRequest&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
 &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;slot&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;req&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;json&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="c1"&gt;// one slot from step 3&lt;/span&gt;
 &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;jar&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;cookies&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

 &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;data&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;cart&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nc"&gt;CartService&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;createOrGet&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;headers&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="s2"&gt;"X-Cart-Id"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;jar&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"cartId"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="o"&gt;?&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;value&lt;/span&gt; &lt;span class="o"&gt;??&lt;/span&gt; &lt;span class="s2"&gt;""&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
 &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

 &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nc"&gt;AppointmentService&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;create&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;body&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="n"&gt;slot&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="n"&gt;productId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;slot&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;productId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="n"&gt;fromDate&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;slot&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;fromDate&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="n"&gt;fromTime&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;slot&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;fromTime&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="n"&gt;toDate&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;slot&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;toDate&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="n"&gt;toTime&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;slot&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;toTime&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
 &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;numberOfAttendees&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;cartId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;cart&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
 &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
 &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="n"&gt;jar&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;set&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"cartId"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;cart&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;httpOnly&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;sameSite&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"lax"&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
 &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nc"&gt;NextResponse&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;json&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;cartId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;cart&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The cart ID lives in an httpOnly cookie, and every cart and checkout call names its cart with the &lt;code&gt;X-Cart-Id&lt;/code&gt; header. Times are UTC. If two people try to hold the same slot at the same moment, one succeeds and the other gets a clear error, so your UI can say "someone just took that time" instead of double-booking.&lt;/p&gt;

&lt;h2&gt;
  
  
  Step 5 — Check out and pay
&lt;/h2&gt;

&lt;p&gt;Checkout turns a held cart into a paid booking in two server calls with the card confirmation in between. &lt;code&gt;start&lt;/code&gt; attaches the customer, re-checks the cart and creates the payment; the browser confirms the card with Stripe; &lt;code&gt;submit&lt;/code&gt; places the order.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// app/api/checkout/start/route.ts&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nc"&gt;NextRequest&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nc"&gt;NextResponse&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"next/server"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;cookies&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"next/headers"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="s2"&gt;"@/lib/opencals"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nc"&gt;CheckoutService&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"@opencals/storefront-sdk"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nc"&gt;POST&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;req&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;NextRequest&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
 &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;email&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;firstName&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;lastName&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;req&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;json&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
 &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;cartId&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;cookies&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"cartId"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;value&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

 &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;data&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;checkout&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nc"&gt;CheckoutService&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;start&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;headers&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="s2"&gt;"X-Cart-Id"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;cartId&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;body&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;provider&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"stripe"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;customer&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;kind&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"new"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;email&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;firstName&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;lastName&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
 &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

 &lt;span class="c1"&gt;// The browser needs these to mount a Stripe Payment Element.&lt;/span&gt;
 &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nc"&gt;NextResponse&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;json&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;clientSecret&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;checkout&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;clientSecret&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;publishableKey&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;checkout&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;publishableKey&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;stripeAccountId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;checkout&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;stripeAccountId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
 &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// app/api/checkout/submit/route.ts — called after stripe.confirmPayment() succeeds in the browser&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nc"&gt;NextRequest&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nc"&gt;NextResponse&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"next/server"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;cookies&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"next/headers"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="s2"&gt;"@/lib/opencals"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nc"&gt;CheckoutService&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"@opencals/storefront-sdk"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nc"&gt;POST&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;req&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;NextRequest&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
 &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;paymentIntentId&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;req&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;json&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
 &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;cartId&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;cookies&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"cartId"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;value&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

 &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;data&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;result&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nc"&gt;CheckoutService&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;submit&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;headers&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="s2"&gt;"X-Cart-Id"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;cartId&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;body&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;stripePaymentIntentId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;paymentIntentId&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
 &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

 &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nc"&gt;NextResponse&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;json&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;result&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The Stripe publishable key comes back from &lt;code&gt;start&lt;/code&gt;, from the store's own Stripe connection, so there is no Stripe key to configure in your app. If the card wasn't authorised (declined, 3-D Secure not finished), &lt;code&gt;submit&lt;/code&gt; answers 402 with the code &lt;code&gt;PAYMENT_NOT_AUTHORIZED&lt;/code&gt;, no order is placed and the cart is untouched, so the customer can try again. A second &lt;code&gt;start&lt;/code&gt; or &lt;code&gt;submit&lt;/code&gt; on the same cart while one is running gets &lt;code&gt;CHECKOUT_IN_PROGRESS&lt;/code&gt; instead of a duplicate order. The slot only becomes a real booking once the payment is authorised.&lt;/p&gt;

&lt;h2&gt;
  
  
  Step 6 — Let customers manage their own bookings
&lt;/h2&gt;

&lt;p&gt;The reschedule-and-cancel flow is the one teams skip first and regret most, because without it every change becomes a support message. These calls run as the signed-in customer: &lt;code&gt;AuthService.signIn&lt;/code&gt; returns an &lt;code&gt;accessToken&lt;/code&gt;, and you send it as a Bearer token next to your store key, so the customer only sees and touches their own bookings.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// server code, with the customer's accessToken from AuthService.signIn&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="s2"&gt;"@/lib/opencals"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nc"&gt;AppointmentService&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"@opencals/storefront-sdk"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;asCustomer&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nc"&gt;Authorization&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="sb"&gt;`Bearer ${accessToken}`&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;data&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;upcoming&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nc"&gt;AppointmentService&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;list&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;headers&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;asCustomer&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;query&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;status&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"scheduled"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"pending"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;orderBy&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"from"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;order&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"ASC"&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nc"&gt;AppointmentService&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;reschedule&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;headers&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;asCustomer&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;path&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;appointmentId&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;body&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;slot&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;newSlot&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="c1"&gt;// a slot from getCurrentAvailabilities, fetched with excludeAppointmentId&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Pass &lt;code&gt;excludeAppointmentId&lt;/code&gt; when you fetch availability for a reschedule, so the appointment's own slot isn't shown as taken. The store's reschedule and cancel windows still apply. Wire these into an account page and the reschedule requests that used to hit your inbox now resolve themselves.&lt;/p&gt;

&lt;h2&gt;
  
  
  Putting it together
&lt;/h2&gt;

&lt;p&gt;The full flow, from the frontend's point of view, is six typed calls in five steps:&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;1. List services&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;ProductService.list() → render the catalog on a Server Component.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;2. Check availability&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;ProductService.getCurrentAvailabilities() → the open slots for a date, computed server-side.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;3. Hold the slot&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;CartService.createOrGet() + AppointmentService.create() → the chosen slot is held in a cart while the customer checks out.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;4. Start checkout&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;CheckoutService.start() → the customer is attached and a payment is created for the browser to confirm.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;5. Place the order&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;CheckoutService.submit() → the held slot becomes a real, paid booking.&lt;/p&gt;

&lt;p&gt;Everything hard about scheduling — the availability math, the race conditions, the payment-to-booking handoff — lives behind those calls. Your Next.js app stays a frontend: forms, a calendar grid, and route handlers that proxy to the API with your secret key.&lt;/p&gt;

&lt;h2&gt;
  
  
  When not to use an API for this
&lt;/h2&gt;

&lt;p&gt;Honest caveat, because not every project needs this. If you're a solo consultant booking 1:1 calls and you don't take payment up front, a hosted tool like &lt;a href="https://opencals.com/blog/compare/calendly" rel="noopener noreferrer"&gt;Calendly&lt;/a&gt; is simpler and you shouldn't build anything. An API earns its keep when you need a custom-branded flow, multiple staff or locations, payments at booking, or booking embedded inside a product you already own. That's when owning the frontend while renting the backend is the right trade — and the links below cover the endpoint surface, the architecture, and the typed SDK.&lt;/p&gt;

&lt;h2&gt;
  
  
  Where to go from here
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;a href="https://opencals.com/blog/booking-api" rel="noopener noreferrer"&gt;&lt;strong&gt;Booking API guide&lt;/strong&gt;&lt;/a&gt;: The endpoint-level reference: auth model, core routes, and the full booking flow in raw REST.&lt;/li&gt;
&lt;li&gt;
&lt;a href="https://opencals.com/blog/booking-sdk" rel="noopener noreferrer"&gt;&lt;strong&gt;Booking SDK&lt;/strong&gt;&lt;/a&gt;: The typed TypeScript SDK used in this guide — services, availability, cart, and checkout end to end.&lt;/li&gt;
&lt;li&gt;
&lt;a href="https://opencals.com/blog/headless-booking-system" rel="noopener noreferrer"&gt;&lt;strong&gt;Headless booking system&lt;/strong&gt;&lt;/a&gt;: The architecture behind building a custom booking frontend on any stack.&lt;/li&gt;
&lt;li&gt;
&lt;a href="https://opencals.com/developers" rel="noopener noreferrer"&gt;&lt;strong&gt;Opencals for developers&lt;/strong&gt;&lt;/a&gt;: API docs, the OpenAPI spec, and how to get a storefront key.&lt;/li&gt;
&lt;li&gt;
&lt;a href="https://opencals.com/blog/build-a-booking-website" rel="noopener noreferrer"&gt;&lt;strong&gt;Build a booking website&lt;/strong&gt;&lt;/a&gt;: Three approaches compared, from no-code to a fully custom build.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Frequently asked questions
&lt;/h2&gt;

&lt;h3&gt;
  
  
  Can I add booking to Next.js without a third-party API?
&lt;/h3&gt;

&lt;p&gt;Yes, but you're then building a scheduling engine: real-time availability across staff and services, buffer logic, race-safe slot holding, and payment-to-booking handoff. For a single service with no payments that's doable in a weekend. For anything with multiple staff, locations, or paid bookings, the availability and concurrency logic is where most of the effort goes — which is what an API removes.&lt;/p&gt;

&lt;h3&gt;
  
  
  Where do I keep the booking API key in Next.js?
&lt;/h3&gt;

&lt;p&gt;Server-side only — in an environment variable read by Route Handlers or Server Actions. A storefront key can create real bookings and charges, so it must never ship in a client bundle. The browser calls your own Next.js API routes; those routes call the booking API with the secret key.&lt;/p&gt;

&lt;h3&gt;
  
  
  Does this work with the App Router and Server Components?
&lt;/h3&gt;

&lt;p&gt;Yes. Public reads like the service catalog fit Server Components and stream as HTML, which is good for SEO. Anything that mutates — cart, checkout, reschedule — goes in Route Handlers or Server Actions so the secret key stays on the server.&lt;/p&gt;

&lt;h3&gt;
  
  
  How is a booking API different from a calendar API like Google Calendar?
&lt;/h3&gt;

&lt;p&gt;A calendar API stores and returns events. A booking API computes availability — it knows service durations, staff assignments, buffers, and existing bookings, and returns the slots a customer can actually book. With a calendar API you'd still have to write all of that logic yourself on top of raw events.&lt;/p&gt;

&lt;h3&gt;
  
  
  Can customers reschedule or cancel on their own?
&lt;/h3&gt;

&lt;p&gt;Yes. The customer signs in through the API (AuthService.signIn returns an access token), and your server calls AppointmentService.list, reschedule and cancel with that token as a Bearer header next to the store key, so each customer only sees their own bookings. The store's reschedule and cancel windows still apply. Wire them into an account page and the change requests you'd otherwise answer by email resolve themselves.&lt;/p&gt;

</description>
      <category>nextjs</category>
      <category>react</category>
      <category>webdev</category>
      <category>tutorial</category>
    </item>
    <item>
      <title>Headless Booking System: Run Booking Behind Your Own UI</title>
      <dc:creator>Stan</dc:creator>
      <pubDate>Tue, 10 Nov 2026 05:48:44 +0000</pubDate>
      <link>https://dev.to/stangineer/headless-booking-system-run-booking-behind-your-own-ui-2h1d</link>
      <guid>https://dev.to/stangineer/headless-booking-system-run-booking-behind-your-own-ui-2h1d</guid>
      <description>&lt;p&gt;&lt;em&gt;Originally published on &lt;a href="https://opencals.com/blog/headless-booking-system" rel="noopener noreferrer"&gt;opencals.com&lt;/a&gt;. The original stays updated; check it for the latest version.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;Most booking software ships as a complete package: the database, the availability logic, the calendar widget, and the customer-facing UI are all bundled together. You install it, configure it, and your booking page looks like everyone else's booking page.&lt;/p&gt;

&lt;p&gt;A &lt;strong&gt;headless booking system&lt;/strong&gt; takes a different approach. It exposes everything the software knows — services, staff, real-time availability, cart, checkout, payments — through a REST API. You build the customer-facing UI however you want. The backend handles the hard parts; the frontend is entirely yours.&lt;/p&gt;

&lt;p&gt;This is the same architectural pattern that powers headless commerce (Shopify Storefront API, Medusa) and headless CMS (Contentful, Sanity). Headless booking applies the same idea to scheduling and service businesses.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Key takeaway&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;In a headless booking system, the API is the product. The UI is your responsibility — but it can look like anything, live anywhere, and be built with any technology stack.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  Headless vs traditional booking software
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;&lt;/th&gt;
&lt;th&gt;Traditional booking software&lt;/th&gt;
&lt;th&gt;Headless booking system&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Frontend UI&lt;/td&gt;
&lt;td&gt;Provided by the vendor — limited customisation&lt;/td&gt;
&lt;td&gt;Fully custom — you build it&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Integration&lt;/td&gt;
&lt;td&gt;Embed a widget or use a hosted page&lt;/td&gt;
&lt;td&gt;API calls from any frontend or backend&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Design control&lt;/td&gt;
&lt;td&gt;Theme options, CSS overrides&lt;/td&gt;
&lt;td&gt;Pixel-perfect, no constraints&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Stack flexibility&lt;/td&gt;
&lt;td&gt;Vendor's stack only&lt;/td&gt;
&lt;td&gt;React, Next.js, Vue, mobile — anything&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Multi-surface&lt;/td&gt;
&lt;td&gt;One widget, one hosted page&lt;/td&gt;
&lt;td&gt;Web, mobile, kiosk, Shopify, voice — same API&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Setup time&lt;/td&gt;
&lt;td&gt;Hours to days&lt;/td&gt;
&lt;td&gt;Days to weeks (frontend build)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Best for&lt;/td&gt;
&lt;td&gt;Businesses that want to move fast with standard UX&lt;/td&gt;
&lt;td&gt;Businesses that need a custom experience or multi-channel booking&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;h2&gt;
  
  
  When does a headless approach make sense?
&lt;/h2&gt;

&lt;p&gt;Not every business needs headless. Here's how to tell if it's the right fit:&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;You need a custom UI.&lt;/strong&gt; Your brand is strong enough that a generic booking widget would feel wrong. A high-end spa, a luxury hotel, a medical clinic with specific patient flows — these businesses need a booking experience that matches their identity, not a themed SaaS widget.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;You're building a multi-surface product.&lt;/strong&gt; You want the same availability engine to power a website, a mobile app, and a Shopify storefront — all at once. Traditional booking software typically forces you to pick one surface. Headless lets one backend serve all of them.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;You're an agency or freelancer building for clients.&lt;/strong&gt; Every client needs a different booking UI. With a headless backend, you write one integration and deploy customised frontends across multiple clients, and the backend stays the same underneath each one.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;You're a developer who wants control.&lt;/strong&gt; You're comfortable with REST APIs and you'd rather spend a week building a clean Next.js booking page than spend a month hacking around widget limitations.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;You need to embed booking inside another product.&lt;/strong&gt; Not a standalone booking page — a booking flow inside your existing app or platform, with your own auth, your own data model, and your own UX.&lt;/p&gt;

&lt;p&gt;When headless isn't the right choice&lt;/p&gt;

&lt;p&gt;If you're a single-location salon or yoga studio that just needs a booking page live this week, headless adds friction without much benefit. A traditional Shopify booking app or an all-in-one SaaS platform will get you there faster. Headless pays off when the UI customisation need is real and the development resources exist.&lt;/p&gt;

&lt;h2&gt;
  
  
  What a headless booking API actually exposes
&lt;/h2&gt;

&lt;p&gt;A proper headless booking API needs to cover the full customer journey, not just availability lookup. The Opencals Storefront API, for example, covers:&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;1. Service catalog&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;List services (products), collections, variants, and pricing. This is what you show on your booking homepage — the service menu.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;2. Staff and locations&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;List staff members and locations. Customers pick who they want to book with and where, filtering availability accordingly.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;3. Real-time availability&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Get available time slots for a given service, staff member, location, and date range. The API handles all the scheduling logic — staff hours, existing bookings, break times, buffer time.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;4. Cart&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Create and manage a booking cart. Supports multiple services, multiple staff, mixed appointment types. The cart persists so customers can build a complex booking across multiple steps.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;5. Checkout and payment&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Initiate checkout, collect payment via Stripe (or pay later, if the store allows it), and confirm the booking. Deposits are in beta.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;6. Customer self-service&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Authenticated endpoints for customers to view, reschedule, and cancel their own bookings without calling the salon.&lt;/p&gt;

&lt;p&gt;Some booking APIs stop at availability and booking creation, which leaves you to build or bolt on your own cart, payment, and post-booking management. A complete headless booking API handles that whole chain.&lt;/p&gt;

&lt;h2&gt;
  
  
  Building on the Opencals Storefront API
&lt;/h2&gt;

&lt;p&gt;Opencals is built headless-first. The same API that powers the Opencals dashboard and the Shopify app is publicly available as the &lt;a href="https://opencals.com/docs/api-reference/introduction" rel="noopener noreferrer"&gt;Storefront API&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;Server code authenticates with a private storefront key (&lt;code&gt;spk_…&lt;/code&gt;) scoped to a single store, sent in an &lt;code&gt;X-Api-Key&lt;/code&gt; header. You create it in the Opencals dashboard under Users → your user → API Keys, and the SDK's &lt;code&gt;buyerIp&lt;/code&gt; option forwards each visitor's IP so rate limits count per visitor.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="c"&gt;# Get your store's available services&lt;/span&gt;
curl https://api.opencals.com/storefront/products \
 -H &lt;span class="s2"&gt;"X-Api-Key: spk_your_api_key"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The typed TypeScript SDK handles auth, request construction, and response parsing:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;setupOpencals&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nc"&gt;ProductService&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"@opencals/storefront-sdk"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;nextBuyerIp&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"@opencals/storefront-sdk/next"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="nf"&gt;setupOpencals&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;apiKey&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nb"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="no"&gt;OPENCALS_API_KEY&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="c1"&gt;// spk_…&lt;/span&gt;
  &lt;span class="n"&gt;buyerIp&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;nextBuyerIp&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="c1"&gt;// forwards each visitor's IP (Next.js, SDK 0.3.19+)&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;data&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;page&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nc"&gt;ProductService&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;list&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;throwOnError&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="c1"&gt;// page.data is the typed service list, page.meta the pagination — no casting needed&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The fastest way to see the full stack in action is the &lt;a href="https://github.com/letsopencals/template-haar" rel="noopener noreferrer"&gt;Haar open-source template&lt;/a&gt; — a complete Next.js 15 salon booking website built on the Storefront API, MIT licensed, one-click Vercel deploy.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fletsopencals%2Ftemplate-haar" rel="noopener noreferrer"&gt;Deploy with Vercel&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Headless booking and Shopify
&lt;/h2&gt;

&lt;p&gt;A common pattern: a Shopify store as the product storefront, headless booking for the service side. Instead of embedding a widget inside a Shopify product page, you build a custom &lt;code&gt;/book&lt;/code&gt; route (or an entirely separate domain) that calls the Opencals API, with the same availability engine and the same Shopify customer account.&lt;/p&gt;

&lt;p&gt;The Opencals Shopify app and the Storefront API share one backend. You can run both simultaneously — the Shopify app for customers who discover you through the product storefront, the custom UI for customers who arrive at your booking site directly. If the Shopify half isn't set up yet, &lt;a href="https://opencals.com/blog/sell-services-on-shopify" rel="noopener noreferrer"&gt;selling services on Shopify&lt;/a&gt; covers that side step by step.&lt;/p&gt;

&lt;h2&gt;
  
  
  Related reading
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;a href="https://opencals.com/docs" rel="noopener noreferrer"&gt;&lt;strong&gt;Storefront API reference&lt;/strong&gt;&lt;/a&gt;: Every endpoint, with an interactive playground and TypeScript examples.&lt;/li&gt;
&lt;li&gt;
&lt;a href="https://opencals.com/docs/guides/build-a-booking-page" rel="noopener noreferrer"&gt;&lt;strong&gt;Build a booking page tutorial&lt;/strong&gt;&lt;/a&gt;: End-to-end walkthrough: services → availability → cart → checkout in Next.js.&lt;/li&gt;
&lt;li&gt;
&lt;a href="https://opencals.com/docs/open-source/templates" rel="noopener noreferrer"&gt;&lt;strong&gt;Open-source booking templates&lt;/strong&gt;&lt;/a&gt;: Production-ready Next.js starters built on the Storefront API. MIT licensed.&lt;/li&gt;
&lt;li&gt;
&lt;a href="https://opencals.com/blog/booking-api" rel="noopener noreferrer"&gt;&lt;strong&gt;Booking API guide for developers&lt;/strong&gt;&lt;/a&gt;: What to look for in a booking API and how the Opencals API is structured.&lt;/li&gt;
&lt;li&gt;
&lt;a href="https://opencals.com/blog/supabase-booking-system" rel="noopener noreferrer"&gt;&lt;strong&gt;Supabase booking system&lt;/strong&gt;&lt;/a&gt;: Keep Supabase for users and data, and let the headless API handle availability, carts and payments.&lt;/li&gt;
&lt;li&gt;
&lt;a href="https://opencals.com/blog/online-booking-system-for-hotels" rel="noopener noreferrer"&gt;&lt;strong&gt;Online booking system for hotels&lt;/strong&gt;&lt;/a&gt;: Direct hotel bookings with extras, add-ons and guest accounts on the same API.&lt;/li&gt;
&lt;li&gt;
&lt;a href="https://opencals.com/blog/sell-services-on-shopify" rel="noopener noreferrer"&gt;&lt;strong&gt;Selling services on Shopify&lt;/strong&gt;&lt;/a&gt;: Set up the Shopify storefront side: service products, variants, checkout and the booking app's job.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Frequently asked questions
&lt;/h2&gt;

&lt;h3&gt;
  
  
  What is a headless booking system?
&lt;/h3&gt;

&lt;p&gt;A headless booking system separates the booking backend (availability engine, scheduling logic, payments) from the frontend UI. Instead of providing a pre-built widget or hosted page, it exposes a REST API that you use to build any booking UI you want. The term 'headless' comes from the headless CMS and headless commerce patterns — same idea applied to booking.&lt;/p&gt;

&lt;h3&gt;
  
  
  What's the difference between headless booking and embedding a booking widget?
&lt;/h3&gt;

&lt;p&gt;A booking widget is a pre-built UI component provided by the booking software vendor. You embed it in your site, but you can't control what it looks like or how it works beyond the configuration options the vendor provides. A headless API gives you the raw data and logic — availability, staff, pricing — and you build the UI from scratch. More work, but complete control.&lt;/p&gt;

&lt;h3&gt;
  
  
  Do I need headless booking, or will a standard booking app be enough?
&lt;/h3&gt;

&lt;p&gt;If you need a booking page live quickly and a standard widget UI is acceptable, a traditional booking app is faster and cheaper. Headless makes sense when: (1) your brand requires a custom UI, (2) you need to embed booking inside an existing product, (3) you're building for multiple surfaces (web, mobile, Shopify), or (4) you're an agency building for multiple clients.&lt;/p&gt;

&lt;h3&gt;
  
  
  What technology stack do I need to build on a headless booking API?
&lt;/h3&gt;

&lt;p&gt;Any stack that can make HTTP requests. Most teams building on the Opencals Storefront API use Next.js with the typed TypeScript SDK, which handles request construction, authentication, and response parsing. But you can use the REST API directly from Python, Go, Ruby, mobile (iOS/Android), or any other language. The OpenAPI spec is published at opencals.com/docs.&lt;/p&gt;

&lt;h3&gt;
  
  
  Is there an open-source headless booking example I can start from?
&lt;/h3&gt;

&lt;p&gt;Yes — the Haar template is a complete Next.js 15 salon booking website built on the Opencals Storefront API. It covers the full flow: service catalog, staff picker, real-time availability, cart, Stripe checkout, and customer account. MIT licensed. Clone it from GitHub or one-click deploy to Vercel.&lt;/p&gt;

&lt;h3&gt;
  
  
  Does Opencals support both headless and native Shopify integration?
&lt;/h3&gt;

&lt;p&gt;Yes. The Opencals Shopify app and the Storefront API share the same backend. You can run both simultaneously — a native Shopify integration for customers who discover your store through Shopify, and a custom headless frontend for customers arriving via your own domain. Both use the same availability engine, the same staff schedules, and the same calendar.&lt;/p&gt;

</description>
      <category>webdev</category>
      <category>api</category>
      <category>nextjs</category>
      <category>tutorial</category>
    </item>
    <item>
      <title>One availability read per house: how my open-source coworking template books a whole day</title>
      <dc:creator>Stan</dc:creator>
      <pubDate>Thu, 05 Nov 2026 05:51:46 +0000</pubDate>
      <link>https://dev.to/stangineer/one-availability-read-per-house-how-my-open-source-coworking-template-books-a-whole-day-25he</link>
      <guid>https://dev.to/stangineer/one-availability-read-per-house-how-my-open-source-coworking-template-books-a-whole-day-25he</guid>
      <description>&lt;p&gt;A coworking member's day is rarely one booking. It's a desk from nine, a meeting room for the 11 o'clock, and somewhere quiet for a call at two. Most booking widgets sell those one at a time: three flows, three checkouts, three confirmation emails.&lt;/p&gt;

&lt;p&gt;Gable is the open-source Next.js template I built to sell the day instead. It's a coworking site for a made-up network of six buildings in Dublin, Cork and Galway, with 77 bookable spaces, and the whole design is drawn like an architect's drawing set. This post is about the parts I'd copy into any multi-resource booking site: how it reads availability, why the browser does the maths, and how it suggests what your day is missing without calling an API.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://template-gable.vercel.app" rel="noopener noreferrer"&gt;Live demo&lt;/a&gt; · &lt;a href="https://github.com/letsopencals/template-gable" rel="noopener noreferrer"&gt;GitHub&lt;/a&gt; (MIT) · &lt;a href="https://opencals.com/blog/templates/gable" rel="noopener noreferrer"&gt;the longer write-up&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  The cart is a day sheet
&lt;/h2&gt;

&lt;p&gt;The planner at &lt;code&gt;/book&lt;/code&gt; is a search, not a wizard. You pick a house, a day, how long, a start time and how many people, and you get the spaces that fit, each with a day bar where booked time is hatched like a cut wall in a drawing.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fhu59xe6pbg02f20n3dwo.jpg" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fhu59xe6pbg02f20n3dwo.jpg" alt="Gable's planner at Dock House: the day, length and start pickers on the left, nine desks listed below, and on the right a day sheet holding a flex desk (14:00–18:00) and the Liffey meeting room (14:30–15:30, coffee for six), held for 14:46, total €107 with a first-day discount" width="800" height="500"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;Whatever you add lands on the &lt;strong&gt;day sheet&lt;/strong&gt; on the right, which is the cart drawn as a timeline from 08:00 to 20:00. Each booking is held for 15 minutes while you plan the rest, so the room you picked first is still yours when you go back for a desk. Checkout happens once, for everything.&lt;/p&gt;

&lt;p&gt;The planner state lives in the URL (&lt;code&gt;/book?house=dock-house&amp;amp;kind=room&amp;amp;date=…&amp;amp;start=10:00&amp;amp;length=60&amp;amp;people=6&lt;/code&gt;), so a link from the home page or a space page lands on the exact search.&lt;/p&gt;

&lt;h2&gt;
  
  
  One availability read per house, not one per space per day
&lt;/h2&gt;

&lt;p&gt;Every space in Gable is its own resource: a room, a booth, a studio desk. The booking API answers availability per space. The naive version of this page asks for every space, for the selected day, every time you change the day, and with 77 spaces across six houses and a 21-day window, that gets expensive fast.&lt;/p&gt;

&lt;p&gt;Gable flips it. The server asks each space &lt;strong&gt;once&lt;/strong&gt; for its merged free ranges across the whole booking horizon (no &lt;code&gt;date&lt;/code&gt; parameter), caches each space for 60 seconds, and sends the browser one response per house. This is &lt;code&gt;lib/availability-server.ts&lt;/code&gt;, trimmed:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;readRanges&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;spaceId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;houseId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;tz&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt;&lt;span class="p"&gt;):&lt;/span&gt; &lt;span class="nb"&gt;Promise&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nx"&gt;Packed&lt;/span&gt;&lt;span class="p"&gt;[]&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;for &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kd"&gt;let&lt;/span&gt; &lt;span class="nx"&gt;attempt&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="nx"&gt;attempt&lt;/span&gt;&lt;span class="o"&gt;++&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;try&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="c1"&gt;// throwOnError is required: without it the SDK resolves a 429 as an empty result.&lt;/span&gt;
      &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;data&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;ProductService&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;getCurrentAvailabilitiesMerged&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt;
        &lt;span class="na"&gt;path&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;productId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;spaceId&lt;/span&gt; &lt;span class="p"&gt;},&lt;/span&gt;
        &lt;span class="na"&gt;query&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;locationId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;houseId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;timezone&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;tz&lt;/span&gt; &lt;span class="p"&gt;},&lt;/span&gt;
        &lt;span class="na"&gt;throwOnError&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="p"&gt;});&lt;/span&gt;
      &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;until&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;nowMin&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;WINDOW_DAYS&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="mi"&gt;1440&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
      &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nf"&gt;mergePacked&lt;/span&gt;&lt;span class="p"&gt;((&lt;/span&gt;&lt;span class="nx"&gt;data&lt;/span&gt; &lt;span class="o"&gt;??&lt;/span&gt; &lt;span class="p"&gt;[]).&lt;/span&gt;&lt;span class="nf"&gt;map&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;pack&lt;/span&gt;&lt;span class="p"&gt;)).&lt;/span&gt;&lt;span class="nf"&gt;filter&lt;/span&gt;&lt;span class="p"&gt;(([&lt;/span&gt;&lt;span class="nx"&gt;s&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;len&lt;/span&gt;&lt;span class="p"&gt;])&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nx"&gt;len&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="nx"&gt;s&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&lt;/span&gt; &lt;span class="nx"&gt;until&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;catch &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;err&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;status&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;err&lt;/span&gt; &lt;span class="k"&gt;instanceof&lt;/span&gt; &lt;span class="nx"&gt;OpencalsApiError&lt;/span&gt; &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="nx"&gt;err&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;status&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
      &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;retriable&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;status&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="mi"&gt;429&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="nx"&gt;status&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="mi"&gt;503&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="nx"&gt;status&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
      &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nx"&gt;retriable&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="nx"&gt;attempt&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;=&lt;/span&gt; &lt;span class="nx"&gt;MAX_RETRIES&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;throw&lt;/span&gt; &lt;span class="nx"&gt;err&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
      &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;sleep&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;400&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="mi"&gt;2&lt;/span&gt; &lt;span class="o"&gt;**&lt;/span&gt; &lt;span class="nx"&gt;attempt&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="nb"&gt;Math&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;floor&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nb"&gt;Math&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;random&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="mi"&gt;250&lt;/span&gt;&lt;span class="p"&gt;));&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;cachedRanges&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;spaceId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;houseId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;tz&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nf"&gt;unstable_cache&lt;/span&gt;&lt;span class="p"&gt;(()&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nf"&gt;readRanges&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;spaceId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;houseId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;tz&lt;/span&gt;&lt;span class="p"&gt;),&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;space-ranges-v1&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;spaceId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;houseId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;tz&lt;/span&gt;&lt;span class="p"&gt;],&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="na"&gt;revalidate&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;60&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="na"&gt;tags&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;availability&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;`space:&lt;/span&gt;&lt;span class="p"&gt;${&lt;/span&gt;&lt;span class="nx"&gt;spaceId&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s2"&gt;`&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;`house:&lt;/span&gt;&lt;span class="p"&gt;${&lt;/span&gt;&lt;span class="nx"&gt;houseId&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s2"&gt;`&lt;/span&gt;&lt;span class="p"&gt;],&lt;/span&gt;
  &lt;span class="p"&gt;})();&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Three details in there cost me time:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;That &lt;code&gt;throwOnError&lt;/code&gt; comment is real.&lt;/strong&gt; Without it, a rate-limited request resolves as an empty list, and an empty list looks exactly like "fully booked". You'd show a house as full because you asked too fast.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The reads run three at a time&lt;/strong&gt;, with exponential backoff and jitter on 429 and 503. A space that still fails isn't cached; it goes into a &lt;code&gt;failed&lt;/code&gt; list in the response, and the client asks again for just that space a moment later.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The cache tags are what keep it honest.&lt;/strong&gt; A booking drops the &lt;code&gt;space:&amp;lt;id&amp;gt;&lt;/code&gt; tag for that space; a cancel, a move or a cart removal drops the house. So the 60-second cache never shows a slot as free after someone took it through this site.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  The browser does the maths
&lt;/h2&gt;

&lt;p&gt;Each free range is packed into a tuple, &lt;code&gt;[start, length, taken, capacity]&lt;/code&gt;, in UTC epoch minutes. For a meeting room &lt;code&gt;taken&lt;/code&gt; is 0 and &lt;code&gt;capacity&lt;/code&gt; is 1. For the open-plan flex floor, which is one product with 40 seats, &lt;code&gt;taken&lt;/code&gt; is the peak number of seats already booked over that span.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;type&lt;/span&gt; &lt;span class="nx"&gt;Packed&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nx"&gt;start&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;number&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;length&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;number&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;taken&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;number&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;capacity&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;number&lt;/span&gt;&lt;span class="p"&gt;];&lt;/span&gt;

&lt;span class="cm"&gt;/** Seats still free for the whole of [start, start + minutes] (0 when it doesn't fit). */&lt;/span&gt;
&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;seatsLeft&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;ranges&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;Packed&lt;/span&gt;&lt;span class="p"&gt;[]&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="kc"&gt;undefined&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;start&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;number&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;minutes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;number&lt;/span&gt;&lt;span class="p"&gt;):&lt;/span&gt; &lt;span class="kr"&gt;number&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;r&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;covering&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;ranges&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;start&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;minutes&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;r&lt;/span&gt; &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="nb"&gt;Math&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;max&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;r&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="mi"&gt;3&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt; &lt;span class="nx"&gt;r&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="mi"&gt;2&lt;/span&gt;&lt;span class="p"&gt;])&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;fits&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;ranges&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;Packed&lt;/span&gt;&lt;span class="p"&gt;[]&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="kc"&gt;undefined&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;start&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;number&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;minutes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;number&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;seats&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;):&lt;/span&gt; &lt;span class="nx"&gt;boolean&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nf"&gt;seatsLeft&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;ranges&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;start&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;minutes&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;=&lt;/span&gt; &lt;span class="nb"&gt;Math&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;max&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;seats&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Everything on the planner comes from those few functions: which spaces fit, "Free at 10:00", "Next free 14:30", "23 seats free", the start times, the day strip. Changing the day, the length, the start or the number of people never calls the API.&lt;/p&gt;

&lt;p&gt;Two small things worth knowing if you do this yourself. The API can split one free range at a one-second seam, so &lt;code&gt;mergePacked&lt;/code&gt; joins spans that touch. And because the merged range reports the &lt;em&gt;peak&lt;/em&gt; seats taken, "seats left" is conservative: it may say 22 when 23 are free for part of the span, never the other way round.&lt;/p&gt;

&lt;h2&gt;
  
  
  "Fits in your day" runs without a single API call
&lt;/h2&gt;

&lt;p&gt;Under the day sheet there's a short list of suggestions, and it's my favourite part of the template:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;a desk around your meetings, on the same floor,&lt;/li&gt;
&lt;li&gt;a phone booth in the half hour between two meetings,&lt;/li&gt;
&lt;li&gt;lunch or coffee for the number of people in a room,&lt;/li&gt;
&lt;li&gt;a bigger room that's free at the same time, when your guest list is close to the room's seats,&lt;/li&gt;
&lt;li&gt;parking at the houses that have it.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;All of it is &lt;code&gt;lib/upsell.ts&lt;/code&gt;, computed from what's already on the sheet and the ranges the browser already holds. The booth one is the whole idea in eight lines:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// 3. A booth in a gap&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;booths&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;houseSpaces&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;filter&lt;/span&gt;&lt;span class="p"&gt;((&lt;/span&gt;&lt;span class="nx"&gt;s&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nx"&gt;s&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;kind&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;booth&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="k"&gt;for &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kd"&gt;let&lt;/span&gt; &lt;span class="nx"&gt;i&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="nx"&gt;i&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&lt;/span&gt; &lt;span class="nx"&gt;today&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;length&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="nx"&gt;booths&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;length&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="nx"&gt;i&lt;/span&gt;&lt;span class="o"&gt;++&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;gapStart&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;today&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nx"&gt;i&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;end&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;gapEnd&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;today&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nx"&gt;i&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;start&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;gapEnd&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt; &lt;span class="nx"&gt;gapStart&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&lt;/span&gt; &lt;span class="mi"&gt;30&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;continue&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;booth&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;booths&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;find&lt;/span&gt;&lt;span class="p"&gt;((&lt;/span&gt;&lt;span class="nx"&gt;s&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nf"&gt;fits&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;ranges&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nx"&gt;s&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt;&lt;span class="p"&gt;],&lt;/span&gt; &lt;span class="nx"&gt;gapStart&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;30&lt;/span&gt;&lt;span class="p"&gt;));&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;booth&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nx"&gt;out&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;push&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt; &lt;span class="na"&gt;key&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;`booth:&lt;/span&gt;&lt;span class="p"&gt;${&lt;/span&gt;&lt;span class="nx"&gt;gapStart&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s2"&gt;`&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;type&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;add&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;space&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;booth&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;start&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;gapStart&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;minutes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;30&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
               &lt;span class="na"&gt;price&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nf"&gt;priceFor&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;booth&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;30&lt;/span&gt;&lt;span class="p"&gt;),&lt;/span&gt; &lt;span class="na"&gt;title&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;A booth between meetings&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
               &lt;span class="na"&gt;note&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;`&lt;/span&gt;&lt;span class="p"&gt;${&lt;/span&gt;&lt;span class="nx"&gt;booth&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;name&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s2"&gt; is free for that half hour`&lt;/span&gt; &lt;span class="p"&gt;});&lt;/span&gt;
    &lt;span class="k"&gt;break&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Every suggestion is checked with &lt;code&gt;fits()&lt;/code&gt; before it's shown, so it never offers a booth that's taken.&lt;/p&gt;

&lt;h2&gt;
  
  
  Same key setup as the other templates
&lt;/h2&gt;

&lt;p&gt;Gable calls the API from its own server, so it uses a private storefront key (&lt;code&gt;spk_&lt;/code&gt;) and forwards each visitor's IP, which means every visitor gets their own rate limit instead of all of them sharing your server's:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// lib/opencals.ts&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;setupOpencals&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;@opencals/storefront-sdk&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;nextBuyerIp&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;@opencals/storefront-sdk/next&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="nf"&gt;setupOpencals&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt;
  &lt;span class="na"&gt;baseUrl&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;OPENCALS_API_URL&lt;/span&gt; &lt;span class="o"&gt;??&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;https://api.opencals.com&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="na"&gt;apiKey&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;OPENCALS_API_KEY&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="c1"&gt;// spk_…&lt;/span&gt;
  &lt;span class="na"&gt;buyerIp&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;nextBuyerIp&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;});&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  The confirmation is a drawing of the building
&lt;/h2&gt;

&lt;p&gt;After checkout, &lt;code&gt;/thank-you&lt;/code&gt; draws a section through the house, with each booked space on its floor and a dashed route from the front door, next to a title block with the date, the bookings, the total and how you're paying. It prints as a one-page day sheet with the site chrome hidden.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fcxjbh4xq0ey86hkfc4hf.jpg" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fcxjbh4xq0ey86hkfc4hf.jpg" alt="Gable's confirmation page: &amp;quot;You're booked, Aoife.&amp;quot; above a building section drawing of Dock House with Liffey on level 2 and the flex floor on level 1 highlighted, and a title block with the date, two bookings and €98.60 to pay at the front desk" width="800" height="500"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;The account opens on a &lt;strong&gt;Week plan&lt;/strong&gt; rather than a list, because coworking members book in patterns: Monday and Thursday at a desk, the same room every Tuesday. Desks are hatched, rooms are solid, and each upcoming booking has Change time, Stay longer, Invite and Cancel.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fz7c8k3f860md4q0cm7zx.jpg" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fz7c8k3f860md4q0cm7zx.jpg" alt="Gable's account page: a Week plan with seven columns, Monday to Sunday, desk bookings hatched and room bookings in solid blue, drawn to scale" width="800" height="500"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Where it stops
&lt;/h2&gt;

&lt;p&gt;So you don't find out after you've forked it:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;No monthly memberships or credit allowances.&lt;/strong&gt; Gable is pay-as-you-go. If your coworking space runs on "10 room hours included" plans, you need a membership system alongside it. Memberships are in beta on the Opencals side.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;No doors, Wi-Fi or printers.&lt;/strong&gt; It collects a meeting name "for the door screen" at checkout, and that's as far as it goes into the building.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;No webhooks yet.&lt;/strong&gt; Booking events reach other tools through Zapier.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The engine isn't open source.&lt;/strong&gt; The template, the SDK and the agent skills are MIT. Availability, holds, payments and accounts run on Opencals, which is a hosted service and the thing I build. The free development store has every feature in test mode, but it can't take real payments.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Running your own copy
&lt;/h2&gt;

&lt;ol&gt;
&lt;li&gt;Sign up at &lt;a href="https://app.opencals.com" rel="noopener noreferrer"&gt;app.opencals.com&lt;/a&gt;, create a Dev Store in Ireland (the store's country sets the currency) and choose the &lt;strong&gt;Gable (Coworking)&lt;/strong&gt; dataset. It seeds the six houses, 77 spaces, 16 extras, three discounts and the checkout questions.&lt;/li&gt;
&lt;li&gt;Create a private storefront key (&lt;code&gt;spk_&lt;/code&gt;) in the dashboard.&lt;/li&gt;
&lt;li&gt;Deploy with the Vercel button in the README, setting &lt;code&gt;OPENCALS_API_KEY&lt;/code&gt; and &lt;code&gt;AUTH_SECRET&lt;/code&gt;.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fspyojv9mmtbnp1992eje.jpg" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fspyojv9mmtbnp1992eje.jpg" alt="Gable's planner showing meeting rooms at Dock House for six people, with day, length and start-time pickers and an empty day sheet reading &amp;quot;Plan the day in one go&amp;quot;" width="800" height="500"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;To check the screens after booking without making a booking, run it locally and open &lt;code&gt;/preview&lt;/code&gt;, which renders them from fixtures built from your catalogue.&lt;/p&gt;

&lt;p&gt;The previous post in this series was the &lt;a href="https://dev.to/stangineer/i-rebuilt-my-open-source-salon-booking-template-one-page-instead-of-a-wizard-301l"&gt;Haar salon template rebuild&lt;/a&gt;. If you build something on Gable, or think the one-read-per-house approach breaks somewhere I haven't hit yet, I'd like to hear it in the comments.&lt;/p&gt;

</description>
      <category>nextjs</category>
      <category>webdev</category>
      <category>opensource</category>
      <category>showdev</category>
    </item>
    <item>
      <title>Supabase Booking System: Add Real Bookings (2026)</title>
      <dc:creator>Stan</dc:creator>
      <pubDate>Tue, 03 Nov 2026 11:41:00 +0000</pubDate>
      <link>https://dev.to/stangineer/supabase-booking-system-add-real-bookings-2026-1pil</link>
      <guid>https://dev.to/stangineer/supabase-booking-system-add-real-bookings-2026-1pil</guid>
      <description>&lt;p&gt;&lt;em&gt;Originally published on &lt;a href="https://opencals.com/blog/supabase-booking-system" rel="noopener noreferrer"&gt;opencals.com&lt;/a&gt;. The original stays updated; check it for the latest version.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;The question usually arrives after the first demo works. Someone has built an app in Lovable or Bolt, Supabase is already the backend, there's a &lt;code&gt;bookings&lt;/code&gt; table with a start time in it, and the calendar looks right. Then a friend books the same 10:30 as their mum, both get a confirmation, and the question becomes: how do I make this real?&lt;/p&gt;

&lt;p&gt;My answer is to stop treating the booking table as something you have to build. Supabase is very good at the parts of your app that are yours: sign-in, profiles, your own data, file storage. Availability across staff and opening hours, slot holds, checkout, refunds, change-and-cancel links and reminder emails are a different product, and that's the one we build at Opencals. So the setup I'd recommend is both, wired together: Supabase for your app, the &lt;a href="https://opencals.com/developers" rel="noopener noreferrer"&gt;Opencals Storefront API&lt;/a&gt; for the bookings. You'd do the same with Stripe for payments rather than writing your own card processing.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Key takeaway&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;The fastest way to a real Supabase booking system is to keep Supabase for users and app data and connect a booking API for the bookings. With Opencals, the browser uses a public sfk_ key for availability, cart and checkout; a Supabase Edge Function holds the private spk_ key for server-side calls; and a small Supabase table links each Opencals order to a Supabase user under RLS. You get double-booking protection, holds, Stripe checkout, refunds, reschedule links and reminders without writing them. You can hand-roll all of it in Postgres instead, and the second half of this article shows how, but expect weeks, not days.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  Supabase keeps your users, Opencals keeps the calendar
&lt;/h2&gt;

&lt;p&gt;The split is simple once you draw it. Everything a customer or a staff member &lt;em&gt;is&lt;/em&gt; lives in Supabase. Everything about &lt;em&gt;time&lt;/em&gt; lives in Opencals.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Job&lt;/th&gt;
&lt;th&gt;Where it lives&lt;/th&gt;
&lt;th&gt;Why&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Sign-in, profiles, your app's own tables&lt;/td&gt;
&lt;td&gt;Supabase&lt;/td&gt;
&lt;td&gt;It's your product data, under your RLS policies&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Services, staff, schedules, locations&lt;/td&gt;
&lt;td&gt;Opencals dashboard&lt;/td&gt;
&lt;td&gt;The merchant edits hours and prices without a deploy&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Availability and double-booking protection&lt;/td&gt;
&lt;td&gt;Opencals API&lt;/td&gt;
&lt;td&gt;Computed per staff, location and booking length, server-side&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Cart holds and checkout&lt;/td&gt;
&lt;td&gt;Opencals API&lt;/td&gt;
&lt;td&gt;Carts expire on their own; payment goes to the merchant's own Stripe account&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Refunds, reschedule and cancel links&lt;/td&gt;
&lt;td&gt;Opencals&lt;/td&gt;
&lt;td&gt;Inside the merchant's notice rules, from the confirmation email&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Confirmation and reminder emails&lt;/td&gt;
&lt;td&gt;Opencals&lt;/td&gt;
&lt;td&gt;Sent for you, nothing to schedule&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Which of your users made which booking&lt;/td&gt;
&lt;td&gt;Supabase&lt;/td&gt;
&lt;td&gt;A small table of order references, one row per booking&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Nothing in that table needs Supabase to give anything up. Your auth stays Supabase Auth, your database stays your database, and Opencals never sees your tables.&lt;/p&gt;

&lt;h2&gt;
  
  
  Two keys, and which side of the app each one goes on
&lt;/h2&gt;

&lt;p&gt;Opencals has two kinds of storefront key, and the SDK's README is explicit about where each belongs. A public key starting &lt;code&gt;sfk_&lt;/code&gt; is meant to be visible in browser code, and you restrict it to your own domains with allowed origins in the dashboard. A private key starting &lt;code&gt;spk_&lt;/code&gt; is secret and belongs on a server only.&lt;/p&gt;

&lt;p&gt;In a Supabase app that maps neatly:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="c"&gt;# Frontend env (Vite / Next.js / Lovable): public, restricted to your domain&lt;/span&gt;
&lt;span class="nv"&gt;VITE_OPENCALS_KEY&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;sfk_...

&lt;span class="c"&gt;# Supabase Edge Function secret: private, never shipped to the browser&lt;/span&gt;
supabase secrets &lt;span class="nb"&gt;set &lt;/span&gt;&lt;span class="nv"&gt;OPENCALS_API_KEY&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;spk_...
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Create both in the Opencals dashboard under your user's API keys. On a free development store they work against seeded sample businesses in test mode, so you can build the whole flow before anyone has a card out.&lt;/p&gt;

&lt;h2&gt;
  
  
  The booking flow runs in the browser
&lt;/h2&gt;

&lt;p&gt;The customer-facing part is four calls with the &lt;a href="https://opencals.com/blog/booking-sdk" rel="noopener noreferrer"&gt;Storefront SDK&lt;/a&gt;, &lt;code&gt;@opencals/storefront-sdk&lt;/code&gt; (MIT, 0.3.19 on npm as of 27 October 2026). These are the calls from the SDK's own README:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;setupOpencals&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;ProductService&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;AppointmentService&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nx"&gt;CartService&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;CheckoutService&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;@opencals/storefront-sdk&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="nf"&gt;setupOpencals&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt; &lt;span class="na"&gt;apiKey&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="k"&gt;import&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;meta&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;VITE_OPENCALS_KEY&lt;/span&gt; &lt;span class="p"&gt;});&lt;/span&gt; &lt;span class="c1"&gt;// sfk_&lt;/span&gt;

&lt;span class="c1"&gt;// 1. What's free on the day the customer picked&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;data&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;slots&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;ProductService&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;getCurrentAvailabilities&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt;
  &lt;span class="na"&gt;path&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;productId&lt;/span&gt; &lt;span class="p"&gt;},&lt;/span&gt;
  &lt;span class="na"&gt;query&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;date&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;2026-11-12&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;staffMemberId&lt;/span&gt; &lt;span class="p"&gt;},&lt;/span&gt;
&lt;span class="p"&gt;});&lt;/span&gt;

&lt;span class="c1"&gt;// 2. Reserve the chosen slot&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;data&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;appointment&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;AppointmentService&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;create&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt;
  &lt;span class="na"&gt;body&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="na"&gt;slot&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;productId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;fromDate&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;2026-11-12&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;fromTime&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;10:30:00&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
            &lt;span class="na"&gt;toDate&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;2026-11-12&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;toTime&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;11:30:00&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt; &lt;span class="p"&gt;},&lt;/span&gt;
    &lt;span class="na"&gt;numberOfAttendees&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
 &lt;span class="p"&gt;},&lt;/span&gt;
&lt;span class="p"&gt;});&lt;/span&gt;

&lt;span class="c1"&gt;// 3. Put it in a cart, which holds it while they pay&lt;/span&gt;
&lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;CartService&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;createOrGet&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
&lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;CartService&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;addItem&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt; &lt;span class="na"&gt;body&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;appointmentId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;appointment&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="p"&gt;});&lt;/span&gt;

&lt;span class="c1"&gt;// 4. Check out with Stripe&lt;/span&gt;
&lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;CheckoutService&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;start&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt;
  &lt;span class="na"&gt;body&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;provider&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;stripe&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;customer&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;email&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;user&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;email&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="p"&gt;},&lt;/span&gt;
&lt;span class="p"&gt;});&lt;/span&gt;
&lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;CheckoutService&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;submit&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Two customers racing for the same 10:30 is now Opencals' problem, not yours. The second request is refused instead of producing a duplicate confirmation, and your UI shows the next free times. The cart expires on its own if they abandon checkout, and there's an &lt;code&gt;extendExpiration&lt;/code&gt; call for when they've started paying and need a few more minutes.&lt;/p&gt;

&lt;p&gt;If the user is signed in with Supabase, pass their email from &lt;code&gt;supabase.auth.getUser()&lt;/code&gt; into checkout so the booking lands under the same address they use in your app.&lt;/p&gt;

&lt;h2&gt;
  
  
  Server-side calls go through an Edge Function
&lt;/h2&gt;

&lt;p&gt;Some calls shouldn't come from the browser: an availability check your server renders into a page, an AI agent asking for the next free slot, or an admin view that lists today's bookings. Those go through a Supabase Edge Function with the private key:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// supabase/functions/availability/index.ts&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;setupOpencals&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;ProductService&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;npm:@opencals/storefront-sdk@0.3.19&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="nf"&gt;setupOpencals&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt; &lt;span class="na"&gt;apiKey&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;Deno&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;OPENCALS_API_KEY&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt; &lt;span class="p"&gt;});&lt;/span&gt; &lt;span class="c1"&gt;// spk_&lt;/span&gt;

&lt;span class="nx"&gt;Deno&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;serve&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;async &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;req&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
 &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;productId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;date&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;req&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;json&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
 &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;data&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;ProductService&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;getCurrentAvailabilities&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt;
    &lt;span class="na"&gt;path&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;productId&lt;/span&gt; &lt;span class="p"&gt;},&lt;/span&gt;
    &lt;span class="na"&gt;query&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;date&lt;/span&gt; &lt;span class="p"&gt;},&lt;/span&gt;
 &lt;span class="p"&gt;});&lt;/span&gt;
 &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;Response&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;json&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;data&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="p"&gt;});&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;With a private key you can also forward the buyer's IP through the SDK's &lt;code&gt;buyerIp&lt;/code&gt; option, so rate limits and abuse protection count each visitor separately instead of treating your Edge Function as one very busy customer. The README covers the header it uses.&lt;/p&gt;

&lt;h2&gt;
  
  
  Link each booking to a Supabase user
&lt;/h2&gt;

&lt;p&gt;The last piece is remembering which of your users booked what, so your app can show "your upcoming sessions" next to everything else it knows about them. That's one table and one policy:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="k"&gt;create&lt;/span&gt; &lt;span class="k"&gt;table&lt;/span&gt; &lt;span class="k"&gt;public&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;booking_ref&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;
  &lt;span class="n"&gt;id&lt;/span&gt;               &lt;span class="n"&gt;uuid&lt;/span&gt; &lt;span class="k"&gt;primary&lt;/span&gt; &lt;span class="k"&gt;key&lt;/span&gt; &lt;span class="k"&gt;default&lt;/span&gt; &lt;span class="n"&gt;gen_random_uuid&lt;/span&gt;&lt;span class="p"&gt;(),&lt;/span&gt;
  &lt;span class="n"&gt;user_id&lt;/span&gt;          &lt;span class="n"&gt;uuid&lt;/span&gt; &lt;span class="k"&gt;not&lt;/span&gt; &lt;span class="k"&gt;null&lt;/span&gt; &lt;span class="k"&gt;references&lt;/span&gt; &lt;span class="n"&gt;auth&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;users&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;on&lt;/span&gt; &lt;span class="k"&gt;delete&lt;/span&gt; &lt;span class="k"&gt;cascade&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;opencals_order&lt;/span&gt;   &lt;span class="nb"&gt;text&lt;/span&gt; &lt;span class="k"&gt;not&lt;/span&gt; &lt;span class="k"&gt;null&lt;/span&gt; &lt;span class="k"&gt;unique&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;starts_at&lt;/span&gt;        &lt;span class="n"&gt;timestamptz&lt;/span&gt; &lt;span class="k"&gt;not&lt;/span&gt; &lt;span class="k"&gt;null&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;created_at&lt;/span&gt;       &lt;span class="n"&gt;timestamptz&lt;/span&gt; &lt;span class="k"&gt;not&lt;/span&gt; &lt;span class="k"&gt;null&lt;/span&gt; &lt;span class="k"&gt;default&lt;/span&gt; &lt;span class="n"&gt;now&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt;
&lt;span class="p"&gt;);&lt;/span&gt;

&lt;span class="k"&gt;alter&lt;/span&gt; &lt;span class="k"&gt;table&lt;/span&gt; &lt;span class="k"&gt;public&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;booking_ref&lt;/span&gt; &lt;span class="n"&gt;enable&lt;/span&gt; &lt;span class="k"&gt;row&lt;/span&gt; &lt;span class="k"&gt;level&lt;/span&gt; &lt;span class="k"&gt;security&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;create&lt;/span&gt; &lt;span class="n"&gt;policy&lt;/span&gt; &lt;span class="nv"&gt;"own bookings"&lt;/span&gt; &lt;span class="k"&gt;on&lt;/span&gt; &lt;span class="k"&gt;public&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;booking_ref&lt;/span&gt;
  &lt;span class="k"&gt;for&lt;/span&gt; &lt;span class="k"&gt;all&lt;/span&gt; &lt;span class="k"&gt;using&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;user_id&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;auth&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;uid&lt;/span&gt;&lt;span class="p"&gt;())&lt;/span&gt; &lt;span class="k"&gt;with&lt;/span&gt; &lt;span class="k"&gt;check&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;user_id&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;auth&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;uid&lt;/span&gt;&lt;span class="p"&gt;());&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Write the row when checkout succeeds. Treat it as a pointer, not the record: the booking itself, its status and its payment stay in Opencals, and your app reads the current state from the API when it needs it. That keeps one source of truth and means a customer who reschedules from their email doesn't leave your table claiming the old time.&lt;/p&gt;

&lt;p&gt;If you're building in Lovable, you don't have to write any of this by hand. &lt;a href="https://opencals.com/blog/lovable-booking-system" rel="noopener noreferrer"&gt;The Lovable setup guide&lt;/a&gt; connects Opencals as a connector, and Lovable generates the same flow on top of its Supabase backend.&lt;/p&gt;

&lt;h2&gt;
  
  
  If you'd rather hand-roll the bookings in Postgres
&lt;/h2&gt;

&lt;p&gt;Some people want every line in their own database, and that's a fair requirement. Supabase gives you the parts. Here's the honest version of what it takes.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;The constraint.&lt;/strong&gt; Store each booking as a &lt;code&gt;tstzrange&lt;/code&gt; and let Postgres refuse overlaps. Supabase lists &lt;code&gt;btree_gist&lt;/code&gt; among its available extensions:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="k"&gt;create&lt;/span&gt; &lt;span class="n"&gt;extension&lt;/span&gt; &lt;span class="n"&gt;if&lt;/span&gt; &lt;span class="k"&gt;not&lt;/span&gt; &lt;span class="k"&gt;exists&lt;/span&gt; &lt;span class="n"&gt;btree_gist&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;alter&lt;/span&gt; &lt;span class="k"&gt;table&lt;/span&gt; &lt;span class="k"&gt;public&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;booking&lt;/span&gt;
  &lt;span class="k"&gt;add&lt;/span&gt; &lt;span class="k"&gt;constraint&lt;/span&gt; &lt;span class="n"&gt;no_overlap&lt;/span&gt;
  &lt;span class="n"&gt;exclude&lt;/span&gt; &lt;span class="k"&gt;using&lt;/span&gt; &lt;span class="n"&gt;gist&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;resource_id&lt;/span&gt; &lt;span class="k"&gt;with&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;during&lt;/span&gt; &lt;span class="k"&gt;with&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="k"&gt;where&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;status&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&amp;gt;&lt;/span&gt; &lt;span class="s1"&gt;'cancelled'&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The full concurrency argument, including the &lt;code&gt;23P01&lt;/code&gt; error and the payment race, is in &lt;a href="https://opencals.com/blog/prevent-double-booking-system-design" rel="noopener noreferrer"&gt;the double-booking system design article&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Privacy.&lt;/strong&gt; The Supabase publishable key ships in every browser. Supabase's docs tell you to enable RLS on every table in an exposed schema and warn that views bypass RLS by default unless you set &lt;code&gt;security_invoker = true&lt;/code&gt;. A booking table full of emails should have no anonymous policies at all, with reads and writes going through Edge Functions.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Holds.&lt;/strong&gt; An unpaid hold has to expire, and a constraint can't use &lt;code&gt;now()&lt;/code&gt;, so you sweep with &lt;code&gt;pg_cron&lt;/code&gt;. Supabase Cron runs jobs from every second to once a year and recommends no more than eight jobs at once, each under ten minutes.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Payment.&lt;/strong&gt; Confirm only from a Stripe webhook in an Edge Function. Supabase's example reads the raw body, verifies with &lt;code&gt;constructEventAsync&lt;/code&gt;, and deploys with &lt;code&gt;verify_jwt = false&lt;/code&gt;. Duplicate events and payments that land after the hold expired are yours to handle.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Emails.&lt;/strong&gt; Supabase's built-in SMTP only delivers to your project team, at two messages an hour, and isn't meant for production, so confirmations and reminders need a provider such as Resend or Postmark and another cron job.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;The free plan pauses.&lt;/strong&gt; Supabase's pricing page says free projects pause after one week of inactivity. A booking site with a quiet week then can't load availability. Budget for Pro, from $25 a month (checked 27 October 2026), before real customers book. That applies to both setups, by the way: if your Supabase app is paused, the booking page inside it is too.&lt;/p&gt;

&lt;p&gt;Add it up and the first four take a few days if you know Postgres. Multi-staff availability with shifts, breaks and daylight saving, deposits and partial refunds, guest change-and-cancel links with repricing, and reminders that never silently fail are the weeks. That's the part I'd hand to an API, and it's the reason the first half of this article exists.&lt;/p&gt;

&lt;h2&gt;
  
  
  What isn't there yet
&lt;/h2&gt;

&lt;p&gt;Three limits that change how you'd design the Opencals setup:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Webhooks aren't live yet.&lt;/strong&gt; Opencals can't push "booking changed" into a Supabase table today. Keep &lt;code&gt;booking_ref&lt;/code&gt; as a pointer and read status from the API, or poll from a scheduled Edge Function if you need a local copy. When webhooks ship, this becomes a one-function job.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The engine is hosted, not open source.&lt;/strong&gt; The SDK and the Next.js templates are MIT. The booking engine runs on our servers.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The free development store runs in test mode.&lt;/strong&gt; Every endpoint works and the sample data is real enough to test races with two browser tabs, but it can't take real money until you switch to a live store.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Pricing, from &lt;a href="https://opencals.com/pricing" rel="noopener noreferrer"&gt;opencals.com/pricing&lt;/a&gt; on 27 October 2026: $0.99 per booking with no monthly fee on Elastic, or $14.98 a month including 300 bookings and $0.20 each after that, with features as add-ons.&lt;/p&gt;

&lt;p&gt;If you're starting today, create a development store, put the &lt;code&gt;sfk_&lt;/code&gt; key in your frontend and the &lt;code&gt;spk_&lt;/code&gt; key in a Supabase secret, and get one real booking through test checkout before you write anything else. You'll know within an hour whether the booking side is solved, and everything left on your list will be the parts of the app that are actually yours.&lt;/p&gt;

&lt;h2&gt;
  
  
  Related reading
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;a href="https://opencals.com/blog/lovable-booking-system" rel="noopener noreferrer"&gt;&lt;strong&gt;Lovable + Opencals&lt;/strong&gt;&lt;/a&gt;: The connector setup for Lovable apps, which run on Supabase.&lt;/li&gt;
&lt;li&gt;
&lt;a href="https://opencals.com/blog/booking-sdk" rel="noopener noreferrer"&gt;&lt;strong&gt;The Storefront SDK&lt;/strong&gt;&lt;/a&gt;: Typed TypeScript client for availability, carts, checkout and accounts.&lt;/li&gt;
&lt;li&gt;
&lt;a href="https://opencals.com/blog/prevent-double-booking-system-design" rel="noopener noreferrer"&gt;&lt;strong&gt;Prevent double booking&lt;/strong&gt;&lt;/a&gt;: The database design if you hand-roll bookings in Postgres.&lt;/li&gt;
&lt;li&gt;
&lt;a href="https://opencals.com/blog/build-booking-website-with-ai" rel="noopener noreferrer"&gt;&lt;strong&gt;Build a booking site with AI&lt;/strong&gt;&lt;/a&gt;: Lovable, v0, Base44 and coding agents, all on one booking API.&lt;/li&gt;
&lt;li&gt;
&lt;a href="https://opencals.com/developers" rel="noopener noreferrer"&gt;&lt;strong&gt;Opencals for developers&lt;/strong&gt;&lt;/a&gt;: API reference, SDK, agent skills and the free development store.&lt;/li&gt;
&lt;li&gt;
&lt;a href="https://opencals.com/blog/booking-system-for-developers" rel="noopener noreferrer"&gt;&lt;strong&gt;Booking systems for developers&lt;/strong&gt;&lt;/a&gt;: What a booking system asks of you after launch.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Frequently asked questions
&lt;/h2&gt;

&lt;h3&gt;
  
  
  Can I build a booking system with Supabase?
&lt;/h3&gt;

&lt;p&gt;Yes. The quickest route is to keep Supabase for users and app data and connect a booking API such as Opencals for availability, carts, checkout, refunds and reminders. You can also hand-roll it in Postgres with a tstzrange exclusion constraint, RLS, pg_cron for expiring holds and a Stripe webhook in an Edge Function, but the availability, refund and reminder logic is yours to write and maintain.&lt;/p&gt;

&lt;h3&gt;
  
  
  How do I add Opencals to a Supabase app?
&lt;/h3&gt;

&lt;p&gt;Create two keys in the Opencals dashboard. Put the public sfk_ key, restricted to your domain, in your frontend and use the Storefront SDK for availability, appointments, cart and checkout. Store the private spk_ key as a Supabase Edge Function secret for server-side calls. Save each Opencals order id in a Supabase table linked to auth.uid() under RLS.&lt;/p&gt;

&lt;h3&gt;
  
  
  Does Opencals replace Supabase Auth?
&lt;/h3&gt;

&lt;p&gt;No. Your users keep signing in with Supabase Auth. Pass the signed-in user's email into Opencals checkout so the booking is under the same address, and link the order to the user in your own Supabase table.&lt;/p&gt;

&lt;h3&gt;
  
  
  How do I prevent double bookings in Supabase?
&lt;/h3&gt;

&lt;p&gt;With a booking API, the API refuses the second booking for you. If you hand-roll it, enable btree_gist and add EXCLUDE USING gist (resource_id WITH =, during WITH &amp;amp;&amp;amp;) WHERE (status &amp;lt;&amp;gt; 'cancelled') to the bookings table, so the second overlapping insert fails with SQLSTATE 23P01.&lt;/p&gt;

&lt;h3&gt;
  
  
  Can Opencals send booking changes to Supabase automatically?
&lt;/h3&gt;

&lt;p&gt;Not yet. Opencals webhooks aren't live, so keep a pointer to each order in Supabase and read the current status from the API, or poll from a scheduled Edge Function if you need a local copy.&lt;/p&gt;

&lt;h3&gt;
  
  
  Will a Supabase free project work for a live booking site?
&lt;/h3&gt;

&lt;p&gt;It's risky. Supabase pauses free projects after one week of inactivity, and a small business can easily have a quiet week. Move to the Pro plan, from $25 a month as of October 2026, before real customers book.&lt;/p&gt;

</description>
      <category>supabase</category>
      <category>nextjs</category>
      <category>webdev</category>
      <category>tutorial</category>
    </item>
    <item>
      <title>I rebuilt my open-source salon booking template: one page instead of a wizard</title>
      <dc:creator>Stan</dc:creator>
      <pubDate>Thu, 29 Oct 2026 08:39:49 +0000</pubDate>
      <link>https://dev.to/stangineer/i-rebuilt-my-open-source-salon-booking-template-one-page-instead-of-a-wizard-301l</link>
      <guid>https://dev.to/stangineer/i-rebuilt-my-open-source-salon-booking-template-one-page-instead-of-a-wizard-301l</guid>
      <description>&lt;p&gt;In June I posted &lt;a href="https://dev.to/stangineer/built-a-full-salon-booking-website-in-a-weekend-heres-the-stack-2fkd"&gt;how I built a salon booking site in a weekend&lt;/a&gt; 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.&lt;/p&gt;

&lt;p&gt;If you just want to click around: &lt;a href="https://template-haar.vercel.app/" rel="noopener noreferrer"&gt;live demo&lt;/a&gt; · &lt;a href="https://github.com/letsopencals/template-haar" rel="noopener noreferrer"&gt;GitHub&lt;/a&gt; (MIT).&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fg6mr81n2r50bcnpm45si.jpg" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fg6mr81n2r50bcnpm45si.jpg" alt="Haar's home page: the &amp;quot;Issue Nº 17&amp;quot; masthead, &amp;quot;The Art of Hair&amp;quot; and the arched hero photo" width="800" height="500"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  The wizard was the wrong shape
&lt;/h2&gt;

&lt;p&gt;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.&lt;/p&gt;

&lt;p&gt;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.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F27oy6mzspcq1uo1uqm6s.jpg" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F27oy6mzspcq1uo1uqm6s.jpg" alt="The booking page: day ribbon, afternoon time slots with the free stylists' avatars on each, a &amp;quot;Who would you like at 15:30?&amp;quot; picker, and the appointment card on the right" width="800" height="500"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;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.&lt;/p&gt;

&lt;h2&gt;
  
  
  All of it is one availability call
&lt;/h2&gt;

&lt;p&gt;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:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// app/api/availability/route.ts&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;@/lib/opencals&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;ProductService&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;@opencals/storefront-sdk&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;NextRequest&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;NextResponse&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;next/server&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;GET&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;request&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;NextRequest&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;p&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;request&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;nextUrl&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;searchParams&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;productId&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;p&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;productId&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;date&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;p&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;date&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nx"&gt;productId&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nx"&gt;date&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;NextResponse&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;json&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt; &lt;span class="na"&gt;error&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;productId and date are required&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt; &lt;span class="p"&gt;},&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;status&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;400&lt;/span&gt; &lt;span class="p"&gt;});&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;

  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;data&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;ProductService&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;getCurrentAvailabilities&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt;
    &lt;span class="na"&gt;path&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;productId&lt;/span&gt; &lt;span class="p"&gt;},&lt;/span&gt;
    &lt;span class="na"&gt;query&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="nx"&gt;date&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="na"&gt;timezone&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;p&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;timezone&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;??&lt;/span&gt; &lt;span class="kc"&gt;undefined&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="na"&gt;staffMemberId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;p&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;staffMemberId&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;??&lt;/span&gt; &lt;span class="kc"&gt;undefined&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="c1"&gt;// leave out for "Any stylist"&lt;/span&gt;
      &lt;span class="na"&gt;locationId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;p&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;locationId&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;??&lt;/span&gt; &lt;span class="kc"&gt;undefined&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="c1"&gt;// when rescheduling, the appointment's own slot must not block itself&lt;/span&gt;
      &lt;span class="na"&gt;excludeAppointmentId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;p&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;excludeAppointmentId&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;??&lt;/span&gt; &lt;span class="kc"&gt;undefined&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="p"&gt;},&lt;/span&gt;
    &lt;span class="na"&gt;throwOnError&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;});&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;NextResponse&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;json&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;data&lt;/span&gt; &lt;span class="o"&gt;??&lt;/span&gt; &lt;span class="p"&gt;[]);&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;excludeAppointmentId&lt;/code&gt; 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.&lt;/p&gt;

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

&lt;h2&gt;
  
  
  One change you should copy: a private key and the buyer's IP
&lt;/h2&gt;

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

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// lib/opencals.ts&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;setupOpencals&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;@opencals/storefront-sdk&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;nextBuyerIp&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;@opencals/storefront-sdk/next&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="nf"&gt;setupOpencals&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt;
  &lt;span class="na"&gt;baseUrl&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;OPENCALS_API_URL&lt;/span&gt; &lt;span class="o"&gt;??&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;https://api.opencals.com&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="na"&gt;apiKey&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;OPENCALS_API_KEY&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="c1"&gt;// spk_…&lt;/span&gt;
  &lt;span class="na"&gt;buyerIp&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;nextBuyerIp&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;});&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;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 &lt;code&gt;nextBuyerIp&lt;/code&gt;, 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.&lt;/p&gt;

&lt;h2&gt;
  
  
  Reserving holds the chair
&lt;/h2&gt;

&lt;p&gt;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 &lt;a href="https://dev.to/stangineer/prevent-double-booking-system-design-that-holds-2026-o2i"&gt;why holds are the hard part of preventing double bookings&lt;/a&gt;, if you want the database side of it.&lt;/p&gt;

&lt;p&gt;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.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F99ys8r189mdgesrlgpac.jpg" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F99ys8r189mdgesrlgpac.jpg" alt="Checkout: &amp;quot;Reserve your chair&amp;quot;, three numbered sections with Pay at the salon selected, two appointment cards with a finishing touch, the total and a &amp;quot;Held for you 04:25 / Extend&amp;quot; timer" width="" height=""&gt;&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Accounts without passwords
&lt;/h2&gt;

&lt;p&gt;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.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fkjz2ivg37o6620r1qozy.jpg" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fkjz2ivg37o6620r1qozy.jpg" alt="The customer account: &amp;quot;Your salon diary&amp;quot; with the next visit and a countdown" width="800" height="786"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Mobile first, for real this time
&lt;/h2&gt;

&lt;p&gt;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.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fb7gmv4iwazcs2kkyb2tz.jpg" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fb7gmv4iwazcs2kkyb2tz.jpg" alt="Mobile: the home page, the day and time picker with the sticky card bar, and the &amp;quot;Held for you&amp;quot; sheet with the countdown" width="800" height="532"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Deploy it
&lt;/h2&gt;

&lt;ol&gt;
&lt;li&gt;Create a free dev store at &lt;a href="https://app.opencals.com" rel="noopener noreferrer"&gt;app.opencals.com&lt;/a&gt; and choose the &lt;strong&gt;HAAR Salon&lt;/strong&gt; dataset when asked. It seeds the same services, stylists and locations as the demo.&lt;/li&gt;
&lt;li&gt;Create a private storefront key (&lt;code&gt;spk_&lt;/code&gt;) under Users → your user → API Keys.&lt;/li&gt;
&lt;li&gt;Click &lt;strong&gt;Deploy with Vercel&lt;/strong&gt; in the &lt;a href="https://github.com/letsopencals/template-haar" rel="noopener noreferrer"&gt;README&lt;/a&gt; and set two variables: &lt;code&gt;OPENCALS_API_KEY&lt;/code&gt; (your &lt;code&gt;spk_&lt;/code&gt; key) and &lt;code&gt;AUTH_SECRET&lt;/code&gt; (any random string).&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Locally it's the usual:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;git clone https://github.com/letsopencals/template-haar.git
&lt;span class="nb"&gt;cd &lt;/span&gt;template-haar
npm &lt;span class="nb"&gt;install
cp&lt;/span&gt; .env.example .env   &lt;span class="c"&gt;# OPENCALS_API_KEY=spk_… and AUTH_SECRET=…&lt;/span&gt;
npm run dev
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



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

&lt;h2&gt;
  
  
  What to know before you build on it
&lt;/h2&gt;

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

&lt;h2&gt;
  
  
  It's a series now
&lt;/h2&gt;

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

&lt;ul&gt;
&lt;li&gt;
&lt;a href="https://github.com/letsopencals/template-frisor" rel="noopener noreferrer"&gt;Frisor&lt;/a&gt;: barbershop, dark editorial design&lt;/li&gt;
&lt;li&gt;
&lt;a href="https://github.com/letsopencals/template-clarity" rel="noopener noreferrer"&gt;Clear Care&lt;/a&gt;: medical clinic, department-first booking&lt;/li&gt;
&lt;li&gt;
&lt;a href="https://github.com/letsopencals/template-alba" rel="noopener noreferrer"&gt;Alba&lt;/a&gt;: dental group, a tooth-chart "Smile Check" and a chair-time planner&lt;/li&gt;
&lt;li&gt;
&lt;a href="https://github.com/letsopencals/template-volt" rel="noopener noreferrer"&gt;VOLT&lt;/a&gt;: padel and squash clubs, a live court grid&lt;/li&gt;
&lt;li&gt;
&lt;a href="https://github.com/letsopencals/template-noir" rel="noopener noreferrer"&gt;NOIR Drive&lt;/a&gt;: car rental by the day, with chauffeur packages&lt;/li&gt;
&lt;li&gt;
&lt;a href="https://github.com/letsopencals/template-fluently" rel="noopener noreferrer"&gt;Fluently&lt;/a&gt;: language school, group classes with live seats&lt;/li&gt;
&lt;li&gt;
&lt;a href="https://github.com/letsopencals/template-bali-villas" rel="noopener noreferrer"&gt;Lumbung Sidemen&lt;/a&gt;: villa rental, nightly stays&lt;/li&gt;
&lt;li&gt;
&lt;a href="https://github.com/letsopencals/template-reformer" rel="noopener noreferrer"&gt;Tensile&lt;/a&gt;: reformer Pilates timetable with beds left&lt;/li&gt;
&lt;li&gt;
&lt;a href="https://github.com/letsopencals/template-gable" rel="noopener noreferrer"&gt;Gable&lt;/a&gt;: coworking, desks, rooms and booths on one day sheet&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;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.&lt;/p&gt;

&lt;p&gt;— Stan, building &lt;a href="https://opencals.com" rel="noopener noreferrer"&gt;Opencals&lt;/a&gt;&lt;/p&gt;

</description>
      <category>nextjs</category>
      <category>webdev</category>
      <category>opensource</category>
      <category>showdev</category>
    </item>
    <item>
      <title>Prevent Double Booking: System Design That Holds (2026)</title>
      <dc:creator>Stan</dc:creator>
      <pubDate>Thu, 29 Oct 2026 07:22:30 +0000</pubDate>
      <link>https://dev.to/stangineer/prevent-double-booking-system-design-that-holds-2026-o2i</link>
      <guid>https://dev.to/stangineer/prevent-double-booking-system-design-that-holds-2026-o2i</guid>
      <description>&lt;p&gt;&lt;em&gt;Originally published on &lt;a href="https://opencals.com/blog/prevent-double-booking-system-design" rel="noopener noreferrer"&gt;opencals.com&lt;/a&gt;. The original stays updated; check it for the latest version.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;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.&lt;/p&gt;

&lt;p&gt;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.&lt;/p&gt;

&lt;p&gt;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.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Key takeaway&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;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.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  The availability check is a read, and reads don't lock anything
&lt;/h2&gt;

&lt;p&gt;Here's the sequence with two requests, A and B, both for Lena at 10:30 on Thursday:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;A: SELECT ... WHERE staff = lena AND overlaps(10:30–11:30)  -&amp;gt; 0 rows
B: SELECT ... WHERE staff = lena AND overlaps(10:30–11:30)  -&amp;gt; 0 rows
A: INSERT booking (lena, 10:30–11:30)                        -&amp;gt; ok
B: INSERT booking (lena, 10:30–11:30)                        -&amp;gt; ok
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;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.&lt;/p&gt;

&lt;p&gt;The first fix most people reach for is a unique index on &lt;code&gt;(staff_id, starts_at)&lt;/code&gt;. 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.&lt;/p&gt;

&lt;p&gt;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.&lt;/p&gt;

&lt;h2&gt;
  
  
  Let Postgres refuse the overlapping insert
&lt;/h2&gt;

&lt;p&gt;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.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="k"&gt;CREATE&lt;/span&gt; &lt;span class="n"&gt;EXTENSION&lt;/span&gt; &lt;span class="n"&gt;IF&lt;/span&gt; &lt;span class="k"&gt;NOT&lt;/span&gt; &lt;span class="k"&gt;EXISTS&lt;/span&gt; &lt;span class="n"&gt;btree_gist&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;CREATE&lt;/span&gt; &lt;span class="k"&gt;TABLE&lt;/span&gt; &lt;span class="n"&gt;booking&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;
  &lt;span class="n"&gt;id&lt;/span&gt;         &lt;span class="n"&gt;uuid&lt;/span&gt; &lt;span class="k"&gt;PRIMARY&lt;/span&gt; &lt;span class="k"&gt;KEY&lt;/span&gt; &lt;span class="k"&gt;DEFAULT&lt;/span&gt; &lt;span class="n"&gt;gen_random_uuid&lt;/span&gt;&lt;span class="p"&gt;(),&lt;/span&gt;
  &lt;span class="n"&gt;staff_id&lt;/span&gt;   &lt;span class="n"&gt;uuid&lt;/span&gt; &lt;span class="k"&gt;NOT&lt;/span&gt; &lt;span class="k"&gt;NULL&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;during&lt;/span&gt;     &lt;span class="n"&gt;tstzrange&lt;/span&gt; &lt;span class="k"&gt;NOT&lt;/span&gt; &lt;span class="k"&gt;NULL&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;status&lt;/span&gt;     &lt;span class="nb"&gt;text&lt;/span&gt; &lt;span class="k"&gt;NOT&lt;/span&gt; &lt;span class="k"&gt;NULL&lt;/span&gt; &lt;span class="k"&gt;DEFAULT&lt;/span&gt; &lt;span class="s1"&gt;'confirmed'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="k"&gt;CONSTRAINT&lt;/span&gt; &lt;span class="n"&gt;no_overlap_per_staff&lt;/span&gt;
    &lt;span class="n"&gt;EXCLUDE&lt;/span&gt; &lt;span class="k"&gt;USING&lt;/span&gt; &lt;span class="n"&gt;gist&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;staff_id&lt;/span&gt; &lt;span class="k"&gt;WITH&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;during&lt;/span&gt; &lt;span class="k"&gt;WITH&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="k"&gt;WHERE&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;status&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&amp;gt;&lt;/span&gt; &lt;span class="s1"&gt;'cancelled'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;btree_gist&lt;/code&gt; is there so a plain &lt;code&gt;uuid&lt;/code&gt; column can sit in a GiST index next to the range. The &lt;code&gt;WHERE&lt;/code&gt; 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.&lt;/p&gt;

&lt;p&gt;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 &lt;code&gt;23P01&lt;/code&gt;, exclusion_violation, which your code catches and turns into the message the customer actually needs: that slot just went, here are the next three.&lt;/p&gt;

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

&lt;p&gt;Two details that bite later. Store the range as half-open, &lt;code&gt;[10:30, 11:30)&lt;/code&gt;, so a booking ending at 11:30 and one starting at 11:30 don't conflict; that's the default for &lt;code&gt;tstzrange&lt;/code&gt;. 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.&lt;/p&gt;

&lt;h2&gt;
  
  
  A booking usually occupies more than one thing
&lt;/h2&gt;

&lt;p&gt;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.&lt;/p&gt;

&lt;p&gt;What's worked for me is splitting "the booking" from "what it occupies":&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="k"&gt;CREATE&lt;/span&gt; &lt;span class="k"&gt;TABLE&lt;/span&gt; &lt;span class="n"&gt;allocation&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;
  &lt;span class="n"&gt;booking_id&lt;/span&gt;   &lt;span class="n"&gt;uuid&lt;/span&gt; &lt;span class="k"&gt;NOT&lt;/span&gt; &lt;span class="k"&gt;NULL&lt;/span&gt; &lt;span class="k"&gt;REFERENCES&lt;/span&gt; &lt;span class="n"&gt;booking&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;),&lt;/span&gt;
  &lt;span class="n"&gt;resource_id&lt;/span&gt;  &lt;span class="n"&gt;uuid&lt;/span&gt; &lt;span class="k"&gt;NOT&lt;/span&gt; &lt;span class="k"&gt;NULL&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;          &lt;span class="c1"&gt;-- a staff member, room, chair or bike&lt;/span&gt;
  &lt;span class="n"&gt;during&lt;/span&gt;       &lt;span class="n"&gt;tstzrange&lt;/span&gt; &lt;span class="k"&gt;NOT&lt;/span&gt; &lt;span class="k"&gt;NULL&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;active&lt;/span&gt;       &lt;span class="nb"&gt;boolean&lt;/span&gt; &lt;span class="k"&gt;NOT&lt;/span&gt; &lt;span class="k"&gt;NULL&lt;/span&gt; &lt;span class="k"&gt;DEFAULT&lt;/span&gt; &lt;span class="k"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;EXCLUDE&lt;/span&gt; &lt;span class="k"&gt;USING&lt;/span&gt; &lt;span class="n"&gt;gist&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;resource_id&lt;/span&gt; &lt;span class="k"&gt;WITH&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;during&lt;/span&gt; &lt;span class="k"&gt;WITH&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;WHERE&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;active&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;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.&lt;/p&gt;

&lt;h2&gt;
  
  
  Seats in a class are a counter, not an overlap
&lt;/h2&gt;

&lt;p&gt;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.&lt;/p&gt;

&lt;p&gt;The cleanest version I know is a conditional update on the class session itself:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="k"&gt;UPDATE&lt;/span&gt; &lt;span class="n"&gt;class_session&lt;/span&gt;
   &lt;span class="k"&gt;SET&lt;/span&gt; &lt;span class="n"&gt;seats_taken&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;seats_taken&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="err"&gt;$&lt;/span&gt;&lt;span class="mi"&gt;2&lt;/span&gt;
 &lt;span class="k"&gt;WHERE&lt;/span&gt; &lt;span class="n"&gt;id&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="err"&gt;$&lt;/span&gt;&lt;span class="mi"&gt;1&lt;/span&gt;
   &lt;span class="k"&gt;AND&lt;/span&gt; &lt;span class="n"&gt;seats_taken&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="err"&gt;$&lt;/span&gt;&lt;span class="mi"&gt;2&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;=&lt;/span&gt; &lt;span class="n"&gt;capacity&lt;/span&gt;
&lt;span class="n"&gt;RETURNING&lt;/span&gt; &lt;span class="n"&gt;seats_taken&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;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 &lt;code&gt;WHERE&lt;/code&gt; clause against the new row. The same shape works in MySQL.&lt;/p&gt;

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

&lt;h2&gt;
  
  
  Without exclusion constraints: lock the person, then look
&lt;/h2&gt;

&lt;p&gt;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:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="k"&gt;START&lt;/span&gt; &lt;span class="n"&gt;TRANSACTION&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;SELECT&lt;/span&gt; &lt;span class="n"&gt;id&lt;/span&gt; &lt;span class="k"&gt;FROM&lt;/span&gt; &lt;span class="n"&gt;staff&lt;/span&gt; &lt;span class="k"&gt;WHERE&lt;/span&gt; &lt;span class="n"&gt;id&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="o"&gt;?&lt;/span&gt; &lt;span class="k"&gt;FOR&lt;/span&gt; &lt;span class="k"&gt;UPDATE&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;      &lt;span class="c1"&gt;-- one at a time per staff member&lt;/span&gt;

&lt;span class="k"&gt;SELECT&lt;/span&gt; &lt;span class="k"&gt;COUNT&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;*&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;FROM&lt;/span&gt; &lt;span class="n"&gt;booking&lt;/span&gt;
 &lt;span class="k"&gt;WHERE&lt;/span&gt; &lt;span class="n"&gt;staff_id&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="o"&gt;?&lt;/span&gt; &lt;span class="k"&gt;AND&lt;/span&gt; &lt;span class="n"&gt;status&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&amp;gt;&lt;/span&gt; &lt;span class="s1"&gt;'cancelled'&lt;/span&gt;
   &lt;span class="k"&gt;AND&lt;/span&gt; &lt;span class="n"&gt;starts_at&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&lt;/span&gt; &lt;span class="o"&gt;?&lt;/span&gt; &lt;span class="k"&gt;AND&lt;/span&gt; &lt;span class="n"&gt;ends_at&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="o"&gt;?&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;              &lt;span class="c1"&gt;-- requested end, requested start&lt;/span&gt;

&lt;span class="c1"&gt;-- insert only if the count was 0&lt;/span&gt;
&lt;span class="k"&gt;INSERT&lt;/span&gt; &lt;span class="k"&gt;INTO&lt;/span&gt; &lt;span class="n"&gt;booking&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;staff_id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;starts_at&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;ends_at&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;VALUES&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;?&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="o"&gt;?&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="o"&gt;?&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="k"&gt;COMMIT&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The &lt;code&gt;FOR UPDATE&lt;/code&gt; 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.&lt;/p&gt;

&lt;p&gt;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 &lt;code&gt;40001&lt;/code&gt;, 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.&lt;/p&gt;

&lt;h2&gt;
  
  
  Holds expire, and constraints can't tell time
&lt;/h2&gt;

&lt;p&gt;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 &lt;code&gt;status = 'held'&lt;/code&gt; and an expiry time, and the exclusion constraint treats it exactly like a confirmed booking. Good.&lt;/p&gt;

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

&lt;p&gt;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:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="k"&gt;UPDATE&lt;/span&gt; &lt;span class="n"&gt;booking&lt;/span&gt; &lt;span class="k"&gt;SET&lt;/span&gt; &lt;span class="n"&gt;status&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s1"&gt;'cancelled'&lt;/span&gt;
 &lt;span class="k"&gt;WHERE&lt;/span&gt; &lt;span class="n"&gt;staff_id&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="err"&gt;$&lt;/span&gt;&lt;span class="mi"&gt;1&lt;/span&gt; &lt;span class="k"&gt;AND&lt;/span&gt; &lt;span class="n"&gt;status&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s1"&gt;'held'&lt;/span&gt;
   &lt;span class="k"&gt;AND&lt;/span&gt; &lt;span class="n"&gt;hold_expires_at&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&lt;/span&gt; &lt;span class="n"&gt;now&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt;
   &lt;span class="k"&gt;AND&lt;/span&gt; &lt;span class="n"&gt;during&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="err"&gt;$&lt;/span&gt;&lt;span class="mi"&gt;2&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;INSERT&lt;/span&gt; &lt;span class="k"&gt;INTO&lt;/span&gt; &lt;span class="n"&gt;booking&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;staff_id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;during&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;status&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;hold_expires_at&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="k"&gt;VALUES&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="err"&gt;$&lt;/span&gt;&lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="err"&gt;$&lt;/span&gt;&lt;span class="mi"&gt;2&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;'held'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;now&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="n"&gt;interval&lt;/span&gt; &lt;span class="s1"&gt;'10 minutes'&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



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

&lt;p&gt;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.&lt;/p&gt;

&lt;h2&gt;
  
  
  The card can succeed after the hold is gone
&lt;/h2&gt;

&lt;p&gt;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.&lt;/p&gt;

&lt;p&gt;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:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="k"&gt;UPDATE&lt;/span&gt; &lt;span class="n"&gt;booking&lt;/span&gt; &lt;span class="k"&gt;SET&lt;/span&gt; &lt;span class="n"&gt;status&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s1"&gt;'confirmed'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;hold_expires_at&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;NULL&lt;/span&gt;
 &lt;span class="k"&gt;WHERE&lt;/span&gt; &lt;span class="n"&gt;id&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="err"&gt;$&lt;/span&gt;&lt;span class="mi"&gt;1&lt;/span&gt; &lt;span class="k"&gt;AND&lt;/span&gt; &lt;span class="n"&gt;status&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s1"&gt;'held'&lt;/span&gt;
&lt;span class="n"&gt;RETURNING&lt;/span&gt; &lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;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.&lt;/p&gt;

&lt;p&gt;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 &lt;code&gt;held&lt;/code&gt; 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.&lt;/p&gt;

&lt;h2&gt;
  
  
  Where a Redis lock fits, and where it doesn't
&lt;/h2&gt;

&lt;p&gt;A short-lived lock in Redis (&lt;code&gt;SET key value NX PX 5000&lt;/code&gt;) on &lt;code&gt;lena:2026-11-12&lt;/code&gt; 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.&lt;/p&gt;

&lt;h2&gt;
  
  
  Shopify's inventory counts units, not hours
&lt;/h2&gt;

&lt;p&gt;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.&lt;/p&gt;

&lt;p&gt;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 &lt;a href="https://opencals.com/blog/embed-booking-shopify-checkout" rel="noopener noreferrer"&gt;the article on embedding booking in Shopify checkout&lt;/a&gt;; 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.&lt;/p&gt;

&lt;h2&gt;
  
  
  What we do, and the parts we don't do yet
&lt;/h2&gt;

&lt;p&gt;Opencals is a hosted booking engine, so if you build on it, none of the SQL above is yours to maintain. On the &lt;a href="https://opencals.com/developers" rel="noopener noreferrer"&gt;Storefront API&lt;/a&gt;, 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. &lt;a href="https://opencals.com/shopify" rel="noopener noreferrer"&gt;The Opencals for Shopify page&lt;/a&gt; shows that message as it appears.&lt;/p&gt;

&lt;p&gt;Now the limits, because they affect how you'd design around us.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Webhooks aren't live. &lt;a href="https://opencals.com/docs/guides/webhooks" rel="noopener noreferrer"&gt;The webhooks guide&lt;/a&gt; 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.&lt;/li&gt;
&lt;li&gt;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 &lt;a href="https://opencals.com/blog/templates/haar" rel="noopener noreferrer"&gt;Haar&lt;/a&gt; and the &lt;code&gt;@opencals/storefront-sdk&lt;/code&gt; package on npm.&lt;/li&gt;
&lt;li&gt;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.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;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, &lt;a href="https://opencals.com/blog/booking-system-for-developers" rel="noopener noreferrer"&gt;the developer's guide to booking systems&lt;/a&gt; covers reschedule links, refunds and reminders.&lt;/p&gt;

&lt;h2&gt;
  
  
  Frequently asked questions
&lt;/h2&gt;

&lt;h3&gt;
  
  
  How do you prevent double booking in a database?
&lt;/h3&gt;

&lt;p&gt;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 &amp;amp;&amp;amp;) 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.&lt;/p&gt;

&lt;h3&gt;
  
  
  Why doesn't a unique index stop double bookings?
&lt;/h3&gt;

&lt;p&gt;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.&lt;/p&gt;

&lt;h3&gt;
  
  
  What is the race condition in a booking system?
&lt;/h3&gt;

&lt;p&gt;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.&lt;/p&gt;

&lt;h3&gt;
  
  
  How do you handle capacity for group classes?
&lt;/h3&gt;

&lt;p&gt;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 &amp;lt;= 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.&lt;/p&gt;

&lt;h3&gt;
  
  
  How long should a booking hold last during checkout?
&lt;/h3&gt;

&lt;p&gt;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.&lt;/p&gt;

&lt;h3&gt;
  
  
  Is a Redis lock enough to prevent double booking?
&lt;/h3&gt;

&lt;p&gt;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.&lt;/p&gt;

</description>
      <category>webdev</category>
      <category>postgres</category>
      <category>api</category>
      <category>programming</category>
    </item>
    <item>
      <title>Built a full salon booking website in a weekend — here's the stack</title>
      <dc:creator>Stan</dc:creator>
      <pubDate>Tue, 23 Jun 2026 06:08:00 +0000</pubDate>
      <link>https://dev.to/stangineer/built-a-full-salon-booking-website-in-a-weekend-heres-the-stack-2fkd</link>
      <guid>https://dev.to/stangineer/built-a-full-salon-booking-website-in-a-weekend-heres-the-stack-2fkd</guid>
      <description>&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Update, October 2026:&lt;/strong&gt; 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: &lt;a href="https://dev.to/stangineer/i-rebuilt-my-open-source-salon-booking-template-one-page-instead-of-a-wizard-301l"&gt;I rebuilt my open-source salon booking template&lt;/a&gt;. The post below describes the June version.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  The thing nobody warns you about with booking sites
&lt;/h2&gt;

&lt;p&gt;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: &lt;strong&gt;is this slot actually available?&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;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.&lt;/p&gt;

&lt;p&gt;I did &lt;strong&gt;not&lt;/strong&gt; 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.&lt;/p&gt;

&lt;h2&gt;
  
  
  The stack
&lt;/h2&gt;

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

&lt;p&gt;The part I want to be honest about: the &lt;strong&gt;Opencals Storefront API&lt;/strong&gt; is the reason this was a weekend and not a month. It's the booking infrastructure behind &lt;a href="https://opencals.com" rel="noopener noreferrer"&gt;Opencals&lt;/a&gt; (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.&lt;/p&gt;

&lt;h2&gt;
  
  
  Step 1 — Clone the template
&lt;/h2&gt;

&lt;p&gt;I didn't start from &lt;code&gt;create-next-app&lt;/code&gt;. There's an open-source salon template — &lt;strong&gt;Haar&lt;/strong&gt; — that already wires the whole flow to the API (&lt;a href="https://opencals.com/blog/templates/haar?utm_source=devto&amp;amp;utm_medium=article&amp;amp;utm_campaign=booking-weekend" rel="noopener noreferrer"&gt;announcement post&lt;/a&gt; · &lt;a href="https://opencals.com/docs/open-source/haar?utm_source=devto&amp;amp;utm_medium=article&amp;amp;utm_campaign=booking-weekend" rel="noopener noreferrer"&gt;docs&lt;/a&gt;):&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;git clone https://github.com/letsopencals/template-haar.git
&lt;span class="nb"&gt;cd &lt;/span&gt;template-haar
npm &lt;span class="nb"&gt;install&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;It's &lt;a href="https://github.com/letsopencals/template-haar" rel="noopener noreferrer"&gt;&lt;code&gt;template-haar&lt;/code&gt;&lt;/a&gt; — 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 &lt;a href="https://template-haar.vercel.app/" rel="noopener noreferrer"&gt;live demo&lt;/a&gt; if you want to click through it first. My weekend was mostly rebranding and tweaking, not plumbing.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F6p32g2sunxu7twk3ahv7.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F6p32g2sunxu7twk3ahv7.png" alt="The template's storefront out of the box — service menu with prices and durations, before any rebranding." width="800" height="494"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Step 2 — Create a store, seed it with Haar data, and deploy
&lt;/h2&gt;

&lt;p&gt;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:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Create a free Dev Store&lt;/strong&gt; in the &lt;a href="https://app.opencals.com" rel="noopener noreferrer"&gt;Opencals dashboard&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Choose the "HAAR Salon" seed dataset&lt;/strong&gt; when prompted. It's built specifically for this template — it pre-loads the exact services, staff, and locations from the &lt;a href="https://template-haar.vercel.app/" rel="noopener noreferrer"&gt;live demo&lt;/a&gt;, so your store isn't empty and the cloned site renders real content from the very first load.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Create a Storefront API Key&lt;/strong&gt; under &lt;strong&gt;Settings → API Keys&lt;/strong&gt; (it starts with &lt;code&gt;sfk_&lt;/code&gt;).&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Then deploy: hit &lt;strong&gt;Deploy with Vercel&lt;/strong&gt; in the README, paste your &lt;code&gt;sfk_&lt;/code&gt; 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.&lt;/p&gt;

&lt;p&gt;Running it locally instead? Drop the key into &lt;code&gt;.env.local&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nv"&gt;OPENCALS_API_KEY&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;sfk_your_key_here
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Keep the key server-side — it identifies your store and not recommended to ship to the browser. The &lt;a href="https://opencals.com/docs/quickstart?utm_source=devto&amp;amp;utm_medium=article&amp;amp;utm_campaign=booking-weekend" rel="noopener noreferrer"&gt;quickstart&lt;/a&gt; covers it in more detail.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Ffxh2nx0cyxb5uih0t1ly.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Ffxh2nx0cyxb5uih0t1ly.png" alt="The whole no-code path in one place — create a store, choose the HAAR Salon seed data, grab your  raw `sfk_` endraw  key in Settings, and deploy with that key." width="800" height="538"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Step 3 — Listing services and fetching availability
&lt;/h2&gt;

&lt;p&gt;The whole booking flow is seven typed calls (list services → pick staff → fetch slots → create appointment → cart → add-ons → checkout), and with the &lt;a href="https://www.npmjs.com/package/@opencals/storefront-sdk" rel="noopener noreferrer"&gt;&lt;code&gt;@opencals/storefront-sdk&lt;/code&gt;&lt;/a&gt; each one is basically a one-liner. You initialize the SDK once and the key stays server-side:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;npm &lt;span class="nb"&gt;install&lt;/span&gt; @opencals/storefront-sdk
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// lib/opencals.ts — run once, server-side only&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;setupOpencals&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;@opencals/storefront-sdk&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="nf"&gt;setupOpencals&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt;
  &lt;span class="na"&gt;apiKey&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;OPENCALS_API_KEY&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="c1"&gt;// sfk_… from Settings → API Keys&lt;/span&gt;
&lt;span class="p"&gt;});&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Then the two calls that drive the whole front page — the service menu and real-time slots:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;@/lib/opencals&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;ProductService&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;@opencals/storefront-sdk&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="c1"&gt;// 1. List the bookable services (your menu)&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;data&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;ProductService&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;list&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt; &lt;span class="na"&gt;query&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;take&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;50&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="p"&gt;});&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;services&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;data&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;data&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="c1"&gt;// Product[] — title, price, duration, staffMembers…&lt;/span&gt;

&lt;span class="c1"&gt;// 2. Real-time availability for one service on a given day&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;data&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;slots&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;ProductService&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;getCurrentAvailabilities&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt;
  &lt;span class="na"&gt;path&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;productId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;services&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;].&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt; &lt;span class="p"&gt;},&lt;/span&gt;
  &lt;span class="na"&gt;query&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="na"&gt;date&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;2026-07-01&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="na"&gt;timezone&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;America/New_York&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="c1"&gt;// slots come back converted for display&lt;/span&gt;
  &lt;span class="p"&gt;},&lt;/span&gt;
&lt;span class="p"&gt;});&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;That &lt;code&gt;getCurrentAvailabilities&lt;/code&gt; 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 &lt;code&gt;staffMemberId&lt;/code&gt; and it filters to one person. I render the slots and move on with my life.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F85kpzxdrgn9w7ipvmhxu.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F85kpzxdrgn9w7ipvmhxu.png" alt="Real-time slots for the selected day and stylist — straight from  raw `getCurrentAvailabilities` endraw ." width="800" height="534"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;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 &lt;a href="https://opencals.com/docs/guides/build-a-booking-page?utm_source=devto&amp;amp;utm_medium=article&amp;amp;utm_campaign=booking-weekend" rel="noopener noreferrer"&gt;Build a booking page guide&lt;/a&gt;, so I won't paste all seven here.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fh5b0buzex4ny77eiwmg0.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fh5b0buzex4ny77eiwmg0.png" alt="Add-ons (e.g. &amp;quot;+ deep conditioning treatment&amp;quot;) attached to a service before checkout" width="799" height="533"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Step 4 — Customer accounts (the part I almost skipped)
&lt;/h2&gt;

&lt;p&gt;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.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fczb7jlort1keuf2udh12.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fczb7jlort1keuf2udh12.png" alt="A logged-in customer rescheduling their own appointment — no phone call, no email" width="800" height="538"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Step 5 — Make it yours
&lt;/h2&gt;

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

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight css"&gt;&lt;code&gt;&lt;span class="k"&gt;@theme&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="py"&gt;--color-accent&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;#E8530E&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;   &lt;span class="c"&gt;/* your brand color */&lt;/span&gt;
  &lt;span class="py"&gt;--font-display&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;'Playfair Display'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;Georgia&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nb"&gt;serif&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="py"&gt;--font-body&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;'Inter'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;system-ui&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nb"&gt;sans-serif&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;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.&lt;/p&gt;

&lt;h2&gt;
  
  
  What you actually get
&lt;/h2&gt;

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

&lt;h2&gt;
  
  
  Try it without committing
&lt;/h2&gt;

&lt;p&gt;You don't need an account to look around. The &lt;a href="https://opencals.com/docs/api-reference/introduction?utm_source=devto&amp;amp;utm_medium=article&amp;amp;utm_campaign=booking-weekend" rel="noopener noreferrer"&gt;interactive API reference&lt;/a&gt; lets you browse every endpoint in the browser, no key required. If you want to build:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;🧬 &lt;strong&gt;Clone the template:&lt;/strong&gt; &lt;a href="https://github.com/letsopencals/template-haar" rel="noopener noreferrer"&gt;github.com/letsopencals/template-haar&lt;/a&gt; · &lt;a href="https://template-haar.vercel.app/" rel="noopener noreferrer"&gt;live demo&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;📖 &lt;strong&gt;Template write-up + docs:&lt;/strong&gt; &lt;a href="https://opencals.com/blog/templates/haar?utm_source=devto&amp;amp;utm_medium=article&amp;amp;utm_campaign=booking-weekend" rel="noopener noreferrer"&gt;the Haar announcement&lt;/a&gt; · &lt;a href="https://opencals.com/docs/open-source/haar?utm_source=devto&amp;amp;utm_medium=article&amp;amp;utm_campaign=booking-weekend" rel="noopener noreferrer"&gt;Haar docs&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;🚀 &lt;strong&gt;Quickstart (5 min):&lt;/strong&gt; &lt;a href="https://opencals.com/docs/quickstart?utm_source=devto&amp;amp;utm_medium=article&amp;amp;utm_campaign=booking-weekend" rel="noopener noreferrer"&gt;opencals.com/docs/quickstart&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;📦 &lt;strong&gt;SDK:&lt;/strong&gt; &lt;a href="https://www.npmjs.com/package/@opencals/storefront-sdk" rel="noopener noreferrer"&gt;&lt;code&gt;@opencals/storefront-sdk&lt;/code&gt;&lt;/a&gt;
&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;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.&lt;/p&gt;

&lt;p&gt;— Stan, building &lt;a href="https://opencals.com" rel="noopener noreferrer"&gt;Opencals&lt;/a&gt;&lt;/p&gt;

</description>
      <category>webdev</category>
      <category>showdev</category>
      <category>tutorial</category>
      <category>nextjs</category>
    </item>
  </channel>
</rss>
