What is a booking API?

A booking API is a REST (or GraphQL) interface that exposes scheduling and availability logic as a service. Instead of embedding a pre-built booking widget, you call the API from your own frontend to get available slots, create bookings, handle payments, and let customers manage their appointments. The API handles the hard parts — real-time availability, conflict detection, payment flows — while you control the UI.

How is a booking API different from a calendar API like Google Calendar?

Google Calendar is an event storage and sync layer. A booking API is purpose-built for service businesses — it knows about services, staff, working hours, customer-facing availability, cart state, deposits, and payments. You could build a booking system on top of Google Calendar, but you'd be building most of the booking logic yourself. A dedicated booking API gives you the domain logic out of the box.

What authentication do booking APIs use?

Most booking APIs use API keys (bearer tokens) for server-to-server and client-to-server calls. The Opencals Storefront API uses a store-scoped API key (sfk_…) for most endpoints, and customer JWT tokens for authenticated customer actions (view, reschedule, cancel their own bookings). Never expose your API key in client-side JavaScript — proxy calls through your backend or use a Next.js API route.

How does real-time availability work in a booking API?

The API computes available slots server-side by combining staff working hours, existing bookings, service duration, buffer time, and location hours. Your client sends a query (which service, which staff, which date range) and receives back a list of clean available slots. You don't have to fetch and process raw calendar data — the computation is done on the backend and the result is display-ready.

Does the Opencals API support multi-staff and multi-location?

Yes. You can query availability for a specific staff member and location, or leave both optional to show all available options. The API handles the scheduling constraints per staff and per location correctly — if a staff member has a break or an existing booking, those slots won't appear as available.

Can I use the Opencals API without using the Shopify app?

Yes. The Storefront API is independent of the Shopify integration. You can use it to build a fully custom booking website, a mobile app, or any other frontend without touching Shopify. The Shopify app and the Storefront API share the same backend, so you can also run both simultaneously if you want a Shopify storefront and a separate custom booking site from the same account.

Booking API Guide for Developers: How to Integrate Appointment Scheduling

Adding booking to an app sounds simple until you start building. Real-time availability across multiple staff and locations, cart state, payment handling, post-booking management — each piece is more complex than it looks from the outside. A booking API lets you hand off that complexity to a specialist backend and focus on the frontend.

This guide covers what a booking API actually does, what to look for when choosing one, and how the Opencals Storefront API is structured — with working code examples.

What a booking API needs to do

Not all booking APIs are equal. A real-time scheduling API needs to handle several distinct domains:

Services

What can be booked — products, variants, pricing

Availability

Real-time slot calculation across staff + locations

Cart + Checkout

Session state, payments, confirmation

Self-service

Customer reschedule, cancel, history

Some APIs cover only availability lookup and booking creation. You have to wire up the cart, payment, and post-booking management yourself. A complete booking API handles the full flow — which is what determines how much your team actually needs to build.

What to look for in a booking API

Full journey coverage

The API should cover the complete customer flow: browse services → pick staff and location → check availability → add to cart → checkout and pay → manage booking. Missing pieces mean you're building or bolting on additional infrastructure.

Real-time availability

Availability needs to account for existing bookings, staff working hours, buffer time between appointments, and multi-staff conflicts. This logic is hard to get right. Look for an API that exposes clean availability endpoints rather than raw calendar data you have to process yourself.

Multi-staff and multi-location

If your service business has more than one practitioner or site, the API needs to support per-staff schedules, per-location hours, and service-staff assignments. Availability queries need to filter correctly across these dimensions.

OpenAPI / TypeScript support

An OpenAPI spec and a typed TypeScript SDK mean you don't have to guess at request/response shapes. Type safety from the API call to the UI is worth a lot in a domain with complex nested objects (booking slots, cart line items, payment states).

Idempotent checkout

Payment flows fail in the real world. The checkout endpoint should be idempotent — repeating the same request should not create duplicate bookings or double charges.

Webhooks for post-booking events

Your backend often needs to react to booking events: appointment created, order paid, booking cancelled. Signed webhook events let you update your database, send custom notifications, or trigger downstream workflows without polling.

The Opencals Storefront API

The Opencals Storefront API is a REST API for building custom booking experiences. It covers the complete booking flow and is the same API that powers the Opencals Shopify app and dashboard.

Base URL: https://api.opencals.com
Auth: Authorization: Bearer sfk_your_api_key
Format: JSON throughout
Spec: OpenAPI 3.0 — interactive playground at opencals.com/docs

Authentication

API keys are scoped to a single store. You get one from the Opencals dashboard under Settings → API. The key prefix is sfk_ (storefront key).

bash

curl https://api.opencals.com/storefront/products \
  -H "Authorization: Bearer sfk_live_abc123"

Customer JWT tokens

Some endpoints (customer self-service: view bookings, reschedule, cancel) require a customer JWT issued by your own auth flow, not the store API key. See the Authentication docs for details on the dual-auth model.

Core endpoints

List services

bash

GET /storefront/products

Returns the service catalog — name, description, duration, pricing, images, associated staff. This is your booking homepage data.

typescript

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

const opencals = setupOpencals({ apiKey: process.env.OPENCALS_API_KEY });
const { data: products } = await ProductService.listProducts({ opencals });

// products is typed: Product[]
// product.variants holds per-variant pricing and duration

Check availability

bash

GET /storefront/appointments/availability
  ?productId=prod_123
  &staffMemberId=staff_456   # optional — omit to show all available staff
  &locationId=loc_789        # optional for single-location stores
  &from=2026-07-01
  &to=2026-07-07

Returns available time slots grouped by day. The API computes availability server-side — you get back a clean list of { date, slots: [{ start, end, staffMemberId }] } objects.

typescript

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

const { data: availability } = await AppointmentService.getAvailability({
  opencals,
  query: {
    productId: "prod_123",
    from: "2026-07-01",
    to: "2026-07-07",
  },
});

// availability.days is typed: AvailabilityDay[]

Create a cart and add a booking

bash

POST /storefront/cart          # create cart → returns cartId
POST /storefront/cart/items    # add booking to cart

The cart persists server-side. Pass cartId in subsequent requests. A cart can hold multiple bookings — useful for "book haircut + colour" flows.

typescript

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

const { data: cart } = await CartService.createCart({ opencals });

const { data: updatedCart } = await CartService.addCartItem({
  opencals,
  body: {
    cartId: cart.id,
    productId: "prod_123",
    variantId: "var_456",
    staffMemberId: "staff_789",
    startAt: "2026-07-03T14:00:00Z",
  },
});

Checkout

bash

POST /storefront/checkout/initiate   # returns Stripe payment intent
POST /storefront/checkout/confirm    # confirm after payment

The checkout endpoint returns a Stripe Payment Intent client secret. You pass that to Stripe Elements or Stripe.js on the frontend to collect payment. On success, confirm the booking. The API is idempotent on the confirm step.

typescript

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

// Step 1: initiate checkout
const { data: checkout } = await CheckoutService.initiateCheckout({
  opencals,
  body: { cartId: cart.id },
});
// checkout.clientSecret → pass to Stripe Elements

// Step 2: after Stripe confirms payment, confirm the booking
const { data: booking } = await CheckoutService.confirmCheckout({
  opencals,
  body: { cartId: cart.id, paymentIntentId: checkout.paymentIntentId },
});
// booking is confirmed — appointment is locked in the calendar

Full booking flow

Load service catalog

GET /storefront/products — populate your services page. Cache this; it rarely changes.

Load staff and locations

GET /storefront/staff-members and GET /storefront/locations — populate the filters on your booking page.

Fetch availability

GET /storefront/appointments/availability for the selected service, staff, and date range. Render the calendar.

Create cart and add item

POST /storefront/cart to create a cart, then POST /storefront/cart/items. Store the cartId client-side.

Initiate checkout

POST /storefront/checkout/initiate. Render the Stripe Elements payment form with the returned clientSecret.

Confirm on payment success

After Stripe confirms payment, POST /storefront/checkout/confirm. The booking is created, the slot is blocked, and confirmation emails fire.

TypeScript SDK

Installing the SDK removes the boilerplate:

bash

npm install @opencals/storefront-sdk

Every service maps to a class (ProductService, AppointmentService, CartService, CheckoutService, CustomerService). Every request and response is typed from the OpenAPI spec, so TypeScript catches mistakes at build time rather than runtime.

The SDK ships with Zod schemas for runtime validation and formatting helpers for prices (formatPrice(amount, currency)), durations (formatDuration(minutes)), and timezones.

Open-source example

The fastest way to see the complete API integration in context is the Haar open-source template — a Next.js 15 salon booking website that covers the full flow end to end.

Deploy with Vercel

Clone it from GitHub, add your API key, and you have a working booking site in minutes. The source shows exactly how each part of the API is called in a production Next.js app.

Interactive API reference

Try every endpoint directly from the browser — no curl required.

Build a booking page tutorial

Step-by-step walkthrough of the complete booking flow in Next.js.

TypeScript SDK guide

Full SDK documentation — setup, services, error handling, Zod schemas.

What is a headless booking system?

Architecture overview — when headless makes sense and what it actually means.

Booking API for developers: how to integrate appointment scheduling into your app

What a booking API needs to do

What to look for in a booking API

The Opencals Storefront API

Authentication

Core endpoints

Full booking flow

TypeScript SDK

Open-source example

Frequently Asked Questions

Ready to transform your service business?