# Membership Setup Guide (from zero to opening member enrollment) This guide is **the scenario-style manual you should read first**. If you're setting up Membership (a monthly / yearly member service) for the first time, work through this page from top to bottom. > **About the design philosophy:** UnlockOS Membership is not just "subscription billing." It manages **recurring billing × physical access rights × usage quotas as one unit**. Members don't need to book every time — while they are enrolled, they check in with a single tap from the **SpaceCard** in the Member App. Limits like "up to 20 visits per month" or "up to 8 hours per day" are built in at design time, and you can choose whether to **deny the excess (Block)** or **add an overage charge**. The steps in this guide assume that foundation. --- ## The Whole Picture (8 Steps) To open member enrollment, configure roughly in the following order. Many steps depend on the ones before them, so we strongly recommend going through them **in order**. ``` [1] Stripe integration ──────┐ [2] Stripe Customer Portal setup │ ├──→ [3] Create membership plans ──→ [8] Test enrollment │ ├ Application flow │ │ ├ Quotas (usage limits) │ │ └ Covered reservation plans (opt.) │ │ │ [4] Spaces members check into (Check-in Config) ─────────────────┤ [5] Application form (optional, works on either flow) ────────────┤ [6] Confirm and distribute the Member App URL ───────────────────┤ [7] Confirm approval operations (apply-first / manual activation)┘ ``` | # | Step | Required / Optional | Time | Depends on | |---|------|---------------------|------|------------| | 1 | Stripe integration | Required (if you offer paid plans) | 15 min | — | | 2 | Stripe Customer Portal setup | Required (if you offer paid plans) | 10 min | 1 | | 3 | Create membership plans (application flow / quotas / overage policy) | Required | 15–30 min | 1 | | 4 | Prepare spaces members check into (Check-in Config) | Required (if members enter spaces) | 15 min | — | | 5 | Application form (intake form) | Optional | 10 min | 3 | | 6 | Confirm and distribute the Member App URL | Required | 5 min | 3 | | 7 | Confirm approval operations (apply-first / manual activation) | Conditionally required | 5 min | 3 | | 8 | Test enrollment in the Member App | Required | 10 min | 1–4 (and optionally 5, 6, 7) | **Total estimate: 60–90 minutes** (varies with the number of plans) --- ## Step 1: Stripe integration ### Purpose Enable **recurring credit card billing** for paid memberships. If you operate with free plans only, you can skip this step. > Membership pricing and billing intervals are tied to Stripe. Without a Stripe integration, you cannot create paid plans. ### Prerequisites - A Stripe account (free to create) - The following keys obtained from the Stripe dashboard: - **Publishable Key** — `pk_test_...` or `pk_live_...` - **Secret Key** — `sk_test_...` or `sk_live_...` - **Webhook Secret** — `whsec_...` (if you use webhooks) ### Steps 1. Open **App Integrations** from the main app's left menu 2. From the tabs at the top, select **Stripe** 3. Paste the three keys copied from the Stripe dashboard into the **Basic Settings** fields 4. In **Payment Settings**, choose mode (test mode / live mode) and currency 5. Click **Save** ### Verify - The Stripe Payment System card badge turns to **"Connected"** (green) ### Details - [Lock Connection help (Stripe tab)](lock-connection.md#stripe-payment-tab) > **Test mode vs live mode:** Always test in test mode (`pk_test_*` / `sk_test_*`). We recommend switching to live mode only after the test enrollment in step 8 succeeds. Test mode and live mode keep their data separate on the Stripe side, so the next step 2 (Customer Portal) must also be configured separately for each. --- ## Step 2: Stripe Customer Portal setup ### Purpose Enable the **Customer Portal** in your Stripe dashboard so members can change their card and download receipts. If this setup is not complete, members will get an error from Stripe when they tap the "Manage Cards & Invoices" button on the Payment History screen. > Facilities with free plans only can skip this step. ### Prerequisites - Step 1 (Stripe integration) complete - You can log in to the Stripe dashboard ### Steps 1. Log in to [Stripe Dashboard](https://dashboard.stripe.com/) 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 download receipt / invoice PDFs | | **Subscriptions > Cancel subscriptions** | ❌ Disabled | Cancellation is handled through UnlockOS's dedicated flow | | **Subscriptions > Switch plans** | ❌ Disabled | Plan changes are managed through UnlockOS | 4. Click **Save** ### Verify - Once configured, a "Manage Cards & Invoices" button appears on the Member App's **Payment History** page > **Note:** This setting applies to your **entire Stripe account** (not per-facility). Test mode and live mode require **separate** configuration. ### Details - [Membership Plans and Usage Quotas (Stripe Customer Portal Setup)](membership-plans.md#stripe-customer-portal-setup-required-for-facility-owners) --- ## Step 3: Create membership plans ### Purpose Create the **monthly / yearly plans** you sell to members. A plan bundles the application flow, usage quotas, and the overage policy together. ### Prerequisites - For paid plans, step 1 (Stripe integration) complete - No prerequisites for free plans only ### Steps 1. Open the **Membership** tab from the main app's left menu 2. Click the **Create Plan** button (you will be taken to the plan detail page) 3. Enter **basic information**: - Plan name (e.g., "Coworking Standard") - Description (benefits and details shown to members) - **Price** and **billing interval** (monthly / yearly) - Application flow (see "3-1" below) 4. Enter **usage limits (quotas)** (see "3-2" below) 5. Choose the **overage policy** (see "3-3" below) 6. If needed, set **covered reservation plans** (free-quota scope) (see "3-4" below) 7. **Save** > **Important — price and billing interval cannot be changed after creation.** They are labelled **(Not editable after creation)** next to the field. This is due to Stripe integration constraints. To change the amount or the interval, create a new plan instead. ### 3-1. Application flow Choose how applicants progress from signup to activation. | Flow | How it works | |------|-------------| | **Pay first** (default) | The applicant pays during signup. If `auto_approve` is off, the subscription stays in `pending` until staff manually activate it. | | **Apply first** | The application is submitted with no payment. Staff review it in the **Pending Approvals** tab, and once approved the applicant receives an email and activates their membership by completing payment. | - The application form (intake fields) is configured independently of the application flow. Whichever flow you pick, it's set up after you save the plan (step 5). ### 3-2. Usage limits (quotas) | Field | Description | Reset period | |-------|-------------|--------------| | **Monthly Visits** | Maximum number of entries per month | Monthly (1st of each month at 00:00, facility timezone) | | **Daily Hours** | Maximum hours of usage per day | Daily (every day at 00:00) | | **Monthly Bookings** | Maximum time slot bookings per month (three choices: Unlimited / by count / by hours) | Monthly | - Monthly Visits and Daily Hours are treated as **"unlimited" when left blank**. - Once any one of the limits is reached, further usage is restricted (blocked or charged). ### 3-3. Overage policy | Policy | Behavior | |--------|----------| | **Block** | Entry and booking are denied once the limit is reached. No additional charge. | | **Charge** | Usage continues beyond the limit. Each overage is automatically added to the next invoice as a Stripe Invoice Item. | - Selecting **Charge** reveals fee fields for the overage rate per visit / per hour / per booking. Any field left blank is not charged for overages. ### 3-4. Covered reservation plans (free-quota scope, optional) Narrow down which plans members can use **for free (within their monthly quota)**. **This setting applies to both the Booking service and walk-ins (direct check-in).** | Selection state | Behavior for bookings | Behavior for walk-ins | |-----------------|------------------------|-------------------------| | None selected (default) | All reservation plans are covered. Members get the free quota on any plan they book | Not decided at the plan level — falls back to the existing Check-in Config scope (legacy) | | One or more selected | Only the selected plans are covered by the free quota. Plans not on the list are charged the regular rate, even for members | Free only if the selected plan is part of that Check-in Config | > **Non-members are never locked out.** This setting controls whether a booking is *free*, not whether it can be *made*. See [Membership Plans and Usage Quotas](membership-plans.md#feature-6-covered-reservation-plans-free-quota-scope) for details. > Facilities that split member tiers across several Check-in Configs can set covered reservation plans here to move walk-in coverage onto the plan-level setting too, making it easier to consolidate those entrances into one (step 4). ### Verify - The plan you created appears as a card in the plan management tab - The card shows the subscriber count as **"{count} / {max}"** (∞ if no max is set) - Price, billing interval, and quotas are as intended ### Details - [Membership Plans and Usage Quotas](membership-plans.md) > **Design tip:** Start with **one plan** and add variations (student discount, annual billing, etc.) after you're up and running. Since price and billing interval can't be changed later, run enrollment through once in test mode before finalizing your live plans. --- ## Step 4: Prepare spaces members check into (Check-in Config) ### Purpose Define **where and with which key** members enter. The **SpaceCards** lined up on the Member App home screen are the facility's **Check-in Configs** themselves. Check-in Configs linked to a membership plan are shown as SpaceCards, and members check in with a single tap. > Facilities that offer only "reservation slots" as a member benefit, without entry, complete this via the Booking-side settings (covered reservation plans) instead of this step. ### Prerequisites - KEYVOX integration (if you issue keys) - Pricing plan (the plan linked to the Check-in Config) ### Steps The steps to create a Check-in Config are documented in a separate guide. Follow the companion **[Check-in Setup Guide](checkin-setup-guide.md)** to prepare a Check-in Config for each space members enter. ### Verify - The spaces you prepared appear as **SpaceCards** on the Member App home - Each SpaceCard shows the facility space's image, name, and remaining quota > **If SpaceCards don't appear:** The facility's Check-in Config (entrance config) may not be created yet. Check step 4 (= Check-in Config). ### Details - [Check-in Setup Guide](checkin-setup-guide.md) - [SpaceCard Help](member-spacecard.md) / [Home Screen](member-home.md) --- ## Step 5: Application form (intake form, optional) ### Purpose Configure this if you want to collect a **member information form** (name, contact, employer, etc.) at signup. It works on either application flow; on **apply-first** plans in particular, staff can review the application before approving it. > A form is not required. Configure it only if the facility needs additional information. ### Prerequisites - A plan created and saved in step 3 ### Steps 1. On the **Forms** page, create the form with the fields you want applicants to fill in (text, email, phone, number, select, date, textarea, image upload are all supported). You can reuse a form already built for check-in (see [Forms help](forms.md)) 2. Open the edit screen for the membership plan you saved in step 3 (not available immediately on creation — save the plan once, then reopen the edit screen) 3. In the **Application Form** section, select the form 4. The selection takes effect immediately ### Verify - The fields you configured appear at signup - Required fields must be filled in to proceed ### Details - [Member Signup (Application Form)](member-signup.md#feature-3-intake-form) - [Membership Plans and Usage Quotas (Setting Up the Application Form)](membership-plans.md#feature-15-setting-up-the-application-form) - [Forms help](forms.md) --- ## Step 6: Confirm and distribute the Member App URL ### Purpose Obtain the **Member App URL** where members enroll and log in, and announce it. ### Prerequisites - The slug (facility URL identifier) is set ([Base Settings](base-settings.md)) ### Steps 1. Open **Base Settings** and check the slug in the **App URLs** field 2. The Member App URL is in the format `member.unlockos.io/{slug}` 3. From the panel below the slug input, copy the URL / QR code and add it to your printed materials and website ### Verify - Opening `member.unlockos.io/{slug}` shows the **membership plan list (Landing)** in a logged-out state - The highest-priced plan is automatically given a **Recommended badge** > **On navigation:** The Member App is also reachable from the unified portal **Go** (`go.unlockos.io/{slug}`). If you want to present booking, check-in, and membership together, distribute Go instead. See [Go Portal and Service Cross-Linking Guide](go-linking-guide.md) for the relationships and how to set up cross-links. --- ## Step 7: Confirm approval operations (apply-first / manual activation) ### Purpose Confirm the staff-side approval operations for **apply-first** plans or **manual activation** (`auto_approve=false`) plans. > Facilities using only **pay-first + auto-approve** plans can skip this step (they activate the moment payment completes). ### Steps (Pending Approvals tab) 1. Open the **Membership** tab in the admin dashboard 2. Click the **Pending Approvals** sub-tab 3. Each application card shows the applicant's email, the plan they applied for, the application date, and their form answers 4. Tap **Approve** — the applicant receives an email and can proceed to payment 5. Tap **Reject** — a dialog to enter a rejection reason (optional) appears ### Verify - When an application arrives, a count appears on **Pending Approvals** - After approval, the subscription stays in `pending_payment` until the member completes payment, then becomes `active` once payment is confirmed ### Details - [Membership Plans and Usage Quotas (Approving and Rejecting Applications)](membership-plans.md#approving-and-rejecting-applications-pending-approvals-tab) --- ## Step 8: Test enrollment in the Member App ### Purpose Run one enrollment end-to-end as an actual member to confirm the whole setup works correctly. ### Prerequisites - Steps 1–4 complete (steps 1 and 2 too, for paid plans) - Optionally steps 5, 6, 7 ### Steps 1. Open the Member App URL (`member.unlockos.io/{slug}`) in a fresh browser window (incognito preferred) 2. Tap **Apply** on the target plan in the plan list 3. Enter your email address and log in with the **OTP (6-digit code)** you receive 4. Fill in the application form if there is one 5. For paid plans, check the first billing amount and pay with the Stripe **test card** (`4242 4242 4242 4242` / any future date / any CVC) 6. On the completion screen, confirm the result (**Active** / **Pending approval** / **Application submitted**) 7. After activation, confirm the **SpaceCard** and **quota bar** appear on the home screen 8. Confirm entry (key) via **Check in here** on the SpaceCard ### Verify | Item | How to check | |------|--------------| | Plan list displays correctly | Open the Member App URL | | OTP login works | Receive email → enter code | | (Paid) payment goes through | Payment completes with the test card | | The enrollment appears on the staff side | Membership tab (subscriber count on the plan card, or Pending Approvals) | | The quota bar is displayed | Member home screen | | You can check in from the SpaceCard | Home → Check in here | ### After testing - Remove the test enrollment via the cancellation process (cancellation is done through UnlockOS's dedicated flow) - To switch to live mode, **reconfigure in live mode** the Stripe integration (step 1) and the Customer Portal (step 2) - Publish live plans only after finalizing price and billing interval (not editable after creation) --- ## Setup Completion Checklist Once everything is checked, you're ready to open member enrollment. ### Required - [ ] Stripe integration shows "Connected" (facilities offering paid plans only) - [ ] Stripe Customer Portal configured (facilities offering paid plans only) - [ ] At least one membership plan created (price / billing interval / quotas / overage policy) - [ ] Spaces members check into (Check-in Config) prepared, and SpaceCards appear - [ ] The plan list appears at the Member App URL `member.unlockos.io/{slug}` - [ ] Test enrollment succeeded, and the quota bar and SpaceCard appeared ### Optional - [ ] Application form (intake form) configured - [ ] Approval operations for apply-first / manual activation confirmed - [ ] Navigation from the Go portal confirmed --- ## Common stumbles ### Q: I get an error when I try to create a paid plan Check that step 1 (Stripe integration) shows "Connected." Without a Stripe integration, you cannot create paid plans. ### Q: I want to change the price or billing interval later Price and billing interval **cannot be changed after creation** (a Stripe integration constraint). Create a new plan and stop new enrollments in the old one. ### Q: SpaceCards don't appear on the Member App home The spaces members check into (= Check-in Config) may not be created yet. Check step 4 ([Check-in Setup Guide](checkin-setup-guide.md)). ### Q: The quota bar doesn't appear If Monthly Bookings is "Unlimited" and Monthly Visits and Daily Hours are both blank (unlimited), the quota bar is not shown. Set a limit, or confirm this is intended. ### Q: Usage is blocked even though the limit hasn't been reached Reaching **any one** of the multiple limits triggers a block. Check both Daily Hours and Monthly Visits. Also check whether the membership has expired. ### Q: A member is charged the regular rate on a specific reservation plan Check whether that plan is included in the **covered reservation plans**. When one or more covered reservation plans are selected, anything not on the list is charged the regular rate by design. To make all plans covered by the free quota, clear every covered reservation plan selection (none selected = all plans covered). For the same issue on a walk-in, check whether one or more covered plans are selected — if so, the legacy Check-in Config scope is ignored for that plan and coverage is decided by the covered-plans setting instead. ### Q: I submitted an application but no approval email arrives It's under review by the facility. Staff approve it in the **Membership > Pending Approvals** tab. After approval, an email with a payment link is sent. Advise members to check their spam folder too. ### Q: A member gets an error on "Manage Cards & Invoices" The Stripe Customer Portal (step 2) is not configured. Configure it separately for test mode and live mode. --- ## Support If you follow this guide in order and still can't resolve the issue, contact support with **which step** and **what is happening** (attach a screenshot of the error message if you have one). --- ## Related Pages ### Per-step details - Steps 1 & 2: [Lock Connection (Stripe)](lock-connection.md#stripe-payment-tab) / [Membership Plans (Stripe Customer Portal)](membership-plans.md#stripe-customer-portal-setup-required-for-facility-owners) - Step 3: [Membership Plans and Usage Quotas](membership-plans.md) - Step 4: [Check-in Setup Guide](checkin-setup-guide.md) - Step 5: [Member Signup](member-signup.md) / [Forms help](forms.md) - Step 6: [Base Settings](base-settings.md) / [Go Portal and Service Cross-Linking](go-linking-guide.md) - Step 8: [Home Screen](member-home.md) / [SpaceCard](member-spacecard.md) / [My Page](member-mypage.md) ### Related topics - [Member Management](members.md) - [Member & Subscription Bookings (guest-side view)](guest-member-booking.md) - [Time Slot Booking (Member)](timeslot-booking-member.md) - [Booking Setup Guide](booking-setup-guide.md) - [Check-in Setup Guide](checkin-setup-guide.md) - [Go Portal and Service Cross-Linking Guide](go-linking-guide.md)