# Opencals Developer Docs

> Documentation for the Opencals Storefront API — REST booking API, TypeScript SDK, and open-source booking website templates for building custom booking experiences.

- [Introduction](https://opencals.com/docs/introduction.md): The Opencals Storefront API is booking infrastructure for builders — a REST API for services, real-time availability, carts, checkout, and payments, so you can build a fully custom booking experience on any stack.
- [Quickstart](https://opencals.com/docs/quickstart.md): What the Opencals Storefront API is, how to get an API key, and how to make your first request.
- [Authentication](https://opencals.com/docs/authentication.md): How authentication works in the Opencals Storefront API: public and private API keys, forwarding the buyer IP, customer JWT tokens, refresh flows, and error responses.
- [Build a booking page](https://opencals.com/docs/guides/build-a-booking-page.md): Step-by-step tutorial: use the Opencals Storefront API with Next.js and the TypeScript SDK to list services, pick a time slot, manage a cart, and complete checkout.
- [Storefront SDK](https://opencals.com/docs/guides/storefront-sdk.md): Install and use @opencals/storefront-sdk — the type-safe TypeScript client for the Opencals booking API, generated from the OpenAPI spec with Zod schemas and helpers included.
- [Customer email links (magic links)](https://opencals.com/docs/guides/customer-email-links.md): Set up passwordless email links for customer actions: view/reschedule/cancel appointments, leave feedback, verify email, and reset passwords. No additional code — just configure one setting and implement one route.
- [Webhooks](https://opencals.com/docs/guides/webhooks.md): The planned Opencals webhook event catalog for booking automations — and how to keep a headless booking site in sync today with polling and revalidation.
- [API Reference](https://opencals.com/docs/api-reference/introduction.md): Base URL, authentication, and conventions for the Opencals Storefront API — plus an interactive playground for every endpoint.
- [Customer sign in with credentials](https://opencals.com/docs/api-reference/auth/customer-sign-in-with-credentials.md): Authenticate a storefront customer using email and password
- [Customer OAuth sign in](https://opencals.com/docs/api-reference/auth/customer-oauth-sign-in.md): Authenticate or register a storefront customer using an OAuth provider (e.g. Google)
- [Register a new customer](https://opencals.com/docs/api-reference/auth/register-a-new-customer.md): Create a new customer account on the storefront and send a verification email
- [Request customer email verification](https://opencals.com/docs/api-reference/auth/request-customer-email-verification.md): Send a verification email to the customer for account activation within the store context
- [Verify customer email](https://opencals.com/docs/api-reference/auth/verify-customer-email.md): Confirm customer email ownership using the verification token and return auth tokens
- [Refresh customer tokens](https://opencals.com/docs/api-reference/auth/refresh-customer-tokens.md): Exchange a valid customer refresh token for a new pair of access and refresh tokens
- [Request customer password reset](https://opencals.com/docs/api-reference/auth/request-customer-password-reset.md): Send a password reset email to the customer within the store context
- [Reset customer password](https://opencals.com/docs/api-reference/auth/reset-customer-password.md): Reset the customer password using a valid reset token received via email
- [Resolve a magic link token](https://opencals.com/docs/api-reference/auth/resolve-a-magic-link-token.md): Validate a magic link token, authenticate the customer, and return redirect information
- [Request a login code](https://opencals.com/docs/api-reference/auth/request-a-login-code.md): Send a 6-digit login code to the customer email for passwordless authentication
- [Verify a login code](https://opencals.com/docs/api-reference/auth/verify-a-login-code.md): Verify the 6-digit login code and return auth tokens for passwordless sign-in
- [Get current customer profile](https://opencals.com/docs/api-reference/self-service/get-current-customer-profile.md)
- [Update current customer profile](https://opencals.com/docs/api-reference/self-service/update-current-customer-profile.md)
- [Get current customer marketing consent](https://opencals.com/docs/api-reference/self-service/get-current-customer-marketing-consent.md)
- [Update current customer marketing consent](https://opencals.com/docs/api-reference/self-service/update-current-customer-marketing-consent.md)
- [Change current customer password](https://opencals.com/docs/api-reference/self-service/change-current-customer-password.md)
- [List customer appointments](https://opencals.com/docs/api-reference/appointments/list-customer-appointments.md): Returns all appointments for the authenticated customer with pagination
- [Create appointment](https://opencals.com/docs/api-reference/appointments/create-appointment.md): Creates a new appointment for a customer. Authentication is optional. When signed in as a customer, the appointment is always booked for that customer and any `customer` in the body is ignored. Anonymous callers pass the customer by email (a brand-new customer is created and returned). If the email…
- [Get appointment by ID](https://opencals.com/docs/api-reference/appointments/get-appointment-by-id.md): Returns a single appointment by ID for the authenticated customer
- [Get appointment by external order name](https://opencals.com/docs/api-reference/appointments/get-appointment-by-external-order-name.md): Deprecated: look the order up instead. Returns a single appointment by the name of its order on the store's platform (e.g. a Shopify order name).
- [Reschedule appointment](https://opencals.com/docs/api-reference/appointments/reschedule-appointment.md): Reschedules an existing appointment to a new time. Subject to reschedule_gap restrictions defined in the service configuration. The new time must be the same length (the same number of billed units) as the current booking, otherwise 400 is returned; the product cannot be changed.
- [Cancel appointment](https://opencals.com/docs/api-reference/appointments/cancel-appointment.md): Cancels an existing appointment. Subject to cancel_gap restrictions defined in the service configuration.
- [Submit appointment feedback](https://opencals.com/docs/api-reference/appointments/submit-appointment-feedback.md): Allows customers to submit feedback for a completed appointment
- [Add a guest to an appointment](https://opencals.com/docs/api-reference/appointments/add-a-guest-to-an-appointment.md): Adds a guest (by email) to an appointment. Guests are copied on appointment notifications.
- [Remove a guest from an appointment](https://opencals.com/docs/api-reference/appointments/remove-a-guest-from-an-appointment.md): Removes a guest from an appointment and (by default) notifies them of the removal.
- [Get customer booking preferences](https://opencals.com/docs/api-reference/appointments/get-customer-booking-preferences.md): Returns frequently booked services, locations, and staff members based on customer booking history. Results are cached for 24 hours to optimize performance.
- [List customer orders](https://opencals.com/docs/api-reference/orders/list-customer-orders.md): Returns all orders for the authenticated customer with pagination
- [Get order by ID](https://opencals.com/docs/api-reference/orders/get-order-by-id.md): Returns a single order by ID for the authenticated customer
- [Fetch cart](https://opencals.com/docs/api-reference/cart/fetch-cart.md)
- [Create or fetch cart](https://opencals.com/docs/api-reference/cart/create-or-fetch-cart.md)
- [Add appointment to cart](https://opencals.com/docs/api-reference/cart/add-appointment-to-cart.md)
- [Remove cart item](https://opencals.com/docs/api-reference/cart/remove-cart-item.md)
- [Extend cart expiration by 5 minutes](https://opencals.com/docs/api-reference/cart/extend-cart-expiration-by-5-minutes.md)
- [Add an add-on to a cart item](https://opencals.com/docs/api-reference/cart/add-an-add-on-to-a-cart-item.md)
- [Remove a cart add-on item](https://opencals.com/docs/api-reference/cart/remove-a-cart-add-on-item.md)
- [Update quantity of a cart add-on item](https://opencals.com/docs/api-reference/cart/update-quantity-of-a-cart-add-on-item.md)
- [Apply a discount/promo code to the cart](https://opencals.com/docs/api-reference/cart/apply-a-discountpromo-code-to-the-cart.md)
- [Remove the applied discount/promo code from the cart](https://opencals.com/docs/api-reference/cart/remove-the-applied-discountpromo-code-from-the-cart.md)
- [Start checkout for cart (create payment, validate items)](https://opencals.com/docs/api-reference/checkout/start-checkout-for-cart-create-payment-validate-items.md)
- [Submit checkout (capture payment, create order, auto-authenticate customer)](https://opencals.com/docs/api-reference/checkout/submit-checkout-capture-payment-create-order-auto-authenticate-customer.md): Creates the order. Returns `auth` tokens (and `customer`) only when the request is authenticated as the order customer, or when this checkout created a new customer. Otherwise the order is attached to the existing customer, who signs in by code to see it.
- [Get all checkout questions for current cart](https://opencals.com/docs/api-reference/checkout/get-all-checkout-questions-for-current-cart.md)
- [Save customer information to cart and appointments](https://opencals.com/docs/api-reference/checkout/save-customer-information-to-cart-and-appointments.md)
- [Save checkout question answers to appointments](https://opencals.com/docs/api-reference/checkout/save-checkout-question-answers-to-appointments.md)
- [Get store public settings](https://opencals.com/docs/api-reference/store/get-store-public-settings.md)
- [Get product by slug](https://opencals.com/docs/api-reference/products/get-product-by-slug.md): Retrieve a product by its URL-friendly slug for the current store
- [Get product by ID](https://opencals.com/docs/api-reference/products/get-product-by-id.md): Retrieve a product by its internal ID for the current store
- [Get products by external ID](https://opencals.com/docs/api-reference/products/get-products-by-external-id.md): Retrieve products by their external platform ID (e.g., Shopify product ID) for the current store
- [Get a product by external variant ID](https://opencals.com/docs/api-reference/products/get-a-product-by-external-variant-id.md): Retrieve a product by its external variant ID (e.g., Shopify variant ID) for the current store
- [List store products](https://opencals.com/docs/api-reference/products/list-store-products.md): Retrieve a paginated list of active products for the current store, for the current store
- [Get the nearest available slot for a product](https://opencals.com/docs/api-reference/products/get-the-nearest-available-slot-for-a-product.md): Find the nearest upcoming availability slot for a product. Returns null/204 if no slot exists within the advance schedule window.
- [Get current availabilities for a product](https://opencals.com/docs/api-reference/products/get-current-availabilities-for-a-product.md): Retrieve individual bookable time slots for a product on a given date.
- [Get merged availability ranges for a product](https://opencals.com/docs/api-reference/products/get-merged-availability-ranges-for-a-product.md): Retrieve merged availability ranges (broad time windows) for a product. Useful for calendar date highlighting.
- [List available add-ons for a product](https://opencals.com/docs/api-reference/products/list-available-add-ons-for-a-product.md): Returns active add-ons available for the given product, filtered by location and staff member assignments.
- [List available add-ons for a product by slug](https://opencals.com/docs/api-reference/products/list-available-add-ons-for-a-product-by-slug.md): Returns active add-ons available for the given product slug, filtered by location and staff member assignments.
- [Get location by slug](https://opencals.com/docs/api-reference/locations/get-location-by-slug.md): Retrieve a location by its URL-friendly slug for current store
- [Get location by ID](https://opencals.com/docs/api-reference/locations/get-location-by-id.md): Retrieve a location by its internal ID for current store
- [List store locations](https://opencals.com/docs/api-reference/locations/list-store-locations.md): Retrieve a paginated list of locations for the current store
- [Get product collection by slug](https://opencals.com/docs/api-reference/product-collections/get-product-collection-by-slug.md): Retrieve a product collection by its URL-friendly slug for the current store
- [List store product collections](https://opencals.com/docs/api-reference/product-collections/list-store-product-collections.md): Retrieve a paginated list of product collections for the current store
- [Get staff member by slug](https://opencals.com/docs/api-reference/staff-members/get-staff-member-by-slug.md): Retrieve a staff member by their URL-friendly slug for current store
- [List store staff members](https://opencals.com/docs/api-reference/staff-members/list-store-staff-members.md): Retrieve a paginated list of staff members for the current store
- [List add-ons for the current store](https://opencals.com/docs/api-reference/add-ons/list-add-ons-for-the-current-store.md)
- [Get an add-on by ID](https://opencals.com/docs/api-reference/add-ons/get-an-add-on-by-id.md)
- [Get an add-on by slug](https://opencals.com/docs/api-reference/add-ons/get-an-add-on-by-slug.md)
- [Get available payment providers for checkout](https://opencals.com/docs/api-reference/payment/get-available-payment-providers-for-checkout.md): Returns the active, eligible payment providers configured for this store. When the cart is identified (X-Cart-Id header or cart_id cookie) the list is amount-aware: only providers that can charge the current total are returned, and when nothing is collectible (fully discounted, or below every method…
- [Get public payment settings](https://opencals.com/docs/api-reference/payment/get-public-payment-settings.md): Returns public payment configuration like currency and capture method.
- [List invoices issued for the authenticated customer order](https://opencals.com/docs/api-reference/invoices/list-invoices-issued-for-the-authenticated-customer-order.md)
- [List feedback questions translations](https://opencals.com/docs/api-reference/feedback-questions/list-feedback-questions-translations.md)
- [List checkout questions translations for a product](https://opencals.com/docs/api-reference/checkout-questions/list-checkout-questions-translations-for-a-product.md)
- [Generate a presigned S3 URL for a customer file upload](https://opencals.com/docs/api-reference/customer-uploads/generate-a-presigned-s3-url-for-a-customer-file-upload.md)
- [Get image by ID](https://opencals.com/docs/api-reference/images/get-image-by-id.md)
- [Open-source templates](https://opencals.com/docs/open-source/templates.md): Free, open-source booking website templates built on the Opencals Storefront API. Clone, customize, and deploy a production booking site in minutes.
- [Haar — salon booking template](https://opencals.com/docs/open-source/haar.md): Free, open-source beauty salon booking website template. Next.js 15, Stripe checkout, staff and multi-location booking, customer accounts — built on the Opencals Storefront API.
- [Frisor — barbershop booking template](https://opencals.com/docs/open-source/frisor.md): Free, open-source barbershop booking website template. Next.js 15, Stripe checkout, staff and multi-location booking, add-ons, customer accounts — built on the Opencals Storefront API.
- [Clear Care — clinic booking template](https://opencals.com/docs/open-source/clarity.md): Free, open-source medical clinic booking website template. Next.js 15, a guided Care Finder, a single-page booking composer with pre-visit notes and photo uploads, video visits, Stripe checkout and a family care record — built on the Opencals Storefront API.
- [VOLT — padel & squash club template](https://opencals.com/docs/open-source/volt.md): Free, open-source multi-club padel and squash booking website template. Next.js 15, a live hall map and court grid per club, crew-and-kit checkout, match-ticket confirmations, coach-led training and passwordless accounts, built on the Opencals Storefront API.
- [NOIR Drive — luxury car rental template](https://opencals.com/docs/open-source/noir.md): Free, open-source luxury car rental website template. Next.js 15, multi-day booking by the day, delivery or garage collection, per-day extras, chauffeur packages, Stripe checkout and passwordless accounts, built on the Opencals Storefront API.
- [Fluently — language school template](https://opencals.com/docs/open-source/fluently.md): Free, open-source language school website template. Next.js 15, group classes with level variants and live seats left, private lessons, a free trial, teachers, campuses plus an online classroom with a Join button, Stripe checkout and passwordless accounts, built on the Opencals Storefront API.
- [Bali Villa Rentals — villa booking template](https://opencals.com/docs/open-source/bali-villas.md): Free, open-source villa and holiday-rental website template. Next.js 15, nightly stays with fixed check-in and check-out, a calendar on live availability, per-stay extras, guest details, Stripe checkout and passwordless accounts, built on the Opencals Storefront API.
- [Tensile — reformer Pilates studio template](https://opencals.com/docs/open-source/reformer.md): Free, open-source reformer Pilates and fitness studio website template. Next.js 15, a multi-studio weekly timetable with the instructor and beds left on every class, Full classes with the next class that has space, 1:1 and duet privates, dated workshops, live online classes with a Join button, Strip…
- [AI Agents & App Builders](https://opencals.com/docs/ai-agents/overview.md): Agent Skills that teach AI coding tools — Claude Code, Cursor, Codex, Gemini CLI — to build booking integrations on the Opencals API correctly. Install once and let your agent scaffold, wire, and debug.
- [opencals-storefront-api skill](https://opencals.com/docs/ai-agents/storefront-api-skill.md): The ground-truth Agent Skill for building on the Opencals API and @opencals/storefront-sdk — availability, carts, appointments, checkout, discounts, customer accounts, guests, custom durations, reschedule/cancel and rate limits.
- [opencals-build-booking-site skill](https://opencals.com/docs/ai-agents/build-booking-site-skill.md): The Agent Skill that builds a whole booking website on Opencals — pick an official Next.js template, scaffold, wire availability and checkout, rebrand, and deploy to Vercel.
- [Lovable](https://opencals.com/docs/ai-agents/lovable.md): Add Opencals to Lovable as a custom connector so Lovable apps take real bookings: live availability, cart, checkout and Stripe payments. Every field ready to copy.
- [v0](https://opencals.com/docs/ai-agents/v0.md): Attach the Opencals agent skills in v0 from skills.sh, add OPENCALS_API_KEY, and v0 builds a Next.js booking site on the Opencals SDK with live availability and Stripe checkout.
- [Base44](https://opencals.com/docs/ai-agents/base44.md): Connect a Base44 app to Opencals with one backend function, an app secret and two workspace skills: live availability, cart, checkout and Stripe payments.
- [Changelog](https://opencals.com/docs/changelog.md): What's new in the Opencals developer platform — Storefront API, TypeScript SDK, open-source templates, and developer docs.
- [Tensile — reformer Pilates studio template](https://opencals.com/docs/changelog/reformer-template.md): Tensile, a free open-source reformer Pilates and fitness studio website template built on the Storefront API, plus a reformer-studio seed dataset.
- [One confirmation email per order](https://opencals.com/docs/changelog/order-confirmation-email.md): Customers get a single Order Confirmation email listing every appointment they booked, instead of one email per appointment.
- [Customer reschedules keep the booking length](https://opencals.com/docs/changelog/reschedule-same-length.md): PUT /customer/appointments/:id/reschedule now rejects a new slot of a different length and always keeps the appointment's own product.
- [Checkout: existing customers and booking addresses](https://opencals.com/docs/changelog/checkout-customer-trust.md): Storefront checkout no longer returns tokens for, or changes, an existing customer identified only by the email in the request. Addresses entered for such a booking are saved to the customer once the order is placed.
- [Bali Villa Rentals — villa booking template](https://opencals.com/docs/changelog/bali-villas-template.md): Bali Villa Rentals, a free open-source villa and holiday-rental website template built on the Storefront API, plus a villa-resort seed dataset and server-side enforcement of fixed check-in and check-out times.
- [Fluently — language school template](https://opencals.com/docs/changelog/fluently-template.md): Fluently, a free open-source language school website template built on the Storefront API, plus a language-school seed dataset with online classroom links.
- [NOIR Drive — car rental template](https://opencals.com/docs/changelog/noir-template.md): NOIR Drive, a free open-source luxury car rental website template built on the Storefront API, plus a car-rental seed dataset and correct validation for multi-day bookings longer than 24 hours.
- [Lovable, v0 and Base44](https://opencals.com/docs/changelog/ai-app-builders.md): Setup guides for building Opencals booking sites in Lovable (custom connector), v0 (agent skills) and Base44 (backend function + workspace skills).
- [AI Agent Skills](https://opencals.com/docs/changelog/ai-agent-skills.md): Opencals Agent Skills — ground-truth Skills that teach Claude Code, Cursor, Codex and Gemini CLI to build booking integrations on the Opencals API and SDK, plus a new AI Agents docs section and machine-readable llms.txt.
- [VOLT — padel & squash template](https://opencals.com/docs/changelog/volt-template.md): VOLT, a free open-source multi-club padel and squash booking website template built on the Storefront API — Next.js 15, a live hall map and court grid per club, crew-and-kit checkout, match-ticket confirmations, coach-led training, passwordless accounts.
- [Clear Care — clinic template](https://opencals.com/docs/changelog/clarity-template.md): Clear Care, a free open-source medical clinic booking website template built on the Storefront API — Next.js 15, department-first booking, medical intake, passwordless accounts, Stripe checkout.
- [Custom Attributes](https://opencals.com/docs/changelog/custom-attributes.md): Attach arbitrary key-value data to appointments at booking time. Storefront SDK v0.3.11.
- [Discounts](https://opencals.com/docs/changelog/discounts.md): Automatic and promo-code discounts — target by product, staff, location, and schedule, with stacking and usage caps. Storefront SDK v0.3.2.
- [Frisor — barbershop template](https://opencals.com/docs/changelog/frisor-template.md): Frisor, a free open-source barbershop booking website template built on the Storefront API — Next.js 15, Stripe checkout, add-ons, customer accounts.
- [Add-Ons](https://opencals.com/docs/changelog/add-ons.md): Optional extras attached to any bookable service, selected during the booking flow and paid in one transaction. Storefront SDK v0.3.0.
- [Developer docs launched](https://opencals.com/docs/changelog/developer-docs.md): The Opencals developer documentation is live — interactive API reference, quickstart, guides, and open-source templates.
- [Haar — salon template](https://opencals.com/docs/changelog/haar-template.md): Haar, the first open-source Opencals template — a complete beauty-salon booking website built on the Storefront API.
- [Storefront API — v1](https://opencals.com/docs/changelog/storefront-api.md): The Storefront API is publicly available — the full customer-facing booking flow over REST.
- [Storefront SDK](https://opencals.com/docs/changelog/storefront-sdk.md): Version history for @opencals/storefront-sdk — the official TypeScript client for the Storefront API. See which release each feature first shipped in.

## OpenAPI Specs

- [openapi](/docs/api-reference/openapi.json)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.