# Bookings

Bookings, grouping the calendar events, invoices and payments of a guest's stay

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

## The booking object

| Attribute | Type | Description |
| --- | --- | --- |
| `id` | `uuid` | Unique identifier. |
| `creator_id` | `uuid \| null` | Identifier of the user that created the booking. |
| `organization_id` | `uuid` | Identifier of the organization this booking is defined in. References [`organizations.id`](https://www.bookingmood.com/he-IL/api-reference/organizations.md). |
| `site_id` | `uuid \| null` | Identifier of the site the booking was made on. References [`sites.id`](https://www.bookingmood.com/he-IL/api-reference/sites.md). |
| `widget_id` | `uuid \| null` | Identifier of the widget the booking was made in. References [`widgets.id`](https://www.bookingmood.com/he-IL/api-reference/widgets.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. |
| `confirmed_at` | `timestamp with time zone \| null` | Timestamp at which the booking was confirmed. |
| `currency` | `Currency` | Base currency of the booking. |
| `display_currency` | `Currency` | Currency used to display prices to the guest. |
| `exchange_rate` | `real` | Exchange rate used to convert the booking currency to the display currency. |
| `fts` | `tsvector` | Read-only: set by the database. |
| `method` | `BookingMethod` | Method used to make the booking: `request` or `book`. |
| `reference` | `text` | Publicly visible reference of the booking. |
| `secret` | `text` | Secret reference of the booking. |
| `silent` | `boolean` | Whether the booking was made without automatically sending a confirmation email. |

```json
{
  "id": "00000000-0000-0000-0000-000000000000",
  "creator_id": "00000000-0000-0000-0000-000000000000",
  "organization_id": "00000000-0000-0000-0000-000000000000",
  "site_id": "00000000-0000-0000-0000-000000000000",
  "widget_id": "00000000-0000-0000-0000-000000000000",
  "created_at": "2026-10-30T23:37:06.265Z",
  "updated_at": "2026-10-30T23:37:06.265Z",
  "confirmed_at": "2026-10-30T23:37:06.265Z",
  "currency": "ARS",
  "display_currency": "ARS",
  "exchange_rate": 0,
  "method": "request",
  "reference": "ABC123",
  "secret": "",
  "silent": false
}
```

### Types

```typescript
type BookingMethod = "book" | "request";

type Currency = 
  | "ARS"
  | "AUD"
  | "BRL"
  | "BYN"
  | "CAD"
  | "CHF"
  | "CLP"
  | "CNY"
  | "COP"
  | "CZK"
  | "DKK"
  | "EGP"
  | "EUR"
  | "GBP"
  | "HKD"
  | "HUF"
  | "ILS"
  | "INR"
  | "JPY"
  | "KRW"
  | "KYD"
  | "MAD"
  | "MXN"
  | "MYR"
  | "NGN"
  | "NOK"
  | "NZD"
  | "PEN"
  | "PHP"
  | "PLN"
  | "RON"
  | "RUB"
  | "SEK"
  | "SGD"
  | "THB"
  | "TRY"
  | "TWD"
  | "UAH"
  | "USD"
  | "XOF"
  | "VND"
  | "ZAR";
```

### Related resources

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

| Embed | Type | Description |
| --- | --- | --- |
| `organizations!organization_id(*)` | `object \| null` | The [organization](https://www.bookingmood.com/he-IL/api-reference/organizations.md) referenced by `organization_id`. |
| `sites(*)` | `object \| null` | The [site](https://www.bookingmood.com/he-IL/api-reference/sites.md) referenced by `site_id`. |
| `widgets(*)` | `object \| null` | The [widget](https://www.bookingmood.com/he-IL/api-reference/widgets.md) referenced by `widget_id`. |
| `booking_details(*)` | `array` | The [booking details](https://www.bookingmood.com/he-IL/api-reference/booking_details.md) referencing this booking through `booking_details.booking_id`. |
| `booking_updates(*)` | `array` | The [booking updates](https://www.bookingmood.com/he-IL/api-reference/booking_updates.md) referencing this booking through `booking_updates.booking_id`. |
| `calendar_events!booking_id(*)` | `array` | The [calendar events](https://www.bookingmood.com/he-IL/api-reference/calendar_events.md) referencing this booking through `calendar_events.booking_id`. |
| `contact_bookings(*)` | `array` | The [contact bookings](https://www.bookingmood.com/he-IL/api-reference/contact_bookings.md) referencing this booking through `contact_bookings.booking_id`. |
| `coupon_uses(*)` | `array` | The [coupon uses](https://www.bookingmood.com/he-IL/api-reference/coupon_uses.md) referencing this booking through `coupon_uses.booking_id`. |
| `invoices!booking_id(*)` | `array` | The [invoices](https://www.bookingmood.com/he-IL/api-reference/invoices.md) referencing this booking through `invoices.booking_id`. |
| `line_items(*)` | `array` | The [line items](https://www.bookingmood.com/he-IL/api-reference/line_items.md) referencing this booking through `line_items.booking_id`. |
| `messages(*)` | `array` | The [messages](https://www.bookingmood.com/he-IL/api-reference/messages.md) referencing this booking through `messages.booking_id`. |
| `payments(*)` | `array` | The [payments](https://www.bookingmood.com/he-IL/api-reference/payments.md) referencing this booking through `payments.booking_id`. |
| `refunds(*)` | `array` | The [refunds](https://www.bookingmood.com/he-IL/api-reference/refunds.md) referencing this booking through `refunds.booking_id`. |
| `reviews(*)` | `array` | The [reviews](https://www.bookingmood.com/he-IL/api-reference/reviews.md) referencing this booking through `reviews.booking_id`. |

## List bookings

`GET /v1/bookings`

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

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

Responses:

- `200`: A list of bookings 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 bookings

`DELETE /v1/bookings`

Filter on any attribute with `column=operator.value` (see [filtering](https://www.bookingmood.com/he-IL/api-reference/filtering.md)). Without filters, this request deletes all bookings 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/bookings?id=eq.00000000-0000-0000-0000-000000000000" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Responses:

- `200`: The deleted bookings 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 bookings

`PATCH /v1/bookings`

Filter on any attribute with `column=operator.value` (see [filtering](https://www.bookingmood.com/he-IL/api-reference/filtering.md)). Without filters, this request updates all bookings 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/bookings?id=eq.00000000-0000-0000-0000-000000000000" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "ARS"
  }'
```

Responses:

- `200`: The updated bookings 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/he-IL/api-reference.md) for more on errors. The full API is described by the OpenAPI spec at https://api.bookingmood.com/v1/openapi.json.