Recurring blocks

When to use

Predictable closures — “Every Friday 3pm–5pm,” “first Monday of the month,” or “closed all day on the 15th every month.”
Holidays and maintenance that repeat on a structured schedule (this API uses explicit fields, not RFC 5545 RRULE strings).
Parity with the dashboard — the merchant portal Availability tab uses the same recurring-block REST APIs documented here (see the public changelog).

All routes require verifyToken and verifyCompany (same auth model as other protected /v3/* endpoints).

Base path

/v3/unavailability/recurringBlock

Endpoints

Method	Path	Purpose
`GET`	`/v3/unavailability/recurringBlock`	List recurring rules for exactly one of `LocationId`, `ResourceId`, or `ServiceId` (query)
`GET`	`/v3/unavailability/recurringBlock/:id`	Fetch one rule by UUID
`POST`	`/v3/unavailability/recurringBlock`	Create a rule (body JSON); scope via query: exactly one of `LocationId`, `ResourceId`, `ServiceId`
`PUT`	`/v3/unavailability/recurringBlock/:id`	Update a rule (partial body allowed in validation)
`DELETE`	`/v3/unavailability/recurringBlock`	Delete all rules matching the query scope (exactly one of the three IDs)
`DELETE`	`/v3/unavailability/recurringBlock/:id`	Delete one rule by UUID

See the API reference for full schemas (CreateRecurringBlock, UpdateRecurringBlock, RecurringBlock).

Scope rule

For POST (create), GET (list), and DELETE (bulk): provide exactly one of LocationId, ResourceId, or ServiceId — as query parameters on POST/GET/DELETE /.

Create (`POST`) — required and optional fields

Body — schema CreateRecurringBlock in the API reference:

Field	Required	Notes
`frequency`	Yes	`DAILY`, `WEEKLY`, `BIWEEKLY`, `MONTHLY`, or `YEARLY`
`interval`	Yes	Integer ≥ `1` — repeat every n periods (e.g. `2` with `WEEKLY` = every two weeks)
`startDate`	Yes	Date the rule starts (ISO date string)
`startTime`, `endTime`	Yes	Wall-clock times `HH:MM:SS` (24-hour); must match the military-time pattern enforced by the API
`name`	No	Defaults to `Untitled`
`endDate`	No	Optional end of the rule
`daysOfWeek`	No	For `WEEKLY` / `BIWEEKLY`: comma-separated integers `0`–`6` (typically Sunday=`0` through Saturday=`6`)
`dayOfMonth`	No	For `MONTHLY`: `1`–`31`
`iana`	No	IANA timezone override (e.g. `America/New_York`, `UTC`). When omitted, the engine uses the linked location, resource, service, or company default

iana and DST: persisted rules store iana with wall-clock startTime / endTime; expansions respect DST and fractional UTC offsets. Availability and calendar queries share this behavior.

Frequency semantics (high level)

DAILY — Repeats every interval day(s) from startDate between startTime and endTime.
WEEKLY — Repeats on the weekdays listed in daysOfWeek every interval week(s).
BIWEEKLY — Same as weekly but stepped every two weeks when interval is 1 (combine with interval for “every four weeks,” etc.).
MONTHLY — Repeats on dayOfMonth each month (and interval can step months if used).
YEARLY — Repeats annually on the month and day derived from startDate (dashboard behavior: yearly uses the anniversary of the start date).

Structured recurrence only — not arbitrary RRULE strings.

Examples (illustrative JSON bodies)

Use query ?LocationId=<uuid> or ResourceId / ServiceId on POST as required.

Daily lunch closure:

{
  "name": "Lunch",
  "frequency": "DAILY",
  "interval": 1,
  "startDate": "2025-06-01",
  "endDate": "2025-12-31",
  "startTime": "12:00:00",
  "endTime": "13:00:00",
  "iana": "America/Chicago"
}

Weekly on Tuesday and Thursday:

{
  "frequency": "WEEKLY",
  "interval": 1,
  "startDate": "2025-06-01",
  "startTime": "15:00:00",
  "endTime": "17:00:00",
  "daysOfWeek": "2,4"
}

Monthly on the 15th:

{
  "frequency": "MONTHLY",
  "interval": 1,
  "startDate": "2025-01-15",
  "startTime": "09:00:00",
  "endTime": "17:00:00",
  "dayOfMonth": 15
}

Yearly (anniversary of startDate):

{
  "frequency": "YEARLY",
  "interval": 1,
  "startDate": "2025-07-04",
  "startTime": "00:00:00",
  "endTime": "23:59:59"
}

Update and delete

PUT /v3/unavailability/recurringBlock/:id — Send only fields to change; partial updates are allowed for optional body fields.
DELETE /v3/unavailability/recurringBlock/:id — Remove one rule.
DELETE /v3/unavailability/recurringBlock?LocationId=… (or ResourceId / ServiceId) — Remove all rules for that entity scope.