Reports & metrics

Reports turn your venue’s ledgers into operational numbers: how much demand you accepted, how many parties sat and finished, how cancellations split, how long guests waited, and how much money settled — each currency on its own. Every figure is an aggregate recomputed live from the reservation, visit, waitlist and payment ledgers; no guest personal data is queried or returned, and reading a report never changes a booking. You run the report from the operational metric panel in the operator console. The report is also honest about its gaps: five metrics that need data this pilot does not collect are listed as unavailable instead of being filled with zeroes.

Who can run a report

The report is one command guarded by the reporting.read permission, checked against your live venue membership on every run:

Role	Can run the report?
Owner, org admin	Yes
Manager	Yes
Finance	Yes
Read-only	Yes — the same aggregate-only truth
Host, Door	No — PERMISSION_DENIED; hosts and door staff use the service sheet instead

A venue id that does not exist, or that you hold no membership for, reads as plain not-found — cross-tenant probing looks identical to a typo (NOT_FOUND). The report carries a definition version (v1), a generation timestamp and this privacy notice: aggregates only, and every figure recomputes from live state at the generation time shown.

Filters

Filter	Format	Rules
Service business date from / to	YYYY-MM-DD, required	Keys the operational cohort: reservations assigned to service business dates in the range (the venue-local date the service starts — see Languages, time zones & money). The end must not precede the start, the range spans at most 366 days, and a single day is allowed.
Settled window from / to	ISO datetime, optional	Keys the money section separately: payment transactions by their settled instant (settled_at). Provide both bounds or neither; the end must fall strictly after the start, within 366 days.
Currency	three upper-case letters, optional	Narrows the per-currency money section only. It never affects the operational counts.

The two date windows are deliberately separate so a report can never silently mix bases: operations key on business dates, money keys on settled transactions. Every screen states which cohort it used.

Demand and lifecycle

All of these count the service-date cohort for your venue.

Metric	What it counts
accepted parties	Parties that reached CONFIRMED at least once. CONFIRMED and NO_SHOW bookings always qualify; a CANCELLED booking qualifies only if it carries an approval stamp or was born confirmed. A cancelled never-confirmed request never enters accepted demand.
active booked parties / covers	Bookings still CONFIRMED in the window, and the sum of their party sizes.
Outcome breakdown	The accepted parties split into ACTIVE_CONFIRMED, NO_SHOW, CANCELLED_GUEST and CANCELLED_STAFF; the breakdown always sums to the accepted count.
Party-size distribution	Accepted parties grouped by party size.
Source mix	Accepted parties grouped by booking source channel.
Booking lead time	Median and p90 minutes from the moment the booking was decided (for approved requests — see Request-approval bookings) or created (everything else) to the booked start. Imported bookings are excluded and reported separately as an excluded count.

Service outcomes

Metric	Definition as computed
guest cancel rate	Guest-cancelled accepted parties divided by all accepted parties.
venue cancel rate	Staff-cancelled accepted parties divided by all accepted parties.
no-show rate	No-showed accepted parties divided by accepted parties whose start time has passed and that either became a no-show or recorded at least one arrival. Future starts and never-started bookings are not in the denominator.
unclassified	Accepted parties that started, are still CONFIRMED, and never recorded an arrival — shown separately, never folded into the no-show denominator.
seated / completed parties and covers	Visits seated (seated_at stamped) and departed, with covers taken from each visit’s arrival counter — the corrected count of people who actually arrived, not the booked party size.
Visit duration	Median and p90 minutes from seat to departure over completed visits.
repeat guests share	Among departed visits of identified guests, the share whose same guest profile had an earlier completed visit at this venue.
Anonymous completed visits	Departed visits with no guest profile at all.

Waitlist

Counts come from the same business-date window (see the waitlist for the queue itself): total entries, entries converted into a seated party, the waitlist conversion rate (converted divided by total entries), entries still waiting or holding an open offer, entries that left, and the median and p90 wait in minutes from joining the queue to being seated.

Approval funnel

For request-mode bookings submitted in the window (keyed on the venue-local date of submission): approved, declined, pending and expired counts. The acceptance rate is approved divided by (approved + declined) — pending and expired requests are shown separately and never enter the denominator, so an undecided backlog cannot flatter the rate.

Money

Money is reported per currency and never combined: a venue that settles in two currencies gets two independent sections, with no combined total anywhere and no conversion between them (see Refunds for the ledger behind these figures).

Per currency the report shows, in exact integer minor units:

Figure	What it is
collected	Sum of settled capture amounts in the settled window.
refunded	Sum of settled refund amounts (shown as a positive figure).
net	Collected minus refunded.
Capture / refund / dispute counts	How many settled ledger entries of each kind.
pending refund	Refund intents still requested or awaiting the provider — pending cash, never displayed as refunded money.
aged pending	Pending refund intents older than 24 hours, counted separately.

How rates are shown

Every rate carries its own numerator and denominator. The panel prints them as, for example, guest cancel: 3/25 = 12.00%; the CSV export records the raw ratio. When the denominator is zero the report says not applicable — never a misleading 0%.

What is marked unavailable

Five metrics need data this pilot does not collect. They are listed as unavailable with their reasons — hidden, never invented as zeroes:

Metric name	Reason shown
posSpendMetrics	No POS adapter exists in V1 — spend, course and RevPASH figures stay hidden rather than invented zeroes.
onlineBookingConversion	Requires lawful analytics instrumentation that is not configured; unavailable, never a fabricated zero.
demandLost	Requires instrumentation V1 does not collect; no revenue estimate is invented.
resourceUtilization	Deferred: planned utilization needs the operating-window intersection with the allocation seam.
actualResourceOccupancy	Deferred: occupancy needs recorded occupied-minute windows that the visit seam does not persist.

When a report is refused

Code	Meaning and remedy
VALIDATION	A filter was rejected — business dates are YYYY-MM-DD at most 366 days apart, the settled window needs both bounds or neither, and the currency is a three-letter uppercase code. Fix the named fields.
NOT_FOUND	Unknown venue — or not visible to this account. Check the venue id and your membership.
PERMISSION_DENIED	Your role cannot run metric reports. Ask a manager or above, or use the service sheet if you are a host.
UNAUTHENTICATED / SESSION_INVALID	Your staff session is missing, revoked, expired or stale — sign in again.

The full taxonomy lives in Error codes & fixes. The same aggregates can be exported as a formula-escaped CSV — see Service sheet & CSV exports.