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.

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	GET	/booking	Lists bookings one page at a time.
Retrieve a booking	GET	/booking/{booking_id}	Returns one booking with its lines, billing preferences and KPIs.
Create a booking	POST	/booking	Creates a booking and returns it under booking.
Preview a booking	POST	/booking/preview	Previews a booking without creating it; the response holds no prices.
Delete a booking	DELETE	/booking/{booking_id}	Deletes a booking and returns no body.
List booking notes	GET	/booking/notes	Lists the notes of every order, one page at a time.
Retrieve a booking’s billing preferences	GET	/booking/{booking_id}/billing_preferences	Returns a booking’s billing preferences under order.billing_preferences.
Update a booking’s billing preferences	PATCH	/booking/{booking_id}/billing_preferences	Changes a booking’s billing preferences and returns the whole booking.
Change a booking	POST	/booking/{booking_id}/change	Changes a booking from an effective date.
Preview a booking change	POST	/booking/{booking_id}/change/preview	Shows the result of a booking change without making it.
Retrieve a booking’s information	GET	/booking/{booking_id}/information	Returns a booking’s header under order.
Update a booking’s information	PATCH	/booking/{booking_id}/information	Changes a booking’s header and returns the whole booking.
Retrieve a booking’s lines	GET	/booking/{booking_id}/lines	Returns a booking with its lines under order.lines.
Retrieve a booking line	GET	/booking/{booking_id}/lines/{line_uuid}	Returns one line of a booking under order_line.
Update a booking line	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	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	GET	/booking/{booking_id}/custom_objects	Lists the custom objects defined for orders, one page at a time.
Retrieve a booking custom object	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	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)	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)	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)	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	GET	/booking/{booking_id}/invoices	Lists the invoices raised for a booking, one page at a time.
List a booking’s item fulfillments	GET	/booking/{booking_id}/item_fulfillments	Lists the item fulfillments of a booking, one page at a time.
Retrieve a booking item fulfillment	GET	/booking/{booking_id}/item_fulfillments/{fulfillment_id}	Returns one item fulfillment under item_fulfillment.
Retrieve a booking’s KPIs	GET	/booking/{booking_id}/kpis	Returns a booking’s key figures under order_kpis.
List a booking’s payment methods	GET	/booking/{booking_id}/payment_methods	Lists the payment methods bound to a booking.
Retrieve a booking payment method	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	GET	/booking/{booking_id}/payments	Lists the payments made against a booking’s invoices, one page at a time.
Retrieve a booking payment	GET	/booking/{booking_id}/payments/{payment_id}	Returns one payment under payment.
Retrieve a booking’s PDF links	GET	/booking/{booking_id}/pdf	Returns links to a booking’s PDF under order.pdf.
List a booking’s quote partial invoices	GET	/booking/{booking_id}/quote_partial_invoices	Lists the deposit and instalment invoices of a converted quote.
Retrieve a booking shipping line PDF	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. 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.