### 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/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
```

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

### 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
```

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

### 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.
```

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

### 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.
```

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

### 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"
  }
}
```

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

### 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
```

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

### 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
```

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

### 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
```

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

### 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
```

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

### 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.
```

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

### 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"
  }
}
```

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

### Submit Checkout Response

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

Example response structure containing order details and authentication tokens.

```json
{
  "order": { "id": "...", "name": "#1001", ... },
  "tokens": {
    "accessToken": "eyJ...",
    "refreshToken": "eyJ..."
  }
}
```

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

### 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")
```

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

### 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: []
```

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

### Initialize checkout

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

Start the checkout process by specifying a payment provider, which returns either a client secret for Stripe or a redirect URL for other providers.

```ts
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
```

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

### 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/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
```

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

### 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/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
```

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

### 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
```

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

### 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
```

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

### GET /customer/profile

Source: https://opencals.com/docs/api-reference/self-service/get-current-customer-profile

Retrieves the current customer's profile information.

```APIDOC
## GET /customer/profile

### Description
Retrieves the profile details for the currently authenticated customer.

### Method
GET

### Endpoint
/customer/profile
```

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

### OpenAPI Specification for List Customer Appointments

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

The YAML definition for the /storefront/appointments GET endpoint, including request parameters and response schema.

```yaml
  version: '1.0'
  contact: {}
servers:
  - url: https://api.opencals.com
security:
  - Storefront API key: []
tags: []
paths:
  /storefront/appointments:
    get:
      tags:
        - Appointments
      summary: List customer appointments
      description: Returns all appointments for the authenticated customer with pagination
      operationId: appointment_list
      parameters:
        - name: page
          required: false
          in: query
          description: Page number for pagination
          schema:
            minimum: 1
            default: 1
            example: 1
            type: number
        - name: take
          required: false
          in: query
          description: Number of items to return per page. Maximum allowed value is 100.
          schema:
            minimum: 1
            maximum: 100
            default: 50
            example: 50
            type: number
        - name: status
          required: false
          in: query
          description: List of appointment status types to filter by
          schema:
            example:
              - scheduled
              - completed
            type: array
            items:
              type: string
              enum:
                - pending
                - scheduled
                - completed
                - canceled
        - name: staffMembers
          required: false
          in: query
          description: List of staff member IDs to filter by
          schema:
            example:
              - 123e4567-e89b-12d3-a456-426614174000
            type: array
            items:
              type: string
        - name: products
          required: false
          in: query
          description: List of product/service IDs to filter by
          schema:
            example:
              - 123e4567-e89b-12d3-a456-426614174000
            type: array
            items:
              type: string
        - name: locations
          required: false
          in: query
          description: List of location IDs to filter by
          schema:
            example:
              - 123e4567-e89b-12d3-a456-426614174000
            type: array
            items:
              type: string
        - name: date
          required: false
          in: query
          description: Date to filter appointments by in YYYY-MM-DD format
          schema:
            pattern: \d{4}\-(0[1-9]|1[012])\-(0[1-9]|[12][0-9]|3[01])
            example: '2025-06-08'
            type: string
        - name: orderBy
          required: false
          in: query
          description: Field to order the results by
          schema:
            example: from
            enum:
              - from
              - to
              - productId
              - staffMemberId
              - customerId
              - createdAt
            type: string
        - name: order
          required: false
          in: query
          description: Sort direction
          schema:
            default: ASC
            example: DESC
            enum:
              - ASC
              - DESC
            type: string
        - name: limit
          required: false
          in: query
          description: Number of items per page
          schema:
            type: number
      responses:
        '200':
          description: Collection of customer appointments
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AppointmentListItemResponse'
                  meta:
                    $ref: '#/components/schemas/CollectionMeta'
      security:
        - bearer: []
components:
  schemas:
    AppointmentListItemResponse:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the appointment
          example: 123e4567-e89b-12d3-a456-426614174000
        name:
          type: string
          description: >-
            Generated appointment name for the user (starts at 1001 and
            increments)
          example: '1001'
        productId:
          type: string
          description: ID of the service/product for this appointment
          example: 123e4567-e89b-12d3-a456-426614174001
        staffMemberId:
          type: string
          description: ID of the staff member assigned to this appointment (if any)
          example: 123e4567-e89b-12d3-a456-426614174002
          nullable: true
        locationId:
```

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

### GET /customer/appointments/preferences/booking-history

Source: https://opencals.com/docs/api-reference/appointments/get-customer-booking-preferences

Retrieves the booking preferences and history for the authenticated customer.

```APIDOC
## GET /customer/appointments/preferences/booking-history

### Description
Retrieves the booking preferences and history for the authenticated customer.

### Method
GET

### Endpoint
/customer/appointments/preferences/booking-history
```

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

### GET /storefront/self-service/profile

Source: https://opencals.com/docs/api-reference/self-service/get-current-customer-profile

Retrieves the profile details for the currently authenticated customer.

```APIDOC
## GET /storefront/self-service/profile

### Description
Retrieves the profile information for the currently authenticated customer. This request requires a valid customer access token in the Authorization header and the Storefront API Key in the X-Api-Key header.

### Method
GET

### Endpoint
/storefront/self-service/profile

### Headers
- **Authorization** (string) - Required - Bearer <customer_access_token>
- **X-Api-Key** (string) - Required - sfk_your_key_here
```

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

### GET /storefront/appointments

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

Returns all appointments for the authenticated customer with pagination and filtering capabilities.

```APIDOC
## GET /storefront/appointments

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

### Method
GET

### Endpoint
/storefront/appointments

### Parameters
#### Query Parameters
- **page** (number) - Optional - Page number for pagination. Default: 1.
- **take** (number) - Optional - Number of items to return per page. Maximum allowed value is 100. Default: 50.
- **status** (array) - Optional - List of appointment status types to filter by (pending, scheduled, completed, canceled).
- **staffMembers** (array) - Optional - List of staff member IDs to filter by.
- **products** (array) - Optional - List of product/service IDs to filter by.
- **locations** (array) - Optional - List of location IDs to filter by.
- **date** (string) - Optional - Date to filter appointments by in YYYY-MM-DD format.
- **orderBy** (string) - Optional - Field to order the results by (from, to, productId, staffMemberId, customerId, createdAt).
- **order** (string) - Optional - Sort direction (ASC, DESC). Default: ASC.
- **limit** (number) - Optional - Number of items per page.

### Response
#### Success Response (200)
- **data** (array) - Collection of appointment items.
- **meta** (object) - Collection metadata.
```

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

### 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
```

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

### Example Paginated Response

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

The structure of a successful response containing service data and pagination metadata.

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

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

### Combined Availability Query

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

Example of applying multiple filters including location, staff, and timezone to an availability request.

```http
GET /customer/products/:id/current-availabilities
    ?date=2026-06-15
    &locationId=<locationId>
    &staffMemberId=<staffMemberId>
    &timezone=America/New_York
```

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

### Standard JSON Response Format

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

Example of the standard camelCase JSON response structure.

```json
{
  "id": "abc-123",
  "title": "Haircut",
  "maxAttendees": 1,
  "duration": 3600,
  "staffMembers": [
    { "id": "staff-1", "firstName": "John", "lastName": "Doe" }
  ]
}
```

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

### GET /storefront/appointments/{appointmentId}

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

Retrieves a single appointment by its ID for the authenticated customer.

```APIDOC
## GET /storefront/appointments/{appointmentId}

### Description
Returns a single appointment by ID for the authenticated customer.

### Method
GET

### Endpoint
/storefront/appointments/{appointmentId}

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

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

### OpenAPI Schema Definitions

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

Schema definitions for appointment-related objects including properties, types, and example values.

```yaml
        refreshToken:
          type: string
          description: Customer refresh token for authentication
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
          nullable: true
          writeOnly: true
        createdAt:
          format: date-time
          type: string
          description: Date when the customer record was created
          example: '2023-01-15T10:30:00Z'
        updatedAt:
          format: date-time
          type: string
          description: Date when the customer record was last updated
          example: '2023-02-20T14:15:00Z'
          nullable: true
        emailVerifiedAt:
          format: date-time
          type: string
          description: Date and time when the customer verified email
          example: '2023-01-02T00:00:00Z'
          nullable: true
        deletedAt:
          format: date-time
          type: string
          description: Date and time when the order was soft-deleted
          example: '2023-06-03T09:45:00Z'
          nullable: true
        isEmailVerified:
          type: boolean
          description: Indicates whether customer email is verified
        isPasswordSet:
          type: boolean
          description: Indicates whether customer password is set
      required:
        - id
        - externalId
        - firstName
        - lastName
        - email
        - phone
        - companyName
        - companyVatNumber
        - password
        - storeId
        - language
        - refreshToken
        - createdAt
        - updatedAt
        - emailVerifiedAt
        - deletedAt
        - isEmailVerified
        - isPasswordSet
    AppointmentDetailAddOn:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier
        appointmentId:
          type: string
          description: Appointment ID
        addOnId:
          type: string
          description: Add-on ID
        quantity:
          type: number
          description: Quantity of this add-on for the appointment
          default: 1
        createdAt:
          format: date-time
          type: string
          description: Created at timestamp
        addOn:
          description: The add-on details
          allOf:
            - $ref: '#/components/schemas/AppointmentDetailAddOnItem'
      required:
        - id
        - appointmentId
        - addOnId
        - quantity
        - createdAt
        - addOn
    AppointmentDetailGuest:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier
        appointmentId:
          type: string
          description: Appointment ID
        email:
          type: string
          description: Guest email address
        createdAt:
          format: date-time
          type: string
          description: Created at timestamp
      required:
        - id
        - appointmentId
        - email
        - createdAt
    AppointmentDetailFeedbackAnswer:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the feedback question answer
          example: 123e4567-e89b-12d3-a456-426614174000
        appointmentId:
          type: string
          description: ID of the appointment this feedback relates to
          example: 123e4567-e89b-12d3-a456-426614174001
        questionId:
          type: string
          description: ID of the feedback question (set to null if question is deleted)
          example: 123e4567-e89b-12d3-a456-426614174002
          nullable: true
        question:
          type: string
          description: The feedback question text presented to the customer
          example: How would you rate the quality of service provided?
        answer:
          type: string
          description: Customer's answer to the feedback question
          example: The service was excellent, very professional and timely.
          nullable: true
        createdAt:
          format: date-time
          type: string
          description: Date and time when this feedback was recorded
          example: '2023-06-15T14:30:00Z'
        updatedAt:
          format: date-time
          type: string
          description: Date and time when this feedback was last updated
          example: '2023-06-15T15:45:00Z'
          nullable: true
        files:
          description: >-
            Files the customer uploaded for this answer (file-upload questions
            only)
          type: array
          items:
            $ref: '#/components/schemas/AppointmentDetailFeedbackAnswerFile'
      required:
        - id
        - appointmentId
        - questionId
        - question
        - answer
        - createdAt
        - updatedAt
        - files
    AppointmentDetailCheckoutAnswer:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the checkout question answer
```

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

### 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/appointments

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

Retrieves a paginated list of appointments for the currently authenticated customer.

```APIDOC
## GET /customer/appointments

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

### Method
GET

### Endpoint
/customer/appointments

### Authentication
Requires both the Storefront API Key in the `X-Api-Key` header and the customer's JWT token in the `Authorization: Bearer <token>` header.
```

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

### GET /storefront/auth/resolve-link

Source: https://opencals.com/docs/api-reference/auth/resolve-a-magic-link-token

Validates a magic link token to authenticate a customer and provides redirect details.

```APIDOC
## GET /storefront/auth/resolve-link

### Description
Validates a magic link token, authenticates the customer, and returns redirect information.

### Method
GET

### Endpoint
/storefront/auth/resolve-link
```

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

### 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
```

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

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

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

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

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

### 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
```

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

### GET /storefront/appointments/preferences/booking-history

Source: https://opencals.com/docs/api-reference/appointments/get-customer-booking-preferences

Retrieves frequently booked services, locations, and staff members for a customer based on their history.

```APIDOC
## GET /storefront/appointments/preferences/booking-history

### Description
Returns frequently booked services, locations, and staff members based on customer booking history. Results are cached for 24 hours to optimize performance.

### Method
GET

### Endpoint
/storefront/appointments/preferences/booking-history
```

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

### 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 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"
  }
}
```

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

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

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

### 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..."
}
```

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

### 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" }
```

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

### 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…"
  }
```

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

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

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

### Request with Pagination Parameters

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

Use page and take query parameters to control the size and offset of the returned collection.

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

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

### GET /customer/locations/slug/:slug

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

Retrieve a specific location by its slug.

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

### Description
Get location by slug.

### Method
GET

### Endpoint
/customer/locations/slug/:slug

### Parameters
#### Path Parameters
- **slug** (string) - Required - The URL-friendly slug of the location.
```

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

### GET /customer/locations/:id

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

Retrieve a specific location by its ID.

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

### Description
Get location by ID.

### Method
GET

### Endpoint
/customer/locations/:id

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

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

### Interact with Add-Ons via cURL

Source: https://opencals.com/docs/changelog/add-ons

Use these commands to list add-ons for a specific product or add an add-on to a cart item. Requires a valid API key and cart ID.

```bash
# List add-ons for a service
curl -H "X-Api-Key: sfk_your_key" \
  https://api.opencals.com/storefront/products/{productId}/add-ons

# Add to cart
curl -X POST -H "X-Api-Key: sfk_your_key" \
  -H "X-Cart-Id: {cartId}" \
  -H "Content-Type: application/json" \
  -d '{"cartItemId": "...", "addOnId": "...", "quantity": 1}' \
  https://api.opencals.com/storefront/cart/add-ons
```

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

### POST /storefront/auth/sign-in

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

Authenticates a storefront customer using email and password to receive access and refresh tokens.

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

### Description
Authenticate a storefront customer using email and password.

### Method
POST

### Endpoint
/storefront/auth/sign-in

### Request Body
- **tokenName** (string) - Optional - Unique key identifier for this authentication session (e.g., frontend identifier). Default: default.
- **storeId** (string) - Optional - Preferred store ID to scope the JWT to.
- **storeDomain** (string) - Optional - Preferred store domain to resolve store and scope the JWT to.
- **email** (string) - Required - Customer email.
- **password** (string) - Required - Customer password (min 8 chars).

### Request Example
{
  "tokenName": "web_app",
  "storeId": "store-uuid",
  "storeDomain": "my-store.myshopify.com",
  "email": "customer@example.com",
  "password": "password123"
}

### Response
#### Success Response (200)
- **accessToken** (string) - JWT access token for authenticating API requests.
- **refreshToken** (string) - JWT refresh token for obtaining new access tokens.

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

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

### Create an appointment

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

Use the AppointmentService to create a booking. Ensure all date/time values are converted to UTC before submission.

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

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

### GET /customer/cart/checkout/questions/:language

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

Retrieve checkout questions in a specific language.

```APIDOC
## GET /customer/cart/checkout/questions/:language

### Description
Get checkout questions.

### Method
GET

### Endpoint
/customer/cart/checkout/questions/:language

### Parameters
#### Path Parameters
- **language** (string) - Required - The language code for the questions.
```

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

### Authenticate with an API Key

Source: https://opencals.com/docs/api-reference/introduction

Include the X-Api-Key header in requests to authenticate against a specific store.

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

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

### GET /customer/staff-members/slug/:slug

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

Retrieve a specific staff member by their slug.

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

### Description
Get staff member by slug.

### Method
GET

### Endpoint
/customer/staff-members/slug/:slug

### Parameters
#### Path Parameters
- **slug** (string) - Required - The URL-friendly slug of the staff member.
```

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

### POST /customer/cart

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

Create or retrieve a shopping cart.

```APIDOC
## POST /customer/cart

### Description
Create or retrieve a cart.

### Method
POST

### Endpoint
/customer/cart
```

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

### Fetch and attach add-ons

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

Retrieve available add-ons for a product and attach selected items to a specific cart item.

```typescript
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
```

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

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

### POST /customer/cart/checkout/save-customer

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

Saves customer information to the cart if not provided during checkout start.

```APIDOC
## POST /customer/cart/checkout/save-customer

### Description
Saves customer details to the cart. For logged-in customers, provide the customerId.

### Method
POST

### Endpoint
/customer/cart/checkout/save-customer

### Parameters
#### Request Body
- **customer** (object) - Required - Customer details or customerId for existing users

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

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

### Implement Passwordless Login Flow

Source: https://opencals.com/docs/guides/customer-email-links

Demonstrates the two-step process of requesting a 6-digit login code and verifying it to receive authentication tokens. Codes expire after 5 minutes and allow 5 failed attempts.

```ts
// 1. Customer requests a code
await AuthService.requestLoginCode({
  body: { email: "customer@example.com" }
});
// Email is sent with 6-digit code

// 2. Customer enters the code
const { data: tokens } = await AuthService.verifyLoginCode({
  body: { email: "customer@example.com", code: "123456" }
});

// 3. Tokens are returned — sign them in
```

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

### Checkout Questions and Answers

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

Retrieves configured checkout questions and submits user answers.

```http
GET /customer/cart/checkout/questions/en

X-Cart-Id: cart-uuid

→ Returns array of questions with types (text, select, checkbox, etc.)


POST /customer/cart/checkout/save-answers

X-Cart-Id: cart-uuid

{ "answers": [{ "questionId": "...", "value": "..." }]}
```

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

### Resolve Authentication Link

Source: https://opencals.com/docs/guides/customer-email-links

Verify that the authentication service correctly returns the necessary tokens.

```javascript
AuthService.resolveLink
```