Developer docs

Audit log

Read who changed what, when and through which channel: the venue and account log, a booking's history, the CSV export, and what is never recorded.

The audit log answers one question: who did what, when, through which channel, and what exactly changed — above all when a booking's time moved or a sum of money changed hands. Every change a person, an integration, a webhook or a scheduled job makes to a venue's bookings, money, vouchers, team, keys and settings writes one entry, in the same database transaction as the change itself: if the change is rolled back, so is its entry.

These routes are read-only and belong to the operator API under /api/operator/**. They act as a signed-in person (a bearer token, like the console), not through a venue key, so what comes back depends on that person's team role. The same data is available to assistants through the MCP tools and to .NET code through the SDK.

What is recorded

Each entry carries:

  • Who: the actor's kind (Guest, Operator, PlatformAdmin, ApiClient, App or System), an id and a display name as it was then, and the team role of an operator. A call a BookDinePlay platform admin makes while acting inside your account is marked with the admin's name, so the log shows "BookDinePlay support" rather than your own staff.
  • Through which channel: Console, App, Web, Widget, Api, Mcp, Webhook or System, plus the MCP tool that made the call and the id of the API key (never its value).
  • When: the instant in UTC, the venue-local clock time, and the business day: the day the night started in the venue's time zone, so Saturday night includes 01:30 on Sunday.
  • What: an action such as reservation.moved, deposit.refunded or voucher.redeemed; the entity it happened to (entityType, entityId, the human entityReference such as BDP-7Q2M3K, and the groupReference of a group booking); and the before and after of every changed field.
  • Money: the amount, the currency, how it moved (Card, Voucher, Cash, Waived, Store, Manual) and the identifiers a refund needs. Never card data.
  • Time: the resource, start, end and duration a booking moved between, and when a play clock was started and stopped.
  • The outcome: Succeeded, Failed (a money operation that did not go through, with a failureCode) or Refused (a permission refusal). Validation errors are not recorded.

Reading the log is itself recorded: viewing or exporting it writes an audit.viewed or audit.exported entry, and so does opening a booking's history when it showed personal values.

What is never recorded

A credential never enters the log: not an API key, a voucher code, a ticket code, a cancel link, a QR token, a signed payload or a card number. An entry names the reference (BDP-…, GV-…) and the id instead. The writer checks every value by its shape and drops one that looks like a credential.

Who can read what

Reader Venue log and export Account log A booking's or tab's history Personal values
Owner every venue yes yes yes, with client address and user agent
Manager their venue no yes yes, with client address and user agent
Staff no (403) no (403) only a booking or tab they can open the booking's values, never an actor's address
Platform admin (not acting inside the account) any account, through /api/admin/audit — — none

A Manager restricted to one venue who asks for a sibling venue's log gets venue-not-permitted; a slug the account does not own is venue-not-found. A refused role is team-role-required.

Personal data and erasure

The values of personal fields (a guest's name, phone number, notes, the client address and user agent of whoever acted) are stored encrypted with a key per person. When a guest or an employee is erased, their key is destroyed: the entry, its money and time fields and its place in the log stay, and the values become unreadable for good.

You see this as a state, never as an error. Every entry has a personalDataState: None (nothing personal stored), Readable, Withheld (stored, but your role does not show it), Erased (the person was erased) or Tampered (the stored ciphertext no longer verifies; reported, never thrown, so one bad entry cannot hide a history). A changed field that holds personal data is listed with personal: true; its before and after are only filled for a reader who may see them and while the key exists.

Retention and plans

An entry with an amount of money is kept 10 years (commercial and tax record-keeping); every other entry 24 months. Every plan writes the log and can read it, but history older than 90 days and the CSV export need the Pro plan or higher. On Starter a page says windowLimited: true with the earliest instant it reads, and the export answers feature-not-in-plan with requiredPlan: "Pro".

Endpoints

The venue log

GET /api/operator/venue/audit: one page of the selected venue's log, newest first (Manager and up). Select the venue with the X-BookDinePlay-Venue header on an account with several venues. Every filter combines with AND:

Query Meaning
from, to ISO 8601 instants, from inclusive and to exclusive; a plain date means midnight UTC
businessDay yyyy-MM-dd, the day the night started
actorId, actorKind The actor's id; Guest, Operator, PlatformAdmin, ApiClient, App or System
channel Console, App, Web, Widget, Api, Mcp, Webhook or System
action An action name such as reservation.moved
entityType, entityId Reservation, TableSession, Voucher, Event, Venue and so on; the entity's id
reference A booking reference; also finds the entries of the booking's group
moneyOnly, timeOnly true for only the entries that carry an amount, or that moved a booking's time or resource
cursor, pageSize Paging, see below; pageSize is 1 to 200 (default 50)
order desc (default, newest first) or asc

curl

curl "https://api.bookdineplay.com/api/operator/venue/audit?action=reservation.moved&pageSize=50" \
  -H "Authorization: Bearer $OPERATOR_TOKEN" \
  -H "X-BookDinePlay-Venue: your-venue"

JavaScript

// Server-side or in your own console: the bearer token is the signed-in operator's, never a venue key.
const response = await fetch('https://api.bookdineplay.com/api/operator/venue/audit?action=reservation.moved&pageSize=50', {
  headers: { Authorization: `Bearer ${operatorToken}`, 'X-BookDinePlay-Venue': 'your-venue' }
});
const page = await response.json();
for (const entry of page.items) {
  console.log(entry.occurredAt, entry.actor.name, entry.action, entry.entityReference);
}

C#

// `operatorClient` is the BookDinePlayOperatorClient from AddBookDinePlayOperatorClient, sending the operator's bearer token.
var page = await operatorClient.GetAuditLogAsync(
    new AuditLogFilter(Action: "reservation.moved", PageSize: 50), "your-venue", cancellationToken);
foreach (var entry in page.Items)
{
    Console.WriteLine($"{entry.OccurredAt:u} {entry.Actor.Name} {entry.Action} {entry.EntityReference}");
}

PHP

<?php
$response = wp_remote_get( 'https://api.bookdineplay.com/api/operator/venue/audit?action=reservation.moved&pageSize=50', [
    'headers' => [ 'Authorization' => 'Bearer ' . $operator_token, 'X-BookDinePlay-Venue' => 'your-venue' ],
] );
$page = json_decode( wp_remote_retrieve_body( $response ), true );
foreach ( $page['items'] ?? [] as $entry ) {
    echo "{$entry['occurredAt']} {$entry['actor']['name']} {$entry['action']} {$entry['entityReference']}\n";
}

Response 200 OK: items (the entries), nextCursor (null on the last page), personalDataIncluded (whether your role may see personal values), windowLimited and earliestAvailable (the plan reads back only 90 days).

The account log

GET /api/operator/audit: the same page for the whole account, every venue, including entries that belong to no venue (billing, team, the account itself). Owner only; a login bound to one venue gets tenant-operator-required. The optional venue parameter narrows it to one venue slug; a slug the account does not own is 404. It takes the same filters as above.

The CSV export

GET /api/operator/venue/audit/export: the venue's log as CSV (Manager and up, Pro plan or higher; the export is itself recorded). It takes the same filters, ignores cursor and pageSize and walks every page itself, up to 50,000 rows; a larger window stops there and the response carries the header X-BookDinePlay-Export-Truncated: true, so narrow the filter and export again.

The file is UTF-8 with a byte-order mark (Excel reads umlauts right), comma separated, CRLF line ends, with a header row. One column per fact: sequence, occurredAtUtc, businessDay, venueLocalTime, venue, action, outcome, failureCode, the actor (actorKind, actorId, actorName, actorRole, impersonatedBy), channel, mcpTool, the entity (entityType, entityId, reference, groupReference), the money (amount, currency, moneyMethod, cardAmount, voucherAmount), the time (oldResource, newResource, oldStartUtc, newStartUtc, oldEndUtc, newEndUtc, oldDurationMinutes, newDurationMinutes), changes (field: before -> after; …), reason, personalDataState, clientAddress, userAgent and source. Every text cell is made safe against spreadsheet formulas: a value that starts with =, +, -, @, a tab or a carriage return gets a leading apostrophe, so a guest's name typed as =HYPERLINK(…) stays text.

The history routes

A history is what the console shows beside one thing, as a story: oldest first by default (order=desc turns it around), paged like the log.

Route Role What it shows
GET /api/operator/venue/reservations/{reference}/history Staff and up One booking and, for a group booking, every member of the group; memberReferences lists them
GET /api/operator/venue/tabs/{id}/history Staff and up One tab (table session)
GET /api/operator/venue/vouchers/{id}/history Manager and up A gift voucher: its audit entries merged with its own ledger, not paged
GET /api/operator/team/{id}/history Manager and up What one login did at this venue, newest first; needs the plan's team feature like the other team routes

The response is entityType, entityId, reference, groupReference, items, nextCursor, personalDataIncluded, windowLimited and memberReferences. An unknown booking, tab, voucher or login of this venue is 404.

A voucher's history also covers what happened before the log existed: lines of the voucher's own ledger have source: "voucher-ledger" and an action such as voucher-ledger.redeemed. A ledger line the log also recorded shows once, as the richer audit entry. The voucher code is never part of it.

Filter options

GET /api/operator/venue/audit/filters: the values a filter takes, so a console builds its drop-downs from the server: actions, entityTypes, actorKinds, channels, outcomes, maxPageSize, canExport and historyDays (null when the plan reads the whole retention period).

Paging

Pages are a keyset on the entry's sequence, the per-account counter every entry gets inside its transaction. Pass the nextCursor of a page as cursor to read the next; the cursor is opaque. Because a new entry always gets a higher sequence than any existing one, a page never shifts while new entries are written: no entry is skipped or repeated, which an offset cannot promise. A cursor this version did not hand out is 400 invalid-cursor. A bad date, kind, channel or page size is a 400 validation problem naming the field.

Entry fields

Field Meaning
id, sequence A unique id; the per-account order entries were committed in
occurredAt, businessDay, venueLocalTime When, in UTC; the day the night started; the venue-local clock time
action, outcome, failureCode What happened and how it ended
entityType, entityId, entityReference, groupReference What it happened to
actor kind, id, name, role, and impersonatedById and impersonatedByName for a platform admin acting inside the account
origin channel, clientId, mcpTool, mcpConfirmed, apiKeyId, apiKeyType, clientClass, and for an Owner or Manager clientAddress and userAgent
money, time The amount and the moved slot, as described above
changes field, before, after and personal for each changed field
reason The reason the actor gave; a person's reason may name a guest, so it follows the rules of personal values
personalDataState, retentionClass, source See above; Standard or Money; audit or voucher-ledger

Platform admins

GET /api/admin/audit?tenantId=… reads any account's log for support, with the same filters and paging and an optional venue. It shows no personal values, no client addresses and no plan limits, and the read is recorded in the account's own log as audit.viewed by the admin. An admin who acts inside the account (impersonation) is an Owner of it, and the operator routes above apply.

Errors

Status Type When
400 invalid-cursor The cursor is not one this API handed out
400 validation problem A filter value is malformed or out of range
403 team-role-required Your team role does not reach the route
403 venue-not-permitted A Manager bound to one venue asked for another
403 feature-not-in-plan The export, or the team history, needs a higher plan
404 — An unknown booking, tab, voucher or login of this venue; a venue slug the account does not own is venue-not-found

Next steps