Skip to content
/
Create an order — one or...

Listings API V1 (2.0.0)

Overview

The Listings API V1 is a venue-aggregated discovery interface.

The response root carries meta and listings[]. Each entry in listings[] is a ListingGroup — one per operator (venue-group / chain), carrying a groupName and an items[] array.

Each item represents a single venue (or a standalone event when no venue is known): it carries the venue name, a location, and a capabilities[] array. Each entry in capabilities[] is a Listing with exactly one capability (table_reservation or event_ticket), and carries its own media[]. A venue that also hosts a ticketed event therefore yields a single item with two capabilities — one for the venue, one for the event.

All bookable units (venue products, event ticket types, future capability types) are unified under a single bookableProducts[] array. Every entry is a single Bookable shape; capability-specific fields are nullable and the parent Listing's capability sets the context.

Temporal information (venue opening hours, event occurrences, blackout dates) is unified under a single availabilityOccurrence[] field of CalendarRules. Both capabilities use the same shape.

Pre-order assets (packages, menus) are unified under a single preorders container — applicable to either capability when the listing supports pre-orders.

ID formats — two distinct identifiers, named apart on purpose

listingId (Listing.id, as returned in /v1/listings and taken as the path parameter on GET /v1/listings/{listingId}) identifies a venue or a standalone event. It is 3 segments: {VenueGroupId}|{RmsSlug}|{ResourceId}. For a hybrid entity the event-side row uses the EventExt's own resource id (different RmsSlug + ResourceId) so the two rows are unambiguous.

compositeId (Bookable.compositeId — a specific bookable product/ticket type, used in bookableProducts[], and as the compositeId in /v1/availabilities and /v1/orders) is 4 segments: {VenueGroupId}|{RmsSlug}|{ResourceId}|{AdditionalId}.

These are two different identifiers for two different things, not two interchangeable formats for the same one — a listingId never appears where a compositeId is expected, or vice versa.

Download OpenAPI description
ListingsApiV1.json
ListingsApiV1.yaml
Overview
URL
https://www.bookabletech.com
Bookable
hello@bookabletech.com
Languages
Servers
Live
https://api.bookabletech.com
Sandbox
https://api-sandbox.bookabletech.com

Listings

Discover and retrieve bookable listings

Operations

Orders

Create and manage orders

Operations

Create an order — one or more independent bookings, across any platform

Request

Creates an order containing one or more bookings. Each item is resolved and booked independently — there is no cross-item transaction. A failure on one item (e.g. the venue/event on one platform is fully booked) does not block or roll back the others. The response carries one OrderItemResult per requested item, preserving request order — mirroring how POST /v1/availabilities reports one result per compositeId.

Because every item is self-sufficient via its own compositeId (which embeds VenueGroupId + RmsSlug), a single order can span multiple venues and even multiple RMS platforms (e.g. one item on Collins, another on Zonal) — there is no top-level listingId constraining the order to one platform.

Each OrderItem is unified (no capability field, no oneOf) — quantity carries the count for either capability (covers for a table reservation, ticket count for an event-ticket line); time additionally applies to table reservations. Capability is resolved server-side from the compositeId's RMS slug, not from which fields are populated. An order's items may mix capabilities and platforms freely.

Security
Live(Required scopes:
order:create
) or Sandbox(Required scopes:
order:create
)
Headers
X-Correlation-IDstring

Optional ID for cross-system transaction tracking.

Example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA
X-Partner-Referencestring

Required for Bookable Agents — identifies the partner on whose behalf the request is made. Accepts either a partner reference (e.g. bottomlessbrunch.com) or a partner id (e.g. 288); a value matching a known partner reference resolves as that reference, otherwise it is treated as a partner id.

Example: bottomlessbrunch.com
X-Booking-Sourcestring

Identifies the source or channel through which the order was created. Defaults to "api" when not provided. embed marks an order placed through an embedded client (e.g. the partner portal embedded in a partner's site or app).

Enum"email""phone""api""webhook""js-tag""chatbot""puller""portal""embed"
Example: api
Bodyapplication/jsonrequired
customerobject(Customer)required
customer.​firstNamestringrequired
Example: "John"
customer.​lastNamestringrequired
Example: "Doe"
customer.​emailstring(email)required
Example: "john.doe@example.com"
customer.​phonestringrequired

E.164 format.

Example: "+441234567890"
customer.​dateOfBirthstring or null(date)
customer.​companystring or null

Optional company/business name, applied to every item in the order. When omitted, falls back to the company name configured by the operator for the requesting partner/channel, if any. Currently wired through for Collins (table_reservation) only — other platforms accept but ignore it.

Example: "Acme Corp"
partnerOrderIdstring or null

Optional external reference for cross-system tracking.

notesstring or null
adminNotesArray of strings or null

Internal notes visible to venue operators only.

marketingConsentboolean or null
itemsArray of objects(OrderItem)non-emptyrequired

One item per booking to create.

items[].​compositeIdstringrequired

CompositeId of the bookable product.

  • table_reservation → {VenueGroupId}|{RmsSlug}|{VenueId}|{ProductId}
  • event_ticket → {VenueGroupId}|{RmsSlug}|{EventId}|{TicketTypeId}
Example: "29|CO|275cc44dd2e2496fba44857c9257443a|e4d909c290d0fb1ca068ffaddf22cbd0"
items[].​datestring(date)required
Example: "2026-06-15"
items[].​quantityinteger>= 1required

Covers for a table reservation, or ticket count for an event-ticket line.

Example: 4
items[].​notesstring or null

Free-text note or special request for the booking. Applies to either capability — table reservation notes or an event-ticket purchase comment.

Example: "Birthday celebration"
items[].​partnerBookingIdstring or null

Optional external reference supplied by the caller, used to cross-link this booking with records in another system. Applies to either capability.

Example: "ext-ref-123"
items[].​commissionnumber or null(double)

Partner commission for this booking. Wired through for event_ticket (Tonic's partner_commission) and table_reservation on Collins (forwarded as commission_amount); other table_reservation RMS integrations accept but ignore it.

Example: 2.5
items[].​timestring or null^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$
Example: "19:30"
items[].​durationinteger or null

Duration in minutes.

Example: 90
items[].​typestring or null

book or request. book in the availability response means the system has confirmed this slot can be auto-confirmed. request is always a valid choice, even for a slot availability returned as book.

Enum"book""request"
Example: "book"
items[].​preordersobject(PreorderContainer)

Pre-order items attached to a table reservation.

items[].​spaceIdinteger or null

Specific space/area to book, overriding automatic selection by the RMS. Obtain valid ids from AvailabilityResult.availability.times[].product.spaces[].id in the POST /v1/availabilities response for this compositeId/date/time — not from Bookable.spaces[], which is the unfiltered listing-level list.

Example: 12
items[].​depositAmountnumber or null(double)

Deposit amount to charge for this booking. When provided, a payment is taken from the RMS for this exact amount; when omitted, none is taken.

Example: 10
items[].​unitPriceAmountnumber or null(double)
Example: 25
items[].​priceCurrencystring or null
Example: "GBP"
curl -i -X POST \
  https://api.bookabletech.com/v1/orders \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-Booking-Source: api' \
  -H 'X-Correlation-ID: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA' \
  -H 'X-Partner-Reference: bottomlessbrunch.com' \
  -d '{
    "items": [
      {
        "compositeId": "29|CO|275cc44dd2e2496fba44857c9257443a|e4d909c290d0fb1ca068ffaddf22cbd0",
        "date": "2026-06-15",
        "time": "19:30",
        "duration": 90,
        "quantity": 4,
        "type": "book"
      },
      {
        "compositeId": "41|ZO|9a1c20-5b7e-4c1a|8c2d4e60-9a1b-4f3c",
        "date": "2026-06-15",
        "time": "20:00",
        "quantity": 2,
        "type": "book"
      }
    ],
    "customer": {
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com",
      "phone": "+441234567890"
    }
  }'

Responses

One result per requested item, in request order — every item succeeded.

Headers
X-Correlation-IDstring
X-RateLimit-Limitinteger

Maximum number of requests allowed per window.

Example: 200
X-RateLimit-Remaininginteger

Number of requests remaining in the current window.

Example: 150
X-RateLimit-Resetinteger(int64)

Unix timestamp (seconds since epoch) when the current rate-limit window resets.

Example: 1741651200
Body
idstringrequired

Platform-generated unique order identifier.

Example: "ORD-9980140810"
partnerOrderIdstring or null
customerobject(Customer)required
customer.​firstNamestringrequired
Example: "John"
customer.​lastNamestringrequired
Example: "Doe"
customer.​emailstring(email)required
Example: "john.doe@example.com"
customer.​phonestringrequired

E.164 format.

Example: "+441234567890"
customer.​dateOfBirthstring or null(date)
customer.​companystring or null

Optional company/business name, applied to every item in the order. When omitted, falls back to the company name configured by the operator for the requesting partner/channel, if any. Currently wired through for Collins (table_reservation) only — other platforms accept but ignore it.

Example: "Acme Corp"
createdAtstring(date-time)required
Example: "2026-04-21T14:22:00Z"
resultsArray of objects(OrderItemResult)required

One result per requested item, in request order.

results[].​compositeIdstringrequired

The compositeId this result refers to — the product for a table-reservation item, or the ticket-type line for an event-ticket line.

Example: "29|CO|275cc44dd2e2496fba44857c9257443a|e4d909c290d0fb1ca068ffaddf22cbd0"
results[].​datestring(date)required

The date this result refers to.

Example: "2026-06-15"
results[].​bookingobject(BookingResult)

Confirmed booking detail for a single order item. Common fields (including quantity — covers or ticket count) always apply; time/duration/ preorders apply to table reservations only, unitPriceAmount/ priceCurrency to event tickets only. Check capability to know which.

results[].​errorobject(ServerError)
Response
{
  "id": "ORD-8841203A",
  "partnerOrderId": null,
  "customer": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "phone": "+441234567890"
  },
  "createdAt": "2026-06-15T09:12:44Z",
  "results": [
    { … },
    { … }
  ]
}

Update one or more bookings within an order

Request

Partial update — each OrderItemUpdate only carries the fields being changed; anything omitted keeps its current value. Items are resolved and updated independently, same isolation model as POST /v1/orders: a failure on one item does not block the others.

Capability (table reservation vs. event ticket) is resolved server-side from the existing booking, not from the request — every field below applies uniformly to either capability at the API level, even where the RMS-side effect currently differs (noted per field).

compositeId moves the booking to a different bookable product — the same identifier used everywhere else (Bookable.compositeId, the only thing taken from a listing's bookableProducts[]), not a ticket-specific field. Supported for both capabilities: for event tickets it changes the ticket type (the compositeId's 4th segment); for table reservations it changes the booked product/space. The new compositeId must reference the same venue group, RMS and venue/event as the booking's current product — only the trailing product/ticket-type segment may differ; a cross-venue or cross-event move is rejected (400 ORDER-N-007).

firstName/lastName/email/phone update the guest's details, either capability.

Preorders (table-reservation only in practice — event tickets have no preorder concept, these fields are accepted but a no-op for them today): preorders is a full replacement of the current preorder set (omit to leave unchanged, send empty arrays to clear). preorderChanges is the incremental alternative — add or remove specific packages/menus without resending the rest; mutually exclusive with preorders on the same item (400 ORDER-N-008).

Security
Live(Required scopes:
order:create
) or Sandbox(Required scopes:
order:create
)
Path
orderIdstringrequired
Example: ORD-9980140810
Headers
X-Correlation-IDstring

Optional ID for cross-system transaction tracking.

Example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA
X-Partner-Referencestring

Required for Bookable Agents — identifies the partner on whose behalf the request is made. Accepts either a partner reference (e.g. bottomlessbrunch.com) or a partner id (e.g. 288); a value matching a known partner reference resolves as that reference, otherwise it is treated as a partner id.

Example: bottomlessbrunch.com
Bodyapplication/jsonrequired
itemsArray of objects(OrderItemUpdate)non-emptyrequired

One entry per booking to update, within this order.

items[].​bookingIdstringrequired

The booking's platform id — BookingResult.id from the create/update/cancel response.

Example: "1|TN|423458"
items[].​notesstring or null

Internal note. Table reservation → booking notes; event ticket → Tonic purchase comment.

Example: "Customer upgraded to Pay ticket"
items[].​firstNamestring or null

Guest first name. Applies to either capability.

Example: "John"
items[].​lastNamestring or null

Guest last name. Applies to either capability.

Example: "Doe"
items[].​emailstring or null(email)

Guest email address. Applies to either capability.

Example: "john.doe@example.com"
items[].​phonestring or null

Guest phone number, E.164 format. Applies to either capability.

Example: "+441234567890"
items[].​companystring or null

Guest company/business name. Applies to either capability.

Example: "Acme Corp"
items[].​commissionnumber or null(double)

Partner commission for this booking. Currently wired through for table_reservation (Collins) on update — event_ticket (Tonic) only supports commission on create today, not on update.

Example: 2.5
items[].​datestring or null(date)
Example: "2026-06-15"
items[].​timestring or null^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$
Example: "20:00"
items[].​durationinteger or null
Example: 90
items[].​quantityinteger or null>= 1

New covers count for a table reservation, or new ticket count for an event-ticket line. For event tickets: a decrease is processed as a partial refund of the difference; an increase is rejected with 400 (EVENT-N-003) — Tonic has no way to add tickets to an existing purchase, create a new order item instead.

Example: 6
items[].​preordersobject(PreorderContainer)

Pre-order items attached to a table reservation.

items[].​preorderChangesobject(PreorderChanges)

Incremental preorder change for OrderItemUpdate — add or remove specific packages/menus without resending the full current list. Mutually exclusive with preorders on the same item (400 ORDER-N-008 if both are present). An id appearing in both an "add" list and its matching "remove" list in the same request is rejected (400 ORDER-N-009) rather than silently resolved.

items[].​compositeIdstring or null

Full CompositeId of the bookable product to move this booking to — same shape and meaning as Bookable.compositeId (the only identifier taken from a listing's bookableProducts[]), not a ticket-specific field.

Supported for both capabilities: for event tickets, moves to a different ticket type on the same event (the compositeId's 4th segment); for table reservations, moves to a different bookable product/space on the same venue. Optionally combined with date in the same operation — Tonic has no separate "change date only" call.

The new compositeId must reference the same venue group, RMS, and venue/event as the booking's current product — only the trailing product/ticket-type segment (AdditionalId) may differ. A cross-venue or cross-event compositeId is rejected with 400 (ORDER-N-007).

Example: "1|TN|6a2bbc0285bf210719631c44|6a2bbb580ed61600150618f7"
curl -i -X PATCH \
  https://api.bookabletech.com/v1/orders/ORD-9980140810 \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-Correlation-ID: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA' \
  -H 'X-Partner-Reference: bottomlessbrunch.com' \
  -d '{
    "items": [
      {
        "bookingId": "1|TN|6a59f0a0f58eb1c0fa00d040",
        "compositeId": "1|TN|6a2bbc0285bf210719631c44|6a2bbb580ed61600150618f7",
        "date": "2027-02-22",
        "notes": "Customer upgraded to Kids ticket"
      }
    ]
  }'

Responses

One result per requested item, in request order — every item succeeded.

Headers
X-Correlation-IDstring
X-RateLimit-Limitinteger

Maximum number of requests allowed per window.

Example: 200
X-RateLimit-Remaininginteger

Number of requests remaining in the current window.

Example: 150
X-RateLimit-Resetinteger(int64)

Unix timestamp (seconds since epoch) when the current rate-limit window resets.

Example: 1741651200
Bodyapplication/json
idstringrequired

Platform-generated unique order identifier.

Example: "ORD-9980140810"
partnerOrderIdstring or null
customerobject(Customer)required
customer.​firstNamestringrequired
Example: "John"
customer.​lastNamestringrequired
Example: "Doe"
customer.​emailstring(email)required
Example: "john.doe@example.com"
customer.​phonestringrequired

E.164 format.

Example: "+441234567890"
customer.​dateOfBirthstring or null(date)
customer.​companystring or null

Optional company/business name, applied to every item in the order. When omitted, falls back to the company name configured by the operator for the requesting partner/channel, if any. Currently wired through for Collins (table_reservation) only — other platforms accept but ignore it.

Example: "Acme Corp"
createdAtstring(date-time)required
Example: "2026-04-21T14:22:00Z"
resultsArray of objects(OrderItemResult)required

One result per requested item, in request order.

results[].​compositeIdstringrequired

The compositeId this result refers to — the product for a table-reservation item, or the ticket-type line for an event-ticket line.

Example: "29|CO|275cc44dd2e2496fba44857c9257443a|e4d909c290d0fb1ca068ffaddf22cbd0"
results[].​datestring(date)required

The date this result refers to.

Example: "2026-06-15"
results[].​bookingobject(BookingResult)

Confirmed booking detail for a single order item. Common fields (including quantity — covers or ticket count) always apply; time/duration/ preorders apply to table reservations only, unitPriceAmount/ priceCurrency to event tickets only. Check capability to know which.

results[].​errorobject(ServerError)
Response
application/json
{
  "id": "ORD-9980140810",
  "customer": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "phone": "+441234567890"
  },
  "createdAt": "2026-06-10T08:30:00Z",
  "results": [
    { … }
  ]
}

Cancel bookings within an order, or the entire order

Request

Cancels the bookings listed in bookingIds. When bookingIds is omitted or empty, cancels every booking belonging to orderId. Each cancellation is independent — one failure does not block the others.

Security
Live(Required scopes:
order:create
) or Sandbox(Required scopes:
order:create
)
Path
orderIdstringrequired
Example: ORD-9980140810
Headers
X-Correlation-IDstring

Optional ID for cross-system transaction tracking.

Example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA
X-Partner-Referencestring

Required for Bookable Agents — identifies the partner on whose behalf the request is made. Accepts either a partner reference (e.g. bottomlessbrunch.com) or a partner id (e.g. 288); a value matching a known partner reference resolves as that reference, otherwise it is treated as a partner id.

Example: bottomlessbrunch.com
Bodyapplication/json
bookingIdsArray of strings or null

Booking ids to cancel. Omitted or empty → cancel every booking in the order.

Example: ["1|TN|423458"]
curl -i -X DELETE \
  https://api.bookabletech.com/v1/orders/ORD-9980140810 \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-Correlation-ID: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA' \
  -H 'X-Partner-Reference: bottomlessbrunch.com' \
  -d '{}'

Responses

One result per cancelled item, in request order — every cancellation succeeded.

Headers
X-Correlation-IDstring
X-RateLimit-Limitinteger

Maximum number of requests allowed per window.

Example: 200
X-RateLimit-Remaininginteger

Number of requests remaining in the current window.

Example: 150
X-RateLimit-Resetinteger(int64)

Unix timestamp (seconds since epoch) when the current rate-limit window resets.

Example: 1741651200
Bodyapplication/json
idstringrequired

Platform-generated unique order identifier.

Example: "ORD-9980140810"
partnerOrderIdstring or null
customerobject(Customer)required
customer.​firstNamestringrequired
Example: "John"
customer.​lastNamestringrequired
Example: "Doe"
customer.​emailstring(email)required
Example: "john.doe@example.com"
customer.​phonestringrequired

E.164 format.

Example: "+441234567890"
customer.​dateOfBirthstring or null(date)
customer.​companystring or null

Optional company/business name, applied to every item in the order. When omitted, falls back to the company name configured by the operator for the requesting partner/channel, if any. Currently wired through for Collins (table_reservation) only — other platforms accept but ignore it.

Example: "Acme Corp"
createdAtstring(date-time)required
Example: "2026-04-21T14:22:00Z"
resultsArray of objects(OrderItemResult)required

One result per requested item, in request order.

results[].​compositeIdstringrequired

The compositeId this result refers to — the product for a table-reservation item, or the ticket-type line for an event-ticket line.

Example: "29|CO|275cc44dd2e2496fba44857c9257443a|e4d909c290d0fb1ca068ffaddf22cbd0"
results[].​datestring(date)required

The date this result refers to.

Example: "2026-06-15"
results[].​bookingobject(BookingResult)

Confirmed booking detail for a single order item. Common fields (including quantity — covers or ticket count) always apply; time/duration/ preorders apply to table reservations only, unitPriceAmount/ priceCurrency to event tickets only. Check capability to know which.

results[].​errorobject(ServerError)
Response
application/json
{
  "id": "ORD-9980140810",
  "customer": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "phone": "+441234567890"
  },
  "createdAt": "2026-06-15T09:12:44Z",
  "results": [
    { … },
    { … }
  ]
}