> 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 Create the reservation — customer, vehicles, services and consents in one call, confirmed instantly. {% openapi src="" path="/api/widget/v1/bookings" method="post" %} {% 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": [""], "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 full booking object: ```json { "uuid": "0d5f6a34-2b7e-4c1d-9e8f-3a5b7c9d1e2f", "code": "260609-0412", "status": "CREATED", "balance": -35000, "price_vehicles": 30000, "price_services": 5000, "client_title": "Peter Test", "client_phone": "+48123123123", "client_email": "hello@parkflow.io", "arrival_in": 720, "arrival_at": "2026-06-09T12:00", "departure_at": "2026-06-16T12:00", "person_adult": 4, "person_child": 0, "person_disabled": 0, "comment": null, "voucher": "https:///api/widget/v1/bookings//voucher?expires=…&signature=…", "receipt": "https:///api/widget/v1/bookings//receipt?expires=…&signature=…", "pay": "https:///api/widget/v1/bookings//pay?expires=…&signature=…", "depart_to": null, "depart_code": null, "depart_ship": null, "depart_terminal": null, "return_from": null, "return_code": null, "return_terminal": null, "invoice": false, "billing_title": null, "billing_type": "PERSON", "billing_code": null, "billing_city": null, "billing_address": null, "billing_zipcode": null, "billing_country": "PL", "billing_attributes": {}, "action_editable": true, "action_cancelable": true, "updated_at": "2026-05-10T09:41:12+00:00", "created_at": "2026-05-10T09:41:12+00:00", "canceled_at": null, "services": [ { "uuid": "…", "service": "", "title": "Car wash", "count": 1, "price": 5000 } ], "vehicles": [ { "uuid": "…", "type": "CAR", "plate": "WX12345", "comment": null, "price": 30000 } ], "discounts": [], "payform": { "uuid": "af797140-0fe2-458a-a142-6fdd45f03c0c", "title": "Credit card", "comment": null, "type": "STRIPE", "redirect": true, "recurring": false }, "parking": { "uuid": "…", "title": "Airport Parking", "currency": "PLN", "…": "…" }, "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9…" } ``` | Field | Notes | | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `uuid` | The booking's identity for all API calls — globally unique | | `code` | The human-readable reference shown to the customer (format follows the parking's code pattern) | | `status` | `CREATED` at this point — see [booking statuses](/reference/constants.md#booking-statuses) | | `balance` | Outstanding balance in **minor units**, **negative while money is owed** — a freshly created booking carries `-(total price)`, so the total is `abs(balance)` | | `price_vehicles` / `price_services` | Price components in minor units, before discounts; discounts granted are itemised in `discounts[]` | | `arrival_in` | Hours until arrival | | `voucher` / `receipt` | Short-lived **signed URLs** for the booking's documents | | `pay` | Signed payment URL while a balance is outstanding, `null` once settled or canceled | | `payform` | The chosen payment form; `redirect: true` means the customer must complete payment on the gateway's page | | `parking` | The parking object as returned by [Parkings](/widget/parkings.md) — the booking's **currency** is `parking.currency` (ISO 4217) | | `token` | 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 | {% hint style="info" %} **Embedded widget users:** ParkFlow's embeddable widget re-emits this exact object as the `detail` of its `booking` DOM event — the one used for conversion tracking (Google Tag Manager, GA4). The event fires once, when the booking is created — **before** any online payment is completed — so map `transaction_id` to `code`, `value` to `Math.abs(detail.balance) / 100` and `currency` to `detail.parking.currency`, and treat it as a booking-placed (not booking-paid) conversion. Do not push the whole `detail` into your dataLayer: it carries the live booking `token` and signed document URLs. {% endhint %} ### 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="" path="/api/widget/v1/bookings/{booking}" method="delete" %} {% endopenapi %} Cancellation is subject to the operator's cancellation policy, and requires the booking token (or a customer-account token that owns the booking).