Skip to content

BookingZone Domain Glossary

The canonical terms for every entity, role, and concept in the platform. One term — one meaning. Use these names in code, specs, ADRs, API identifiers, and internal documentation. End-user-facing labels MAY differ for localization or white-label branding, but internal names do not.

Tenant Hierarchy

Business

The top-level multi-tenant entity. A single legal/operational owner. Owns multiple Outlets. Has a single billing relationship with the platform.

  • DocType: BZBusiness
  • NEVER call it: Tenant, Account, Company, Organization
  • Examples: "Malibu Jack's", "Scene 75 Entertainment"

Outlet

A single physical location belonging to a Business. Has its own timezone, operating hours, payment configuration, and resource catalog. Most business operations are scoped at the Outlet level.

  • DocType: BZOutlet
  • NEVER call it: Location, Site, Branch, Store, Venue (Venue means something different — see below)
  • Examples: "Malibu Jack's Lexington", "Scene 75 Cincinnati"

Venue

A bookable space within an Outlet — e.g., a party room, a bowling lane section, an arcade zone. An Outlet contains multiple Venues. A Venue contains multiple Resources.

  • DocType: BZVenue
  • Confusing because: industry vocabulary often uses "venue" to mean the whole location. We do not. Outlet = location. Venue = sub-area.

Venue Resource

An individual bookable unit within a Venue — a single lane, a single table, a specific room. The atomic unit of capacity.

  • DocType: BZVenueResource

Bookings

Booking

A confirmed or pending reservation made by a Customer at an Outlet for one or more Service Items at a specific time, possibly involving Venues and Resources.

  • DocType: BZBooking
  • NEVER call it: Reservation, Order, Appointment, Event (Event means a Party — see below)
  • Status values: Pending, Confirmed, CheckedIn, Completed, Cancelled, NoShow, Wait

Booking Item

A line within a Booking representing one Service Item purchased.

  • DocType: BZBookingItem

Booking Addon

An additional purchase attached to a Booking (Power Up, food upsell, etc.)

  • DocType: BZBookingAddon

Multi-Day Booking

A Booking spanning multiple calendar dates. Modeled with daily breakdowns.

  • DocType: BZBookingDailyBreakdown

Walk-In

A Booking created at the front desk for a Customer who arrived without a prior reservation. Identified via is_walk_in: true.

Party / Event

A specifically-marketed event Booking (typically a birthday party with a package). Managed via the Parties module pipeline.

Customers

Customer

A person (or family) who books at one or more Outlets within a Business. Identified by email + phone. May or may not have an authenticated account.

  • DocType: BZCustomer
  • NEVER call them: Guest (see below for the distinction)

Guest

An UNAUTHENTICATED visitor — never logged in, no account. Distinct from a Customer. A Booking made by a Guest stores is_guest: true and may be linked to a Customer later (e.g., if the Guest creates an account post-booking).

Family Member

A relative attached to a Customer profile (typically children whose birthdays trigger party marketing). Not a separate Customer.

  • DocType: BZCustomerFamilyMember

Catalog

Service Item

A bookable thing offered at an Outlet — a Plan, an Addon, or a Package. The unit of what a Customer is buying.

  • DocType: BZServiceItem
  • Subtypes (via item_type field):
  • Plan — a primary booking unit (e.g., "2-hour Bowling")
  • Addon — attached to a Plan (e.g., "Power Up")
  • Package — a bundle (e.g., "Birthday Party Package")

Schedule

A definition of when a Service Item is bookable, with capacity per slot.

  • DocType: BZSchedule

Schedule Slot

A specific bookable time window within a Schedule.

  • DocType: BZScheduleSlot

Roles & Access

System Admin

Platform-level role with access to all Businesses. Internal staff only.

Business Admin

Manages a single Business and all its Outlets.

Outlet Manager

Manages one or more specific Outlets within a Business. A multi-outlet manager has an "active outlet" resolved per session.

Customer

Authenticated end-user. Sees only their own Bookings.

Guest

Unauthenticated visitor. Read-only public catalog access.

Payments

Payment Transaction

A single payment attempt — successful, failed, refunded, or voided.

  • DocType: BZPaymentTransaction
  • Gateways (via payment_gateway field): Magensa, Datacap, Stripe, Square, CenterEdge, Manual

Idempotency Key

A unique identifier on every Payment Transaction request that ensures replays do not duplicate charges. Mandatory for every payment call.

Refund

A reversal of a previous Payment Transaction. May be full or partial. For Datacap same-day, expressed as a Void rather than a Refund.

Gift Card / Promo Code

Stored-value or discount mechanisms applied at Booking creation.

  • DocTypes: BZGiftCard, BZPromoCode

Communication

Notification

A queued, idempotent dispatch of an email, SMS, or push to one or more recipients. All notifications go through the central bookingzone.notifications service.

Notification Template

A named, versioned, Jinja2-renderable template used to compose a Notification.

Notification Channel

The transport: EMAIL, SMS, PUSH. Chosen per template based on the constitution's Communication Channel Routing rules.

Integrations

GHL (GoHighLevel)

External CRM. Used for email delivery and contact sync. Authenticated via OAuth per Business.

GHL Location

A workspace within a GHL agency account. Each BZOutlet maps 1-to-1 to a GHL Location (see specs/SYS-001-ghl-outlet-mapping).

R365 (Restaurant365)

External accounting/finance system. Receives daily SFTP exports of transactions for outlets that have it configured.

OpenPhone

Transactional SMS / voice provider for booking-related communication.

SlickText

Marketing SMS provider. NOT used for transactional flows.

Operations

Cart

A pre-booking shopping basket. Holds Service Items and locked Resources prior to confirmation. Expires.

Lock / Resource Lock

A short-lived hold on a Venue Resource preventing double-booking during the cart phase. Acquired via bookingzone.api.lock_manager.

Confirmation Code

A 6-character alphanumeric code generated when a Booking transitions to Confirmed. Used by Customers to look up their Booking without authentication.

Audit Log

A structured record of a sensitive action (refund, role change, deletion). Different from the application log — never silently dropped.

Anti-Pattern Vocabulary (DO NOT USE)

Wrong Right
Reservation Booking
Order Booking
Location Outlet (top-level) or Venue (sub-area)
Branch Outlet
Site Outlet
Tenant Business
Company Business
Account Business (entity) or Customer (person)
Guest (when authenticated) Customer
Appointment Booking
Slot Schedule Slot (when timestamped) or Time Slot (when display only)