location:read; creating, changing and deleting need location:update, and project API access, like the location endpoints.
The rule object
Last date, inclusive. Equal to
start_date for one day. null only when until_further_notice is true."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"}).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.A stable holiday identifier, such as
US:thanksgiving-day, US:christmas-day or retail:christmas-eve. Needed for repeats_yearly.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.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.Which rule wins
When several rules cover the same location on the same date, the most specific one wins: alocations 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.
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).
PUT keeps working: special_hours is ignored there. Change dates through the rules above.
Errors
Invalid input returns422 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.