Skip to main content
A special-hours rule gives dated opening hours that replace the weekly hours on those dates: Thanksgiving closed, Christmas Eve 09:00–14:00, closed for renovation from 23 November to 14 December, or closed until further notice. One rule can apply to every location, to countries, to states or provinces, to locations with a filter, or to chosen locations. Each location reads its rule on its own local date, so a rule for 26 November applies from midnight to midnight in every location’s time zone. Reading needs location:read; creating, changing and deleting need location:update, and project API access, like the location endpoints.

The rule object

string
What visitors see beside the date, at most 120 characters.
string
First date, YYYY-MM-DD, in each location’s local calendar.
string | null
Last date, inclusive. Equal to start_date for one day. null only when until_further_notice is true.
string | array
"closed", "regular" (the location’s normal weekly hours on those dates), "open_24_hours", or up to six ranges [{"opens": "09:00", "closes": "14:00"}]. A range that closes earlier than it opens runs past midnight into the next date ({"opens": "20:00", "closes": "02:00"}).
object
Required. type is all, countries (ISO codes such as US), regions (country and region code such as CA-QC, GB-SCT, US-NY), filters (filter IDs) or locations (location IDs). Several values within one type mean any of them. all takes no values. Send {"type": "all"} for every location: a missing or null applies_to is refused with 422, never read as every location.
string | null
A stable holiday identifier, such as US:thanksgiving-day, US:christmas-day or retail:christmas-eve. Needed for repeats_yearly.
string | null
Where a repeating holiday’s date is read, as a country or country and region code (AU-QLD). Needed only when the holiday falls on different dates in different regions and the rule does not target that one region: Queensland’s King’s Birthday is in October, the rest of Australia’s in June. null uses the rule’s own region, if it targets one.
boolean
When true, the rule follows its holiday to its date every year (Thanksgiving 2027 is 25 November). Only a single day with a yearly holiday_key can repeat; an observed weekday or a one-time holiday cannot.
string | null
An optional line for visitors, at most 255 characters.

Which rule wins

When several rules cover the same location on the same date, the most specific one wins: a locations rule, then filters, then regions, then countries, then all. Between two rules of the same kind, the shorter date range wins, then the more recently created rule. Rules are never merged. A countries rule matches the location’s country however it was typed (US, USA, United States); a location with no country matches the country of its time zone. A filters rule follows the filter’s current members, including hidden filters. A locations rule whose locations were all deleted matches nothing: it never falls back to every location.

List rules

GET /api/v2/projects/{project_id}/special-hours returns every rule of the project in data, earliest start first.

Get a rule

GET /api/v2/projects/{project_id}/special-hours/{rule_id} returns one rule in data, or 404 when it does not belong to the project.

Create a rule

POST /api/v2/projects/{project_id}/special-hours returns 201 and the rule. A missing end_date means the same day as start_date; send "until_further_notice": true (and no end_date) for an open-ended closure.
Christmas Eve short hours for two chosen locations:

Change a rule

PATCH /api/v2/projects/{project_id}/special-hours/{rule_id} changes only the fields you send; everything else keeps its saved value. applies_to is replaced as a whole when sent. Sending an empty values list for anything but all is refused with 422: clearing the locations never turns a rule into an account-wide one. To end an open-ended closure, send an end_date.

Delete a rule

DELETE /api/v2/projects/{project_id}/special-hours/{rule_id} returns 204. The locations go back to their weekly hours on those dates.

Retrying safely

POST and PATCH accept an Idempotency-Key header (up to 255 characters). A retry with the same key and the same body returns the first answer, with the header Idempotent-Replayed: true, and creates nothing new. The same key with a different body returns 409. Keys are kept for 24 hours, per token user, project and endpoint. Validation errors are not remembered, so a corrected retry can reuse its key.

A location’s resolved dates

Add ?includeSpecialHours=1 to get a location or list locations to see the dates that apply to each location after every rule is resolved, for a rolling window from two days ago to about two months ahead. A dated entry that runs past the window keeps its real end_date (or null when it has none).
The field is read-only. Sending a location you read back in a PUT keeps working: special_hours is ignored there. Change dates through the rules above.

Errors

Invalid input returns 422 with the field in errors, for example {"message": "Choose at least one country.", "errors": {"applies_to": ["Choose at least one country."]}}. A filter or location ID from another project is refused with 422; a rule ID from another project returns 404. See errors.