Update a holiday

PATCHhttps://<your-url>/api/v2/holidays/{holiday}

MCP id holidays.updateAlso on this path: GET Read a holiday, DELETE Delete a holiday

Partially updates a holiday: absent keys are untouched, and an explicit null clears default_month, default_day or recurrence_interval.

Token scope: api:write:holidays
Without it: 403 insufficient-token-scope.
Permission: holidays::manage
Without it: 403 insufficient-permission.
Rate cost: 1 unit, write bucket. A write costs the same whatever view you ask for.
Also: Accepts If-Match. Never cached: private, no-store. Unknown body keys are refused, never dropped.

Both are checked, scope first. A token never does more than its user. How access is checked

Request

Example: Turn a yearly holiday into a variable one

curl -X PATCH \
  'https://<your-url>/api/v2/holidays/1' \
  -H 'Authorization: Bearer <token>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'If-Match: *' \
  -d '{
    "default_month": null,
    "default_day": null
  }'

const response = await fetch('https://<your-url>/api/v2/holidays/1', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer <token>',
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'If-Match': '*',
  },
  body: JSON.stringify({
    "default_month": null,
    "default_day": null
  }),
});

use Illuminate\Support\Facades\Http;

$response = Http::withToken('<token>')
    ->acceptJson()
    ->withHeader('If-Match', '*')
    ->patch('https://<your-url>/api/v2/holidays/1', [
        'default_month' => null,
        'default_day' => null,
    ]);

import requests
response = requests.request(
    'PATCH',
    'https://<your-url>/api/v2/holidays/1',
    headers={'Authorization': 'Bearer <token>', 'Accept': 'application/json', 'Content-Type': 'application/json', 'If-Match': '*'},
    json={'default_month': None, 'default_day': None},
)

Response

The shape of the response, with sample values.

{
  "data": {
    "id": 1,
    "name": "Nieuwjaarsdag",
    "default_month": null,
    "default_day": null,
    "recurrence_interval": 1,
    "sort_order": 1,
    "free_days_count": 1,
    "created_at": "2026-03-04T09:15:00Z",
    "updated_at": "2026-03-04T09:15:00Z",
    "links": {
      "self": "https://<your-url>/api/v2/work-items/1",
      "free_days": "https://<your-url>/api/v2/work-items/1"
    }
  }
}

{
  "type": "https://developers.plnnrly.com/api/v2/problems/precondition-failed",
  "title": "Precondition failed",
  "status": 412,
  "detail": "The record changed since the version named in If-Match. Re-read it and retry.",
  "instance": "/api/v2/work-items/812",
  "request_id": "01K4B7Q9YV3PZ2N8T1E6M0XR4S",
  "current_version": 12
}

{
  "type": "https://developers.plnnrly.com/api/v2/problems/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "3 fields failed validation.",
  "instance": "/api/v2/worklogs",
  "request_id": "01K4B7Q9YV3PZ2N8T1E6M0XR4S",
  "errors": [
    {
      "pointer": "/date",
      "code": "date_format",
      "detail": "The date does not match the format Y-m-d."
    },
    {
      "pointer": "/minutes",
      "code": "min",
      "detail": "The minutes must be at least 1."
    },
    {
      "pointer": "/description",
      "code": "required",
      "detail": "The description field is required."
    }
  ]
}

sort_order is not writable: holidays are reordered in plnnrly. Send If-Match with the ETag from your last read to detect a concurrent edit, which answers 412.

Path parameters

holidayintegerRequired

The Holiday's numeric id.

Query parameters

Unknown parameters are refused with 400, naming the parameter.

viewstring

Which field set to render.

summarydetaildefault

Request headers

X-Request-Idstringpattern

A correlation id of your own. It is recorded in our logs next to the server's request id but never returned: the response header always carries the server's id. A value that does not match the pattern is discarded silently, never rejected.

If-Matchstring

The ETag a write is conditional on. A stale validator is 412 precondition-failed.

Request body

Unknown keys are refused with 422, naming the key.

namestring≤ 255

Name of the holiday, e.g. Nieuwjaarsdag.

default_monthinteger or null1 to 12

Month the holiday normally falls in, 1-12. Null means the holiday moves from year to year (Easter, say), and the organisation fills the date in per year on the free day itself.

default_dayinteger or null1 to 31

Day of the month the holiday normally falls on, 1-31, paired with default_month. Null means the day is not fixed.

recurrence_intervalinteger or null1 to 255

How often the holiday repeats, in years: null is not recurring, 1 is yearly, and n repeats every n years.

Response 200

Returns a Holiday in the detail view.

Headers

ETag: A strong validator of exactly this representation.
RateLimit: The IETF httpapi-ratelimit-headers form of your remaining allowance on the tightest bucket this request touched.
RateLimit-Policy: The ceiling and window of that bucket, as <limit>;w=<seconds>.
X-Request-Id: The server-generated ULID correlating this response with our logs.

Every response also carries Cache-Control, Vary, X-Content-Type-Options, X-Plnnrly-Api-Version, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Headers and versioning