Membership Plans and Usage Quotas

Overview

Membership plans let you define who can access your facility as a member, how they are billed, whether they need approval before starting, and how many visits, hours, or bookings they are allowed per period. When a quota is exceeded, you can either block further usage or automatically charge an overage fee via Stripe Invoice Item.

Members can view their current quota status at a glance on the home screen of the Member App through the QuotaBar component.

Detailed Features

Feature 1: Application Flow

When creating a plan, choose how applicants progress to an active subscription:

Flow How it works
Pay first (default) The applicant pays during signup. If auto_approve is off, the subscription becomes active only after staff manually activate it in the Membership tab.
Apply first The applicant submits an application form with no payment. Staff review the application in the Pending Approvals tab and approve or reject it. Approved applicants receive an email and are prompted to complete payment to activate their membership.

Apply-First Plan Settings

When Apply first is selected:

  • An Application form builder appears, letting you add custom fields (text, email) that the applicant must fill in
  • Required fields are enforced at submission time
  • Submitted answers are displayed on each pending application card so staff can review them before approving

Approving and Rejecting Applications (Pending Approvals Tab)

  1. Open the admin dashboard and navigate to the Membership tab
  2. Click the Pending Approvals sub-tab
  3. Each pending application shows the applicant's email, the plan they applied for, the application date, and their form answers
  4. Tap Approve to approve — the applicant receives an email and can proceed to payment
  5. Tap Reject to open a rejection dialog, enter an optional reason, and confirm

After approval, the subscription remains in pending_payment state until the member completes their payment. It becomes active once payment is confirmed.

Feature 2: Configuring Quotas (Admin)

Quotas are set when creating or editing a membership plan in the Membership tab of the admin dashboard.

Configurable Limits

Field Description Reset Period
Monthly Visits Maximum number of check-ins per month Monthly
Daily Hours Maximum hours of usage per day Daily
Monthly Bookings Maximum time slot bookings per month (by count or by hours) Monthly

Monthly Bookings — Limit Type

Monthly bookings can be set to one of three modes:

Choice Behavior
Unlimited No cap on monthly bookings or booking hours. The quota bar does not show a booking progress row.
By count Sets a maximum number of bookings (slots) per month.
By hours Sets a maximum total booking duration (hours) per month.

Monthly Visits and Daily Hours are treated as unlimited when left blank.

How to Create a Plan with Quotas

  1. Open the admin dashboard and navigate to the Membership tab
  2. Click the Create Plan button — you will be taken to a dedicated plan detail page
  3. Enter basic plan information (name, price, billing interval, application flow, etc.)
    • The Price and Billing interval fields are labelled (Not editable after creation). These cannot be changed after saving due to Stripe integration constraints
  4. In the Usage Limits section, enter the desired limits

Feature 2.5: Subscriber Count on Plan Cards

Each plan card in the Plans tab shows the current subscriber count as {count} / {max}. When no max member limit is set, it shows {count} (no cap). The count includes subscriptions in the active, past_due, pending_approval, and pending_payment statuses. Cancelled subscriptions are excluded.

Feature 3: Overage Policy

Choose what happens when a member exceeds their quota.

Policy Behavior
Block Check-ins and bookings are denied once the limit is reached. No additional charge.
Charge Usage continues beyond the limit. Each overage is added as a Stripe Invoice Item on the next billing cycle.

Overage Fees (Charge policy only)

When the Charge policy is selected, overage fee fields appear.

Field Description Example
Overage fee per visit Charged for each check-in beyond the monthly visit limit ¥500
Overage fee per hour Charged for each hour beyond the daily hours limit ¥200
Overage fee per booking Charged for each booking beyond the monthly bookings limit ¥300

Overage fees are billed in the plan's currency (JPY/USD). Leave a fee field blank to skip overage billing for that specific quota type.

Feature 4: Membership Plans Excluded from the Booking Plan List

Plans created with selected_plan_type='membership' are not shown in the plan list on the booking page (Booking app). They are accessible only through the Open Reservation Plan button on the member app's Home screen. This prevents membership-only booking slots from appearing alongside general reservation plans.

Feature 5: Quota Bar (Member App)

On the home screen of the Member App, a quota bar is displayed for each active limit on the member's plan.

Displayed Information

  • Label: Monthly Visits / Today's Usage / Monthly Bookings
  • Count: Used / Limit (e.g., 2 / 5)
  • Progress bar: Visual indicator of usage percentage
    • Teal (normal): below 80% used
    • Amber (warning): 80%–99% used
    • Red (limit reached): 100% used

Overage Charge Note

When the overage policy is set to Charge, the following note appears below the quota bars:

Overage charges apply when limits are exceeded

Feature 6: Covered Reservation Plans (Free-Quota Scope)

The membership plan edit form includes a Covered reservation plans multi-select inside the Booking Limits section. Only the regular reservation plans selected here are covered by this membership plan's free quota.

Selection state Behavior
None selected (default) All reservation plans are covered — members get the free quota on any plan they book (legacy behavior)
One or more selected Only the selected plans are covered. Plans not on the list are charged at the regular rate, even for members

Non-members are never locked out. Setting covered reservation plans does not restrict who can book — non-members can still book any plan at the regular rate. This setting only controls whether a booking is free, not whether it can be made.

How to Configure

  1. Open the admin dashboard and navigate to the Membership tab, then create or edit a plan
  2. In the Booking Limits section, use Covered reservation plans to select the regular plans this membership's free quota should apply to (multi-select, searchable)
  3. Save — the selected plans appear as tags

Constraints on Covered Plans

  • The selection candidates only include active reservation plans belonging to this facility. Plans from other facilities or inactive plans are excluded from new selections
  • If a linked plan is later deactivated, its name still appears as a tag on the existing selection, but it will not appear as a candidate for new links
  • On save, any plan ID that belongs to another facility or no longer exists is automatically dropped, and a warning — "Some plans could not be linked because they no longer exist in this facility" — appears at the top of the screen (the save itself still succeeds)

How the Free Quota Applies

When a member books a covered reservation plan:

  • If Monthly Bookings (by count or by hours) is set above, the free quota applies within that limit
  • If Monthly Bookings is Unlimited, the booking is always free
  • Exceeding the limit follows Feature 3: Overage Policy (block or charge)

When a member books a plan that is not covered, the standard guest price applies as-is (the free quota is not consumed). See Member & Subscription Bookings for how this appears on the guest-side confirmation screen.

Configuration Examples

Example 1: Standard Coworking Plan

Allow up to 20 visits and 8 hours per day; block when exceeded:

  • Monthly Visits: 20
  • Daily Hours: 8
  • Monthly Bookings: (blank)
  • Overage Policy: Block

Example 2: Flex Membership

Allow up to 10 visits; charge ¥500 per extra visit:

  • Monthly Visits: 10
  • Daily Hours: (blank)
  • Monthly Bookings: (blank)
  • Overage Policy: Charge
  • Overage fee per visit: 500

Example 3: Studio Class Membership

Limit to 4 time slot bookings per month; block further bookings:

  • Monthly Visits: (blank)
  • Daily Hours: (blank)
  • Monthly Bookings: By count → 4
  • Overage Policy: Block

Frequently Asked Questions

Q: When do quotas reset?

Monthly quotas reset automatically on the 1st of each month at 00:00 in the facility's timezone. Daily quotas reset every day at 00:00. No manual action is required.

Q: If multiple limits are set, which one triggers the restriction?

Any one of the limits reaching its quota is enough to trigger the restriction. For example, if both monthly visits and daily hours are set, whichever is reached first will block (or charge) further usage.

Q: When are overage charges billed?

Overage charges are recorded as Stripe Invoice Items each time a limit is exceeded. They are consolidated into the member's next regular invoice (monthly or yearly billing cycle).

Q: The member's quota bar is not visible in the app. Why?

The quota bar only appears when at least one quota limit is active. If Monthly Bookings is set to Unlimited and Monthly Visits and Daily Hours are both blank, no quota bar is shown.

Q: If I update a plan's quota limits, when does the change take effect?

Updated limits take effect after the next quota reset cycle. The current usage count is carried over; only the limit threshold changes.

Q: If I add or change covered reservation plans, does it apply to existing members immediately?

Yes. Covered-plan links take effect the moment you save — no backfill is required. Members with an already-active subscription get the new configuration starting with their next booking.

Q: What happens if I don't select any covered reservation plans?

All reservation plans are covered (the legacy, backward-compatible behavior). Only narrow down the covered reservation plans if you want to limit the free quota to specific plans.

Troubleshooting

Member is blocked even though quota appears not exceeded

Check the following:

  1. Review all quota bars on the member app home screen — daily hours and monthly visits/bookings are tracked separately
  2. Confirm the membership subscription has not expired (check "Valid Until" on the home screen)
  3. If the issue persists, contact the facility admin to review the plan configuration

Quota bar does not appear in the member app

  • Monthly Bookings is set to Unlimited and Monthly Visits and Daily Hours are both blank. The bar is not shown when no limits are active.
  • Check the plan's Usage Limits settings in the admin dashboard and add at least one limit value.

A member is charged the regular rate on a specific plan

  1. In the admin dashboard, check the Covered reservation plans setting for that membership plan and confirm whether the plan in question is selected
  2. If one or more covered reservation plans are selected, any plan not on the list is charged at the regular rate by design — this setting exists to narrow the free-quota scope
  3. To make the free quota apply to all plans again, clear every selection in Covered reservation plans (none selected = all plans covered)
  4. Changes take effect immediately after saving — reload the page if it does not appear to apply

Stripe Customer Portal Setup (Required for Facility Owners)

To allow members to change their payment method and download receipts, you must enable the Customer Portal in your Stripe Dashboard.

Setup Steps

  1. Log in to Stripe Dashboard
  2. Go to Settings → Billing → Customer portal
  3. Configure the following:
Setting Value Reason
Payment methods ✅ Enabled Allow members to add, update, or remove cards
Invoice history ✅ Enabled Allow members to view and download receipt PDFs
Subscriptions > Cancel subscriptions ❌ Disabled Cancellation is handled through UnlockOS
Subscriptions > Switch plans ❌ Disabled Plan changes are managed through UnlockOS
  1. Click Save

Important Notes

  • This setting applies to your entire Stripe account (not per-facility)
  • Test mode and live mode require separate configuration
  • Once configured, a "Manage Cards & Invoices" button appears on the member app's Payment History page
  • Clicking the button opens Stripe's portal; members return to the app when finished

If Customer Portal is Not Configured

If a member clicks the button before setup is complete, Stripe will return an error. Make sure to complete the above configuration before publishing your membership plans.

Last updated: 2026-07-18 - Added Feature 6 "Covered Reservation Plans (Free-Quota Scope)" (#1950)