Calendar & Scheduling

Blocked Time Presets

A BlockedTimePreset captures the reusable metadata for a common kind of blocked time — for example "Lunch break" (30 min, "break"), "Treatment-room cleaning" (15 min, "cleaning"), or "Team meeting" (60 min, "meeting"). Operators pick a preset in the calendar UI to create a BlockedTime with the configured duration, type, label, and colour pre-filled.

get/shop/blocked-time-presets

List blocked-time presets

listBlockedTimePresets

Returns a paginated list of BlockedTimePresets at the given site, alphabetised by name. Use this to populate the preset picker in the operator calendar UI.

Requires the RESERVATIONS_VIEW permission on the site.

Query parameters

  • site_idstringrequired

    Filter results by the site they belong to

  • pageintegeroptional

    The page to retrieve results from

  • per_pageintegeroptional

    The number of results to return per page

Responses

  • 200

    A paginated list of BlockedTimePresets at the site.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

post/shop/blocked-time-presets

Create a blocked-time preset

createBlockedTimePreset

Creates a new BlockedTimePreset at the given site. Only name is required; the remaining fields configure the defaults that pre-fill a BlockedTime created from this preset.

Requires the SETTINGS_MANAGE permission on the site.

Query parameters

  • site_idstringrequired

    Filter results by the site they belong to

Request body

  • namestringrequired

    Display name. Plain text only.

  • durationintegeroptional

    Default duration in minutes (1..1200). Defaults to the site's calendar slot duration when omitted.

  • typestringoptional

    Default block type. Drives the calendar icon.

    Possible values:cleaningbreakmeetingother
  • labelstringoptionalnullable

    Default short label rendered on the calendar tile so staff can distinguish blocks at a glance (e.g. Lunch or Team meeting). Plain text only.

  • notesstringoptionalnullable

    Default free-form note (plain text) shown when staff click into a block created from this preset. Useful for extra context that doesn't fit on the label.

  • colorstringoptionalnullable

    Default hex colour override. Format #rrggbb, lower-case.

  • organisation_iduuidoptional

    Organisation that owns this preset. Defaults to the caller's default organisation. The caller must belong to the chosen organisation.

Responses

  • 201

    A single BlockedTimePreset.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 422

    The request didn't pass validation

get/shop/blocked-time-presets/{blockedTimePresetId}

Get a blocked-time preset

getBlockedTimePreset

Returns a single BlockedTimePreset by ID. Useful when editing the preset or copying its values into a one-off BlockedTime.

Requires the RESERVATIONS_VIEW permission on the preset's site.

Path parameters

Responses

  • 200

    A single BlockedTimePreset.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

put/shop/blocked-time-presets/{blockedTimePresetId}

Update a blocked-time preset

updateBlockedTimePreset

Updates an existing BlockedTimePreset. name is required; other fields fall back to their existing values when omitted.

Requires the SETTINGS_MANAGE permission on the preset's site.

Path parameters

Request body

  • namestringrequired

    Display name. Plain text only.

  • durationintegeroptional

    Default duration in minutes (1..1200).

  • typestringoptional

    Default block type used when a new blocked-time is created from this preset. Drives the calendar icon and the reporting category.

    Possible values:cleaningbreakmeetingother
  • labelstringoptionalnullable

    Default short label rendered on the calendar tile so staff can distinguish blocks at a glance. Plain text only.

  • notesstringoptionalnullable

    Default free-form note (plain text) shown when staff click into a block created from this preset.

  • colorstringoptionalnullable

    Default hex colour (#rrggbb).

Responses

  • 200

    A single BlockedTimePreset.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

  • 422

    The request didn't pass validation

delete/shop/blocked-time-presets/{blockedTimePresetId}

Delete a blocked-time preset

deleteBlockedTimePreset

Soft-deletes the preset. Already-created BlockedTimes are unaffected — deleting a preset only removes it from the picker UI. Use POST /shop/blocked-time-presets/{blockedTimePresetId}/restore to bring it back.

Requires the SETTINGS_MANAGE permission on the preset's site.

Path parameters

Responses

  • 204

    The preset was deleted successfully.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

post/shop/blocked-time-presets/{blockedTimePresetId}/copy

Copy a blocked-time preset

copyBlockedTimePreset

Duplicates an existing BlockedTimePreset into a new record with overridden name (required). Other fields fall back to the source preset's values unless overridden.

Requires the SETTINGS_MANAGE permission on the source preset's site.

Path parameters

Request body

  • namestringrequired

    Display name for the new preset.

  • durationintegeroptional

    Override the source duration.

  • typestringoptional

    Override the source block type.

    Possible values:cleaningbreakmeetingother
  • labelstringoptionalnullable

    Override the source label.

  • notesstringoptionalnullable

    Override the source notes.

  • colorstringoptionalnullable

    Override the source colour (#rrggbb).

Responses

  • 201

    A single BlockedTimePreset.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

  • 422

    The request didn't pass validation

post/shop/blocked-time-presets/{blockedTimePresetId}/restore

Restore a deleted blocked-time preset

restoreBlockedTimePreset

Restores a soft-deleted BlockedTimePreset so it appears in the picker again. Idempotent — restoring an already-live preset is a no-op.

Requires the SETTINGS_MANAGE permission on the preset's site.

Path parameters

Responses

  • 200

    A single BlockedTimePreset.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found