Booking Flow

Area Bookings

An AreaBooking is a confirmed reservation of one or more BookableAreas — for example a pool cabana, treatment pod, or poolside lounger — against a customer order. Area bookings are created via the basket pipeline when an AreaBookingType is added to a basket, and remain the source of truth for the reservation throughout its lifecycle.

The AreaBooking object

Attributes

idobject-idrequired
The ID of the area booking.
area_booking_type_idobject-idrequired
The ID of the AreaBookingType this booking is for.
area_booking_type_namestringrequired
The name of the AreaBookingType at the time the booking was made. This is captured at booking time so the value remains stable even if the parent type is later renamed.
order_idobject-idrequired
The ID of the order this area booking belongs to.
order_refstringrequired
The human-readable reference of the parent order.
order_item_idobject-idrequired
The ID of the OrderItem this area booking represents.
order_labelsobject[]required
order_is_lockedbooleanrequired
Whether the parent order has been locked from further changes.
order_locked_atdate-timeoptionalnullable
The date and time the parent order was locked, if it has been.
statusstringrequired
The current status of the area booking.
Possible values:confirmedin_progressnew
stagestringoptionalnullable
The check-in stage of the parent order.
Possible values:arrivedin_treatmentchecked_outnot_arrived
customer_idobject-idrequired
The ID of the customer the booking is for.
emailstringrequired
The customer's email address.
phonestringrequired
The customer's phone number.
first_namestringrequired
The customer's first name.
last_namestringrequired
The customer's last name.
area_idsstring[]required
The IDs of the BookableAreas assigned to this booking.
areasobject[]required
Summary records for each assigned BookableArea.
guestsobject[]required
start_timedate-timerequired
When the booking starts.
end_timedate-timerequired
When the booking ends.
durationintegerrequired
The duration of the booking in minutes.
end_bufferintegerrequired
Minutes blocked out after the booking for changeover or cleaning.
is_group_bookingbooleanrequired
Whether the parent order has more than one guest.
has_outstanding_balancebooleanrequired
Whether the parent order still has unpaid balance.
has_notesbooleanrequired
Whether the parent order has any notes.
has_special_requestsbooleanrequired
Whether the parent order has special requests recorded.
product_codestringrequired
A custom product code for the AreaBookingType.
is_part_of_packagebooleanrequired
Whether this booking was sold as part of a Package.
package_product_codestringoptional
The product code of the parent Package, if any.
organisation_iduuidrequired
The ID of the organisation the booking belongs to.
site_iduuidrequired
The ID of the site the booking belongs to.
created_atrequired
updated_atrequired

{
  "id": "64a9f3b2c3d8e1f4a5b6c7d8",
  "area_booking_type_id": "64a9f3b2c3d8e1f4a5b6c7d8",
  "area_booking_type_name": "Pool Cabana",
  "order_id": "64a9f3b2c3d8e1f4a5b6c7d8",
  "order_ref": "TRY00",
  "order_item_id": "64a9f3b2c3d8e1f4a5b6c7d8",
  "order_labels": [
    "string"
  ],
  "order_is_locked": false,
  "order_locked_at": "2026-01-15T09:30:00+00:00",
  "status": "confirmed",
  "stage": "arrived",
  "customer_id": "64a9f3b2c3d8e1f4a5b6c7d8",
  "email": "janedoe@example.com",
  "phone": "+447727123456",
  "first_name": "Jane",
  "last_name": "Doe",
  "area_ids": [
    "64a9f3b2c3d8e1f4a5b6c7d8"
  ],
  "areas": [
    {
      "id": "64a9f3b2c3d8e1f4a5b6c7d8",
      "name": "Hot Tub 1"
    }
  ],
  "guests": [
    "string"
  ],
  "start_time": "2019-01-15T12:00:00+01:00",
  "end_time": "2019-01-15T13:00:00+01:00",
  "duration": 60,
  "end_buffer": 15,
  "is_group_booking": false,
  "has_outstanding_balance": false,
  "has_notes": false,
  "has_special_requests": false,
  "product_code": "SPA-CABANA",
  "is_part_of_package": false,
  "package_product_code": "string",
  "organisation_id": "00000000-0000-0000-0000-000000000000",
  "site_id": "00000000-0000-0000-0000-000000000000",
  "created_at": "string",
  "updated_at": "string"
}

get/shop/area-bookings/{areaBookingId}

Retrieve an AreaBooking

getAreaBooking

Retrieves a single AreaBooking by ID. Use this when you have an AreaBooking ID from createBasketAreaBookingItem, a webhook payload, or a calendar view and need the canonical reservation record — including which BookableAreas are assigned, the customer details, and the parent order context.

Path parameters

areaBookingIdobject-idrequired
The unique identifier of the AreaBooking. An area booking is a reservation of one or more BookableAreas for a contiguous period of time, typically created via the basket as part of an order.

Responses

200
The AreaBooking was successfully retrieved.
401
The user is unauthenticated
403
The authenticated user does not have permission.
404
The resource couldn't be found

curl "https://api.playground.try.be/shop/area-bookings/5e932c0901d210625e3a8766" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

const response = await fetch('https://api.playground.try.be/shop/area-bookings/5e932c0901d210625e3a8766', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    Accept: 'application/json',
  },
})

if (!response.ok) {
  throw new Error(`Trybe API ${response.status}: ${await response.text()}`)
}

const data = await response.json()

import httpx

response = httpx.get(
    "https://api.playground.try.be/shop/area-bookings/5e932c0901d210625e3a8766",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Accept": "application/json",
    },
)
response.raise_for_status()
data = response.json()

<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.playground.try.be/shop/area-bookings/5e932c0901d210625e3a8766', [
    'headers' => [
        'Authorization' => 'Bearer YOUR_API_KEY',
        'Accept' => 'application/json',
    ],
]);

$data = json_decode($response->getBody(), true);

package main

import (
	"encoding/json"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.playground.try.be/shop/area-bookings/5e932c0901d210625e3a8766", nil)
	req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
	req.Header.Set("Accept", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	var data map[string]interface{}
	json.NewDecoder(resp.Body).Decode(&data)
}

The `AreaBooking` was successfully retrieved.

{
  "data": {
    "id": "64a9f3b2c3d8e1f4a5b6c7d8",
    "area_booking_type_id": "64a9f3b2c3d8e1f4a5b6c7d8",
    "area_booking_type_name": "Pool Cabana",
    "order_id": "64a9f3b2c3d8e1f4a5b6c7d8",
    "order_ref": "TRY00",
    "order_item_id": "64a9f3b2c3d8e1f4a5b6c7d8",
    "order_labels": [
      {
        "id": "64a9f3b2c3d8e1f4a5b6c7d8",
        "color": "#FF0000",
        "name": "VIP",
        "order_id": "64a9f3b2c3d8e1f4a5b6c7d8"
      }
    ],
    "order_is_locked": false,
    "order_locked_at": "2026-01-15T09:30:00+00:00",
    "status": "confirmed",
    "stage": "arrived",
    "customer_id": "64a9f3b2c3d8e1f4a5b6c7d8",
    "email": "janedoe@example.com",
    "phone": "+447727123456",
    "first_name": "Jane",
    "last_name": "Doe",
    "area_ids": [
      "64a9f3b2c3d8e1f4a5b6c7d8"
    ],
    "areas": [
      {
        "id": "64a9f3b2c3d8e1f4a5b6c7d8",
        "name": "Hot Tub 1"
      }
    ],
    "guests": [
      {
        "id": "5dcb47800000000000000000",
        "checked_in_at": "2025-10-01T12:00:00+00:00",
        "checked_out_at": "2025-10-01T16:30:00+00:00",
        "customer_id": "5f8a1b2c-9d3e-4a5b-8c6d-7e8f9a0b1c2d",
        "email": "jane.doe@example.com",
        "first_name": "Jane",
        "intake_form_submission_id": "5dcb47800000000000000010",
        "intake_form_complete": false,
        "is_lead_booker": true,
        "last_name": "Doe",
        "name": "Jane Doe"
      }
    ],
    "start_time": "2019-01-15T12:00:00+01:00",
    "end_time": "2019-01-15T13:00:00+01:00",
    "duration": 60,
    "end_buffer": 15,
    "is_group_booking": false,
    "has_outstanding_balance": false,
    "has_notes": false,
    "has_special_requests": false,
    "product_code": "SPA-CABANA",
    "is_part_of_package": false,
    "package_product_code": "string",
    "organisation_id": "00000000-0000-0000-0000-000000000000",
    "site_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-02-04T12:00:00+01:00",
    "updated_at": "2025-02-04T12:00:00+01:00"
  }
}

{
  "message": "Unauthenticated"
}

{
  "message": "This action is unauthorized."
}

{
  "message": "The requested resource could not be found"
}

put/shop/area-bookings/{areaBookingId}

Update an AreaBooking

updateAreaBooking

Updates an existing AreaBooking — typically to reassign the booked areas, reschedule the time slot, adjust the duration, or progress the parent order through its check-in stages.

The update is routed through the basket / availability layer, so every change is validated against the same rules as a fresh booking: overlapping area reservations, capacity, site opening hours, and the parent AreaBookingType's permitted areas are all enforced. Users with the reservations.override-rules permission can bypass these checks server-side; everyone else will receive a 400 Bad Request describing the conflict.

When only stage is supplied the booking slot is left untouched and the change is applied to the parent order, saving the availability round-trip entirely.

Path parameters

areaBookingIdobject-idrequired
The unique identifier of the AreaBooking. An area booking is a reservation of one or more BookableAreas for a contiguous period of time, typically created via the basket as part of an order.

Request body

area_idsstring[]optionalnullable
Replace the set of BookableAreas assigned to this booking. Each area must permit the parent AreaBookingType and must be available for the booking's time slot.
start_timedate-timeoptional
Move the booking so it starts at this date and time. If end_time is not also supplied it will be recalculated from the existing duration. Must be an RFC 3339 timestamp with offset.
end_timedate-timeoptional
Move the booking so it ends at this date and time. Must be an RFC 3339 timestamp with offset and must be after start_time.
timedate-timeoptionalDeprecated
Deprecated. Legacy alias for start_time. Will be removed once all calendar drag-and-drop clients have migrated.
durationintegeroptional
Set the booking duration in minutes. Must be positive. When only duration is supplied the booking's end_time is recalculated from the current start_time.
stagestringoptionalnullable
Move the parent order through its check-in flow. When stage is the only field provided the availability layer is skipped entirely. Pass null to clear the stage back to the default.
Possible values:arrivedin_treatmentchecked_outnot_arrived

Responses

200
The AreaBooking was successfully updated.
400
The request failed.
401
The user is unauthenticated
403
The authenticated user does not have permission.
404
The resource couldn't be found
422
The request didn't pass validation

curl -X PUT "https://api.playground.try.be/shop/area-bookings/5e932c0901d210625e3a8766" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "area_ids": [
    "5e932c0901d210625e3a8766"
  ],
  "start_time": "2026-06-01T10:00:00+01:00",
  "end_time": "2026-06-01T12:00:00+01:00",
  "time": "2026-06-01T10:00:00+01:00",
  "duration": 60,
  "stage": "arrived"
}'

const response = await fetch('https://api.playground.try.be/shop/area-bookings/5e932c0901d210625e3a8766', {
  method: 'PUT',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
    Accept: 'application/json',
  },
  body: JSON.stringify({
    "area_ids": [
      "5e932c0901d210625e3a8766"
    ],
    "start_time": "2026-06-01T10:00:00+01:00",
    "end_time": "2026-06-01T12:00:00+01:00",
    "time": "2026-06-01T10:00:00+01:00",
    "duration": 60,
    "stage": "arrived"
  }),
})

if (!response.ok) {
  throw new Error(`Trybe API ${response.status}: ${await response.text()}`)
}

const data = await response.json()

import httpx

response = httpx.put(
    "https://api.playground.try.be/shop/area-bookings/5e932c0901d210625e3a8766",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Accept": "application/json",
        "Content-Type": "application/json",
    },
    json={
        "area_ids": [
            "5e932c0901d210625e3a8766"
        ],
        "start_time": "2026-06-01T10:00:00+01:00",
        "end_time": "2026-06-01T12:00:00+01:00",
        "time": "2026-06-01T10:00:00+01:00",
        "duration": 60,
        "stage": "arrived"
    },
)
response.raise_for_status()
data = response.json()

<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('PUT', 'https://api.playground.try.be/shop/area-bookings/5e932c0901d210625e3a8766', [
    'headers' => [
        'Authorization' => 'Bearer YOUR_API_KEY',
        'Accept' => 'application/json',
        'Content-Type' => 'application/json',
    ],
    'json' => [
            'area_ids' => [
                '5e932c0901d210625e3a8766'
            ],
            'start_time' => '2026-06-01T10:00:00+01:00',
            'end_time' => '2026-06-01T12:00:00+01:00',
            'time' => '2026-06-01T10:00:00+01:00',
            'duration' => 60,
            'stage' => 'arrived'
        ],
]);

$data = json_decode($response->getBody(), true);

package main

import (
	"bytes"
	"encoding/json"
	"net/http"
)

func main() {
	payload, _ := json.Marshal(map[string]interface{}{
		"area_ids": []interface{}{
			"5e932c0901d210625e3a8766",
		},
		"start_time": "2026-06-01T10:00:00+01:00",
		"end_time": "2026-06-01T12:00:00+01:00",
		"time": "2026-06-01T10:00:00+01:00",
		"duration": 60,
		"stage": "arrived",
	})
	req, _ := http.NewRequest("PUT", "https://api.playground.try.be/shop/area-bookings/5e932c0901d210625e3a8766", bytes.NewBuffer(payload))
	req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
	req.Header.Set("Accept", "application/json")
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	var data map[string]interface{}
	json.NewDecoder(resp.Body).Decode(&data)
}

The `AreaBooking` was successfully updated.

{
  "data": {
    "id": "64a9f3b2c3d8e1f4a5b6c7d8",
    "area_booking_type_id": "64a9f3b2c3d8e1f4a5b6c7d8",
    "area_booking_type_name": "Pool Cabana",
    "order_id": "64a9f3b2c3d8e1f4a5b6c7d8",
    "order_ref": "TRY00",
    "order_item_id": "64a9f3b2c3d8e1f4a5b6c7d8",
    "order_labels": [
      {
        "id": "64a9f3b2c3d8e1f4a5b6c7d8",
        "color": "#FF0000",
        "name": "VIP",
        "order_id": "64a9f3b2c3d8e1f4a5b6c7d8"
      }
    ],
    "order_is_locked": false,
    "order_locked_at": "2026-01-15T09:30:00+00:00",
    "status": "confirmed",
    "stage": "arrived",
    "customer_id": "64a9f3b2c3d8e1f4a5b6c7d8",
    "email": "janedoe@example.com",
    "phone": "+447727123456",
    "first_name": "Jane",
    "last_name": "Doe",
    "area_ids": [
      "64a9f3b2c3d8e1f4a5b6c7d8"
    ],
    "areas": [
      {
        "id": "64a9f3b2c3d8e1f4a5b6c7d8",
        "name": "Hot Tub 1"
      }
    ],
    "guests": [
      {
        "id": "5dcb47800000000000000000",
        "checked_in_at": "2025-10-01T12:00:00+00:00",
        "checked_out_at": "2025-10-01T16:30:00+00:00",
        "customer_id": "5f8a1b2c-9d3e-4a5b-8c6d-7e8f9a0b1c2d",
        "email": "jane.doe@example.com",
        "first_name": "Jane",
        "intake_form_submission_id": "5dcb47800000000000000010",
        "intake_form_complete": false,
        "is_lead_booker": true,
        "last_name": "Doe",
        "name": "Jane Doe"
      }
    ],
    "start_time": "2019-01-15T12:00:00+01:00",
    "end_time": "2019-01-15T13:00:00+01:00",
    "duration": 60,
    "end_buffer": 15,
    "is_group_booking": false,
    "has_outstanding_balance": false,
    "has_notes": false,
    "has_special_requests": false,
    "product_code": "SPA-CABANA",
    "is_part_of_package": false,
    "package_product_code": "string",
    "organisation_id": "00000000-0000-0000-0000-000000000000",
    "site_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2025-02-04T12:00:00+01:00",
    "updated_at": "2025-02-04T12:00:00+01:00"
  }
}

{
  "message": "string"
}

{
  "message": "Unauthenticated"
}

{
  "message": "This action is unauthorized."
}

{
  "message": "The requested resource could not be found"
}

{
  "errors": {},
  "message": "The request didn't pass validation"
}