Developer docs

Run several venues from one account

Add venues to a Premium account, give each its own key and widget, pick the venue with a header, limit a login to one branch and understand the downgrade lock.

One BookDinePlay account (a tenant) can own several venues — a group of bars, a restaurant with a separate game room, franchise branches — each with its own slug, opening hours, resources, menus, events and keys. This tutorial shows how the pieces fit: adding a venue, embedding several on one site, choosing the venue in operator requests, limiting a login to one branch and what happens on a downgrade.

Several venues need the Premium plan, which allows up to 25. Starter and Pro have one venue; adding another answers 403 feature-not-in-plan with requiredPlan: "Premium", and at the limit 409 venue-limit-reached with the maxVenues that applies.

1. Add a venue

In the console, add a venue, or ask your assistant over MCP: venues_list shows what the account has, venues_create adds a further venue within the plan limit and venue_create creates the very first one. The slug is the venue's permanent address in the API and is set once. Everything else — profile, hours, resources, menus, events, vouchers, QR codes, messages — belongs to one venue and is edited with that venue selected.

The venue that is oldest (by creation, then slug) is the account's default venue: the one any operator request acts on when it does not name another.

2. Give each venue its own key

API keys are per venue. A key created under one venue used on another venue's route is refused with venue-mismatch, so a site that embeds several venues carries one publishable key per venue. Create each key under its own venue (Venue → API keys with that venue selected) and allow the origins that venue's pages are served from.

On a page with two venues each widget gets its own venue and key:

<div id="bar-widget"></div>
<div id="lounge-widget"></div>
<script src="https://cdn.bookdineplay.com/sdk/v1/bookdineplay.js"></script>
<script>
  window.BookDinePlay.renderBookingWidget({
    container: '#bar-widget',
    venueSlug: 'harbour-bar',
    apiBaseUrl: 'https://api.bookdineplay.com',
    publishableKey: 'bdp_pk_key_of_harbour_bar'
  });
  window.BookDinePlay.renderBookingWidget({
    container: '#lounge-widget',
    venueSlug: 'harbour-lounge',
    apiBaseUrl: 'https://api.bookdineplay.com',
    publishableKey: 'bdp_pk_key_of_harbour_lounge'
  });
</script>

On WordPress, the shortcode's key attribute exists for this: [bookdineplay_widget venue="harbour-lounge" key="bdp_pk_…"]; the key in Settings is the default for shortcodes that name none. A server-side integration holds one secret key per venue in the same way.

3. Choose the venue in operator requests

The operator API — what the console and the MCP server call, authenticated as a signed-in person — acts on one venue per request. Name it with a header:

GET /api/operator/venue HTTP/1.1
Authorization: Bearer <the operator's access token>
X-BookDinePlay-Venue: harbour-lounge
What you send What happens
The header with one of your venues' slugs The request acts on that venue (case-insensitive)
No header, or a blank one It acts on your default venue
A slug that is not one of your account's venues — unknown, or another account's 404 venue-not-found; the answer is the same either way, so it never tells you which
A sibling venue your login may not use 403 venue-not-permitted

Every answer that acted on a venue echoes X-BookDinePlay-Venue with the slug it used, so a client can check it. GET /api/operator/venues lists the venues the caller may choose, with the default and the plan's maxVenues; GET /api/operator/me reports the same and is deliberately lenient about a bad header, so a client with a stale selection can always recover. A single-venue account never needs the header.

Over MCP the header is the venue argument of every venue tool. Without it on an account with several venues, the tool refuses and names the choices.

4. Limit a login to one branch

A login can be restricted to a single venue: a manager of the lounge should see and change the lounge only. A tenant-wide operator may use every venue; a restricted one only their own, which is also their default whether or not they send the header. Naming a sibling venue answers 403 venue-not-permitted.

Today the restriction is set when BookDinePlay's support provisions or updates the operator, not in the console: ask them to set an operator's venue, or to clear it again. A restricted login also cannot do what belongs to the whole account — billing, payout onboarding, adding a venue — which answers 403 tenant-operator-required, and cannot accept the terms of service and data processing agreement for the account: they see a notice that the account owner has to do that.

5. What a downgrade does

If the plan later allows fewer venues, the oldest venues up to the new limit stay fully usable and the rest are locked; upgrading unlocks everything at once, because nothing is stored — the lock is worked out from rank and plan on every request.

Surface A locked venue
Operator reads Work; its data stays readable
Operator changes 403 venue-not-in-plan
Public /api/venues/** 403 tenant-suspended, exactly like a suspended account
The BookDinePlay app's venue directory, table QR codes Gone, and QR codes stop resolving
Tickets, registrations, booking cancel links, voucher lookup, table voucher redemption Keep working: guests already hold those credentials

Next steps

  • Errors — every multi-venue problem and its fix.
  • Authentication — key types and origins.
  • MCP tools — the venue argument and venues_create.