> ## Documentation Index
> Fetch the complete documentation index at: https://opencals.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Attributes

> Attach arbitrary key-value data to appointments at booking time. Storefront SDK v0.3.11.

<Update label="August 1, 2026" tags={["New feature", "SDK v0.3.11"]}>
  ## Custom attributes on appointments

  Custom booking frontends can now attach arbitrary data to an appointment at
  creation time — a booking source, a party size, an external reference id, or
  small JSON strings. Custom attributes are a flat map of string keys to
  string values (the same idea as Shopify order note/custom attributes): no data
  types, no access rules, not searchable — just a simple bag of key-value pairs
  that travels with the appointment.

  **What's in the release:**

  * `POST /storefront/appointments` accepts an optional `customAttributes` object —
    a map of string keys to string values.
  * Appointment responses now echo `customAttributes`.
  * The merchant dashboard shows custom attributes on the appointment detail page.

  **Key behaviors:**

  * Keys and values are always strings (a value can itself be a JSON string — it is
    stored verbatim and never parsed).
  * Limits: up to **250** attributes per appointment, keys up to **255** characters,
    values up to **5000** characters.
  * Not searchable by design — attributes are stored inline with the appointment for
    fast reads, not indexed for querying.

  **SDK support** — available in `@opencals/storefront-sdk`
  [v0.3.11](/docs/changelog/storefront-sdk) and higher. `CreateAppointment` gains an
  optional `customAttributes` field.

  ```bash theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
  # Create an appointment with custom attributes
  curl -X POST -H "X-Api-Key: sfk_your_key" \
    -H "Content-Type: application/json" \
    -d '{
      "slot": { "fromDate": "2026-08-15", "fromTime": "10:00:00", "toDate": "2026-08-15", "toTime": "11:00:00", "productId": "..." },
      "customAttributes": { "source": "widget", "party_size": "4" }
    }' \
    https://api.opencals.com/storefront/appointments
  ```
</Update>