> ## Documentation Index
> Fetch the complete documentation index at: https://memberpulseptyltd.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# UJ-M-004: Renew Membership

> Member renews their expiring or expired membership to maintain access

## Journey Overview

| Attribute      | Value                                                               |
| -------------- | ------------------------------------------------------------------- |
| **Journey ID** | UJ-M-004                                                            |
| **Actor**      | Member with expiring or expired membership                          |
| **Goal**       | Renew membership to continue access to benefits                     |
| **Trigger**    | Membership approaching expiry, expired, or member initiates renewal |
| **Outcome**    | Membership renewed with extended validity period                    |

## Preconditions

* Member has/had an active membership
* Membership is within renewal window or expired within grace period
* Member has valid payment method (or will provide one)

## Journey Flow

```mermaid theme={null}
flowchart TD
    A[Renewal notification received] --> B[Member reviews renewal]
    B --> C{Auto-renewal enabled?}
    C -->|Yes| D[Card charged automatically]
    C -->|No| E[Member initiates renewal]
    D --> F{Payment successful?}
    E --> G[Review renewal options]
    G --> H{Change plan?}
    H -->|Yes| I[Select new plan]
    H -->|No| J[Confirm current plan]
    I --> K[Enter payment]
    J --> K
    K --> F
    F -->|Yes| L[Membership extended]
    F -->|No| M[Payment failure flow]
    M --> N[Update payment method]
    N --> K
    L --> O[Confirmation sent]
```

## Detailed Steps

### Automatic Renewal (Subscription Model)

<Steps>
  <Step title="Pre-Renewal Notification">
    System sends reminder 7 days before renewal:

    **Email Contents:**

    * Upcoming renewal date
    * Amount to be charged
    * Payment method on file (last 4 digits)
    * Link to update payment method
    * Link to cancel/change plan
  </Step>

  <Step title="Automatic Charge">
    On renewal date, system:

    1. Creates Stripe invoice
    2. Attempts charge on default payment method
    3. If successful → extends membership
    4. If failed → enters retry logic
  </Step>

  <Step title="Confirmation">
    On successful renewal:

    * Membership extended by plan period (monthly/annual)
    * Invoice generated and sent
    * Dashboard shows new expiry date
    * No action required from member
  </Step>
</Steps>

### Manual Renewal (Non-Subscription Model)

<Steps>
  <Step title="Renewal Reminder Sequence">
    System sends multiple reminders:

    | Days Before Expiry | Email Type           |
    | ------------------ | -------------------- |
    | 30 days            | First reminder       |
    | 14 days            | Second reminder      |
    | 7 days             | Urgent reminder      |
    | 1 day              | Final reminder       |
    | Expiry day         | Expiry notification  |
    | Grace period       | Grace period warning |
  </Step>

  <Step title="Member Initiates Renewal">
    Member clicks renewal link or navigates to membership page:

    * Current plan details displayed
    * Expiry date highlighted
    * "Renew Now" button prominent
    * Option to change plans shown
  </Step>

  <Step title="Review Renewal Options">
    Member reviews available options:

    **Same Plan:**

    * One-click renewal
    * Same price (or updated if prices changed)
    * Any loyalty discounts applied

    **Different Plan:**

    * Compare available plans
    * Select upgrade or downgrade
    * Price difference shown
  </Step>

  <Step title="Complete Payment">
    Same flow as initial purchase:

    * Apply promo code (if available)
    * Select payment method
    * Complete Stripe checkout
    * Receive confirmation
  </Step>

  <Step title="Membership Extended">
    On successful payment:

    * New expiry date calculated from:
      * Current expiry (if within renewal window)
      * Today (if expired)
    * Access restored/maintained
    * Welcome back email sent (if was expired)
  </Step>
</Steps>

## Renewal Timeline

```
├─────────────────────────────────────────────────────────────────┤
│  Active Membership Period                                        │
├─────────────────────────────────────────────────────────────────┤
                                    │←── Renewal Window ──→│
                                    │    (30 days before)  │
                                                           │
                                                    Expiry Date
                                                           │
                                    │←── Grace Period ────→│
                                    │    (configurable)    │
                                                           │
                                                    Hard Cutoff
                                                    (access lost)
```

## Grace Period Handling

Organizations can configure a grace period after expiry:

| Grace Period Status  | Member Experience                |
| -------------------- | -------------------------------- |
| Active membership    | Full access                      |
| Within grace period  | Limited access + renewal prompts |
| Grace period expired | No access, must renew to restore |

**Limited Access during Grace Period:**

* Can view dashboard
* Can view past content
* Cannot register for new events
* Cannot access premium resources
* Prominent renewal banner displayed

## Renewal Pricing

| Scenario                    | Pricing Rule                      |
| --------------------------- | --------------------------------- |
| Standard renewal            | Current plan price                |
| Price increase since signup | Grandfathered rate (configurable) |
| Loyalty discount            | 5-15% off based on tenure         |
| Lapsed member returning     | May require full price            |
| Promo code at renewal       | Applied if valid                  |

## Early Renewal

Members can renew early (before renewal window):

* New period added to existing period
* No loss of paid time
* Useful for locking in current prices
* May earn loyalty bonus

## Related Entities

* [`User Membership`](/entities/core/user-membership)
* [`Membership Plan`](/entities/core/membership-plan)
* [`Payment Transaction`](/entities/integration/payment-transaction)
* [`Notification Template`](/entities/core/notification-template)

## Related Journeys

* [UJ-M-003](/member/journeys/choose-membership-plan)
* [UJ-M-005](/member/journeys/failed-payment-recovery)
* [UJ-M-031](/member/journeys/view-invoices)

## Acceptance Criteria

### Frontend

* [ ] Renewal status banner on dashboard
* [ ] Membership page shows expiry countdown
* [ ] One-click renewal for same plan
* [ ] Plan change option during renewal
* [ ] Payment method update flow
* [ ] Grace period limited access UI
* [ ] Renewal confirmation page

### Backend

* [ ] `GET /api/membership/renewal-status` - Check renewal eligibility
* [ ] `POST /api/membership/renew` - Process renewal
* [ ] `PUT /api/membership/auto-renew` - Toggle auto-renewal
* [ ] Scheduled job for renewal reminders
* [ ] Scheduled job for automatic renewals
* [ ] Grace period access control

### Permissions

* [ ] Member can only renew their own membership

### Business Rules

* [ ] Renewal window configurable (default 30 days)
* [ ] Grace period configurable (default 14 days)
* [ ] Early renewal extends from current expiry
* [ ] Expired renewal extends from today
* [ ] Loyalty discounts based on continuous membership years

### Error Handling

* [ ] Payment failure triggers retry sequence
* [ ] Failed auto-renewal notifies member
* [ ] Support notification for repeated failures