> ## Documentation Index
> Fetch the complete documentation index at: https://docs.storerocket.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Holiday and special hours

> Close locations for a holiday, open them on special times, or close them until further notice, with one rule for many locations.

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](https://docs.storerocket.io/api/locations/list.md).

## The rule object

```json theme={null}
{
  "id": "k4ZqP0mE7d",
  "name": "Thanksgiving",
  "holiday_key": "US:thanksgiving-day",
  "holiday_region": null,
  "start_date": "2026-11-26",
  "end_date": "2026-11-26",
  "until_further_notice": false,
  "hours": "closed",
  "repeats_yearly": true,
  "note": null,
  "applies_to": { "type": "countries", "values": ["US"] },
  "source": "api",
  "created_at": "2026-11-13T10:00:00+00:00",
  "updated_at": "2026-11-13T10:00:00+00:00"
}
```

**name** `string`

What visitors see beside the date, at most 120 characters.

**start\_date** `string`

First date, `YYYY-MM-DD`, in each location's local calendar.

**end\_date** `string | null`

Last date, inclusive. Equal to `start_date` for one day. `null` only when `until_further_notice` is `true`.

**hours** `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"}`).

**applies\_to** `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.

**holiday\_key** `string | null`

A stable holiday identifier, such as `US:thanksgiving-day`, `US:christmas-day` or `retail:christmas-eve`. Needed for `repeats_yearly`.

**holiday\_region** `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.

**repeats\_yearly** `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.

**note** `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.

```bash theme={null}
curl 'https://storerocket.io/api/v2/projects/PROJECT_ID/special-hours' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json'
```

## 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.

```bash theme={null}
curl -X POST 'https://storerocket.io/api/v2/projects/PROJECT_ID/special-hours' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: thanksgiving-2026-us' \
  -d '{
    "name": "Thanksgiving",
    "holiday_key": "US:thanksgiving-day",
    "start_date": "2026-11-26",
    "hours": "closed",
    "repeats_yearly": true,
    "applies_to": { "type": "countries", "values": ["US"] }
  }'
```

Christmas Eve short hours for two chosen locations:

```bash theme={null}
curl -X POST 'https://storerocket.io/api/v2/projects/PROJECT_ID/special-hours' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Christmas Eve",
    "start_date": "2026-12-24",
    "hours": [{ "opens": "09:00", "closes": "14:00" }],
    "applies_to": { "type": "locations", "values": ["LOCATION_ID_1", "LOCATION_ID_2"] }
  }'
```

## 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`.

```bash theme={null}
curl -X PATCH 'https://storerocket.io/api/v2/projects/PROJECT_ID/special-hours/RULE_ID' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{"hours": [{ "opens": "10:00", "closes": "15:00" }]}'
```

## 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](https://docs.storerocket.io/api/locations/get.md) or [list locations](https://docs.storerocket.io/api/locations/list.md) 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).

```json theme={null}
"special_hours": {
  "window": { "from": "2026-11-18", "to": "2027-01-20" },
  "dates": [
    { "name": "Thanksgiving", "start_date": "2026-11-26", "end_date": "2026-11-26", "hours": "closed", "note": null }
  ]
}
```

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](https://docs.storerocket.io/api/errors.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.