Blackout Dates

Block off dates when the business is closed — holidays, vacations, renovations. The availability engine excludes any slot that falls within a blackout range.

Public Endpoint

GET /v1/public/blackout-dates/{business_id}

Returns all future and ongoing blackout dates. No auth required.

curl https://api.availengine.com/v1/public/blackout-dates/{business_id}

Response:

[
  {
    "start_date": "2026-08-01",
    "end_date": "2026-08-15",
    "reason": "Summer holiday"
  },
  {
    "start_date": "2026-12-24",
    "end_date": "2026-12-26",
    "reason": "Christmas closure"
  }
]

Only returns blackouts where end_date >= today, ordered by start_date.

Management Endpoints

GET /v1/manage/blackout-dates

List all blackout dates. Cursor-paginated, ordered by start_date.

curl https://api.availengine.com/v1/manage/blackout-dates \
  -H "Authorization: Bearer avail_live_YOUR_KEY"

Response:

{
  "items": [
    {
      "id": "uuid",
      "start_date": "2026-08-01",
      "end_date": "2026-08-15",
      "reason": "Summer holiday",
      "is_full_day": true,
      "created_at": "2026-05-01T10:00:00Z"
    }
  ],
  "next_cursor": null,
  "has_more": false
}

POST /v1/manage/blackout-dates

Create a blackout date range.

curl -X POST https://api.availengine.com/v1/manage/blackout-dates \
  -H "Authorization: Bearer avail_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "start_date": "2026-08-01",
    "end_date": "2026-08-15",
    "reason": "Summer holiday"
  }'

Field	Type	Required	Description
start_date	date	Yes	First day of closure (inclusive)
end_date	date	Yes	Last day of closure (inclusive)
reason	string	No	Displayed on public page

end_date must be >= start_date.

PATCH /v1/manage/blackout-dates/{blackout_id}

Update a blackout's date range or reason.

curl -X PATCH https://api.availengine.com/v1/manage/blackout-dates/{blackout_id} \
  -H "Authorization: Bearer avail_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "end_date": "2026-08-20",
    "reason": "Extended summer closure"
  }'

All fields are optional — only send what changed.

DELETE /v1/manage/blackout-dates/{blackout_id}

Remove a blackout. Returns 204 No Content.

curl -X DELETE https://api.availengine.com/v1/manage/blackout-dates/{blackout_id} \
  -H "Authorization: Bearer avail_live_YOUR_KEY"

How Blackouts Affect Availability

When the availability engine checks a date:

1. It queries blackout_dates for any row where start_date <= booking_date <= end_date
2. If a match is found, returns zero available slots — the entire day is blocked
3. This check runs before operating hours, so it overrides the weekly schedule

vs. Blocked Slots (Google Calendar)

	Blackout Dates	Blocked Slots
Source	Manually set by staff	Imported from Google Calendar
Granularity	Full day	Specific time range
Management	Direct CRUD	Synced automatically
Resource scoping	Business-wide	Per-resource

A blackout blocks the entire business. A blocked slot blocks a specific resource for a specific time window. Use blackouts for holidays, blocked slots for when a specific staff member has a personal appointment.

Learn about Google Calendar integration →