Special closings - Chataigne Docs

A special closing is a one-off window during which a location is closed, on top of its regular opening hours — think public holidays, private events, renovations, or an unplanned shutdown. Each closing belongs to exactly one location and is bounded by a start and end instant. Special closings live under their parent location. The full path is /v1/locations/{location_id}/special_closings, with individual closings addressed at /v1/locations/{location_id}/special_closings/{special_closing_id}.

The special_closing object

{
  "id": "7ff7471c-37ff-479d-ac1a-0c82fa6baf82",
  "object": "special_closing",
  "location_id": "loc_r8v4n2c6tz",
  "starts_at": "2026-12-24T22:00:00Z",
  "ends_at": "2026-12-26T06:00:00Z",
  "reason": "Christmas holidays",
  "created_at": "2026-05-29T10:15:00Z",
  "updated_at": "2026-05-29T10:15:00Z"
}

string

Opaque, case-sensitive identifier for the closing.

string

Always "special_closing".

string

The parent location (location ID) this closing applies to.

string

ISO 8601 UTC instant at which the closure begins.

string

ISO 8601 UTC instant at which the closure ends.

string | null

A human-readable explanation for the closure (for example "Public holiday"). It gives the AI clerk the context needed to explain the closure to customers. May be null.

string

ISO 8601 UTC creation timestamp.

string

ISO 8601 UTC last-update timestamp.

Time zones

starts_at and ends_at are absolute UTC instants — the trailing Z is part of the contract. They are not wall-clock times. To present a closing to a restaurant operator, convert each instant into the location’s timezone (an IANA identifier such as Europe/Zurich, available on the location object).

Always send starts_at and ends_at in UTC. If you collect a local date and time from a user, convert it to UTC before calling the API — accounting for daylight saving time in the location’s zone. A closing meant to run “all of December 25th in Zurich” spans 23:00 UTC Dec 24 → 23:00 UTC Dec 25, not midnight to midnight UTC.

The example below converts a local wall-clock window in Europe/Zurich into the UTC instants the API expects.

// "Closed all day on 25 December 2026" in the location's local zone.
const timezone = 'Europe/Zurich';

function toUtcInstant(localDateTime, tz) {
  // localDateTime is "YYYY-MM-DDTHH:mm" in the target zone.
  const target = new Date(`${localDateTime}:00`);
  const asUtc = new Date(target.toLocaleString('en-US', { timeZone: 'UTC' }));
  const asTz = new Date(target.toLocaleString('en-US', { timeZone: tz }));
  const offsetMs = asUtc.getTime() - asTz.getTime();
  return new Date(target.getTime() + offsetMs).toISOString();
}

const startsAt = toUtcInstant('2026-12-25T00:00', timezone); // 2026-12-24T23:00:00.000Z
const endsAt = toUtcInstant('2026-12-26T00:00', timezone); // 2026-12-25T23:00:00.000Z

// Display a stored UTC instant to an operator in the location's zone.
function renderLocal(utcInstant, tz) {
  return new Intl.DateTimeFormat('fr-CH', {
    timeZone: tz,
    dateStyle: 'medium',
    timeStyle: 'short',
  }).format(new Date(utcInstant));
}

renderLocal('2026-12-24T23:00:00Z', 'Europe/Zurich'); // "25 déc. 2026, 00:00"

List special closings

Returns a paginated list of the closings for a location, ordered by created_at.

Endpoint

GET /v1/locations/{location_id}/special_closings

Query parameters

integer

default:"10"

Number of results per page, between 1 and 100.

string

Cursor for the next page — the id of the last object in the previous page. Mutually exclusive with ending_before.

string

Cursor for the previous page — the id of the first object in the current page. Mutually exclusive with starting_after.

string

Return closings created after this ISO 8601 timestamp.

string

Return closings created before this ISO 8601 timestamp.

string

Return closings updated after this ISO 8601 timestamp.

string

Return closings updated before this ISO 8601 timestamp.

curl "https://server.chataigne.ai/v1/locations/loc_r8v4n2c6tz/special_closings?limit=20" \
  -H "x-api-key: ch_org_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

const locationId = 'loc_r8v4n2c6tz';
const res = await fetch(
  `https://server.chataigne.ai/v1/locations/${locationId}/special_closings?limit=20`,
  { headers: { 'x-api-key': process.env.CHATAIGNE_API_KEY } },
);
const closings = await res.json();
console.log(closings.data);

Response

{
  "object": "list",
  "data": [
    {
      "id": "7ff7471c-37ff-479d-ac1a-0c82fa6baf82",
      "object": "special_closing",
      "location_id": "loc_r8v4n2c6tz",
      "starts_at": "2026-12-24T22:00:00Z",
      "ends_at": "2026-12-26T06:00:00Z",
      "reason": "Christmas holidays",
      "created_at": "2026-05-29T10:15:00Z",
      "updated_at": "2026-05-29T10:15:00Z"
    }
  ],
  "has_more": false,
  "url": "/v1/locations/loc_r8v4n2c6tz/special_closings"
}

Create a special closing

Creates a closing under a location. This is a resource-creating POST, so an Idempotency-Key header is required.

Endpoint

POST /v1/locations/{location_id}/special_closings

Body parameters

string

required

ISO 8601 UTC instant at which the closure begins.

string

required

ISO 8601 UTC instant at which the closure ends.

string

Optional human-readable explanation for the closure. It is passed to the AI clerk so it can explain the closure to customers. Omit or send null to leave it unset.

curl https://server.chataigne.ai/v1/locations/loc_r8v4n2c6tz/special_closings \
  -H "x-api-key: ch_org_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: 6f1d3b8a-2c47-4e90-9a1b-0d2f7c5e1234" \
  -H "Content-Type: application/json" \
  -d '{
    "starts_at": "2026-12-24T22:00:00Z",
    "ends_at": "2026-12-26T06:00:00Z",
    "reason": "Christmas holidays"
  }'

import { randomUUID } from 'node:crypto';

const locationId = 'loc_r8v4n2c6tz';
const res = await fetch(`https://server.chataigne.ai/v1/locations/${locationId}/special_closings`, {
  method: 'POST',
  headers: {
    'x-api-key': process.env.CHATAIGNE_API_KEY,
    'Idempotency-Key': randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    starts_at: '2026-12-24T22:00:00Z',
    ends_at: '2026-12-26T06:00:00Z',
    reason: 'Christmas holidays',
  }),
});
const closing = await res.json();

Response

{
  "id": "7ff7471c-37ff-479d-ac1a-0c82fa6baf82",
  "object": "special_closing",
  "location_id": "loc_r8v4n2c6tz",
  "starts_at": "2026-12-24T22:00:00Z",
  "ends_at": "2026-12-26T06:00:00Z",
  "reason": "Christmas holidays",
  "created_at": "2026-05-29T10:15:00Z",
  "updated_at": "2026-05-29T10:15:00Z"
}

Replaying the same Idempotency-Key with the same body returns the original closing, with the header Idempotent-Replayed: true. Reusing the key with a different body returns 409 idempotency_error, and a concurrent in-flight duplicate returns 409 conflict_error. Keys are retained for 24 hours. See Idempotency.

Retrieve a special closing

Fetches a single closing by id.

Endpoint

GET /v1/locations/{location_id}/special_closings/{special_closing_id}

curl https://server.chataigne.ai/v1/locations/loc_r8v4n2c6tz/special_closings/7ff7471c-37ff-479d-ac1a-0c82fa6baf82 \
  -H "x-api-key: ch_org_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

const locationId = 'loc_r8v4n2c6tz';
const closingId = '7ff7471c-37ff-479d-ac1a-0c82fa6baf82';
const res = await fetch(
  `https://server.chataigne.ai/v1/locations/${locationId}/special_closings/${closingId}`,
  { headers: { 'x-api-key': process.env.CHATAIGNE_API_KEY } },
);
const closing = await res.json();

Response

{
  "id": "7ff7471c-37ff-479d-ac1a-0c82fa6baf82",
  "object": "special_closing",
  "location_id": "loc_r8v4n2c6tz",
  "starts_at": "2026-12-24T22:00:00Z",
  "ends_at": "2026-12-26T06:00:00Z",
  "reason": "Christmas holidays",
  "created_at": "2026-05-29T10:15:00Z",
  "updated_at": "2026-05-29T10:15:00Z"
}

A request for an id that does not exist under the location returns 404 not_found_error.

Update a special closing

Updates one or more fields on a closing. Only the fields you send are changed; omitted fields keep their current value.

Endpoint

PATCH /v1/locations/{location_id}/special_closings/{special_closing_id}

Body parameters

string

New start instant, ISO 8601 UTC.

string

New end instant, ISO 8601 UTC.

string | null

New reason passed to the AI clerk so it can explain the closure to customers. Send null to clear an existing reason.

curl -X PATCH https://server.chataigne.ai/v1/locations/loc_r8v4n2c6tz/special_closings/7ff7471c-37ff-479d-ac1a-0c82fa6baf82 \
  -H "x-api-key: ch_org_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "ends_at": "2026-12-27T06:00:00Z",
    "reason": "Christmas & Boxing Day"
  }'

const locationId = 'loc_r8v4n2c6tz';
const closingId = '7ff7471c-37ff-479d-ac1a-0c82fa6baf82';
const res = await fetch(
  `https://server.chataigne.ai/v1/locations/${locationId}/special_closings/${closingId}`,
  {
    method: 'PATCH',
    headers: {
      'x-api-key': process.env.CHATAIGNE_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      ends_at: '2026-12-27T06:00:00Z',
      reason: 'Christmas & Boxing Day',
    }),
  },
);
const closing = await res.json();

Response

{
  "id": "7ff7471c-37ff-479d-ac1a-0c82fa6baf82",
  "object": "special_closing",
  "location_id": "loc_r8v4n2c6tz",
  "starts_at": "2026-12-24T22:00:00Z",
  "ends_at": "2026-12-27T06:00:00Z",
  "reason": "Christmas & Boxing Day",
  "created_at": "2026-05-29T10:15:00Z",
  "updated_at": "2026-05-29T11:42:08Z"
}

Delete a special closing

Permanently removes a closing. The location reverts to its regular opening hours for that window.

Endpoint

DELETE /v1/locations/{location_id}/special_closings/{special_closing_id}

curl -X DELETE https://server.chataigne.ai/v1/locations/loc_r8v4n2c6tz/special_closings/7ff7471c-37ff-479d-ac1a-0c82fa6baf82 \
  -H "x-api-key: ch_org_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

const locationId = 'loc_r8v4n2c6tz';
const closingId = '7ff7471c-37ff-479d-ac1a-0c82fa6baf82';
const res = await fetch(
  `https://server.chataigne.ai/v1/locations/${locationId}/special_closings/${closingId}`,
  {
    method: 'DELETE',
    headers: { 'x-api-key': process.env.CHATAIGNE_API_KEY },
  },
);

Deleting a closing that does not exist returns 404 not_found_error.

Errors

Special closing endpoints use the standard error model. The most common cases:

HTTP status	`error.type`	When
`400`	`invalid_request_error`	A timestamp is missing or not valid ISO 8601, or a parameter is malformed.
`401`	`authentication_error`	No API key was provided.
`403`	`authorization_error`	The key’s scope or permissions do not allow this action.
`404`	`not_found_error`	The location or closing id does not exist or is not accessible to your key.
`409`	`idempotency_error`	The `Idempotency-Key` was reused with a different body.
`409`	`conflict_error`	A concurrent in-flight request used the same `Idempotency-Key`.
`429`	`rate_limit_error`	The per-key rate limit was exceeded; retry after `Retry-After`.

Example error

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "ends_at must be a valid ISO 8601 UTC timestamp.",
    "param": "ends_at",
    "request_id": "req_2y8Fk1Zx0Qm7"
  }
}

Next steps

Opening hours

Special closings sit on top of a location’s regular weekly delivery and pickup schedule.

Locations

Read a location’s timezone to render starts_at and ends_at in local wall-clock time.

Idempotency

Creating a closing requires an Idempotency-Key. Learn how safe retries work.

​The special_closing object

​Time zones

​List special closings

​Query parameters

​Create a special closing

​Body parameters

​Retrieve a special closing

​Update a special closing

​Body parameters

​Delete a special closing

​Errors

​Next steps

Opening hours

Locations

Idempotency

The special_closing object

Time zones

List special closings

Query parameters

Create a special closing

Body parameters

Retrieve a special closing

Update a special closing

Body parameters

Delete a special closing

Errors

Next steps