Build a booking page

This tutorial walks through building a custom booking page on the Opencals Storefront API — an API for booking systems that handles services, real-time availability, carts, checkout, and payments. We’ll use Next.js and the typed @opencals/storefront-sdk, but every step maps 1:1 to plain REST calls, so the same flow works from any language. The complete booking flow is eight API calls:

List services — GET /storefront/products
Pick a staff member — GET /storefront/staff-members
Fetch available time slots — GET /storefront/products/{productId}/current-availabilities
Create an appointment — POST /storefront/appointments
Add it to a cart — POST /storefront/cart and POST /storefront/cart/items
(Optional) Show and attach add-ons — GET /storefront/products/{productId}/add-ons and POST /storefront/cart/add-ons
(Optional) Apply a promo code — POST /storefront/cart/discount-code and DELETE /storefront/cart/discount-code
Check out — POST /storefront/cart/checkout/start and POST /storefront/cart/checkout/submit

Setup

Install the SDK in a Next.js project and initialize it once, for example in a small module imported by your server code:

npm install @opencals/storefront-sdk

lib/opencals.ts

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

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

The API key must stay server-side, so the calls below belong in server components, route handlers, or server actions — not client components.

List services

ProductService.list() wraps GET /storefront/products and returns a paginated list of active services:

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

const { data } = await ProductService.list({ query: { take: 50 } });

// data.data → Product[], data.meta → pagination info
for (const product of data!.data) {
  console.log(product.title, product.price, product.duration);
}

A few product fields drive your UI:

Field	What it means for your booking page
`duration`	Service length in seconds
`price`	Price (0 = free); `minPrice`/`maxPrice` for variable pricing
`maxAttendees`	Greater than 1 → show an attendee count selector
`isCustomDuration`	`true` → show a date-range picker instead of single slots
`staffMembers`	If populated, let the customer pick a staff member
`locations`	If populated, let the customer pick a location

Let the customer pick a staff member

For salons and similar businesses, customers often choose who they book with. StaffMemberService.list() wraps GET /storefront/staff-members:

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

const { data: staff } = await StaffMemberService.list();

The selected staff member’s id filters availability in the next step. The same pattern works for locations via LocationService.list() (GET /storefront/locations) on multi-location stores.

Fetch available time slots

ProductService.getCurrentAvailabilities() wraps GET /storefront/products/{productId}/current-availabilities. It takes a required date (YYYY-MM-DD) plus optional staffMemberId, locationId, and timezone filters:

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

const { data: slots } = await ProductService.getCurrentAvailabilities({
  path: { productId: product.id },
  query: {
    date: "2026-06-15",
    staffMemberId: selectedStaff?.id,
    timezone: "America/New_York",
  },
});

Render the returned slots as your time picker.

For custom-duration products (isCustomDuration: true, e.g. rentals or venue hire), use GET /storefront/products/{productId}/current-availability-ranges and show a date-range picker instead. There’s also GET /storefront/products/{productId}/nearest-availability for “next available slot” badges on service cards.

Create the appointment

When the customer picks a slot, create an appointment with POST /storefront/appointments. The required slot object carries the product and the UTC date/time range; staffMemberId and locationId are optional:

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

const { data: appointment } = await AppointmentService.create({
  body: {
    slot: {
      productId: product.id,
      fromDate: "2026-06-15",
      fromTime: "14:00:00",
      toDate: "2026-06-15",
      toTime: "15:00:00",
      staffMemberId: selectedStaff?.id ?? null,
      locationId: null,
    },
    numberOfAttendees: 1,
  },
});

All slot date/times are UTC — convert from the customer’s timezone before sending.

Cart

Carts hold appointments between slot selection and payment, and they expire after a few minutes so abandoned selections release their slots. Cart endpoints identify the cart with the X-Cart-Id header:

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

// Create a cart (or fetch the existing one if you already have an ID)
const { data: cart } = await CartService.createOrGet({
  headers: { "X-Cart-Id": existingCartId ?? "" },
});

// Add the appointment to it
const { data: updatedCart } = await CartService.addItem({
  body: { appointmentId: appointment!.id },
  headers: { "X-Cart-Id": cart!.id },
});

Persist cart.id (for example in a cookie) so the customer keeps their cart across pages. If checkout takes a while, POST /storefront/cart/extend adds five minutes to the cart’s expiration.

Show and attach add-ons (optional)

If the service has add-ons (extras like equipment rentals, upgrades, or accessories), fetch them and let the customer choose before proceeding to payment.

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

// Fetch add-ons available for the booked service
const { data: addOns } = await AddOnService.listForProduct({
  path: { productId: product.id },
});

// addOns.data → AddOn[] with title, description, price, durationMultiplied, maxQuantity

When the customer selects an add-on, attach it to the cart item:

await CartService.addAddOn({
  body: {
    cartItemId: updatedCart!.items[0].id,
    addOnId: selectedAddOn.id,
    quantity: 1,
  },
  headers: { "X-Cart-Id": cart!.id },
});

A few things to know about add-on pricing:

Field	What it means
`price`	Unit price. Multiply by quantity for the line total.
`durationMultiplied`	If `true`, quantity is auto-set to the service duration units (e.g., 3 days = quantity 3). Don’t ask the customer for quantity.
`maxQuantity`	If non-null, cap your quantity input at this value.

Skip this step if addOns.data is empty — not every service has add-ons configured.

Apply a promo code (optional)

If the store offers discount codes, let customers enter a promo code before checkout. CartService.applyDiscountCode() wraps POST /storefront/cart/discount-code:

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

try {
  const { data: updatedCart } = await CartService.applyDiscountCode({
    body: { code: "SUMMER15" },
    headers: { "X-Cart-Id": cart!.id },
  });
  // updatedCart now includes applied discounts
} catch (error) {
  // Handle typed errors: CODE_NOT_FOUND | CODE_EXPIRED | CODE_DISABLED | CODE_LIMIT_REACHED | CODE_CUSTOMER_INELIGIBLE | CODE_NO_MATCHING_ITEMS
  // Render inline below the input (Shopify-style red)
}

Remove a code with DELETE /storefront/cart/discount-code:

await CartService.removeDiscountCode({
  headers: { "X-Cart-Id": cart!.id },
});

Reading applied discounts

Every cart-returning endpoint now includes appliedDiscounts[] and per-line-item discounts[] fields. Show a “You saved $X” summary by subtracting the cart’s total from the sum of original line prices:

const originalTotal = updatedCart!.items.reduce(
  (sum, item) => sum + item.originalPrice * item.quantity,
  0
);
const saved = originalTotal - updatedCart!.total;

Checkout

Checkout is a three-call sequence against the same X-Cart-Id.Start validates the cart and initializes payment with your chosen provider (list configured providers with GET /storefront/payment/providers):

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

const { data: checkout } = await CheckoutService.start({
  body: { provider: "stripe" },
  headers: { "X-Cart-Id": cart!.id },
});

// Stripe: checkout.clientSecret → confirm with Stripe Payment Element
// Redirect providers: checkout.redirectUrl → send the customer there

Save the customer so the order and appointments have contact details (guests don’t need an account):

await CheckoutService.saveCustomer({
  body: {
    customer: {
      email: "jane@example.com",
      firstName: "Jane",
      lastName: "Doe",
    },
  },
  headers: { "X-Cart-Id": cart!.id },
});

If the store has custom checkout questions, fetch them with GET /storefront/cart/checkout/questions/{language} and save answers via POST /storefront/cart/checkout/save-answers.Submit captures the payment and creates the order:

const { data: result } = await CheckoutService.submit({
  body: { stripePaymentIntentId: paymentIntentId }, // if confirmed client-side with Stripe
  headers: { "X-Cart-Id": cart!.id },
});

// result.order → the confirmed order
// result.auth  → tokens for new/passwordless customers (auto sign-in)

The response includes the created order and, for new customers, an auth token pair you can use to sign them in automatically — see Authentication.

For pay-at-venue stores, start checkout with provider: "cash" and submit directly with no payment confirmation step.

After the booking

With a customer token you can power a full self-service portal:

GET /storefront/appointments — list the customer’s appointments
PUT /storefront/appointments/{appointmentId}/reschedule — move a booking
PUT /storefront/appointments/{appointmentId}/cancel — cancel it
GET /storefront/orders — order history with payments and refunds

Skip the boilerplate

If you’d rather start from working code, Opencals publishes free open-source Next.js booking templates built on this exact flow — browse them at open-source/templates or clone the Haar salon template. For the full endpoint catalog, head to the API reference.

Get started

Guides

Setup

Reading applied discounts

After the booking

Skip the boilerplate

​Setup

​Reading applied discounts

​After the booking

​Skip the boilerplate

Setup

Reading applied discounts

After the booking

Skip the boilerplate