> For the complete documentation index, see [llms.txt](https://help.peoplevine.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.peoplevine.com/products/control-panel-overview/membership-management-hub.md). # Member Management *** ## Contents * [Overview](#overview) * [The Membership Lifecycle](#the-membership-lifecycle) * [1. Application and Enrollment](#application-and-enrollment) * [2. Active Membership](#active-membership) * [3. Changes and Lifecycle Events](#changes-and-lifecycle-events) * [4. Cancellation and Renewal](#cancellation-and-renewal) * [Billing and Dues](#billing-and-dues) * [Member Status Propagation Table](#member-status-propagation-table) * [Interdependency and Impact Reference](#interdependency-and-impact-reference) *** ## Overview **Membership Management** is the core module governing how people become members, how memberships are maintained over time, and how membership status propagates across every platform touchpoint — Control Panel, Member Portal, POS terminals, check-in kiosks, and integrated third-party systems. When a membership status changes, it cascades across billing, access, integrations, and the member experience. > All navigation paths and screenshots are based on the **Standard Dashboard** view. Where the Pro Dashboard differs, a `Note (Pro Dash)` callout is included. Member Portal references were verified against `k8.peoplevine.com`. > For all status codes across entities, see: [Status Code Reference](/status-codes-reference.md). For key terms, see: [Glossary](/glossary.md). *** ## The Membership Lifecycle A membership follows a predictable lifecycle: application, enrollment, active membership, ongoing billing, lifecycle changes, and eventual renewal or cancellation. Each phase has its own triggers, statuses, and downstream effects. ### Application and Enrollment How someone becomes a member — from applying through review to their first active day. #### Application Flow ```mermaid stateDiagram-v2 state "In Progress" as InProgress [*] --> InProgress : Application started (CRM profile created) InProgress --> New : Applicant submits New --> Approved : Staff approves / Auto-approved New --> Rejected : Staff rejects Approved --> Active : Subscription created & payment confirmed (paid memberships only) Rejected --> [*] : Closed note right of InProgress : Filling out application note right of New : Awaiting review note right of Approved : Select billing option note right of Rejected : No further action note right of Active : Card and Subscription created ``` > **Note**: Application statuses are configurable per application via `ApplicationSubmitStatus`. When an application is submitted, the system fires triggers that can send emails or start campaigns (e.g., follow-up campaigns for in-progress applications). The diagram shows the default flow. See [Status Code Reference — Application Statuses](/status-codes-reference.md#application-statuses) for the full list. #### Auto-Triggers in This Phase | Trigger | When It Fires | What It Does | | --------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Auto-Approval** | Application submitted (if program configured) | Skips review, moves to Approved | | **Enrollment / Activation** | Card status set to Active | Issues perks, house account, digital card. Sends welcome email/SMS. Pushes to integrations. See [Interdependency table](#interdependency-and-impact-reference) for full downstream effects. | #### Admin Actions in This Phase | Action | When | What It Does | | ----------------------- | -------------------- | ---------------------------------------------------------------------------------------- | | **Billing at Approval** | Application approved | Admin selects billing option: separate charges, single charge, invoice, or already paid. | *** ### Active Membership Once enrolled, the member is active — they have portal access, can check in, and their membership integrates across all connected systems. #### Member Card Lifecycle ```mermaid stateDiagram-v2 [*] --> Pending : Future start date [*] --> Active : Immediate enrollment Pending --> Active : Start date reached, payment OK Active --> Failed : Payment fails (auto-set) Active --> Suspended : Admin suspends Active --> Cancelled : Admin cancels Active --> Expired : Term expires / admin sets Failed --> Active : Payment resolved Failed --> Cancelled : Admin cancels Suspended --> Active : Admin reactivates Suspended --> Cancelled : Admin cancels Expired --> Active : Renewal processed Expired --> Cancelled : No renewal Cancelled --> Active : Set back to Active Active --> Archived : Admin archives Cancelled --> Archived : Admin archives note right of Active : Full access note right of Pending : No access until start date note right of Failed : Paywall, retry Day 3 and 7 note right of Suspended : Access stopped note right of Cancelled : Access stopped note right of Expired : Access stopped note right of Archived : Hidden from view ``` > **Note**: Upgrade and downgrade transitions exist at the **subscription** level (old subscription marked Upgraded/Downgraded, new one created). You can also manually set a card to Upgraded or Downgraded. See: [Changes and Lifecycle Events](#changes-and-lifecycle-events). #### What "Active" Means Across Touchpoints | Touchpoint | Active Status Effect | | ---------------- | ------------------------------------------------------------------------------------------------------- | | **Portal** | Full access per content permissions — certain content can be restricted to specific membership programs | | **Check-In** | Scan allowed, NFC and barcode work | | **Billing** | Auto-charges on Next Billing Date if subscription auto-charge is enabled (default: yes) | | **Perks** | Guest passes, stipends, reward points active | | **Sub-Members** | All sub-members active | | **POS** | Member lookup works; house account available if enabled on CRM profile | | **Integrations** | Membership data pushed to connected systems (SevenRooms, POS, PMS, etc.) via `membershipPush` | #### Auto-Triggers in This Phase | Trigger | When It Fires | What It Does | | ---------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | **Integration Push** | Card status changes | Pushes to all connected systems. See [Interdependency table](#interdependency-and-impact-reference) for per-status effects. | | **Sub-Member Cascade** | Primary member status changes | All sub-members inherit the new status | *** ### Billing and Dues Membership billing (subscriptions) and house account billing are separate payment engines with different logic and rules. For full billing lifecycle diagrams, retry flows, invoice processing, house account modes, and payment processor routing, see: [**Billing & Payments Hub**](/products/control-panel-overview/billing-payments-hub.md). *** ### Changes and Lifecycle Events Mid-lifecycle changes — upgrades, downgrades, transfers, family membership adjustments, and status changes. #### Upgrades and Downgrades When a member moves to a different tier, the system: 1. Marks the **old** subscription as `Upgraded` or `Downgraded` (reporting status only) 2. Creates a **new** Member Card on the target tier with a new subscription 3. The old card is deactivated; the new card becomes the active enrollment > `Upgraded` and `Downgraded` are reporting-only statuses — they mark the old card for historical tracking. The member's active card is always the new one. The old card still shows in the Member Portal under the membership section, marked as "inactive." > **Note**: You can also manually set a membership card to Upgraded or Downgraded — it is not exclusive to paid subscription memberships. > **Automatic vs manual**: The only time the system automatically upgrades a membership is during the age-out feature. Peoplevine never automatically downgrades a membership — downgrades are always manual. #### Age-Based Transitions | Trigger | When It Fires | What It Does | | --------------------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | **Age-Based Upgrade** | Member age crosses program's `min_age`/`max_age` threshold | Creates new card on age-appropriate tier, marks old card as `Upgraded`, transfers subscription. Ages are configurable per program, not fixed. | #### Sub-Member Operations * Sub-members inherit the primary member's status (cascading) * Sub-members never see a payment option on the Failed Dues Paywall * Sub-members can be swapped to become the primary member * Family memberships can be split into individual memberships **Sub-Member Portal Management** Peoplevine ships two portal versions (React and Upgrade). In both, sub-member management is gated by the program setting **Allow main members to add sub-members via the member portal**. When the toggle is off, primary members cannot add, edit, or cancel sub-members in either portal. See: [How Members Manage Sub-Members in the Portal](/products/control-panel-overview/membership-management-hub/manage-sub-members-portal.md). *** ### Cancellation and Renewal How memberships end — and how they come back. #### End-of-Lifecycle States | Status | What It Means | Reversible? | | ------------- | ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | **Cancelled** | Membership ended by admin or future cancellation date reached | Yes — the old card can be set directly back to Active status. A new card is not required. | | **Expired** | Membership term ended | Yes — renewal creates new billing cycle | | **Archived** | Hidden from customer view and Control Panel. Not accessible in CP once archived — to restore, contact Peoplevine support. | No — requires PV help | #### Renewal Season Renewal requires proactive admin work — there is no fully automatic renewal flow. Key preparation steps: * Review expiring memberships * Communicate renewal terms to members * Process renewals (creates new billing cycle on the existing card) *** ## Member Status Propagation Table What each status means across every touchpoint. Reporting-only statuses are marked. | Status | Portal Access | Check-In | Billing | Perks Active | Sub-Members | POS | | --------------------------------- | -------------------- | -------- | ----------------------------------------- | ------------ | -------------- | ------------ | | **Active** | Full access | Allowed | Auto-charge on billing date | Yes | Active | Lookup works | | **Pending** | Blocked (no paywall) | Blocked | Charges on next billing date | No | Inherit status | Not returned | | **Failed** | Failed Dues Paywall | Blocked | Retry Day 3, Day 7 | No | Inherit status | Not returned | | **Suspended** | Blocked (no paywall) | Blocked | All future payments stopped | No | Inherit status | Not returned | | **Expired** | Blocked (no paywall) | Blocked | All future payments stopped | No | Inherit status | Not returned | | **Cancelled** | Blocked (no paywall) | Blocked | No payments beyond cancellation date | No | Inherit status | Not returned | | **Archived** | Blocked | Blocked | Stopped | No | Inherit status | Not returned | | **Upgraded** *(reporting only)* | N/A | N/A | Stopped (transferred to new subscription) | No | N/A | Not returned | | **Downgraded** *(reporting only)* | N/A | N/A | Stopped (transferred to new subscription) | No | N/A | Not returned | > **Portal Login Priority**: Failed overrides all — routes to Failed Dues Paywall even if other memberships are Active. If no Failed, Active grants access. Suspended, Expired, and Cancelled block access with no paywall. > **POS Lookup**: Only Active members are returned by POS member lookup across all integrations (Micros, Toast, Lightspeed). Non-active members do not appear in search results — staff will see a "member not found" message. Note: Square integration is disconnected. *** ## Interdependency and Impact Reference When something changes in Membership Management, these are the downstream effects: ### High-Impact Changes | If You Change... | Impacted Area | What Happens | | ------------------------ | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Card Status → Failed** | Check-In & Access | Member blocked at door immediately. No grace period. | | | POS Integration | POS cannot find member. House account charges fail. | | | Sub-Members | All sub-members lose access immediately (cascading). | | | Member Portal | Failed Dues Paywall displayed on login. Pay-now option is configurable (contact Peoplevine to enable/disable). | | **Card Status → Active** | Customer Record | Sets `isMember=Y`, `lifecycle_stage_no=5`, `member_since` date. Issues perks. House account enabled only if configured on CRM profile. Lifecycle stage changes on cancellation and reactivation. | | **Program Settings** | POS Integration | Discount rules can be updated via membership settings anytime — unlikely to break. Verify Vendor Key Discount mappings if changing tiers. | | | Perks & Loyalty | Guest pass allocations, stipend amounts, voucher eligibility may change. | | **Delete a Program** | Membership Management | Only allowed if all member subscriptions are archived first (cancelled is not enough). Historical reporting data is lost. Not recommended — use Upgraded status + re-enroll instead, or rename the program. See: [How to Deactivate or Delete a Membership Program](/products/control-panel-overview/membership-setup-overview/deactivate-program.md). | > For billing-related impact changes (Program Price, Payment Processor Config, Subscription Payment Type, House Account Mode), see: [Billing & Payments Hub — Interdependency](/products/control-panel-overview/billing-payments-hub.md#interdependency-and-impact-reference). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://help.peoplevine.com/products/control-panel-overview/membership-management-hub.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.