Set what happens on one date (admin, or manage_org_settings)

An upsert keyed on (company_id, special_date), so sending the same body twice is the same as sending it once.

An empty windows array means CLOSED, and it is the most common write this route takes. That is the opposite of what an empty book_company_hours means, and the two live inches apart: zero rows there means UNCLAMPED (every org is in that state until it saves hours), while here the row EXISTS, so [] is somebody deliberately saying "nothing". Closing a date is therefore NOT the same as DELETEing it, which returns the date to the ordinary week.

An endTime earlier than startTime runs past midnight (migration 0042) and is accepted: an 18:00 to 02:00 New Year's Eve is the single most likely row anyone writes here. Only a zero-length window is refused.

No replace-the-set function stands behind this, unlike the hours and service-period routes: one date is one row, so an upsert is already one statement and therefore one transaction. Gated to admin, or a staff login granted manage_org_settings (migration 0082).

Conflicts against existing, non-cancelled bookings on the date are checked live, unconditionally, the same findConflictingAppointments predicate POST /api/providers/{id}/availability-overrides already uses: does the booking fall inside one of the proposed windows. Reads book_reservations for a hospitality company and book_appointments for an appointments one, company-wide rather than per-provider, since this table has no provider column. A conflict refuses with 409 and nothing is written; resend with conflictAcknowledged: true to proceed anyway. Unlike the override route this never hard-blocks by role: every caller who can reach this route already holds manage_org_settings, so acknowledgment alone is the gate. The route never touches the conflicting bookings themselves: no auto-move, no auto-cancel, no auto-refund. Resolving each one is a separate, deliberate action from Bookings.

Response BodyCopy Anchor Link

curl -X POST "https://example.com/api/organization/special-hours" \  -H "Content-Type: application/json" \  -d '{    "date": "2019-08-24"  }'

{  "ok": true,  "date": {    "special_date": "2019-08-24",    "windows": [      {        "startTime": "string",        "endTime": "string"      }    ],    "label": "string",    "holiday_name": "string"  }}