> ## Documentation Index
> Fetch the complete documentation index at: https://exsited.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Bookings

> Create, preview, change and delete bookings, and read their lines, billing, invoices, payments and PDFs.

A booking is an order whose lines reserve a labour for set booking times. These endpoints create, preview, change and delete bookings, update their information, lines and billing preferences, and read their invoices, payments, fulfillments, KPIs, custom objects and PDFs. This area has 33 endpoints, each available in all seven SDKs.

> [!WARNING]
>
> **Deleting a booking deletes whatever order has that `id`, of any type.** Check the `id` before you call it. The delete returns no body, and a later read of the `id` returns `404`.

## At a glance

| Endpoint | Method | Path | What it does |
| - | - | - | - |
| [List bookings](https://exsited.mintlify.site/api-reference/bookings/list-bookings.md) | GET | `/booking` | Lists bookings one page at a time. |
| [Retrieve a booking](https://exsited.mintlify.site/api-reference/bookings/retrieve-a-booking.md) | GET | `/booking/{booking_id}` | Returns one booking with its lines, billing preferences and KPIs. |
| [Create a booking](https://exsited.mintlify.site/api-reference/bookings/create-a-booking.md) | POST | `/booking` | Creates a booking and returns it under `booking`. |
| [Preview a booking](https://exsited.mintlify.site/api-reference/bookings/preview-a-booking.md) | POST | `/booking/preview` | Previews a booking without creating it; the response holds no prices. |
| [Delete a booking](https://exsited.mintlify.site/api-reference/bookings/delete-a-booking.md) | DELETE | `/booking/{booking_id}` | Deletes a booking and returns no body. |
| [List booking notes](https://exsited.mintlify.site/api-reference/bookings/list-booking-notes.md) | GET | `/booking/notes` | Lists the notes of every order, one page at a time. |
| [Retrieve a booking's billing preferences](https://exsited.mintlify.site/api-reference/bookings/retrieve-a-bookings-billing-preferences.md) | GET | `/booking/{booking_id}/billing_preferences` | Returns a booking's billing preferences under `order.billing_preferences`. |
| [Update a booking's billing preferences](https://exsited.mintlify.site/api-reference/bookings/update-a-bookings-billing-preferences.md) | PATCH | `/booking/{booking_id}/billing_preferences` | Changes a booking's billing preferences and returns the whole booking. |
| [Change a booking](https://exsited.mintlify.site/api-reference/bookings/change-a-booking.md) | POST | `/booking/{booking_id}/change` | Changes a booking from an effective date. |
| [Preview a booking change](https://exsited.mintlify.site/api-reference/bookings/preview-a-booking-change.md) | POST | `/booking/{booking_id}/change/preview` | Shows the result of a booking change without making it. |
| [Retrieve a booking's information](https://exsited.mintlify.site/api-reference/bookings/retrieve-a-bookings-information.md) | GET | `/booking/{booking_id}/information` | Returns a booking's header under `order`. |
| [Update a booking's information](https://exsited.mintlify.site/api-reference/bookings/update-a-bookings-information.md) | PATCH | `/booking/{booking_id}/information` | Changes a booking's header and returns the whole booking. |
| [Retrieve a booking's lines](https://exsited.mintlify.site/api-reference/bookings/retrieve-a-bookings-lines.md) | GET | `/booking/{booking_id}/lines` | Returns a booking with its lines under `order.lines`. |
| [Retrieve a booking line](https://exsited.mintlify.site/api-reference/bookings/retrieve-a-booking-line.md) | GET | `/booking/{booking_id}/lines/{line_uuid}` | Returns one line of a booking under `order_line`. |
| [Update a booking line](https://exsited.mintlify.site/api-reference/bookings/update-a-booking-line.md) | PATCH | `/booking/{booking_id}/lines/{line_uuid}` | Changes one line of a booking and returns the whole booking. |
| [Update a booking line's billing preferences](https://exsited.mintlify.site/api-reference/bookings/update-a-booking-lines-billing-preferences.md) | PATCH | `/booking/{booking_id}/lines/{line_uuid}/billing_preferences` | Changes the billing settings of one line and returns the whole booking. |
| [List a booking's custom objects](https://exsited.mintlify.site/api-reference/bookings/list-a-bookings-custom-objects.md) | GET | `/booking/{booking_id}/custom_objects` | Lists the custom objects defined for orders, one page at a time. |
| [Retrieve a booking custom object](https://exsited.mintlify.site/api-reference/bookings/retrieve-a-booking-custom-object.md) | GET | `/booking/{booking_id}/custom_objects/{custom_object_id}` | Returns one custom object with this booking's instances of it. |
| [Retrieve a booking custom object instance](https://exsited.mintlify.site/api-reference/bookings/retrieve-a-booking-custom-object-instance.md) | GET | `/booking/{booking_id}/custom_objects/{custom_object_id}/instances/{instance_id}` | Returns one instance of a custom object on a booking. |
| [List a booking's custom objects (alternate path)](https://exsited.mintlify.site/api-reference/bookings/list-a-bookings-custom-objects-alternate-path.md) | GET | `/booking/{booking_id}/custom_objects_instances` | Lists the custom objects defined for orders, by the `custom_objects_instances` path. |
| [Retrieve a booking custom object (alternate path)](https://exsited.mintlify.site/api-reference/bookings/retrieve-a-booking-custom-object-alternate-path.md) | GET | `/booking/{booking_id}/custom_objects_instances/{custom_object_id}` | Returns one custom object with this booking's instances, by the `custom_objects_instances` path. |
| [Retrieve a booking custom object instance (alternate path)](https://exsited.mintlify.site/api-reference/bookings/retrieve-a-booking-custom-object-instance-alternate-path.md) | GET | `/booking/{booking_id}/custom_objects_instances/{custom_object_id}/instances/{instance_id}` | Returns one custom object instance, by the `custom_objects_instances` path. |
| [List a booking's invoices](https://exsited.mintlify.site/api-reference/bookings/list-a-bookings-invoices.md) | GET | `/booking/{booking_id}/invoices` | Lists the invoices raised for a booking, one page at a time. |
| [List a booking's item fulfillments](https://exsited.mintlify.site/api-reference/bookings/list-a-bookings-item-fulfillments.md) | GET | `/booking/{booking_id}/item_fulfillments` | Lists the item fulfillments of a booking, one page at a time. |
| [Retrieve a booking item fulfillment](https://exsited.mintlify.site/api-reference/bookings/retrieve-a-booking-item-fulfillment.md) | GET | `/booking/{booking_id}/item_fulfillments/{fulfillment_id}` | Returns one item fulfillment under `item_fulfillment`. |
| [Retrieve a booking's KPIs](https://exsited.mintlify.site/api-reference/bookings/retrieve-a-bookings-kpis.md) | GET | `/booking/{booking_id}/kpis` | Returns a booking's key figures under `order_kpis`. |
| [List a booking's payment methods](https://exsited.mintlify.site/api-reference/bookings/list-a-bookings-payment-methods.md) | GET | `/booking/{booking_id}/payment_methods` | Lists the payment methods bound to a booking. |
| [Retrieve a booking payment method](https://exsited.mintlify.site/api-reference/bookings/retrieve-a-booking-payment-method.md) | GET | `/booking/{booking_id}/payment_methods/{payment_method_ref}` | Returns one payment method bound to a booking, found by its reference. |
| [List a booking's payments](https://exsited.mintlify.site/api-reference/bookings/list-a-bookings-payments.md) | GET | `/booking/{booking_id}/payments` | Lists the payments made against a booking's invoices, one page at a time. |
| [Retrieve a booking payment](https://exsited.mintlify.site/api-reference/bookings/retrieve-a-booking-payment.md) | GET | `/booking/{booking_id}/payments/{payment_id}` | Returns one payment under `payment`. |
| [Retrieve a booking's PDF links](https://exsited.mintlify.site/api-reference/bookings/retrieve-a-bookings-pdf-links.md) | GET | `/booking/{booking_id}/pdf` | Returns links to a booking's PDF under `order.pdf`. |
| [List a booking's quote partial invoices](https://exsited.mintlify.site/api-reference/bookings/list-a-bookings-quote-partial-invoices.md) | GET | `/booking/{booking_id}/quote_partial_invoices` | Lists the deposit and instalment invoices of a converted quote. |
| [Retrieve a booking shipping line PDF](https://exsited.mintlify.site/api-reference/bookings/retrieve-a-booking-shipping-line-pdf.md) | GET | `/booking/{booking_id}/shipping_pdf/{shipping_line_id}` | Returns the PDF of one shipping line of a booking. |

## Before you call

Register your API credentials once when your app starts, as shown in
[Authentication](https://exsited.mintlify.site/authentication.md). Every SDK sample on these pages then gets its client in one line.
With cURL, send the access token in an `Authorization` header: `Authorization: Bearer $ACCESS_TOKEN`.

## Things to know

* **Reads, updates and delete under `/booking/{booking_id}` work on any order.** They do not check the order's type. Change a booking and Preview a booking change accept only a booking-type order.
* **Each line of a new booking needs a labour and its booking times.** The rest of the body is the order body, under `order`: `account_id`, `name` and `lines`.
* **Most request bodies go under `order`; the change bodies go under `booking`.** The line billing update takes `order.line.item_properties`, not `billing_preferences`.
* **Updates return the whole booking under `order`.** Some single reads use their own keys: `order_line`, `custom_object`, `item_fulfillment`, `order_kpis` and `payment`; the rest return under `order`.
* **Listings page by cursor.** Records are under `data`; pass `limit` and the previous page's `pagination.next_cursor` as `cursor`, and stop when `has_more` is `false`.
* **There is no per-booking notes listing.** List booking notes returns the notes of every order, and `/booking/{booking_id}/notes` is refused.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.