Quickstart

The Opencals Storefront API is a REST booking API for developers. It exposes everything a booking website needs — services, real-time availability, staff members, locations, carts, checkout, and payments — so you can build a fully custom booking experience on any stack while Opencals handles scheduling logic, conflict prevention, and order management. Everything you configure in the Opencals dashboard is available over the API.

Base URL

All Storefront API endpoints live under a single base URL:

https://api.opencals.com

Endpoint paths are prefixed with /storefront — for example GET /storefront/products lists your bookable services. Responses are JSON with camelCase property names.

Make your first request

Get an API key

Sign up at opencals.com and set up your store — services, staff members, locations, and schedules.
In the dashboard, go to Users → your user → API Keys and create a key. Calling the API from a server? Create a private storefront key (spk_). For browser code, create a public storefront key (sfk_).
Each key is scoped to your store. See API keys for the difference.

Keep a private key server-side (for example in an environment variable), never in browser code.

List your services

List your store’s active services with a single call:

curl "https://api.opencals.com/storefront/products" \
  -H "X-Api-Key: sfk_your_key_here"

Read the response

The response is a paginated collection:

{
  "data": [
    {
      "id": "9c6f7c2e-…",
      "title": "Haircut",
      "duration": 3600,
      "price": 4500,
      "maxAttendees": 1
    }
  ],
  "meta": {
    "page": 1,
    "take": 50,
    "itemCount": 12,
    "pageCount": 1,
    "hasPreviousPage": false,
    "hasNextPage": false
  }
}

You can also try every endpoint directly in the interactive API reference.

Pagination

List endpoints accept page (1-indexed) and take (items per page, maximum 100) query parameters and return a meta object with page, take, itemCount, pageCount, hasPreviousPage, and hasNextPage.

curl "https://api.opencals.com/storefront/products" \
  -H "X-Api-Key: sfk_your_key_here" \
  --url-query "page=2" \
  --url-query "take=20"

Rate limits

Limits are per API key and visitor IP, never a total for your store, so a busy site isn’t capped. The visitor IP is the buyer IP your server forwards with a private key (X-Opencals-Buyer-Ip); otherwise it’s the IP the request comes from, which for a server-side site is your server’s, shared by all your visitors.

Category	Limit
General	50 requests / second, 300 / 10 seconds, 1,200 / minute
Sign-up	3 per buyer IP / 10 minutes (30 per IP when the buyer IP isn’t forwarded)
Emails: verification, password reset, login code	3 per email address and 10 per buyer IP / 10 minutes (30 per IP when not forwarded)
Sign-in, login-code check	10 per email address and 30 per buyer IP / 10 minutes (60 per IP when not forwarded)
Verify email, reset password, magic links, OAuth	30 per buyer IP / 10 minutes (60 per IP when not forwarded)

When you exceed a limit the API responds with 429 Too Many Requests. Back off and retry; the windows are short.

Timezones

All date and time values in requests and responses are in UTC. Availability endpoints accept a timezone query parameter (for example America/New_York) to return slots in the user’s local timezone. Convert user-selected times back to UTC before creating appointments.

Next steps

Authentication

API keys, customer tokens, and error responses.

Build a booking page

The full flow from listing services to a confirmed booking.

Storefront SDK

The typed TypeScript client for this API.

API reference

Every endpoint, parameter, and response shape.

Get started

Guides

Base URL

Make your first request

Rate limits

Timezones

Next steps

Authentication

Build a booking page

Storefront SDK

API reference

​Base URL

​Make your first request

​Pagination

​Rate limits

​Timezones

​Next steps

Authentication

Build a booking page

Storefront SDK

API reference

Base URL

Make your first request

Pagination

Rate limits

Timezones

Next steps