WooCommerce Subscriptions Gifting - wcsg_gift_recipients_email Processing Flow

This plugin allows customers to purchase WooCommerce subscription products as gifts for other users. Here’s how it interacts with WC()->cart->add_to_cart() to process the wcsg_gift_recipients_email meta.

1. Product Page - Initial Data Capture

File: includes/class-wcsg-product.php:38-56

When a user adds a subscription product to their cart from the product page with a recipient email:

  • Hook: woocommerce_add_cart_item_data (line 22)
  • Method: WCSG_Product::add_recipient_data()
  • Process:
    1. Checks if $_POST['recipient_email'][0] is set and not empty
    2. Verifies nonce (_wcsgnonce with action wcsg_add_recipient)
    3. Validates the recipient email using WCS_Gifting::validate_recipient_emails():
      • Checks if email format is valid
      • Ensures email doesn’t belong to the current user (no self-gifting)
    4. If validation passes: Sanitizes and adds wcsg_gift_recipients_email to $cart_item_data
    5. If validation fails: Throws an Exception (caught by WooCommerce, preventing add to cart)

2. Cart Storage - Session Persistence

File: includes/class-wcsg-product.php:66-72

  • Hook: woocommerce_get_cart_item_from_session (line 23)
  • Method: WCSG_Product::get_cart_items_from_session()
  • Process:
    • Restores wcsg_gift_recipients_email from session data to cart item when cart is loaded from session
    • Ensures the recipient email persists across page loads

3. Cart Page - Display & Updates

File: includes/class-wcsg-cart.php

Display (lines 48-88)

  • Shows recipient email in cart items (both main cart and mini-cart)
  • Renders editable fields for updating recipient information
  • Method: WCSG_Cart::maybe_display_gifting_information() (line 154)

Updates (lines 95-111)

  • Hook: woocommerce_update_cart_action_cart_updated (line 32)
  • Method: WCSG_Cart::cart_update()
  • Process:
    1. When cart is updated, checks for $_POST['recipient_email'] array
    2. Validates nonce
    3. Validates all recipient emails
    4. Calls WCS_Gifting::update_cart_item_key() to update each cart item’s recipient

Key Function: WCS_Gifting::update_cart_item_key() (woocommerce-subscriptions-gifting.php:225-259)

  • Regenerates cart item key including the recipient email
  • Merges cart items if they have the same key after recipient update
  • Maintains cart item position in the cart

4. Checkout Page - Final Validation

File: includes/class-wcsg-checkout.php

Pre-checkout Update (lines 105-121)

  • Hook: woocommerce_checkout_process (line 27)
  • Method: WCSG_Checkout::update_cart_before_checkout()
  • Process:
    • Final validation and update of recipient emails right before checkout
    • If validation fails, sets session flag to reload checkout
    • Applies same validation and update process as cart page

Session Management (lines 164-176)

  • Hook: woocommerce_checkout_update_order_review (line 33)
  • Method: WCSG_Checkout::store_recipients_in_session()
  • Process:
    • Stores recipient emails during AJAX checkout updates
    • Prevents loss of recipient information when checkout fields refresh

5. Order Creation - Converting to User ID

File: includes/class-wcsg-cart.php:236-258

Method: WCSG_Cart::get_recipient_from_cart_item()

  • Called during order/subscription creation
  • Converts wcsg_gift_recipients_email to a recipient user ID:
    1. Checks if email exists in WordPress users via email_exists()
    2. If user doesn’t exist: Creates new user account via WCS_Gifting::create_recipient_user() (woocommerce-subscriptions-gifting.php:663-682)
      • Generates username from email
      • Creates random password
      • Sets wcsg_update_account flag to force account setup on first login
    3. Returns the recipient’s user ID

6. Order Item Meta - Storing Recipient Information

File: includes/class-wcsg-recipient-management.php:633-639

  • Hook: woocommerce_checkout_create_order_line_item (line 55, WC 3.0+)
  • Method: WCSG_Recipient_Management::add_order_item_meta()
  • Process:
    1. Calls WCSG_Cart::get_recipient_from_cart_item() to get/create recipient user ID
    2. Adds order item meta: wcsg_recipient = wcsg_recipient_id_{user_id}
    3. This meta appears in order emails, order pages, and admin

7. Subscription Creation - Linking Recipient

File: includes/class-wcsg-checkout.php:58-82

  • Hook: woocommerce_checkout_subscription_created (line 23)
  • Method: WCSG_Checkout::subscription_created()
  • Process:
    1. Gets first item from recurring cart
    2. Checks for wcsg_gift_recipients_email in cart item
    3. Verifies user exists via email_exists()
    4. Sets subscription meta: _recipient_user = user ID via WCS_Gifting::set_recipient_user()
    5. Copies recipient’s shipping address to subscription
    6. Saves subscription

Key Data Structures

Cart Item Data 

[
    'wcsg_gift_recipients_email' => 'recipient@example.com',
    // ... other cart item data
]

Order Item Meta 

'wcsg_recipient' => 'wcsg_recipient_id_123'

Subscription Meta 

'_recipient_user' => 123 // user ID

Important Validation Rules

  1. Email must be in valid format (is_email())
  2. Email cannot belong to current user (no self-gifting)
  3. Email is sanitized with sanitize_email()
  4. Nonce verification required for all form submissions
  5. Cart key regeneration ensures proper item grouping

Recipient Cart Key Generation

File: includes/class-wcsg-checkout.php:92-97

  • Hook: woocommerce_subscriptions_recurring_cart_key (line 25)
  • Method: WCSG_Checkout::add_recipient_email_recurring_cart_key()
  • Appends recipient email to recurring cart keys to differentiate subscriptions gifted to different recipients

Flow Summary 

Product Page (Add to Cart)
    ↓
[Capture recipient email via POST]
    ↓
[Validate email format & non-self-gifting]
    ↓
[Add wcsg_gift_recipients_email to cart_item_data]
    ↓
Cart Session
    ↓
[Persist wcsg_gift_recipients_email across sessions]
    ↓
Cart/Checkout Page
    ↓
[Allow recipient email updates]
    ↓
[Regenerate cart keys when recipient changes]
    ↓
Checkout Processing
    ↓
[Final validation before order creation]
    ↓
Order Creation
    ↓
[Convert email → user ID (create user if needed)]
    ↓
[Add wcsg_recipient order item meta]
    ↓
Subscription Creation
    ↓
[Link recipient to subscription via _recipient_user meta]
    ↓
[Copy recipient shipping address to subscription]

Additional Features

Recipient User Account Creation

  • File: woocommerce-subscriptions-gifting.php:663-682
  • Automatically creates WordPress user accounts for recipients who don’t exist
  • Generates unique usernames from email address
  • Creates secure random password
  • Sets flag requiring recipient to complete account setup on first login

Recipient Management

  • Recipients can view and manage their gifted subscriptions
  • Recipients can suspend, reactivate, or cancel subscriptions
  • Recipients cannot change payment methods (purchaser retains billing control)
  • Purchaser and recipient both have access to subscription details

Security Features

  • All form submissions require nonce verification
  • Email sanitization prevents XSS attacks
  • Self-gifting prevention
  • Proper capability checks for subscription access

This comprehensive flow ensures that gift recipient information is captured, validated, persisted, and properly converted from an email address to a WordPress user account that’s linked to both the order and subscription records.