Opencals

https://opencals.com/docs
Admin
Opencals is a standalone-first booking platform providing a REST API and TypeScript SDK to build...
Tokens:60,898
Snippets:761
Trust Score:5.2
Update:1 month ago
Show doc for...
Tokens:
Raw
### Clone and install the Haar template

Source: https://opencals.com/docs/open-source/haar

Initializes the project repository and installs necessary dependencies.

```bash
git clone https://github.com/letsopencals/template-haar.git
cd template-haar
npm install
```

--------------------------------

### Clone and install Frisor

Source: https://opencals.com/docs/open-source/frisor

Initializes the project repository and installs necessary dependencies.

```bash
git clone https://github.com/letsopencals/template-frisor.git
cd template-frisor
npm install
```

--------------------------------

### Install Storefront SDK

Source: https://opencals.com/docs/changelog/storefront-sdk

Use npm to install the official TypeScript client for the Storefront API.

```bash
npm install @opencals/storefront-sdk
```

--------------------------------

### GET /storefront/add-ons/slug/:slug

Source: https://opencals.com/docs/api-reference/auth/customer-oauth-sign-in

Get an add-on by its slug.

```APIDOC
## GET /storefront/add-ons/slug/:slug

### Description
Get add-on by slug.

### Method
GET

### Endpoint
/storefront/add-ons/slug/:slug

### Parameters
#### Path Parameters
- **slug** (string) - Required - The slug of the add-on.
```

--------------------------------

### GET /customer/products

Source: https://opencals.com/docs/api-reference/auth/customer-oauth-sign-in

List all active products.

```APIDOC
## GET /customer/products

### Description
List all active products (paginated).

### Method
GET

### Endpoint
/customer/products
```

--------------------------------

### Run development server

Source: https://opencals.com/docs/open-source/frisor

Starts the local development environment to preview the shop with live data.

```bash
npm run dev
```

--------------------------------

### GET /customer/product-collections/slug/:slug

Source: https://opencals.com/docs/api-reference/auth/customer-oauth-sign-in

Get a collection by its slug.

```APIDOC
## GET /customer/product-collections/slug/:slug

### Description
Get collection by slug.

### Method
GET

### Endpoint
/customer/product-collections/slug/:slug
```

--------------------------------

### GET /storefront/products/:id/add-ons

Source: https://opencals.com/docs/api-reference/auth/customer-oauth-sign-in

List add-ons for a specific product.

```APIDOC
## GET /storefront/products/:id/add-ons

### Description
List add-ons for a specific product.

### Method
GET

### Endpoint
/storefront/products/:id/add-ons

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the product.
```

--------------------------------

### GET /customer/product-collections

Source: https://opencals.com/docs/api-reference/auth/customer-oauth-sign-in

List all product collections.

```APIDOC
## GET /customer/product-collections

### Description
List all collections (paginated).

### Method
GET

### Endpoint
/customer/product-collections
```

--------------------------------

### Start Checkout Request

Source: https://opencals.com/docs/api-reference/auth/customer-oauth-sign-in

Initiates the checkout process by specifying the payment provider and customer details.

```json
POST /customer/cart/checkout/start

X-Cart-Id: cart-uuid

{
  "provider": "stripe",
  "customer": { "email": "john@example.com", "firstName": "John", "lastName": "Smith" }
}
```

--------------------------------

### GET /customer/stores/public-settings

Source: https://opencals.com/docs/api-reference/auth/customer-oauth-sign-in

Retrieves public store configuration settings.

```APIDOC
## GET /customer/stores/public-settings

### Description
Retrieves store configuration including name, logo, currency, timezone, and contact info.

### Method
GET

### Endpoint
/customer/stores/public-settings
```

--------------------------------

### GET /storefront/add-ons

Source: https://opencals.com/docs/api-reference/auth/customer-oauth-sign-in

List add-ons, optionally filtered by product ID.

```APIDOC
## GET /storefront/add-ons

### Description
List add-ons (filter by productId).

### Method
GET

### Endpoint
/storefront/add-ons

### Parameters
#### Query Parameters
- **productId** (string) - Optional - Filter add-ons by product ID.
```

--------------------------------

### Start Checkout Request

Source: https://opencals.com/docs/api-reference/auth/customer-oauth-sign-in

Initiates a checkout process by providing provider details and customer information.

```json
POST /customer/cart/checkout/start

X-Cart-Id: <cart_id>


{
  "provider": "stripe",
  "customer": {
    "email": "john@example.com",
    "firstName": "John",
    "lastName": "Smith"
  }
}
```

--------------------------------

### Add-on Object Structure

Source: https://opencals.com/docs/api-reference/auth/customer-oauth-sign-in

Example of the add-on object returned by the storefront API.

```json
{
  "id": "addon-uuid",
  "slug": "deep-conditioning",
  "title": "Deep Conditioning Treatment",
  "description": "Intensive moisture treatment added to any color or cut service.",
  "price": 20.00,
  "taxable": true,
  "durationMultiplied": false,
  "maxQuantity": 1,
  "status": "active",
  "imageId": "img-uuid-or-null"
}
```

--------------------------------

### GET /customer/products/:id

Source: https://opencals.com/docs/api-reference/auth/customer-oauth-sign-in

Retrieve details for a specific product by ID.

```APIDOC
## GET /customer/products/:id

### Description
Get product by ID.

### Method
GET

### Endpoint
/customer/products/:id
```

--------------------------------

### Start Checkout Request

Source: https://opencals.com/docs/api-reference/auth/request-a-login-code

Initiates the checkout process for a specific cart ID.

```json
POST /customer/cart/start

X-Cart-Id: <cart_id>


{
  "provider": "stripe",
  "customer": {
    "email": "john@example.com",
    "firstName": "John",
    "lastName": "Smith"
  }
}
```

--------------------------------

### GET /customer/products/:id/nearest-availability

Source: https://opencals.com/docs/api-reference/auth/customer-oauth-sign-in

Find the next available slot for a product.

```APIDOC
## GET /customer/products/:id/nearest-availability

### Description
Find next available slot.

### Method
GET

### Endpoint
/customer/products/:id/nearest-availability
```

--------------------------------

### GET /customer/cart/checkout/questions/{lang}

Source: https://opencals.com/docs/api-reference/auth/customer-oauth-sign-in

Retrieves checkout questions configured for the store.

```APIDOC
## GET /customer/cart/checkout/questions/{lang}

### Description
Fetches an array of checkout questions based on the specified language.

### Method
GET

### Endpoint
/customer/cart/checkout/questions/{lang}

### Parameters
#### Path Parameters
- **lang** (string) - Required - Language code (e.g., "en")
```

--------------------------------

### GET /storefront/products

Source: https://opencals.com/docs/quickstart

Retrieves a paginated list of the store's active bookable services.

```APIDOC
## GET /storefront/products

### Description
List your store's active services.

### Method
GET

### Endpoint
https://api.opencals.com/storefront/products

### Parameters
#### Query Parameters
- **page** (integer) - Optional - Page number (1-indexed)
- **take** (integer) - Optional - Items per page (maximum 100)

### Response
#### Success Response (200)
- **data** (array) - List of service objects
- **meta** (object) - Pagination metadata including page, take, itemCount, pageCount, hasPreviousPage, and hasNextPage

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

--------------------------------

### GET /customer/products/slug/:slug

Source: https://opencals.com/docs/api-reference/auth/customer-oauth-sign-in

Retrieve details for a specific product by URL slug.

```APIDOC
## GET /customer/products/slug/:slug

### Description
Get product by URL slug.

### Method
GET

### Endpoint
/customer/products/slug/:slug
```

--------------------------------

### GET /customer/orders/:id

Source: https://opencals.com/docs/api-reference/orders/list-customer-orders

Get order details.

```APIDOC
## GET /customer/orders/:id

### Description
Get order details.

### Method
GET

### Endpoint
/customer/orders/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the order.
```

--------------------------------

### GET /storefront/add-ons/:id

Source: https://opencals.com/docs/api-reference/auth/customer-oauth-sign-in

Get an add-on by its ID.

```APIDOC
## GET /storefront/add-ons/:id

### Description
Get add-on by ID.

### Method
GET

### Endpoint
/storefront/add-ons/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the add-on.
```

--------------------------------

### Initialize Storefront SDK

Source: https://opencals.com/docs/guides/storefront-sdk

Configure the SDK at application startup. Ensure the API key is kept secure by performing calls on the server.

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

setupOpencals({
  apiKey: "sfk_…",          // or set the OPENCALS_API_KEY env var
  baseUrl: "https://…",     // optional, defaults to https://api.opencals.com
  logging: true,            // optional request/response logging
  errorHandler: true,       // throw OpencalsApiError on failures (default)
  customerToken: "eyJ…",    // optional customer JWT for authenticated requests
});
```

--------------------------------

### GET /customer/cart

Source: https://opencals.com/docs/api-reference/auth/customer-oauth-sign-in

Get the current shopping cart details.

```APIDOC
## GET /customer/cart

### Description
Get current cart.

### Method
GET

### Endpoint
/customer/cart
```

--------------------------------

### POST /customer/cart/checkout/start

Source: https://opencals.com/docs/api-reference/auth/customer-oauth-sign-in

Initialize the checkout process.

```APIDOC
## POST /customer/cart/checkout/start

### Description
Start checkout (initialize payment).

### Method
POST

### Endpoint
/customer/cart/checkout/start
```

--------------------------------

### GET /customer/products/:id/current-availabilities

Source: https://opencals.com/docs/api-reference/auth/customer-oauth-sign-in

Get bookable time slots for a specific date.

```APIDOC
## GET /customer/products/:id/current-availabilities

### Description
Get bookable time slots for a date.

### Method
GET

### Endpoint
/customer/products/:id/current-availabilities

### Parameters
#### Query Parameters
- **date** (string) - Required - Date in YYYY-MM-DD format
- **locationId** (string) - Optional - Filter by location
- **staffMemberId** (string) - Optional - Filter by staff member
- **timezone** (string) - Optional - Timezone for date/time calculations
```

--------------------------------

### Fetch products and availability using ProductService

Source: https://opencals.com/docs/guides/storefront-sdk

Demonstrates retrieving a product by slug and checking its availability for a specific date and timezone.

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

// GET /storefront/products/slug/{slug}
const { data: product } = await ProductService.getBySlug({
  path: { slug: "haircut" },
});

// GET /storefront/products/{productId}/current-availabilities
const { data: slots } = await ProductService.getCurrentAvailabilities({
  path: { productId: product!.id },
  query: { date: "2026-06-15", timezone: "America/New_York" },
});
```

--------------------------------

### GET /customer/appointments/:id

Source: https://opencals.com/docs/api-reference/appointments/list-customer-appointments

Get appointment details by ID. Requires a customer token.

```APIDOC
## GET /customer/appointments/:id

### Description
Get appointment details.

### Method
GET

### Endpoint
/customer/appointments/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the appointment.
```

--------------------------------

### SDK Service Usage

Source: https://opencals.com/docs/guides/storefront-sdk

Demonstrates how to invoke service methods using the options object pattern for path and query parameters.

```APIDOC
## SDK Service Method Invocation

### Description
Methods are called via static service classes. Each method accepts a single options object with `path`, `query`, `body`, and `headers` fields.

### Usage Example
```ts
import { ProductService } from "@opencals/storefront-sdk";

// GET /storefront/products/slug/{slug}
const { data: product } = await ProductService.getBySlug({
  path: { slug: "haircut" },
});

// GET /storefront/products/{productId}/current-availabilities
const { data: slots } = await ProductService.getCurrentAvailabilities({
  path: { productId: product!.id },
  query: { date: "2026-06-15", timezone: "America/New_York" },
});
```
```

--------------------------------

### GET /customer/products/:id/current-availability-ranges

Source: https://opencals.com/docs/api-reference/auth/customer-oauth-sign-in

Get available date ranges for custom duration products.

```APIDOC
## GET /customer/products/:id/current-availability-ranges

### Description
Get available date ranges (for custom duration).

### Method
GET

### Endpoint
/customer/products/:id/current-availability-ranges

### Parameters
#### Query Parameters
- **timezone** (string) - Optional - Timezone for date/time calculations
```

--------------------------------

### POST /storefront/auth/sign-up

Source: https://opencals.com/docs/api-reference/auth/register-a-new-customer

Create a new customer account on the storefront and send a verification email.

```APIDOC
## POST /storefront/auth/sign-up

### Description
Create a new customer account on the storefront and send a verification email.

### Method
POST

### Endpoint
/storefront/auth/sign-up

### Request Body
- **email** (string) - Required - Customer email
- **password** (string) - Required - Customer password (min 8 chars)
- **firstName** (string) - Optional - First name
- **lastName** (string) - Optional - Last name

### Request Example
{
  "email": "user@example.com",
  "password": "password123",
  "firstName": "John",
  "lastName": "Doe"
}

### Response
#### Success Response (204)
- No content returned
```

--------------------------------

### POST /auth/customer/sign-up

Source: https://opencals.com/docs/api-reference/auth/register-a-new-customer

Registers a new customer account on the storefront and sends a verification email.

```APIDOC
## POST /auth/customer/sign-up

### Description
Registers a new customer account on the storefront. This action triggers a verification email to the provided address.

### Method
POST

### Endpoint
/auth/customer/sign-up
```

--------------------------------

### Use SDK utility helpers

Source: https://opencals.com/docs/guides/storefront-sdk

Access built-in utilities for price formatting, duration formatting, and timezone conversions.

```ts
import {
  formatPrice,
  formatDuration,
  toLocalFromUtc,
  toUtcFromLocal,
  mergeTimeIntervals,
} from "@opencals/storefront-sdk";

formatPrice(4500, "USD");                              // "$45.00"
formatDuration(3600);                                  // "1h"
toLocalFromUtc("2026-06-15T14:00:00Z", "America/New_York");
```

--------------------------------

### OpenAPI Specification for Get Appointment by ID

Source: https://opencals.com/docs/api-reference/appointments/get-appointment-by-id

The OpenAPI definition for the GET request to retrieve appointment details, including path parameters and response schema.

```yaml
  version: '1.0'
  contact: {}
servers:
  - url: https://api.opencals.com
security:
  - Storefront API key: []
tags: []
paths:
  /storefront/appointments/{appointmentId}:
    get:
      tags:
        - Appointments
      summary: Get appointment by ID
      description: Returns a single appointment by ID for the authenticated customer
      operationId: appointment_find
      parameters:
        - name: appointmentId
          required: true
          in: path
          description: Appointment unique identifier
          schema:
            example: 123e4567-e89b-12d3-a456-426614174000
            type: string
      responses:
        '200':
          description: The appointment details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppointmentDetailResponse'
      security:
        - bearer: []
```

--------------------------------

### OpenAPI Specification for Get Appointment by External Order Name

Source: https://opencals.com/docs/api-reference/appointments/get-appointment-by-external-order-name

The OpenAPI definition for the GET request to retrieve appointment details by external order name.

```yaml
  version: '1.0'
  contact: {}
servers:
  - url: https://api.opencals.com
security:
  - Storefront API key: []
tags: []
paths:
  /storefront/appointments/by-external-order-name/{externalOrderName}:
    get:
      tags:
        - Appointments
      summary: Get appointment by external order name
      description: >-
        Returns a single appointment by its external order name. Useful for
        integrations with external payment or ordering systems.
      operationId: appointment_findByExternalOrderName
      parameters:
        - name: externalOrderName
          required: true
          in: path
          description: External order name identifier
          schema:
            example: order_123456789
            type: string
      responses:
        '200':
          description: The appointment details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppointmentDetailResponse'
      security:
        - bearer: []
```

--------------------------------

### POST /customer/cart/checkout/start

Source: https://opencals.com/docs/api-reference/auth/customer-oauth-sign-in

Initiates the checkout process for a customer.

```APIDOC
## POST /customer/cart/checkout/start

### Description
Starts the checkout process for a given cart.

### Method
POST

### Endpoint
/customer/cart/checkout/start

### Parameters
#### Request Body
- **provider** (string) - Required - Payment provider (e.g., stripe, cash)
- **customer** (object) - Required - Customer details including email, firstName, and lastName

### Request Example
{
  "provider": "stripe",
  "customer": {
    "email": "john@example.com",
    "firstName": "John",
    "lastName": "Smith"
  }
}
```

--------------------------------

### GET /customer/locations

Source: https://opencals.com/docs/api-reference/auth/customer-oauth-sign-in

List all locations.

```APIDOC
## GET /customer/locations

### Description
List all locations.

### Method
GET

### Endpoint
/customer/locations
```

--------------------------------

### Initialize Opencals SDK

Source: https://opencals.com/docs/guides/build-a-booking-page

Configure the SDK with your API key in a server-side module.

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

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

--------------------------------

### GET /customer/staff-members

Source: https://opencals.com/docs/api-reference/auth/customer-oauth-sign-in

List all staff members.

```APIDOC
## GET /customer/staff-members

### Description
List staff members.

### Method
GET

### Endpoint
/customer/staff-members
```

--------------------------------

### POST /customer/cart/checkout/start

Source: https://opencals.com/docs/api-reference/auth/customer-oauth-sign-in

Initiates the checkout process for the current cart.

```APIDOC
## POST /customer/cart/checkout/start

### Description
Starts the checkout process. Returns payment provider details such as a clientSecret for Stripe.

### Method
POST

### Endpoint
/customer/cart/checkout/start

### Parameters
#### Request Body
- **provider** (string) - Required - Payment provider (e.g., "stripe", "cash")
- **customer** (object) - Required - Customer details including email, firstName, and lastName

### Request Example
{
  "provider": "stripe",
  "customer": { "email": "john@example.com", "firstName": "John", "lastName": "Smith" }
}
```

--------------------------------

### POST /auth/customer/sign-in

Source: https://opencals.com/docs/api-reference/auth/customer-sign-in-with-credentials

Authenticates a customer with their email and password. Requires the Storefront API Key in the header.

```APIDOC
## POST /auth/customer/sign-in

### Description
Authenticates a storefront customer using their email and password. Returns access and refresh tokens.

### Method
POST

### Endpoint
/auth/customer/sign-in

### Parameters
#### Request Body
- **email** (string) - Required - The customer's email address.
- **password** (string) - Required - The customer's password.

### Request Example
{
  "email": "customer@example.com",
  "password": "securepassword"
}

### Response
#### Success Response (200)
- **accessToken** (string) - JWT access token for authenticated requests.
- **refreshToken** (string) - JWT refresh token.

#### Response Example
{
  "accessToken": "eyJhbGciOi...",
  "refreshToken": "eyJhbGciOi..."
}
```

--------------------------------

### GET /customer/orders

Source: https://opencals.com/docs/api-reference/orders/list-customer-orders

List customer orders (paginated).

```APIDOC
## GET /customer/orders

### Description
List customer orders (paginated).

### Method
GET

### Endpoint
/customer/orders
```

--------------------------------

### GET /customer/locations

Source: https://opencals.com/docs/api-reference/auth/customer-oauth-sign-in

List all locations in a paginated format.

```APIDOC
## GET /customer/locations

### Description
List all locations (paginated).

### Method
GET

### Endpoint
/customer/locations
```

--------------------------------

### Create Cart and Add Items

Source: https://opencals.com/docs/api-reference/auth/customer-oauth-sign-in

Initializes a new cart and adds an appointment item to it using the cart ID.

```json
POST /customer/cart

→ Returns { "id": "cart-uuid", ... }


POST /customer/cart/items

X-Cart-Id: cart-uuid

{ "appointmentId": "appointment-uuid" }
```

--------------------------------

### GET /storefront/orders

Source: https://opencals.com/docs/api-reference/orders/list-customer-orders

Returns all orders for the authenticated customer with pagination.

```APIDOC
## GET /storefront/orders

### Description
Returns all orders for the authenticated customer with pagination.

### Method
GET

### Endpoint
/storefront/orders
```

--------------------------------

### Sign In Customer

Source: https://opencals.com/docs/authentication

Exchange credentials for an access and refresh token pair.

```bash
curl -X POST "https://api.opencals.com/storefront/auth/sign-in" \
  -H "X-Api-Key: sfk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
      "email": "customer@example.com",
      "password": "securepassword"
    }'
```

```json
{
    "accessToken": "eyJhbGciOi…",
    "refreshToken": "eyJhbGciOi…"
  }
```

--------------------------------

### GET /customer/payment/providers

Source: https://opencals.com/docs/api-reference/auth/customer-oauth-sign-in

Fetches available payment providers for the store.

```APIDOC
## GET /customer/payment/providers

### Description
Retrieves a list of configured payment providers.

### Method
GET

### Endpoint
/customer/payment/providers
```

--------------------------------

### Manage the booking cart

Source: https://opencals.com/docs/guides/build-a-booking-page

Initialize or retrieve a cart using the X-Cart-Id header, then add the created appointment to it.

```typescript
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 },
});
```

--------------------------------

### GET /customer/staff-members

Source: https://opencals.com/docs/api-reference/auth/customer-oauth-sign-in

List all staff members in a paginated format.

```APIDOC
## GET /customer/staff-members

### Description
List all staff members (paginated).

### Method
GET

### Endpoint
/customer/staff-members
```
Tokens:
Raw