Overview.

A prepaid pass is a product your staff sell at the counter: a 10-wash card, a 5-class pack, a monthly unlimited. The customer pays once, up front, at your till. The platform hands them a digital pass, counts visits down on each scan, and reminds them before unused visits expire.

Points and stamps reward future behavior. Vouchers discount a present purchase. A pass monetizes commitment: the customer pays today for visits they will make later. For service businesses such as car washes, studios, and barbers, the pass is the product.

What a Pass Is

A pass has two dials:

• Uses. A counted pass covers a fixed number of visits, for example ten washes. An unlimited pass covers any number of visits while it stays valid.
• Validity. An optional window in days, counted from the day of sale. A counted pass can run without one (the ten washes never expire). An unlimited pass requires one, because unlimited visits with unlimited time is not a sellable product. Thirty days of unlimited visits is a monthly membership.

A pass also carries a display price. The platform records what the customer paid for receipts and reports. Payment itself stays at your till; the platform never charges members.

How a Pass Moves Through the System

1. A partner designs the pass product per club: name, uses, validity, price. A QR code per product opens its public page for counter displays. See Partner setup. Sales, visits, and breakage land in Analytics & History.
2. Staff sell it in one scan-and-confirm flow. The member receives the pass in their wallet plus an email receipt branded with your business name. See Selling and scanning.
3. On each visit, staff scan the pass QR and tick off one or more visits. Mistakes have an undo.
4. The member watches the remaining count in their wallet. See The member view.
5. A daily task closes out lapsed passes and sends one reminder per pass that enters its final week with visits left. It runs with cron, on portal traffic without cron, or by hand from Health Center → Scheduled tasks. No queue worker is involved.

What Sold Passes Keep

Each sold pass snapshots the product at the moment of sale: uses, price, currency, and validity. Editing the product later changes future sales only. Deleting it stops future sales and leaves every sold pass working. Members keep what they bought.

Every movement on a pass lands in a ledger: the sale, each visit, each correction, the expiry. Nothing in that history is edited or deleted afterwards; corrections add an offsetting entry. The pass detail page shows this history to the member in plain words.

What Stays Out

Version 1 keeps money simple. Members cannot buy passes online, passes cannot move between members, and there is no auto-renew. Refunds are not a money flow here; staff undo a wrongly scanned visit, and anything beyond that happens at your till, where the payment lives. The Agent API does not cover passes yet.

Plan Requirements

Prepaid passes are a plan feature, like vouchers. The administrator grants the permission and a template limit per partner, on the plan or as an override under Partners → Permissions. Partners without the feature see no pass surfaces at all. Admin setup covers the full admin side, and the FAQ answers the common questions from all roles.

Two keys in config/plans.php control the feature per plan:

'has_prepaid_passes' => true,  // plan includes the feature
'max_prepaid_passes' => 10,    // pass products per partner, -1 = unlimited

Fresh installations ship with vouchers-style defaults: off on the free tier, then 3, 10, and unlimited on the paid tiers.

Upgrading From an Earlier Version

config/plans.php is a protected file: updates never overwrite it, so your existing plan configuration survives. That also means an upgraded installation keeps a plans.php without the two prepaid keys. Nothing breaks; the feature stays off on every plan until you add them.

You have two ways to enable it:

Edit config/plans.php (recommended). Add both keys to each plan, next to the voucher keys. The shipped defaults:

'tier1' => [
    // ...
    'has_prepaid_passes' => false,
    'max_prepaid_passes' => 0,
],
'tier2' => [
    // ...
    'has_prepaid_passes' => true,
    'max_prepaid_passes' => 3,
],
'tier3' => [
    // ...
    'has_prepaid_passes' => true,
    'max_prepaid_passes' => 10,
],
'tier4' => [
    // ...
    'has_prepaid_passes' => true,
    'max_prepaid_passes' => -1,
],

Run php artisan config:clear afterwards if your installation caches configuration. That is the whole job: every partner on a plan with the feature sees the Prepaid Passes menu on their next page load, existing partners included. No partner needs to be re-saved or re-assigned. The only exception is a partner with an explicit per-partner override, which always wins over the plan, whether it switches the feature on or off.

Or grant it per partner. Without touching plans.php, open Partners → edit a partner → Permissions, switch on Prepaid Passes, and set the limit (-1 for unlimited). This override wins over the plan and suits a single partner or a trial run of the feature.