What's the difference between headless booking and embedding a booking widget?

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.

Do I need headless booking, or will a standard booking app be enough?

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.

What technology stack do I need to build on a headless booking API?

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.

Is there an open-source headless booking example I can start from?

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.

Does Opencals support both headless and native Shopify integration?

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.

What Is a Headless Booking System? (And When You Need One)

Q: What is a headless booking system?

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.

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.

A headless booking system 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.

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.

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.

Headless vs traditional booking software

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

When does a headless approach make sense?

Not every business needs headless. Here's how to tell if it's the right fit:

You need a custom UI. 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.

You're building a multi-surface product. 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.

You're an agency or freelancer building for clients. Every client needs a different booking UI. With a headless backend, you write one integration and deploy customised frontends across multiple clients. The backend handles the hard parts; you focus on the client's design.

You're a developer who wants control. 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.

You need to embed booking inside another product. 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.

When headless isn't the right choice

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.

What a headless booking API actually exposes

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

Service catalog

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

Staff and locations

List staff members and locations. Customers pick who they want to book with and where, filtering availability accordingly.

Real-time availability

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.

Cart

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.

Checkout and payment

Initiate checkout, collect payment (deposits or full amount) via Stripe, and confirm the booking. The API handles idempotency, payment failures, and partial payment flows.

Customer self-service

Authenticated endpoints for customers to view, reschedule, and cancel their own bookings without calling the salon.

This is the full picture. Some booking APIs only expose availability and booking creation — which means you have to build or bolt on your own cart, payment, and post-booking management. A complete headless booking API handles the entire flow.

Building on the Opencals Storefront API

Opencals is built headless-first. The same API that powers the Opencals dashboard and the Shopify app is publicly available as the Storefront API.

Authentication uses a Storefront API key (sfk_…) scoped to a single store. You get a key from the Opencals dashboard.

bash

# Get your store's available services
curl https://api.opencals.com/storefront/products \
  -H "Authorization: Bearer sfk_your_api_key"

The typed TypeScript SDK handles auth, request construction, and response parsing:

typescript

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

const opencals = setupOpencals({ apiKey: "sfk_your_api_key" });
const products = await ProductService.listProducts({ opencals });
// products.data is fully typed — no casting needed

The fastest way to see the full stack in action is the Haar open-source template — a complete Next.js 15 salon booking website built on the Storefront API, MIT licensed, one-click Vercel deploy.

Deploy with Vercel

Headless booking and Shopify

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 /book route (or an entirely separate domain) that calls the Opencals API, with the same availability engine and the same Shopify customer account.

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.

Storefront API reference

Every endpoint, with an interactive playground and TypeScript examples.

Build a booking page tutorial

End-to-end walkthrough: services → availability → cart → checkout in Next.js.

Open-source booking templates

Production-ready Next.js starters built on the Storefront API. MIT licensed.

Booking API guide for developers

What to look for in a booking API and how the Opencals API is structured.

What is a headless booking system (and when does your business need one)?

Headless vs traditional booking software

When does a headless approach make sense?

What a headless booking API actually exposes

Building on the Opencals Storefront API

Headless booking and Shopify

Frequently Asked Questions

Ready to transform your service business?