---
title: "Bookings"
description: "Create and update bookings in a customer's WaW account."
---

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

# Bookings

## Create a booking

`POST /v1/bookings`

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `external_id` | string, max 128 | Yes | Your own ID for this booking. Unique per customer team. |
| `name` | string, max 300 | Yes | |
| `start_date` | date-time | Yes | See [Dates](#dates). |
| `location` | string, max 1.000 | Yes | |
| `end_date` | date-time or `null` | No | Must be after `start_date`. |
| `contact_id` | WaW contact ID or `null` | No | Sets the primary contact. The contact must belong to the same team. |
| `status` | string | No | See [Statuses](#statuses). Defaults to `draft`. |
| `lost_reason` | string, max 1.000, or `null` | No | Required when `status` is `lost`. |

```json
{
  "external_id": "booking-8421",
  "name": "Wedding Noor and Sam",
  "start_date": "2027-06-12T16:00:00+02:00",
  "end_date": "2027-06-13T02:00:00+02:00",
  "location": "Ghent",
  "status": "confirmed"
}
```

**Response:** `201 Created`

```json
{ "id": "3f1e9a2b-5c4d-4e6f-8a7b-9c0d1e2f3a4b", "external_id": "booking-8421" }
```

Sending the same request again returns `200` with the same IDs. No duplicate is created. See [Retries](/partners-api/errors-and-limits#retries).

## Update a booking

`PATCH /v1/bookings/{id}`

Use the WaW `id` from the create response. Send only the fields you want to change. You can send every field from the create table except `external_id`.

```json
{ "location": "Bruges", "status": "confirmed" }
```

**Response:** `200 OK`

```json
{ "id": "3f1e9a2b-5c4d-4e6f-8a7b-9c0d1e2f3a4b", "updated": true }
```

- Fields you leave out stay as they are.
- `null` clears an optional field.
- The last successful update wins. If the customer edits the same field in WaW, your next update overwrites it.

## Statuses

WaW has three statuses: `draft` (the default), `confirmed` and `lost`. These are the booking statuses the customer sees in WaW.

`lost` needs a non-empty `lost_reason`. Moving a booking away from `lost` clears its `lost_reason`. `cancelled` is not a valid status; use `lost` with a reason.

## Dates

Dates use RFC 3339 with seconds and a timezone offset, for example `2027-06-12T16:00:00+02:00`. A date without a time, or a time without an offset, is rejected with `422`.

## Good to know

- Create the contact first, then pass its WaW ID as `contact_id`.
- WaW automations the customer has set up for new bookings still run.

Source: https://docs.withoutaworry.com/partners-api/bookings/index.mdx
