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
Sell and redeem gift vouchers
Set up gift vouchers, sell them via Stripe, let guests pay a tab, deposit or tickets with one, redeem at the table and know what a refund does to the balance.
A gift voucher is money a guest can give away: it is bought online (or issued by hand), arrives by e-mail with a code, and is spent at the table or online against a tab, a deposit or tickets. This tutorial covers the whole life of a voucher — setup, sale, redemption, refund — and where each step touches the API.
Issuing a voucher by hand and redeeming it at the table work on every plan. Selling vouchers online needs Premium, a connected Stripe payout account and online payments switched on. Paying with a voucher and refunding one are never plan-gated.
1. Set up what you sell
In the console's gift voucher settings (or with voucher_settings_update over MCP) you choose:
- The kinds you offer. An amount voucher is spent in parts until the balance is used up. A percentage voucher takes a percentage off one bill, optionally capped in money. An item voucher is one menu item. Each product has a title; amount products have a price or let the buyer pick an amount between a minimum and maximum.
- How long a voucher is valid: a number of months from the day it is issued, a fixed date, or until the end of a year. A voucher bought online is valid for at least a year; a rule that would give less is refused (
voucher-validity-too-short), and online sale stays off until a rule is set (voucher-validity-not-set). - Terms in English and German, kept on each voucher as they were when it was issued.
- Online sale on or off.
Amount products also need a VAT classification, which you choose in the settings.
2. See what is for sale
Your page asks the venue what it sells right now. The call answers on every plan: when vouchers cannot be bought online, onlineSaleAvailable is false and unavailableReason says why. Show guests the same sentence for any reason — they cannot act on the venue's setup.
curl
curl "https://api.bookdineplay.com/api/venues/your-venue/vouchers/offers" \
-H "X-BookDinePlay-Key: bdp_pk_your_publishable_key" \
-H "Origin: https://www.your-venue.example"JavaScript
const offers = await client.voucherOffers();
if (!offers.onlineSaleAvailable) console.log(offers.unavailableReason);C#
var offers = await client.GetVoucherOffersAsync("your-venue", cancellationToken);PHP
<?php
$response = wp_remote_get( 'https://api.bookdineplay.com/api/venues/your-venue/vouchers/offers', [ 'headers' => [ 'X-BookDinePlay-Key' => BOOKDINEPLAY_SECRET_KEY ] ] );
$offers = json_decode( wp_remote_retrieve_body( $response ), true );The quickest shop is the widget — window.BookDinePlay.renderVoucherShop({ container, venueSlug, apiBaseUrl, publishableKey }) — or [bookdineplay_vouchers venue="your-venue"] on WordPress (Voucher shop).
3. Sell one
The buyer picks an offer and gives their name and e-mail, optionally a recipient, a message and a delivery date up to a year ahead. The checkout opens a Stripe session on the venue's own account and returns the address to send the buyer to. Send an Idempotency-Key so a retry replays the same checkout:
curl
curl -X POST "https://api.bookdineplay.com/api/venues/your-venue/vouchers/checkout" \
-H "X-BookDinePlay-Key: bdp_pk_your_publishable_key" \
-H "Origin: https://www.your-venue.example" \
-H "Idempotency-Key: 4f9c2a1e8b7d4c3f9e0a1b2c3d4e5f60" \
-H "Content-Type: application/json" \
-d '{ "productId": "3f2a1b4c5d6e4f708192a3b4c5d6e7f8", "buyerName": "Ben Buyer", "buyerEmail": "ben@example.com", "recipientName": "Ada" }'JavaScript
const checkout = await client.checkoutVoucher(
{ productId, buyerName: 'Ben Buyer', buyerEmail: 'ben@example.com', recipientName: 'Ada' },
{ idempotencyKey: crypto.randomUUID() }
);
window.location.assign(checkout.checkoutUrl);C#
var checkout = await client.StartVoucherCheckoutAsync("your-venue",
new StartVoucherCheckoutRequest { ProductId = productId, BuyerName = "Ben Buyer", BuyerEmail = "ben@example.com", RecipientName = "Ada" },
idempotencyKey: Guid.NewGuid().ToString(), cancellationToken);PHP
<?php
$response = wp_remote_post( 'https://api.bookdineplay.com/api/venues/your-venue/vouchers/checkout', [
'headers' => [ 'X-BookDinePlay-Key' => BOOKDINEPLAY_SECRET_KEY, 'Content-Type' => 'application/json', 'Idempotency-Key' => wp_generate_uuid4() ],
'body' => wp_json_encode( [ 'productId' => $product_id, 'buyerName' => 'Ben Buyer', 'buyerEmail' => 'ben@example.com', 'recipientName' => 'Ada' ] ),
] );
$checkout = json_decode( wp_remote_retrieve_body( $response ), true );The voucher does not exist until the payment is confirmed. Then it is issued, its code is created and the buyer — or the recipient, on the delivery date — receives an e-mail with the code and the voucher's page. The response carries only a display reference (GV-…) and never a code. A sale whose payment never arrives creates no voucher and is deleted 30 days after its checkout expired.
To give a voucher without selling it — a prize, an apology — or to record one sold at the till, issue it by hand in the console or with vouchers_issue. That works on every plan; you say how it was paid, or that it was not (a promotion or goodwill voucher).
4. Look a voucher up
The code is a bearer credential, like a gift card: whoever holds it can spend it. A guest's page or your own can look it up with no key, by the code in any form a guest might type, and gets its kind, status, balance and expiry — never its history or the buyer's details. Every code that does not resolve answers the same 404, so codes cannot be tried one after another, and the lookup is limited to 30 a minute per client:
curl
curl "https://api.bookdineplay.com/api/vouchers/K7QM-2XRP-9DTA-HV3N-8W4F"JavaScript
const voucher = await client.voucher(code); // sends no key; null when unknownC#
var voucher = await client.GetVoucherAsync(code, cancellationToken); // sends no key; null when unknownPHP
<?php
$response = wp_remote_get( 'https://api.bookdineplay.com/api/vouchers/' . rawurlencode( $code ) ); // sends no key
$voucher = json_decode( wp_remote_retrieve_body( $response ), true );Never log a code, and never put one in a URL of your own: the lookup is the only route with the code in its path, and BookDinePlay strips it from its own logs.
5. Pay with a voucher
Online, a guest adds the voucher code to a payment they are making anyway; leave it out and nothing changes. The same three payments take an optional voucherCode:
| Payment | Kinds accepted |
|---|---|
| A table tab (QR ordering) | Amount, percentage |
| A reservation deposit (Deposits) | Amount |
| Event tickets (Events) | Amount |
The rules are the same everywhere. The voucher pays first and the card the rest; the voucher's value is held while the guest is on Stripe's page and taken when the payment lands, so it cannot be spent twice, and a hold the guest abandons lapses on its own. The card part is never below Stripe's minimum (€0.50 in euro): if less would be left, the voucher pays a little less so the card pays exactly the minimum. A voucher that covers everything opens no payment page — the payment completes at once and the returned address is the success page, so a client that just follows it works either way. A percentage voucher is a discount on the whole bill, applied before amount vouchers and capped at what is due.
6. Redeem at the table
Staff redeem a voucher in the console: look the code up (scan or type it), choose what it pays and confirm — the full amount or a part for an amount voucher, the discount for a percentage one, the line it covers for an item voucher. Over MCP: voucher_lookup, voucher_redeem and voucher_reverse_redemption. A table redemption can be undone once, within the undo window unless staff give a reason (voucher-undo-not-allowed); an online redemption is undone by refunding the payment instead.
Table redemption stays available even if the venue's subscription is suspended: the guest has already paid for the voucher.
7. Refunds and what happens to the balance
A voucher's balance is not a stored number but the sum of an append-only ledger of everything that happened to it, so a refund never edits history, it adds an entry:
- Refunding a payment that a voucher helped pay puts the voucher's part back on the voucher and sends only the card part back to the card. An expired voucher is extended to 30 days from the refund, so the guest can still use what came back. A voucher the venue has voided stays void: the refund is recorded and the venue settles the value with the guest directly.
- Refunding a voucher's sale is possible only while the voucher is unused, and it voids the voucher.
- Voiding, changing the expiry and resending the e-mail are venue actions (
vouchers_void,vouchers_change_expiry,vouchers_resend). Voiding asks for confirmation first over MCP.
Next steps
- Vouchers API — every route, field and problem.
- Voucher shop — the ready-made widget.
- Errors — what to show for each voucher problem.