Developer docs

Menus

Read every published menu, its groups and items, priced in the venue's currency — the display menu, not the seated guest's order menu.

Every published menu with its groups and items, priced in the venue's currency. This is the display menu; what a seated guest can order from is the table session's menus (QR codes and table sessions). It follows the same key rules as the rest of /api/venues/** (Keys and headers) and answers 404 with a problem body when no venue has that slug.

Endpoints

GET /api/venues/{venueSlug}/menus

Response 200 OK

Field Type Meaning
slug, currency string The venue and the ISO 4217 currency of every price below
menus[] object[] id, name, description, groups[]
groups[] object[] name, description (nullable), items[]
items[] object[] name, description, price (decimal), currency, tags (string[], e.g. dietary labels), imageUrl (nullable), id (nullable) — the item's stable identity: it survives a rename, so reference an item by id, not by name. Null only for an item stored before ids existed
{
  "slug": "demo-sportsbar",
  "currency": "EUR",
  "menus": [
    {
      "id": "kitchen",
      "name": "Kitchen",
      "description": "Served from open until one hour before close.",
      "groups": [
        {
          "name": "Small plates",
          "description": null,
          "items": [
            {
              "name": "Loaded nachos",
              "description": "Melted cheese, jalapeños, lime crema",
              "price": 9.50,
              "currency": "EUR",
              "tags": [
                "vegetarian"
              ],
              "imageUrl": "_content/BookDinePlay.App.Shared/menu/nachos.webp",
              "id": "cccb4f0acf5604910b9edff5eb7d85d3"
            },
            {
              "name": "Buffalo wings",
              "description": "Blue-cheese dip, celery",
              "price": 11.00,
              "currency": "EUR",
              "tags": [],
              "imageUrl": "_content/BookDinePlay.App.Shared/menu/wings.webp",
              "id": "af1cc7fd0772f60da833b1612f46fa69"
            },
            {
              "name": "Padrón peppers",
              "description": "Sea salt, olive oil",
              "price": 7.00,
              "currency": "EUR",
              "tags": [
                "vegan",
                "gluten-free"
              ],
              "imageUrl": "_content/BookDinePlay.App.Shared/menu/padron-peppers.webp",
              "id": "08d1b4c209107e4e8b8bd809ee0dedf4"
            }
          ]
        },
        {
          "name": "Mains",
          "description": null,
          "items": [
            {
              "name": "Smash burger",
              "description": "Double patty, house sauce, fries",
              "price": 14.50,
              "currency": "EUR",
              "tags": [],
              "imageUrl": "_content/BookDinePlay.App.Shared/menu/smash-burger.webp",
              "id": "787f5afafde1b8be62dc96b0db2e5735"
            },
            {
              "name": "BBQ ribs",
              "description": "Slow-cooked, slaw, fries",
              "price": 19.00,
              "currency": "EUR",
              "tags": [],
              "imageUrl": "_content/BookDinePlay.App.Shared/menu/bbq-ribs.webp",
              "id": "ead9e92d6a163e0e8fe95b27a7c96fa5"
            },
            {
              "name": "Halloumi flatbread",
              "description": "Grilled halloumi, harissa, greens",
              "price": 13.00,
              "currency": "EUR",
              "tags": [
                "vegetarian"
              ],
              "imageUrl": "_content/BookDinePlay.App.Shared/menu/halloumi-flatbread.webp",
              "id": "655fa085e02ec363972091746b29e2cb"
            }
          ]
        },
        {
          "name": "Sweet",
          "description": null,
          "items": [
            {
              "name": "Churros",
              "description": "Cinnamon sugar, chocolate",
              "price": 7.00,
              "currency": "EUR",
              "tags": [
                "vegetarian"
              ],
              "imageUrl": "_content/BookDinePlay.App.Shared/menu/churros.webp",
              "id": "d668f32064f026a8ce33c30ebbd4cb5a"
            }
          ]
        }
      ]
    },
    {
      "id": "bar",
      "name": "Bar",
      "description": "Draft, cocktails and zero-proof.",
      "groups": [
        {
          "name": "Draft beer",
          "description": null,
          "items": [
            {
              "name": "House lager 0.3L",
              "description": "Crisp pilsner",
              "price": 4.50,
              "currency": "EUR",
              "tags": [],
              "imageUrl": "_content/BookDinePlay.App.Shared/menu/lager.webp",
              "id": "139018ac588c888bddc135dcb72099f7"
            },
            {
              "name": "Local IPA 0.5L",
              "description": "Hoppy, citrus finish",
              "price": 6.50,
              "currency": "EUR",
              "tags": [],
              "imageUrl": "_content/BookDinePlay.App.Shared/menu/ipa.webp",
              "id": "f65791315063c5eb8a9006d8f85ba5b5"
            }
          ]
        },
        {
          "name": "Cocktails",
          "description": null,
          "items": [
            {
              "name": "Old Fashioned",
              "description": "Bourbon, bitters, orange",
              "price": 11.00,
              "currency": "EUR",
              "tags": [],
              "imageUrl": "_content/BookDinePlay.App.Shared/menu/old-fashioned.webp",
              "id": "371c345ec3f606b3195ec7c5d596f418"
            },
            {
              "name": "Spicy margarita",
              "description": "Tequila, chilli, lime",
              "price": 10.50,
              "currency": "EUR",
              "tags": [],
              "imageUrl": "_content/BookDinePlay.App.Shared/menu/margarita.webp",
              "id": "cb63f7f8f82dcabc46206b49d34f641d"
            }
          ]
        },
        {
          "name": "Zero proof",
          "description": null,
          "items": [
            {
              "name": "Craft soda",
              "description": "House-made, ask for today's flavour",
              "price": 4.00,
              "currency": "EUR",
              "tags": [
                "vegan"
              ],
              "imageUrl": "_content/BookDinePlay.App.Shared/menu/craft-soda.webp",
              "id": "af0cb8e85bf03fbc2e997bd4bdbe0136"
            }
          ]
        }
      ]
    }
  ]
}

Errors — 404 no venue with that slug.

curl

curl "https://api.bookdineplay.com/api/venues/your-venue/menus" \
  -H "X-BookDinePlay-Key: bdp_pk_your_publishable_key" \
  -H "Origin: https://www.your-venue.example"

JavaScript

const { menus, currency } = await (await fetch('https://api.bookdineplay.com/api/venues/your-venue/menus', {
  headers: { 'X-BookDinePlay-Key': 'bdp_pk_your_publishable_key' }
})).json();
for (const menu of menus) for (const group of menu.groups) for (const item of group.items) {
  console.log(menu.name, group.name, item.name, item.price, currency);
}

C#

var menus = await client.GetMenusAsync("your-venue", cancellationToken);

PHP

<?php
$response = wp_remote_get( 'https://api.bookdineplay.com/api/venues/your-venue/menus', [ 'headers' => [ 'X-BookDinePlay-Key' => BOOKDINEPLAY_SECRET_KEY ] ] );
$data = json_decode( wp_remote_retrieve_body( $response ), true );
foreach ( $data['menus'] as $menu ) {
    foreach ( $menu['groups'] as $group ) {
        foreach ( $group['items'] as $item ) {
            echo "{$menu['name']} {$group['name']} {$item['name']} {$item['price']} {$data['currency']}\n";
        }
    }
}

Operator: saving menus

The operator console reads and saves a venue's menus through the operator API (bearer token of the venue's operator), not through the public /api/venues/** surface. Neither route is plan-gated.

Reading and saving

  • GET /api/operator/venue/menus answers every menu with its id, its kind (Food or Drinks), groups and items, each item with its taxRate (a fraction, 0.19 for 19 %) and id, and an ETag header. A tenant with no venue yet gets 204.
  • PUT /api/operator/venue/menus with { "menus": [ … ] } replaces the whole collection: a menu, group or item left out is removed, and [] clears every menu. It answers the saved menus and their new ETag.
  • Send back what you read: an omitted imageUrl clears the picture, and an item without an id keeps the id of the stored item of the same menu with the same name (otherwise it gets a new one). That match needs the menu's own id: a menu sent without it is treated as new, so every item in it gets a new id, which unlinks anything that referred to the old ones, such as an item voucher. An id the venue does not have, or one used twice, is refused with 400 under errors.menu and nothing is saved.

Rules a save must keep

Each broken rule is a 400 validation problem under the indexed key of the value, for example menus[0].groups[1].items[2].price, and every error is reported, not only the first.

  • Menu, group and item names are required, at most 120 characters; descriptions at most 500.
  • A price is at least 0, at most 99,999.99, with at most two decimal places.
  • A taxRate is empty (no VAT rate) or between 0 and 1.
  • At most 12 tags of at most 40 characters each; blank and repeated tags are dropped before they are counted.
  • Item names are unique per menu, compared trimmed and ignoring case. Every item of a clash is marked under its .name: QR ordering finds an item by its menu and name, so a namesake would make a guest pay the wrong price.

Saving only what you read

Send the ETag of your last read as If-Match to save only if the menus are still the ones you read. If they changed meanwhile — another device saved, or a demo venue was reset by a deploy — the answer is 412 Precondition Failed and nothing is written; read again, or send the save without If-Match to overwrite. Without If-Match a save is unconditional, and in the rare case that it loses to other saves arriving at the same moment it answers 409: try again.

curl

curl -i "https://api.bookdineplay.com/api/operator/venue/menus" \
  -H "Authorization: Bearer $OPERATOR_TOKEN"

curl -X PUT "https://api.bookdineplay.com/api/operator/venue/menus" \
  -H "Authorization: Bearer $OPERATOR_TOKEN" \
  -H "If-Match: $ETAG" \
  -H "Content-Type: application/json" \
  -d @menus.json

JavaScript

const url = 'https://api.bookdineplay.com/api/operator/venue/menus';
const headers = { 'Authorization': `Bearer ${process.env.OPERATOR_TOKEN}` }; // Node.js, server-side
const read = await fetch(url, { headers });
const etag = read.headers.get('ETag');
const { menus } = await read.json();

const save = await fetch(url, {
  method: 'PUT',
  headers: { ...headers, 'If-Match': etag, 'Content-Type': 'application/json' },
  body: JSON.stringify({ menus }) // the whole collection
});
if (save.status === 412) { /* changed meanwhile - read again */ }

C#

// `http` is an HttpClient with BaseAddress https://api.bookdineplay.com and the operator's bearer token.
using var read = await http.GetAsync("api/operator/venue/menus", cancellationToken);
var etag = read.Headers.ETag;
var menusJson = await read.Content.ReadAsStringAsync(cancellationToken);

using var request = new HttpRequestMessage(HttpMethod.Put, "api/operator/venue/menus")
{
    Content = new StringContent(menusJson, Encoding.UTF8, "application/json")
};
request.Headers.IfMatch.Add(etag!);
using var save = await http.SendAsync(request, cancellationToken);
if (save.StatusCode == HttpStatusCode.PreconditionFailed) { /* changed meanwhile - read again */ }

PHP

<?php
$url     = 'https://api.bookdineplay.com/api/operator/venue/menus';
$headers = [ 'Authorization' => 'Bearer ' . OPERATOR_TOKEN ]; // server-side only
$read    = wp_remote_get( $url, [ 'headers' => $headers ] );
$etag    = wp_remote_retrieve_header( $read, 'etag' );

$save = wp_remote_request( $url, [
    'method'  => 'PUT',
    'headers' => $headers + [ 'If-Match' => $etag, 'Content-Type' => 'application/json' ],
    'body'    => wp_remote_retrieve_body( $read ), // the whole collection
] );
if ( 412 === wp_remote_retrieve_response_code( $save ) ) { /* changed meanwhile - read again */ }

Operator: item images

The operator console gives a menu item a picture in two steps: it uploads the file, then saves the returned URL as the item's imageUrl with PUT /api/operator/venue/menus. This is the operator API (bearer token of the venue's operator), not part of the public /api/venues/** surface.

Uploading an image

POST /api/operator/venue/menus/media takes multipart/form-data with one file part. Not plan-gated, like the menu editor itself. The image rules are the same as for event images: PNG, JPEG or WebP (recognised by content, not by the declared type), at most 5 MB, at least 400 × 400 pixels, and a complete file.

Response 201 Created with id, url, contentType, width and height. Save url as the item's imageUrl.

Errors — each is a problem body naming the file field, so a picker can show it beside itself: 400 no file, an empty file, an unsupported or truncated image, or one smaller than 400 × 400; 413 larger than 5 MB. A tenant with no venue yet gets 404 with a plain message.

curl

curl -X POST "https://api.bookdineplay.com/api/operator/venue/menus/media" \
  -H "Authorization: Bearer $OPERATOR_TOKEN" \
  -F "file=@burger.jpg"

JavaScript

const form = new FormData();
form.append('file', imageFile); // a File or Blob
const response = await fetch('https://api.bookdineplay.com/api/operator/venue/menus/media', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${operatorToken}` }, // no Content-Type: the browser sets the boundary
  body: form
});
const { url } = await response.json(); // save it as the item's imageUrl

C#

using var form = new MultipartFormDataContent();
form.Add(new StreamContent(File.OpenRead("burger.jpg")), "file", "burger.jpg");
using var response = await http.PostAsync("api/operator/venue/menus/media", form, cancellationToken);
// `http` carries the operator's bearer token; the body holds id, url, contentType, width, height

PHP

<?php
// cURL: the WordPress HTTP API cannot send multipart uploads.
$ch = curl_init( 'https://api.bookdineplay.com/api/operator/venue/menus/media' );
curl_setopt_array( $ch, [
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [ 'Authorization: Bearer ' . OPERATOR_TOKEN ],
    CURLOPT_POSTFIELDS     => [ 'file' => new CURLFile( 'burger.jpg' ) ],
    CURLOPT_RETURNTRANSFER => true,
] );
$image = json_decode( curl_exec( $ch ), true ); // save $image['url'] as the item's imageUrl
curl_close( $ch );

Which imageUrl a save accepts

PUT /api/operator/venue/menus accepts an item imageUrl that is empty (no picture), an absolute http(s) URL of at most 2048 characters — what the upload returns — or one of the images bundled with the app, exactly as the demo menus store them: _content/BookDinePlay.App.Shared/menu/{name}.webp. Anything else is a 400 under the item's indexed key, for example menus[0].groups[1].items[2].imageUrl. An omitted imageUrl clears the picture, so send the stored one back.

Lifecycle

  • There is no delete route for menu images. The media store is shared with event images, so a menu-side delete could remove a saved event image and bypass the event route's plan gate. Saved images also stay reachable for guests who still have a cached page (media URLs are cached for a year).
  • An upload that is replaced, removed or never saved stays in the store as an orphan; a separate sweep reclaims orphans of both kinds.
  • The demo venues' menus are reset on every deploy, so a picture uploaded to a demo menu is gone from it after the next release.

Next steps