Downgrade (Renew to Standard) System

Overview

The downgrade system allows premium subscribers to downgrade their subscription to a standard subscription. This process is handled through a “Renew to Standard” flow, which creates a new standard subscription and manages the transition from the premium subscription.

Eligibility

A subscriber is eligible to downgrade their subscription when:

  1. The subscription is in the early renewal period
    • The early renewal period is defined by the renew_to_standard_days option (default: 60 days)
    • The system checks if the subscription’s next payment date is within this period
  2. The subscription is either:
    • Active
    • On hold
  3. The subscription is a premium subscription (has benefactor status)
  4. The user is either:
    • The owner of the subscription
    • The subscription is on hold (allows gift recipients to downgrade at end of term)

Quickstart - Admin Configuration

Downgrade links show on the memberships in My Account. There are two modes of operation for the links:

  1. Clicking the link takes you straight to checkout to purchase the downgrade subscription
  2. Clicking the link takes you to first to an interstitial page with advisory on benefits that will be lost if you downgrade

To configure:

  1. Create an interstitial page (if required)
  2. Insert the downgrade subscription block into that page. It displays a link; clicking that link will direct to checkout with the downgrade product in the cart:
    • The link can be configured to display as a standard link or as button
    • The text shown on the link can be amended
    • The link can be aligned left, right or center

    Downgrade Link Block Configuration

  3. Configure the downgrade set up in site options:
    • Enter the text that will show on the link in My Account
    • Select the interstitial page (if being used). If none is selected the My Account links will go straight to checkout
    • Select the number of days prior to renewal that the downgrade link will show. It’s in tended to only be used close to renewal, so 30-40 days would be a good setting to use. Note: they’ll lose premium benefits as soon as they’ve downgraded
    • Enter the product ID for our standard subscription

    Downgrade Options Configuration

Downgrade Process

1. Initiation

The downgrade process can be initiated in two ways:

  1. Through the Downgrade Link Block
    • A Gutenberg block that can be placed on any page
    • Requires a subscription_id in the URL
    • Configurable link text and button styling
  2. Through the Subscription Actions
    • Automatically appears in the subscription view
    • Only visible when eligibility criteria are met

2. Flow Options

The system supports two flow types:

  1. Direct Cart Flow
    • Adds the standard subscription product to cart
    • Includes subscription ID and renewal type
    • Redirects to checkout
  2. Interstitial Page Flow
    • If renew_to_standard_interstitial_page is configured
    • Redirects to an informational page first
    • Includes subscription ID in URL
    • User can then proceed to cart

3. Cart Processing

When the standard subscription is added to cart:

  1. The system adds metadata to the cart item:
    • journal_renew_to_standard: ‘renew-to-standard’
    • subscription_id: The original subscription ID
  2. If the subscription is gifted:
    • Adds recipient email information
    • Maintains gifting relationship

4. Order Processing

When the order is processed:

  1. The system creates a new standard subscription
  2. Attempts to merge the subscriptions:
    • Uses TSJ_Subscriptions_Controller->merge_subscriptions()
    • If merge fails, marks the old subscription for cancellation
  3. Adds order notes tracking the downgrade
  4. Updates subscription statuses appropriately

Configuration Options

The following options can be configured in the WordPress admin:

  • renew_to_standard_days: Number of days before expiry to show downgrade option
  • renew_to_standard_label: Text for the downgrade button/link
  • renew_to_standard_interstitial_page: Page ID for informational page
  • downgrade_subscription_id: Product ID for the standard subscription

Technical Implementation

Key Functions

  • maybe_renew_to_standard_button(): Handles button display logic
  • maybe_renew_to_standard_payment(): Processes the downgrade payment
  • is_renew_to_standard_subscription(): Checks if a subscription is a downgrade

Hooks and Filters

  • wcs_view_subscription_actions: Adds downgrade button to subscription view
  • journal_subscription_created: Triggers after new subscription creation
  • woocommerce_checkout_get_value: Pre-fills checkout fields from original subscription

Error Handling

The system includes error handling for:

  • Invalid subscription IDs
  • Ineligible subscriptions
  • Missing required parameters
  • Failed subscription merges

Testing

To test the downgrade system:

  1. Create a premium subscription
  2. Set the next payment date within the early renewal period
  3. Attempt to downgrade through both the block and subscription actions
  4. Verify the cart and checkout process
  5. Confirm the subscription transition