> For the complete documentation index, see [llms.txt](https://docs.parkflow.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.parkflow.io/widget/bookings/booking.md).

# Create a booking

{% openapi src="<https://demo.parkflow.io/api/swagger.json>" path="/api/widget/v1/bookings" method="post" %}
<https://demo.parkflow.io/api/swagger.json>
{% endopenapi %}

### Request

```json
{
  "parking": "65891dfe-db0e-4e35-b41a-79ad5b791951",
  "arrival_at": "2026-06-09T12:00",
  "departure_at": "2026-06-16T12:00",
  "payform": "af797140-0fe2-458a-a142-6fdd45f03c0c",
  "client_title": "Peter Test",
  "client_email": "hello@parkflow.io",
  "client_phone": "+48123123123",
  "client_consent_rule": true,
  "client_consent_marketing": false,
  "person_adult": 4,
  "person_child": 0,
  "person_disabled": 0,
  "invoice": false,
  "billing_country": "PL",
  "services": ["<service-uuid>"],
  "vehicles": [
    { "type": "CAR", "plate": "WX12345" }
  ],
  "source": "Website"
}
```

| Field                                               | Req. | Notes                                                                                       |
| --------------------------------------------------- | :--: | ------------------------------------------------------------------------------------------- |
| `parking`                                           |   ✅  | Parking `uuid`; use the **same stay** you priced in the [offer](/widget/bookings/offers.md) |
| `arrival_at` / `departure_at`                       |   ✅  | Parking local time, `YYYY-MM-DDTHH:II`                                                      |
| `client_title`                                      |   ✅  | Customer full name                                                                          |
| `client_phone`                                      |   ✅  | E.164 preferred                                                                             |
| `client_email`                                      |  ◻︎  | Drives voucher/receipt delivery                                                             |
| `client_consent_rule`                               |   ✅  | Acceptance of the operator's terms — must be `true`                                         |
| `client_consent_marketing`                          |  ◻︎  | Marketing consent, stored with the customer                                                 |
| `vehicles[]`                                        |   ✅  | At least one; `type` required, plus `plate`, `brand`, `model`, `color`                      |
| `services[]`                                        |  ◻︎  | Service `uuid`s — the same set you priced                                                   |
| `payform`                                           |  ◻︎  | The payment form the customer chose (from the parking's catalogue)                          |
| `person_adult` / `person_child` / `person_disabled` |  ◻︎  | Headcount for shuttle / meet-and-greet operations                                           |
| `invoice` + `billing_*`                             |  ◻︎  | Set `invoice: true` and supply billing fields when the customer wants one                   |
| `discount`                                          |  ◻︎  | Discount code, if any                                                                       |
| `source`                                            |  ◻︎  | Free-text origin label shown to the operator (e.g. `Website`)                               |

Where the operator has enabled it, the request must also carry a **`recaptcha`** token — the widget surface is public, and reCAPTCHA is its bot protection.

### Response

A `2xx` response is a **confirmed reservation**. It returns the booking with:

* `uuid` — the booking's identity for all API calls;
* `code` — the human-readable reference shown to the customer;
* `status` — see [booking statuses](/reference/constants.md#booking-statuses);
* a **booking token** — a customer-scoped Bearer token for the [self-service endpoints](/widget/bookings/manage.md), so your front-end can continue straight into payment without re-authenticating.

### Payment

If the booking is to be paid online, initiate the payment as the next call and redirect the customer to the returned gateway URL — see [Manage a booking → Payments](/widget/bookings/manage.md#payments). Vouchers and receipts are issued on signed URLs and delivered with the booking's notifications.

### Cancel

{% openapi src="<https://demo.parkflow.io/api/swagger.json>" path="/api/widget/v1/bookings/{booking}" method="delete" %}
<https://demo.parkflow.io/api/swagger.json>
{% endopenapi %}

Cancellation is subject to the operator's cancellation policy, and requires the booking token (or a customer-account token that owns the booking).