Membership is a lifecycle, not a hidden plan card.
This manual shows where benefits appear from admin setup through Olivia's wallet, booking, payment, receipt, vendor booking review, usage ledger, renewal, and reporting.
Benefit lifecycle
Benefits should never be visible in only one place. A customer needs to know what they get, what they used, and what remains. A vendor needs to know why the booking price changed and whether support/refund review exists.
Admin Programs: what members get
Programs tabs and operator flow
| Tab | Use it for | Proof screen |
|---|---|---|
| Overview | Program health, segment mix, lifecycle explanation, and top benefit proof. | Programs overview metrics and lifecycle cards. |
| Plans & Perks | Create membership plans, create packages, and manage customer-visible perk CRUD. | Membership Perk CRUD rows and plan benefit chips. |
| Assign & Sell | Assign a selected plan to a selected customer or sell a selected package using dropdown-first forms. | Customer membership rows, package purchase rows, and wallet cards. |
| Members | Review active assignments, dependent count, rules, and usage count. | Members and eligibility table. |
| Usage | Audit discounts, deposit waivers, package credits, and vouchers applied to bookings. | Benefit usage ledger. |
| Renewals | Check expiring memberships and package credit watch items. | Renewal queue and package credit watch. |
Perk CRUD: what happens when
If you add a perk
BookFlow stores it as an active membership_benefit_rules row with rule_type = perk, syncs the plan's legacy perks summary, and shows the perk as a customer-facing chip in Programs, wallet, booking/payment benefit summaries, and storefront program blocks where applicable.
If you edit, disable, or delete a perk
The Programs page updates the rule immediately. Disabled perks stay available for audit but disappear from active customer summaries. Deleted perks are removed from the plan's visible benefit set.
Plan rule setup
15% off recovery visits
The discount rule should identify eligible services, locations/staff if scoped, usage limits, and blackout windows if any.
No deposit at booking
The booking form should explain that the deposit is waived because the account is matched to an active membership.
Preferred booking access
The customer-facing preview should say what priority means and where it applies instead of hiding it inside admin metadata.
Credits left and eligible services
Credits must show remaining count, used count, expiry, service eligibility, and whether a booking consumed a credit.
Olivia preview example
Nimbus Recovery Member: 15% off recovery visits, deposit waived, priority slots, 3 recovery credits left, renews monthly, benefits match when Olivia books with the same account or email.
Customer wallet: what I get, used, remains
Booking benefit summary
Benefit resolution order
- Membership discount and deposit waiver.
- Voucher benefit.
- Package credit.
The order stays predictable unless an explicit rule overrides it. When a benefit applies, BookFlow should store a booking snapshot so the vendor and customer can explain the price later.
Payment ledger and receipt
Vendor booking review
Invoice and receipt state
Shows whether the customer paid, what remains due, and which receipt or payment record proves it.
Applied benefit snapshot
Shows membership discount, waived deposit, package/voucher usage, and the benefit source.
TicketPro case reference
Shows external support reference when a customer submits a support request or a receptionist escalates.
Manual refund review
Shows paid cancellation context without creating a separate dispute domain.
Usage ledger and reporting
| Ledger entry | When created | Visible proof | Why it matters |
|---|---|---|---|
| Membership discount | Eligible booking/payment applies percent or amount discount. | Booking snapshot, payment ledger, Programs usage. | Explains reduced price. |
| Deposit waiver | Eligible membership waives required deposit. | Booking benefit summary and payment ledger. | Explains why no deposit was collected. |
| Package credit | Eligible booking consumes one or more credits. | Wallet remaining credits and usage ledger. | Prevents invisible credit loss. |
| Voucher | Voucher applies before payment or booking finalization. | Benefit history and invoice/payment breakdown. | Supports customer questions about discount source. |
| Renewal/expiry | Plan renews, lapses, or benefit expires. | Wallet, Programs renewals, reports. | Shows retention risk and next action. |
Technical reference: membership data that must stay explainable
Rules should stay first-class where available: discount, deposit waiver, priority booking, service eligibility, location/staff scope, package/credit rules, blackout windows, usage limits, dependents, renewal, expiry, and usage ledger records.
Old saved membership/package data should still normalize into the customer-facing preview even if new rule fields are missing.
Troubleshooting
| User says | Check first | Likely explanation |
|---|---|---|
| Membership benefits are not visible. | Programs strip, Olivia preview, customer wallet. | The data may exist but the UI/docs must show what the member gets, used, and has left. |
| Discount did not apply. | Customer account/email, active membership, service eligibility. | The booking may not match the member or eligible service rule. |
| Deposit was not waived. | Deposit waiver rule and booking benefit summary. | The rule may not be active, eligible, or matched to the booking context. |
| Package credit disappeared. | Usage ledger and wallet remaining credits. | A booking may have consumed it, or the credit may be expired/ineligible. |
| Payment amount is confusing. | Payment ledger beside invoice totals. | The customer needs line-level benefit explanation, not only final total. |