# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [7.0.0] - 2026-04-17

![Deploy on production](https://img.shields.io/badge/Deploy--on-production-green)

### Changed

- **BREAKING CHANGE** `BookingRequest.areaId` renamed to `BookingRequest.spaceId`. Type changed from `string` to `integer`. Obtain valid space IDs from the `spaces` array in the availability response time slots.


### Removed

- `AvailabilityTimeSlot.areas`: removed. Use `spaces` from the product data to obtain valid space IDs for booking.


## [6.4.0] - 2026-04-15

### Added

- `AvailabilityResponse.noAvailabilityCode`: new nullable string field, populated only when `times` is empty. Machine-readable code indicating why no availability was found. Known values:
  - `NO_AVAILABILITY` — no available slots for the requested parameters.
  - `NO_ELIGIBLE_PRODUCTS` — no products match the request.
  - `FILTERED_BY_OPERATOR_RULES` — all slots were filtered out by operator availability rules.
  - `FILTERED_BY_CAPACITY` — no slots satisfy the requested party size.
  - Clients should treat unknown values as a generic no-availability condition, as new values may be introduced without prior notice.


### Removed

- `AvailabilityResponse.noAvailabilityAction`: removed. Use `noAvailabilityReason` (human-readable) and the new `noAvailabilityCode` (machine-readable) instead.


## [6.3.0] - 2026-04-14

### Added

- `AvailabilityTimeSlot.requestReason`: new nullable string field, present only when `type` is `request`. Indicates why the time slot requires manual operator approval rather than instant confirmation. Possible values:
  - `fully_booked` — no real-time availability for this slot, but the operator is open to receiving enquiries.
  - `exceeds_auto_confirm` — availability exists but the requested party size exceeds the venue's auto-confirm threshold and requires explicit operator approval.
  - Clients should handle unknown values gracefully as new values may be introduced in future versions.
- `AvailabilityResponse.noAvailabilityReason`: new nullable string field, populated only when `times` is empty. Human-readable message explaining why no availability was found for the requested parameters.
- `Product.slug`: new nullable string field — aggregation slug identifier for the product.
- `PreorderPackage.slug`: new nullable string field — aggregation slug identifier for the package.
- `Menu.slug`: new nullable string field — aggregation slug identifier for the menu.


## [6.2.0] - 2026-04-01

### Added

- `Product.spaces`: new field on `GET /venues` and `GET /venues/{venueId}` responses. Each product now returns the list of spaces available within it, including physical data (`spaceName`, `description`, `floorLocation`, `facilities`, capacity layout fields) and space policies (`minimumSpend`, `occasionTypes`, `under18s`, `promotedEvents`, `accessibility`, `servesFood`).
- `Product.preOrderRequiredType`: enum specifying which type of preorder is required — `none`, `package`, `menu`, or `packageAndMenu`.
- `Product.depositRequired`: boolean indicating whether a deposit is required when booking a product.
- `AvailabilityRequest.children`: optional field for the number of children in the party. Note: not all TMS providers distinguish between adults and children — when unsupported, children may be added to the total party size or ignored.
- `AvailabilityRequest` space policy filters — new optional query parameters to filter time slots by space policy:
  - `minimumSpend`: maximum minimum spend (in pence); excludes slots above this threshold.
  - `under18s`: soft filter on the under-18s policy.
  - `occasionTypes`: filter by supported occasion type.
  - `promotedEvents`: soft filter on the promoted-events policy.
  - `accessibility`: filter by wheelchair accessibility.
  - `servesFood`: soft filter on the serves-food policy.
  - `includeUnavailable`: when `true`, filtered-out slots are included in the response with `unavailableReasons` populated instead of being excluded.
- `AvailabilityTimeSlot.product`: new object returned in each time slot containing the product's `id`, `name`, and `spaces` array. Space policies within this object (including `minimumSpend`) are pre-filtered to the requested date and time slot.
- `AvailabilityTimeSlot.areas`: list of available areas/zones for this time slot. Populated only for TMS providers that support area-based booking (e.g. Zonal). Pass the desired `id` as `areaId` when creating a booking.
- `AvailabilityTimeSlot.unavailableReasons`: present only when `includeUnavailable=true`; contains human-readable explanations for each failing policy filter.
- `BookingRequest.children`: optional field for the number of children included in the booking.
- `BookingRequest.areaId`: optional area/zone ID to target when creating a booking. Obtain valid IDs from `AvailabilityTimeSlot.areas`.
- `Booking.depositAmount`: deposit amount (float, in pence) captured from the TMS at reservation time.
- `Booking.area`: area or zone assigned to the booking, with `id` and `name` as reported by the TMS.
- New schemas: `SpaceCapacityRange`, `Area`, `BookingArea`.
- New shared component files: `common/VenueSpaces.yaml` (space schemas and policy types) and `common/Headers.yaml` (shared header parameter definitions).


### Changed

- `AvailabilityRequest.partySize` and `BookingRequest.partySize`: description clarified from "number of guests/people" to "number of adults".
- `CorrelationID` and `PartnerReference` header parameters refactored to reference `common/Headers.yaml` instead of being defined inline.


### Deprecated

- `AvailabilityTimeSlot.productId`: use `AvailabilityTimeSlot.product.id` instead.


## [6.1.0] - 2026-03-13

### Added

- Sparse fieldsets support via the `fields` query parameter on all GET endpoints. Request only the fields you need to reduce payload size and improve response times. See [Sparse Fieldsets](/resources/sparse-fieldsets) for details.
- `text/toon` response format support across all Bookings API endpoints that return a body. Set `Accept: text/toon` to receive responses in TOON (Terse Object-Oriented Notation) — a compact format that reduces token count by 30–60% compared to JSON. Fully opt-in; omitting the header continues to return standard JSON. See [TOON Format](/resources/toon-format) for details.
- `VenuePreorders`: added `preorders` field to `GET /venues` and `GET /venues/{venueId}` responses.


## [6.0.0] - 2026-02-26

### Added

- `VenuePreorders` schema: new wrapper object containing `packages` and `menus` arrays
- `ProductAvailabilityRules` schema: availability rules for a product grouped by source (`weekly`, `exceptions`, `rules`)
- `WeeklyRule` schema: weekly booking schedule, one entry per day of the week
- `RuleException` schema: date-specific availability exceptions imposed by the TMS
- `AvailabilityRule` schema: operator-defined availability rules per partner
- `AvailabilityRuleType` enum: `date_range`, `recurring`, `time_based`, `specific_dates`, `specific_dates_with_time`, `date_range_with_time`, `recurring_with_time`
- `RuleDataBase` and all discriminated subtypes: `DateRangeRuleData`, `RecurringRuleData`, `TimeBasedRuleData`, `SpecificDatesRuleData`, `SpecificDatesWithTimeRuleData`, `DateRangeWithTimeRuleData`, `RecurringWithTimeRuleData`
- `PreorderContainer` schema: container for all preorder items (`packages` → `PreorderPackageRequest`, `menus` → `PreorderMenuRequestV2`)
- `MenuItemOption` schema: configurable option for a menu item (field `value`)
- `MenuItem`: added fields `name`, `price`, `description`, `diet_types`, `allergens`, `configurable_options`, `type`, `subType`, `displayOrder`
- `MenuItemSelection`: added field `options` (array of `MenuItemOption`)
- `Booking.preorders.menus`: added field `submitted` (enum: `pre` / `post`)
- `PATCH /venues/bookings/{bookingId}`: new endpoint for partial booking updates via JSON Patch (RFC 6902)
- `JsonPatchOperation` schema supporting `add`, `remove`, `replace` operations
- `Product`: added field `preOrderRequired` (boolean)


### Changed

- `MenuItem.subGroupName` renamed to `subType`
- `POST /venues/{compositeId}/booking` response `201`: changed from `BookingResponse` to full `Booking` schema
- Terminology updated throughout: "RMS (Restaurant Management System)" → "TMS (Table Management System)"
- Security schemes consolidated: staging environments (`Staging`, `SandboxStaging`, `SandboxProduction`) removed; only `Production` and `Sandbox` remain
- Servers list reduced to `Production` (`https://api.bookabletech.com`) and `Sandbox` (`https://api-sandbox.bookabletech.com`)


### Removed

- `Venue.packages` (top-level array) — replaced by `Venue.preorders.packages`
- `Venue.menus` (top-level array) — replaced by `Venue.preorders.menus`
- `BookingRequest.preorderPackages` — replaced by `BookingRequest.preorders.packages`
- `BookingRequest.preorderMenus` — replaced by `BookingRequest.preorders.menus`
- Sandbox Staging server `https://api-sandbox-staging.bookabletech.com`
- 

## [5.1.0] - 2026-02-09

### Added

- `compositeId` query filter to the `GET /venues/bookings` endpoint.


## [5.0.0] - 2026-01-27

### Changed

**BREAKING CHANGE** in the following endpoints:

- `GET /venues/bookings`
- `GET /venues/bookings/{bookingId}`
- `PUT /venues/bookings/{bookingId}`
- **Changed**:
  - `company` field is now `venueGroupName`
  - `productType` field is now `productName`
- **Removed**:
  - `cursor` query parameter from `GET /venues/bookings`
  - `cursor` field from response from `GET /venues/bookings`
- **Added**: Standard pagination parameters in `GET /venues/bookings`:
  - `pageNumber` (integer, default: 1, min: 1) - The page index to return
  - `pageSize` (integer, default: 20, min: 1, max: 100) - Items per pageNumber
  - `meta` object with pagination metadata:

```
"meta": {
      "currentPage": 1,
      "pageSize": 20,
      "totalItems": 26,
      "totalPages": 2
  }
```
- **Migration Guide**:

```
  - GET /venues/bookings?cursor=abc123
  + GET /venues/bookings?pageNumber=1&pageSize=20
```
- `GET /venues/{compositeId}/availability`
- **Added**: preOrderItems


## [4.12.0] - 2026-01-19

### Added

- `venueGroupName` field on venue object in `GET /venues` and `GET /venues/{venueId}` endpoints.


## [4.11.1] - 2026-01-13

### Changed

- Remove constraints on bookingRules.


## [4.10.0] - 2025-12-05

### Changed

- `X-Booking-Source` header in `POST venues/bookings` is now an enumeration.


## [4.9.0] - 2025-12-03

### Added

- Added sorting capabilities to `GET /venues` endpoint:
**New Query Parameters**
  - **`sortBy`** (optional): Field to sort results by
    - `default` - Sort by composite ID (venue_group_id, rms_id, venue_id)
    - `name` - Sort alphabetically by venue name
    - `city` - Sort by city name, then venue name
    - `area` - Sort by area, then venue name
    - `venueGroup` - Sort by venue group name (requires venueGroupName filter)
    - `relevance` - Sort by semantic similarity using vector embeddings (requires embedding filters)
  - **`sortDirection`** (optional): Sort direction
    - `ASC` - Ascending (A-Z, 0-9, most to least similar)
    - `DESC` - Descending (Z-A, 9-0, least to most similar)


## [4.8.0] - 2025-12-01

### Added

- Operator Booking Id and Partner Booking Id support to `GET venues/bookings` by `operatorBookingId` and `partnerBookingId` fields
- Partner Booking Id support to `POST venues/bookings` by`partnerBookingId` field


### Changed

- `Reference` field is deprecated in `GET venues/bookings` ; use `operatorBookingId` instead.


## [4.7.0] - 2025-10-13

### Added

- Booking Overrides support to `GET venues` and  `GET venues\{venueId}`  by `bookingOverrides` field
- Operator availability rule support to `GET venues` and  `GET venues\{venueId}`  by `operatorAvailabilityRules` field


## [4.6.0] - 2025-10-13

### Added

- Preorders support to `GET venues/bookings` by `preorders` field
- Preorder menus support to `GET venues/bookings` by `preorderMenus` field


## [4.5.0] - 2025-09-29

### Added

- Possibility to filter by `date` and `time` within the `GET /venues` endpoint.


## [4.4.0] - 2025-09-26

### Added

- `X-Booking-Source` header which identifies the source or channel through which the booking was created.


## [4.3.0] - 2025-09-22

### Added

- `X-Partner-Reference` header is now mandatory on all the endpoints for Bookable Agent clients.


## [4.2.0] - 2025-09-15

### Added

- noAvailabilityAction support to `GET venues/:venueId/availability`
- autoConfirmRule support to `GET venues/:venueId/availability`


## [4.1.0] - 2025-09-08

### Added

- Preorder menu support to `GET venues` and `GET venues/:venueId` by `menus` field
- Preorder menu support to `POST venues/:venueId/booking` by `preorderMenus` field
- Preorder menu email triggering on submit booking
- Preorder menu support to `GET venues/bookings/:bookingId` by `preorderMenus` field


### Removed

- `packageId` field on `POST venues/:venueId/booking` request


## [4.0.0] - 2025-09-02

### Added

- **BREAKING CHANGE:** Booking PUT request now requires `compositeId`


### Removed

- `GET /venues/products/{compositeId}` endpoint


## [3.4.0] - 2025-08-20

### Added

- Venue packages detail by `packages`
- Booking POST request now accepts `packageId`
- Booking POST request now accepts `preorders`


## [3.3.0] - 2025-08-13

### Added

- Endpoint to get a venue product detail by `compositeId`


## [3.2.0] - 2025-08-12

### Changed

- Venue Schema Fields: Deprecated `is_active` and `created_at` fields in venue responses
- Booking POST request now accepts `null` value for `duration` field


## [3.1.0] - 2025-07-30

### Added

- Booking POST request includes admin_notes, comments & labels field


## [3.0.0] - 2025-07-29

### Added

- Standardized error handling across all endpoints


### Changed

- **BREAKING CHANGE**: Modified venue composition - products are now contained within the venue structure


## [2.3.0] - 2025-07-02

### Added

- **X-Partner-Reference** header for Bookable Agents. The header specifies the partner reference for whom the booking is being made.


## [2.2.0] - 2025-06-06

### Added

- Endpoint to update an existing booking by its unique ID
- Endpoint to cancel a booking by its unique ID


## [2.1.0] - 2025-05-30

### Added

- Endpoint to retrieve a paginated list of **bookings**
- Endpoint to retrieve a specific **booking** by its unique ID


## [2.0.0] - 2025-05-16

### Added

- Support for paginated **venue** listings


### Changed

- Rename **shut** into **bookingCutoff**


## [1.2.0] - 2025-05-14

### Added

- **bookingRules**: Insert booking rules on Venue to show information about the opening/ close time, max min number of people, and other


## [1.1.1] - 2025-05-08

### Fixed

- Validation on require field (#TS-948)


## [1.1.0] - 2025-05-02

### Unified API

- Add the unified api


### Added

- **VenueId**: Introduced the concept of composite Id to manage id into the system
- **type** into avalability response: Specifies how an operators time slot can be handled.
- **type** into revervation request
- **product_name**: the name of product offer from venue