---
title: "Create a blocked time"
method: POST
path: "/shop/blocked-times"
tags: ["BlockedTimes"]
---

# Create a blocked time

`POST /shop/blocked-times`

Carves a window out of one or more resource calendars
(practitioners, rooms, or bookable areas). At least one of
`practitioner_ids`, `room_ids`, or `area_ids` must be non-empty.

If `recurrence.weekdays` is set, the server fans the block out
across matching weekdays within
`recurrence.date_from`..`recurrence.date_to` (max 366 days). The
first ~30 occurrences are created synchronously; the remainder
are queued via an async job.

Requires the `RESERVATIONS_MANAGE` permission on the site.

## Query parameters

- `site_id` string, required

## Request body

- object
  - `start_time` string, date-time, required — Start of the blocked window. ISO-8601, in the site's timezone.
  - `end_time` string, date-time, required — End of the blocked window. Must be strictly after `start_time`.
  - `type` 'cleaning' | 'break' | 'meeting' | 'other', required — The kind of block. Drives the calendar icon.
  - `label` string, nullable — Optional short label shown on the calendar tile.
  - `notes` string, nullable — Optional longer note (plain text).
  - `color` string, nullable — Optional hex colour override. Format `#rrggbb` (lower-case).
  - `practitioner_ids` string[] — Practitioners whose calendars should be blocked. Required unless `room_ids` or `area_ids` is provided.
  - `room_ids` string[] — Rooms to block. Required unless `practitioner_ids` or `area_ids` is provided.
  - `area_ids` string[] — Bookable areas to block. Required unless `practitioner_ids` or `room_ids` is provided.
  - `recurrence` BlockedTimeRecurrence — Optional recurrence configuration sent with a `BlockedTime` create request. When `weekdays` is non-empty, the server fans out copies of the blocked time across the matching weekdays in `date_from`..`date_to`. The configured range cannot exceed 366 days.
    - `weekdays` string[] — Weekdays the blocked time should repeat on. Empty/omitted disables recurrence.
    - `date_from` string, date, nullable — First day of the recurrence range (inclusive), in the site's timezone. Defaults to today when omitted. Must be today or later.
    - `date_to` string, date, nullable — Last day of the recurrence range (inclusive). Required when `weekdays` is set.

## Response `201`

A single `BlockedTime`.

- object
  - `data` BlockedTime, required — A `BlockedTime` carves a window out of one or more resource calendars (practitioners, rooms, or bookable areas) so they cannot be booked during that window. Use blocked times for breaks, cleaning, internal meetings, or any other reason an otherwise-available resource should be hidden from availability. At least one of `practitioner_ids`, `room_ids`, or `area_ids` must be non-empty — a blocked time always targets at least one resource.
    - `id` string, object-id, required — Unique identifier for the blocked time.
    - `start_time` string, date-time, required — Start of the blocked window. Stored as a date-time in the site's timezone.
    - `end_time` string, date-time, required — End of the blocked window. Must be strictly after `start_time`.
    - `type` 'cleaning' | 'break' | 'meeting' | 'other', required — The kind of block. Drives the icon shown on the operator calendar and acts as an audit aid.
    - `label` string, nullable — Optional short label shown on the calendar tile. Plain text only.
    - `notes` string, nullable — Optional longer note (free-form, plain text). Visible to operators on the calendar tile.
    - `color` string, nullable — Optional hex colour (`#RRGGBB`, lower-case) to override the default colour for this `type` on the calendar.
    - `practitioner_ids` string[], required — Practitioner calendars covered by this blocked time. May be empty if the block targets rooms or areas only.
    - `room_ids` string[], required — Room calendars covered by this blocked time. May be empty.
    - `area_ids` string[], required — Bookable-area calendars covered by this blocked time. May be empty.
    - `site_id` string, uuid, required — ID of the site this blocked time belongs to.
    - `organisation_id` string, uuid, required — ID of the organisation that owns this blocked time.

## Other responses

- `400` — The request failed.
- `401` — The user is unauthenticated
- `403` — The authenticated user does not have permission.
- `422` — The request didn't pass validation

---

[API](https://skmtc.dev/try/apis/trybe-api.md) · [All operations](https://skmtc.dev/try/apis/trybe-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/try/trybe-api/revisions/f37f92702da5/schema)