Booking policies & cancellation

A policy version is the exact set of booking terms a guest accepts when they book: whether money is involved, how long before the service they may cancel for free, and how much is retained if they cancel late or do not arrive. Versions are immutable and every booking stores the version it accepted, so terms can never be rewritten under an existing booking. Policies are published per offering by a manager or above (venues.manage) in the “Version policies and price/cancel preview (DEV-015 panel)” at /app/panels.

Versions are immutable

Publishing creates the next version number of the offering (1, 2, 3, …). A published version is never edited. To change your terms you retire the active version (form “Retire a version”) and publish a new one; the listing marks rows active or RETIRED with a timestamp.

This is what makes the system honest for guests: a booking stores a full snapshot of the terms it accepted — version id, amounts, windows and the accepted text — and the cancellation calculation reads that snapshot and nothing else. Later publishes never change what an existing booking owes.

Scope and the strict-chain rule

A version always targets one offering, and may be narrowed with:

• a specific weekly schedule (blank = the whole offering), and/or
• a party-size range (minimum and maximum come as a pair).

When a booking is priced or quoted, the most specific active rule for that offering, schedule and party size wins. To keep “most specific” unambiguous, the active rules of one offering must form a strict chain: a new version may overlap an existing one only if it is strictly narrower (or strictly wider). An overlap with neither side strictly more specific — including two rules with an identical scope — is refused with RULE_VIOLATION (422): “This predicate overlaps an active rule without being strictly more specific — retire first or narrow it.”

Publishing a version

Form “Publish a policy version”:

Field	What it is	Rules/limits
Offering id	Which service the terms govern.	Required; must belong to the venue.
Schedule id	Optional narrower scope to one weekly window.	Blank = offering-wide.
Minimum / maximum party	Optional party range.	1–200, given as a pair with maximum at least the minimum; blank = any party size.
Payment mode	None (free booking) or Deposit.	See the pilot note below before choosing Deposit.
Amount basis	Per booking or Per person.	Deposit versions only.
Amount in integer minor units	The deposit amount.	A positive whole number of minor units for deposits; None versions always carry zero. No floating-point amounts anywhere.
Currency	The amount’s currency.	Must equal the venue currency (a venue never mixes currencies); blank takes the venue currency.
Free cancellation minutes	How long before the start cancelling is free.	0–20160 minutes (up to two weeks), default 1440 (24 hours).
Late retention bps	Share retained on a late cancellation.	0–10000 basis points of the expected amount (10000 = the whole amount).
No-show retention bps	Share retained on a no-show.	0–10000 basis points.
Grace minutes	How long after the booked start a no-show may be recorded.	0–1440, default 15; marking a no-show earlier is refused.
Localized accepted texts	The terms text guests accept, per locale.	A JSON object of locale → text, up to 20 locales, each up to 5000 characters. Must include the venue default locale and every locale the venue lists as active.

The accepted text is the guest-facing wording of the terms — write it for guests, not as internal rules.

What guests see and accept

During booking, the terms are shown under “Booking terms” in the guest’s locale (falling back to the venue default); a deposit version also shows the exact expected amount. Accepting pins the version id to the booking, and the snapshot travels with the reservation:

• Cancelling quotes the snapshot: the free-cancellation cutoff is the booked start minus the free-cancellation window (real elapsed minutes). At or before the cutoff the outcome is FREE_CANCELLATION; after it, LATE_CANCELLATION with the late retention share applied to the expected amount. Refundable and retained parts are reported in exact integer minor units and always sum to the expected amount.
• POLICY_STALE (409) — the terms changed between the guest accepting and the booking committing. Remedy: review and accept the current policy, then rebook.
• REBOOK_REQUIRED (409) — a proposed self-service change would alter the booked amount. Remedy: cancel and rebook under the current disclosed terms; the edit path never charges anything.

You can rehearse all of it without booking: the panel’s form “Resolve policy + cancellation preview” resolves the rule a candidate booking would get and quotes its cancellation at any instant you name.

Deposits in this pilot

The DEPOSIT mode is fully built but switched off in the live pilot:

• Publishing a deposit version requires the venue’s connected payment account to be charge-ready — an active, charge-capable account in the venue currency with an approved country. Without that readiness the publish is refused with the exact blocking reason.
• In the current pilot no production payment provider is configured and the capability gates stay closed, so any booking attempt against a deposit offering refuses with PAID_BOOKING_UNAVAILABLE (422): paid booking is not available yet; only free bookings complete. Deposits you model are configuration only — nothing is ever charged while the gates are closed.

Single-market pilot evidence only: one approved country and its listed capabilities do not constitute global support; unlisted countries and capabilities stay disabled.

The same statement is published on the public /capabilities page.

Once the gates open, the payment flow — holds, checkout, refunds — is described in Payments (pilot posture) and Refunds.