Handling Blackouts & Exceptions¶

This guide is for Operators and Partners who need to manage irregular schedule changes (Exceptions).

What are Exceptions?¶

Exceptions are one-off changes that override the standard Template. Each exception applies to a single day and can be either:

Blackout (UNAVAILABLE): Closes a service for maintenance, holidays, or staff illness.
Extra Availability (AVAILABLE): Opens a service on a day it is usually closed (e.g., a special event Sunday).

Full-Day vs Time-Range¶

Each exception can be:

Full day: Blocks or opens the entire day (no time range needed).
Time range: Blocks or opens a specific time window on that day (e.g., 14:00–18:00).

Batch Exceptions¶

When you need to block or open multiple days (e.g., a holiday week), use batch creation. This creates one exception per day, grouped by a shared batch_id. Batches can be deleted together in one operation.

Prioritization Rules¶

The Availability Engine calculates schedules in this order of priority:

Exceptions (Highest Priority)
Service Rules (Custom overrides)
Template Rules (Base schedule)

This means if a Template says "Open Monday 9–5", but you create a Blackout Exception for a specific Monday, the service will be Closed that day.

Managing Exceptions¶

Via Partner Console¶

Exceptions can be managed directly from the Partner Console in both: - Template editing — add exceptions that apply to all services using that template - Service management — add exceptions that apply to a specific service

Both support single-day and batch (date range) creation.

Via API¶

Create a Single Exception¶

POST /exceptions

{
  "scope": "SERVICE",
  "partner_id": "uuid",
  "service_id": "uuid",
  "reason": "Christmas Holiday",
  "availability_type": "UNAVAILABLE",
  "is_full_day": true,
  "exception_date": "2026-12-25"
}

Create a Time-Range Exception¶

{
  "scope": "SERVICE",
  "partner_id": "uuid",
  "service_id": "uuid",
  "reason": "Afternoon maintenance",
  "availability_type": "UNAVAILABLE",
  "is_full_day": false,
  "exception_date": "2026-12-20",
  "start_time": "14:00",
  "end_time": "18:00"
}

Create a Batch (Multiple Days)¶

POST /exceptions/batch

{
  "scope": "SERVICE",
  "partner_id": "uuid",
  "service_id": "uuid",
  "reason": "Holiday week",
  "availability_type": "UNAVAILABLE",
  "is_full_day": true,
  "dates": ["2026-12-23", "2026-12-24", "2026-12-25", "2026-12-26"]
}

This creates 4 individual exceptions with a shared batch_id.

Delete a Batch¶

DELETE /exceptions/batch/:batchId

Removes all exceptions in the batch at once.