# Calendar events

Events on the timeline: bookings, blocked periods or notes

Endpoint: `https://api.bookingmood.com/v1/calendar_events`, supporting `GET`, `DELETE`, `PATCH`. Authenticate with the header `Authorization: Bearer YOUR_API_KEY` (see [authentication](https://www.bookingmood.com/en-GB/api-reference/authentication.md)).

## The calendar event object

| Attribute | Type | Description |
| --- | --- | --- |
| `id` | `uuid` | Unique identifier. |
| `booking_id` | `uuid \| null` | Identifier of the related booking. References [`bookings.id`](https://www.bookingmood.com/en-GB/api-reference/bookings.md). |
| `calendar_id` | `uuid \| null` | Identifier of the external calendar the event is imported from. References [`external_calendars.id`](https://www.bookingmood.com/en-GB/api-reference/external_calendars.md). |
| `creator_id` | `uuid \| null` | Identifier of the user that created the event. References [`user_profiles.user_id`](https://www.bookingmood.com/en-GB/api-reference/user_profiles.md). |
| `organization_id` | `uuid` | Identifier of the organization this event is defined in. References [`organizations.id`](https://www.bookingmood.com/en-GB/api-reference/organizations.md). |
| `product_id` | `uuid` | Identifier of the related unit. References [`products.id`](https://www.bookingmood.com/en-GB/api-reference/products.md). |
| `created_at` | `timestamp with time zone` | Creation timestamp. Read-only: set by the database. |
| `updated_at` | `timestamp with time zone` | Last modification timestamp. Read-only: set by the database. |
| `duration` | `integer` | Number of nights of the event, or days for units rented per day. Read-only: set by the database. |
| `end_date` | `date` | End date of the event. |
| `fts` | `tsvector` |  |
| `generated_title` | `text` | Title of the event, generated from the unit name and the guest name. |
| `has_non_invoiced_items` | `boolean` | Whether the booking of the event has line items that are not on an invoice. |
| `has_open_payments` | `boolean` | Whether the booking of the event has payments that are due. |
| `notes` | `text` | Private notes about the event. |
| `occupancy` | `Record<uuid, integer>` | Occupancy per capacity group. |
| `origin` | `text \| null` | Origin of the event. |
| `padding` | `smallint` | Padding of the event due to cooldown time. |
| `start_date` | `date` | Start date of the event. |
| `status` | `CalendarEventStatus` | Status of the event. |
| `title` | `text` | Title of the event. |
| `type` | `CalendarEventType` | Type of the event. |
| `uid` | `text` | Identifier of the event in the external calendar. |

```json
{
  "id": "00000000-0000-0000-0000-000000000000",
  "booking_id": "00000000-0000-0000-0000-000000000000",
  "calendar_id": "00000000-0000-0000-0000-000000000000",
  "creator_id": "00000000-0000-0000-0000-000000000000",
  "organization_id": "00000000-0000-0000-0000-000000000000",
  "product_id": "00000000-0000-0000-0000-000000000000",
  "created_at": "2026-10-30T23:31:32.587Z",
  "updated_at": "2026-10-30T23:31:32.587Z",
  "duration": 0,
  "end_date": "2026-10-30",
  "generated_title": "Summer cottage",
  "has_non_invoiced_items": false,
  "has_open_payments": false,
  "notes": "A short description.",
  "occupancy": {},
  "origin": "",
  "padding": 0,
  "start_date": "2026-10-30",
  "status": "CONFIRMED",
  "title": "Summer cottage",
  "type": "booking",
  "uid": ""
}
```

### Types

```typescript
type CalendarEventStatus = "CONFIRMED" | "TENTATIVE" | "CANCELLED";

type CalendarEventType = "booking" | "blocked-period" | "note";
```

### Related resources

Embed related resources with the [`select` parameter](https://www.bookingmood.com/en-GB/api-reference/selecting.md), e.g. `select=*,bookings!booking_id(*)`. Resources related through more than one column need the column as a hint, like `table!column(*)`.

| Embed | Type | Description |
| --- | --- | --- |
| `bookings!booking_id(*)` | `object \| null` | The [booking](https://www.bookingmood.com/en-GB/api-reference/bookings.md) referenced by `booking_id`. |
| `external_calendars(*)` | `object \| null` | The [external calendar](https://www.bookingmood.com/en-GB/api-reference/external_calendars.md) referenced by `calendar_id`. |
| `organizations!organization_id(*)` | `object \| null` | The [organization](https://www.bookingmood.com/en-GB/api-reference/organizations.md) referenced by `organization_id`. |
| `products!product_id(*)` | `object \| null` | The [product](https://www.bookingmood.com/en-GB/api-reference/products.md) referenced by `product_id`. |
| `user_profiles!creator_id(*)` | `object \| null` | The [user profile](https://www.bookingmood.com/en-GB/api-reference/user_profiles.md) referenced by `creator_id`. |
| `booking_details(*)` | `array` | The [booking details](https://www.bookingmood.com/en-GB/api-reference/booking_details.md) referencing this calendar event through `booking_details.calendar_event_id`. |
| `calendar_event_notes(*)` | `array` | The [calendar event notes](https://www.bookingmood.com/en-GB/api-reference/calendar_event_notes.md) referencing this calendar event through `calendar_event_notes.calendar_event_id`. |
| `calendar_event_updates(*)` | `array` | The [calendar event updates](https://www.bookingmood.com/en-GB/api-reference/calendar_event_updates.md) referencing this calendar event through `calendar_event_updates.calendar_event_id`. |
| `line_items(*)` | `array` | The [line items](https://www.bookingmood.com/en-GB/api-reference/line_items.md) referencing this calendar event through `line_items.event_id`. |
| `tasks(*)` | `array` | The [tasks](https://www.bookingmood.com/en-GB/api-reference/tasks.md) referencing this calendar event through `tasks.calendar_event_id`. |

## List calendar events

`GET /v1/calendar_events`

Filter on any attribute with `column=operator.value` (see [filtering](https://www.bookingmood.com/en-GB/api-reference/filtering.md)). Choose columns and embed related resources with `select` (see [selecting](https://www.bookingmood.com/en-GB/api-reference/selecting.md)), and sort and paginate with `order`, `limit` and `offset` (see [sorting and pagination](https://www.bookingmood.com/en-GB/api-reference/sorting-pagination.md)).

```bash
curl -X GET "https://api.bookingmood.com/v1/calendar_events?select=*&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Responses:

- `200`: A list of calendar events with the selected columns. `206` when the list is a partial range.
- `400`: The request is malformed, for example an unknown column or an invalid filter.
- `401`: The API key is missing or invalid.

## Delete calendar events

`DELETE /v1/calendar_events`

Filter on any attribute with `column=operator.value` (see [filtering](https://www.bookingmood.com/en-GB/api-reference/filtering.md)). Without filters, this request deletes all calendar events you have access to. Always filter on at least one column, e.g. `id=eq.{id}`.

```bash
curl -X DELETE "https://api.bookingmood.com/v1/calendar_events?id=eq.00000000-0000-0000-0000-000000000000" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Responses:

- `200`: The deleted calendar events with the selected columns. `204` without a body when sending the header `Prefer: return=minimal`.
- `400`: The request is malformed, for example an unknown column or an invalid filter.
- `401`: The API key is missing or invalid.
- `403`: The API key has no permission for this change, for example when writing rows of another organization.

## Update calendar events

`PATCH /v1/calendar_events`

Filter on any attribute with `column=operator.value` (see [filtering](https://www.bookingmood.com/en-GB/api-reference/filtering.md)). Without filters, this request updates all calendar events you have access to. Always filter on at least one column, e.g. `id=eq.{id}`. The body holds the attributes to change.

```bash
curl -X PATCH "https://api.bookingmood.com/v1/calendar_events?id=eq.00000000-0000-0000-0000-000000000000" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "end_date": "2026-10-30"
  }'
```

Responses:

- `200`: The updated calendar events with the selected columns. `204` without a body when sending the header `Prefer: return=minimal`.
- `400`: The request is malformed, for example an unknown column, an invalid filter or an invalid body.
- `401`: The API key is missing or invalid.
- `403`: The API key has no permission for this change, for example when writing rows of another organization.
- `409`: The change conflicts with existing data, for example a duplicate key or a reference to a row that does not exist.

Errors have a JSON body with a `code`, `message`, `details` and `hint`. See the [introduction](https://www.bookingmood.com/en-GB/api-reference.md) for more on errors. The full API is described by the OpenAPI spec at https://api.bookingmood.com/v1/openapi.json.