Sign in to see your venue's slug and publishable key in every sample.
Your account has no venue yet, so the samples keep their placeholders. Sign out
Signed in as · . Create a publishable key in the console and reload to see it here. Sign out
Signed in as · . The samples show your venue's publishable key. Sign out
Developer docs
Run an event with tickets
Create and publish an event, show it on your site, take free registrations or paid Stripe tickets, check guests in at the door and handle refunds.
A venue's events — a darts league night, a screening, a quiz — can be shown on your own site, take free registrations with named tickets, or sell paid tickets through Stripe. This tutorial follows one event from the console to the door: create it, publish it, put it on a page, let a guest buy tickets, scan them in and refund one.
Events are a Pro feature; selling paid tickets online is Premium and needs a connected Stripe payout account (Billing → Payouts in the console). You also need a publishable key for the page (Authentication).
1. Create the event
In the console open the events area and create an event, or ask your assistant over MCP (events_create). The fields that matter:
| Field | What it does |
|---|---|
| Title, slug | The slug is the event's address in the API (darts-league-night); leave it blank to derive it from the title. It is set once |
| Description | Markdown, rendered for guests. A preview shows exactly what they will see |
| Date, start, end | Venue-local. Leave the date empty for an ongoing event ("Every Thursday") and put the wording in the time label |
| Registration mode | None shows the event only. Free issues named tickets without payment. Paid sells tickets through Stripe Checkout |
| Capacity, tickets per registration | The total number of tickets (empty is unlimited) and how many one guest may take at once (default 6) |
| Registration closes | An optional instant before the event starts after which no more registrations are accepted |
| Ticket price, currency | Paid events only |
| Refund policy | Paid events only: no online refund, or a full refund up to a number of hours before the start (0 to 720) |
An event is a draft until you publish it; only published events are listed. Publish it in the console or with events_publish. A published event can be cancelled, which stops registrations, keeps the page readable and flags it as cancelled.
2. Show it on a page
The quickest way is the widget. It renders the cards, the detail, the registration form and the ticket confirmation, with Stripe Checkout for a Paid event:
<div id="bookdineplay-events"></div>
<script src="https://cdn.bookdineplay.com/sdk/v1/bookdineplay.js"></script>
<script>
window.BookDinePlay.renderEventsWidget({
container: '#bookdineplay-events',
venueSlug: 'your-venue',
apiBaseUrl: 'https://api.bookdineplay.com',
publishableKey: 'bdp_pk_your_publishable_key',
layout: 'grid',
language: 'en'
});
</script>On WordPress the same is [bookdineplay_events venue="your-venue"], and [bookdineplay_event venue="your-venue" event="darts-league-night"] gives one event its own page. A Paid event should also set the return addresses (success_url and cancel_url on the shortcode) so a guest lands back on your site after Stripe. See Events widget and WordPress.
3. Build your own event page
To use your own markup, read the list and the detail. The detail's registration object says whether a registration would be accepted right now (open) and, if not, why (reason):
curl
curl "https://api.bookdineplay.com/api/venues/your-venue/events/darts-league-night" \
-H "X-BookDinePlay-Key: bdp_pk_your_publishable_key" \
-H "Origin: https://www.your-venue.example"JavaScript
const event = await client.event('darts-league-night');
if (!event.registration.open) console.log(event.registration.reason); // closed, sold-out, past or not-openC#
var detail = await client.GetEventAsync("your-venue", "darts-league-night", cancellationToken);
Console.WriteLine($"{detail?.Registration.Open} {detail?.Registration.Remaining}");PHP
<?php
$response = wp_remote_get( 'https://api.bookdineplay.com/api/venues/your-venue/events/darts-league-night', [ 'headers' => [ 'X-BookDinePlay-Key' => BOOKDINEPLAY_SECRET_KEY ] ] );
$event = json_decode( wp_remote_retrieve_body( $response ), true );Ask for at most the smaller of maxPerRegistration and remaining tickets. The window can shut between your read and the registration, so handle the refusal as well as the flag.
4. Register guests
For a Free event, register: the buyer and one name per ticket. You get a reference, one ticket per attendee and a cancel link, and the guest an e-mail with the same:
curl
curl -X POST "https://api.bookdineplay.com/api/venues/your-venue/events/darts-league-night/registrations" \
-H "X-BookDinePlay-Key: bdp_pk_your_publishable_key" \
-H "Origin: https://www.your-venue.example" \
-H "Content-Type: application/json" \
-d '{ "buyerName": "Ada Lovelace", "email": "ada@example.com", "quantity": 2, "attendees": ["", "Grace Hopper"] }'JavaScript
const registration = await client.registerForEvent('darts-league-night', {
buyerName: 'Ada Lovelace', email: 'ada@example.com', quantity: 2, attendees: ['', 'Grace Hopper']
});
console.log(registration.reference, registration.tickets.map((t) => t.code));C#
var registration = await client.RegisterForEventAsync("your-venue", "darts-league-night",
new EventRegistrationRequest { BuyerName = "Ada Lovelace", Email = "ada@example.com", Quantity = 2, Attendees = ["", "Grace Hopper"] },
cancellationToken);PHP
<?php
$response = wp_remote_post( 'https://api.bookdineplay.com/api/venues/your-venue/events/darts-league-night/registrations', [
'headers' => [ 'X-BookDinePlay-Key' => BOOKDINEPLAY_SECRET_KEY, 'Content-Type' => 'application/json' ],
'body' => wp_json_encode( [ 'buyerName' => 'Ada Lovelace', 'email' => 'ada@example.com', 'quantity' => 2, 'attendees' => [ '', 'Grace Hopper' ] ] ),
] );
$registration = json_decode( wp_remote_retrieve_body( $response ), true );An empty first attendee means the buyer's own name. Seats are taken from capacity the moment the registration is accepted, so two guests racing for the last seat cannot both get it.
5. Sell paid tickets
For a Paid event the same body goes to the checkout route instead, with return addresses. It does not issue tickets yet: it holds the seats and opens a Stripe Checkout session on the venue's own account, and answers with the checkoutUrl to send the guest to:
curl
curl -X POST "https://api.bookdineplay.com/api/venues/your-venue/events/gala-night/tickets/checkout" \
-H "X-BookDinePlay-Key: bdp_pk_your_publishable_key" \
-H "Origin: https://www.your-venue.example" \
-H "Content-Type: application/json" \
-d '{ "buyerName": "Ada Lovelace", "email": "ada@example.com", "quantity": 2, "attendees": ["", "Grace Hopper"], "successUrl": "https://www.your-venue.example/event/gala-night?paid=1", "cancelUrl": "https://www.your-venue.example/event/gala-night?cancelled=1" }'JavaScript
const checkout = await client.checkoutEventTickets('gala-night', {
buyerName: 'Ada Lovelace', email: 'ada@example.com', quantity: 2, attendees: ['', 'Grace Hopper'],
successUrl: location.origin + '/event/gala-night?paid=1',
cancelUrl: location.origin + '/event/gala-night?cancelled=1'
});
window.location.assign(checkout.checkoutUrl);C#
var checkout = await client.CheckoutEventTicketsAsync("your-venue", "gala-night", new EventTicketCheckoutRequest
{
BuyerName = "Ada Lovelace",
Email = "ada@example.com",
Quantity = 2,
Attendees = ["", "Grace Hopper"],
SuccessUrl = "https://www.your-venue.example/event/gala-night?paid=1",
CancelUrl = "https://www.your-venue.example/event/gala-night?cancelled=1"
}, cancellationToken);PHP
<?php
$response = wp_remote_post( 'https://api.bookdineplay.com/api/venues/your-venue/events/gala-night/tickets/checkout', [
'headers' => [ 'X-BookDinePlay-Key' => BOOKDINEPLAY_SECRET_KEY, 'Content-Type' => 'application/json' ],
'body' => wp_json_encode( [
'buyerName' => 'Ada Lovelace', 'email' => 'ada@example.com', 'quantity' => 2, 'attendees' => [ '', 'Grace Hopper' ],
'successUrl' => 'https://www.your-venue.example/event/gala-night?paid=1', 'cancelUrl' => 'https://www.your-venue.example/event/gala-night?cancelled=1',
] ),
] );
$checkout = json_decode( wp_remote_retrieve_body( $response ), true );The return addresses must be https and on the key's origin allowlist. The seats are held until the session expires (expiresAt); if the guest abandons Checkout the seats go back on sale. Send an Idempotency-Key so a retried request returns the same checkout instead of holding seats twice. A gift voucher can pay part or all of the tickets (voucherCode); when it covers everything no Stripe page opens and the tickets are issued at once (Vouchers).
If any of the three conditions — plan, payout account, a Paid event — is missing, the answer is the same 409 ticket-sales-not-enabled on purpose, so a guest never learns which one it was.
6. Tickets and the door
Every ticket has a 12-character code and a ticket page with a QR code that encodes the page address; the guest keeps the e-mail or the page. Neither route needs a key:
curl "https://api.bookdineplay.com/api/tickets/<code>"At the door a team member opens the event's check-in view in the console, enters or scans a ticket, and the ticket turns from Valid to CheckedIn with the time. A wrong scan is undone with the undo action (event_checkin and event_undo_checkin over MCP). A cancelled event's tickets still read Valid, so check the event's own status as well.
7. Cancel and refund
The guest's own registration page (GET /api/registrations/{cancelToken}) says whether cancelling is possible right now (canCancel) and why not (cancelNote): the ticket was checked in, or the refund policy no longer allows an online refund. For a paid event with the policy "full refund until N hours before the start", cancelling before that point refunds the card; afterwards it is refused with refund-not-available and the registration stays untouched.
The venue can always cancel or refund a registration from the console (event_registrations_cancel and event_registrations_refund), whatever the policy says. A refund puts the seats back on sale and returns any voucher part to its voucher. Neither the ticket page, the registration page nor the cancel link is plan-gated: a guest keeps them after a downgrade.
Next steps
- Events API — every field, the registration window and the refund policy in full.
- Events widget and WordPress — the ready-made UI.
- Vouchers — let a gift voucher pay for tickets.