Upgrade & Renew to Premium System

Overview

The upgrade system manages two types of premium subscription transitions:

1. Upgrading an active standard subscription to premium
2. Renewing a standard subscription to premium during the early renewal period

Eligibility

For Upgrades (Active Subscriptions)

A subscriber is eligible to upgrade when:

1. The subscription is active
2. The subscription is a standard subscription (not premium)
3. The subscription is based on copies (not digital)

For Renew to Premium

A subscriber is eligible to renew to premium when:

1. The subscription is in the early renewal period
   • Defined by early_renew_days option
   • System checks if next payment date is within this period
2. The subscription is either:
   • Active
   • On hold
3. The user is the owner of the subscription (not a recipient)

Upgrade Process

1. Initiation

The upgrade process can be initiated through:

1. Subscription Actions
   • Automatically appears in subscription view
   • Only visible when eligibility criteria are met
   • Can include informational modal if configured
2. Digital Upgrade Links
   • Available for digital subscriptions
   • Supports both premium and standard upgrades
   • Includes special discount handling

2. Flow Types

The system supports multiple flow types:

1. Standard Upgrade Flow
   • Adds supplemental product to cart
   • Includes subscription ID and upgrade type
   • Redirects to checkout
2. Renew to Premium Flow
   • Adds premium subscription to cart
   • Includes subscription ID and renewal type
   • Can include variation ID for term selection
   • Redirects to checkout
3. Digital Upgrade Flow
   • Special handling for digital subscriptions
   • Applies specific discounts
   • Maintains digital access

3. Cart Processing

When adding to cart:

1. For standard upgrades:
   • journal_upgrade: ‘upgrade’
   • subscription_id: Original subscription ID
2. For renew to premium:
   • journal_renew_to_premium: ‘renew-to-premium’
   • subscription_id: Original subscription ID
   • Optional: variation_id and term for term selection
3. For digital upgrades:
   • digital_upgrade: true
   • digital_upgrade_type: ‘premium’ or ‘standard’
   • subscription_id: Original subscription ID
   • nonce: Security token

4. Order Processing

When the order is processed:

1. For standard upgrades:
   • Updates existing subscription to premium
   • Adjusts shipping and product details
   • Fires journal_subscription_upgraded action
2. For renew to premium:
   • Creates new premium subscription
   • Attempts to merge with old subscription
   • Updates statuses and adds notes
3. For digital upgrades:
   • Creates new digital subscription
   • Applies appropriate discounts
   • Maintains digital access

Configuration Options

The following options can be configured in the WordPress admin:

• early_renew_days: Days before expiry to show renew to premium option
• renew_to_premium_label: Text for the renew to premium button
• supplemental_product_label: Text for the upgrade button
• premium_subscription_id: Product ID for premium subscription
• supplemental_product_id: Product ID for upgrade product
• one_year_variation_id: Variation ID for one-year term
• one_year_term_slug: Term slug for one-year option
• upgrade_enable_modal: Toggle for upgrade information modal
• renew_to_premium_enable_modal: Toggle for renew to premium modal
• upgrade_modal_content: Content for upgrade information modal
• renew_to_premium_modal_content: Content for renew to premium modal

Technical Implementation

Key Functions

• standard_upgrade_button(): Handles standard upgrade button logic
• digital_upgrade_buttons(): Handles digital upgrade options
• maybe_renew_to_premium_payment(): Processes renew to premium payment
• maybe_upgrade_payment(): Processes standard upgrade payment
• maybe_digital_upgrade_payment(): Processes digital upgrade payment

Hooks and Filters

• wcs_view_subscription_actions: Adds upgrade buttons to subscription view
• journal_subscription_upgraded: Fires after successful upgrade
• journal_subscription_after_upgrade: Fires after upgrade completion
• woocommerce_checkout_get_value: Pre-fills checkout fields

Error Handling

The system includes error handling for:

• Invalid subscription IDs
• Ineligible subscriptions
• Missing required parameters
• Failed subscription merges
• Invalid user permissions
• Cart processing errors

Testing

To test the upgrade system:

1. Test Standard Upgrade:
   • Create an active standard subscription
   • Attempt upgrade through subscription actions
   • Verify cart and checkout process
   • Confirm subscription transition
2. Test Renew to Premium:
   • Create a standard subscription in early renewal period
   • Attempt renew to premium
   • Verify term selection if applicable
   • Confirm subscription transition
3. Test Digital Upgrade:
   • Create a digital subscription
   • Attempt both premium and standard upgrades
   • Verify discount application
   • Confirm digital access maintenance