Wcs Data Model Switching Gifting

WooCommerce Subscriptions: data model, switching, gifting

Use this when exact storage names or switch/gift internals matter. Prefer WCS CRUD functions and WC_Subscription methods for writes; use raw keys only for audits, migrations, debugging, or compatibility glue.

Core names

Subscription statuses are WooCommerce order statuses with wc- prefix in storage: wc-pending, wc-active, wc-on-hold, wc-cancelled, wc-switched, wc-expired, and wc-pending-cancel. Object APIs usually use unprefixed values.

Subscription meta keys

These keys map to WC_Subscription props in both CPT and HPOS subscription data stores.

Use WC_Subscription::update_dates(), delete_date(), setters like set_billing_period(), and save(). Directly updating these meta keys can desync validation and scheduled actions.

Product subscription meta

Subscription product data lives on product or product_variation posts.

Use WC_Subscriptions_Product helpers such as get_price(), get_period(), get_interval(), get_length(), get_trial_length(), get_sign_up_fee(), and get_gifting().

Related order relation meta

WCS relates ordinary orders to subscriptions with order meta and relation stores. Do not infer relation from parent ID alone.

Use wcs_get_subscription_ids_for_order(), wcs_get_subscriptions_for_order(), wcs_get_subscriptions_for_renewal_order(), wcs_get_subscriptions_for_switch_order(), and $subscription->get_related_orders().

Switcher flow

Switching replaces or adds subscription line items through checkout. It is not a simple product ID update.

1. A user clicks the switch link printed in My Account by WC_Subscriptions_Switcher::print_switch_link().
2. The link points to the product/grouped product URL with switch-subscription, item, and _wcsnonce query args.
3. subscription_switch_handler() validates ownership, nonce, and item switchability.
4. validate_switch_request() blocks non-subscription products and identical product/variation/quantity switches.
5. set_switch_details_in_cart() adds cart item data under subscription_switch.
6. WCS_Switch_Totals_Calculator calculates proration, switch direction, first payment timestamp, and possible prepaid-term changes.
7. Checkout line item meta records prorated amounts on the switch order and switched item links on subscription items.
8. process_checkout() creates _subscription_switch_data on the switch order and may create pending switch items on the existing subscription.
9. When the switch order is paid/completed, complete_subscription_switches() applies the payload to the subscription.
10. WCS fires woocommerce_subscriptions_switch_completed and item-level switch actions after completion.

Custom switch flows

WCS does not expose a simple customer REST endpoint for "switch this subscription item to that product". The built-in switcher is a cart/checkout/order-completion flow. Custom account UI, AJAX, or REST layers must wrap that flow or deliberately reproduce its order payload.

Safe pattern:

1. Verify the current user can switch the exact subscription item with WC_Subscriptions_Switcher::can_item_be_switched_by_user().
2. Build a temporary cart/session context for the current user and add the replacement product with subscription_switch cart item data.
3. Let WCS_Switch_Totals_Calculator calculate prorations, first_payment_timestamp, end_timestamp, force_payment, and switch direction.
4. Return preview totals from the calculated cart/order data, not from hand-written price math.
5. On confirmation, create the switch order with the same _subscription_switch_data shape WCS checkout writes.
6. If an immediate payment is due, process it through the gateway/order payment flow; if no payment is due, complete/apply the switch through WCS completion logic.
7. Let complete_subscription_switches() apply the change and let WCS fire its normal hooks.

Do not implement switching by directly calling $subscription->remove_item() and $subscription->add_product() from a customer action. That bypasses switch orders, prorations, tax/fee/coupon handling, old item archival, pending switch item types, cancellation of older unpaid switch orders, and completion hooks.

For read-only previews or eligibility checks, it is fine to expose custom endpoints that return allowed products, switchable item IDs, and WCS-calculated preview totals. For writes, prefer a service that uses WCS cart/checkout objects internally.

Switch cart data

The cart item key is subscription_switch. Typical shape:

$cart_item['subscription_switch'] = array(
    'subscription_id'        => 123,
    'item_id'                => 456,
    'next_payment_timestamp' => 1770000000,
    'upgraded_or_downgraded' => 'upgraded', // or downgraded/crossgraded, after calculation
    'first_payment_timestamp' => 1771000000, // after proration calculation
    'end_timestamp'          => 1780000000, // when length changes
    'recurring_payment_prorated' => true,
    'force_payment'          => true,
);

item_id is the subscription line item being replaced. When adding an item to a subscription without replacing one, item_id can be empty and wcs_cart_contains_switches( 'add' ) is relevant.

Switch order data

Switch orders store subscription_switch_data, persisted as _subscription_switch_data on the order. Shape by subscription ID:

$switch_data[ $subscription_id ] = array(
    'switches' => array(
        $switch_order_item_id => array(
            'remove_line_item'  => 456,
            'add_line_item'     => 789,
            'switch_direction'  => 'upgrade',
        ),
    ),
    'billing_schedule' => array(
        '_billing_period'   => 'month',
        '_billing_interval' => 1,
    ),
    'dates' => array(
        'update' => array(
            'next_payment' => '2026-06-01 00:00:00',
            'trial_end'    => 0,
            'end'          => '2027-06-01 00:00:00',
        ),
        'delete' => array( 'trial_end' ),
    ),
    'coupons'             => array( 111 ),
    'fee_items'           => array( 222 ),
    'shipping_line_items' => array( 333 ),
);

WCS can cancel older unpaid switch orders for the same subscription when a new switch order is created.

Switched item types and meta

WCS uses custom order item types during and after switch execution.

Important item meta:

Switch extension points

Gifting storage

Gifting is included in Subscriptions. It lets purchaser and recipient differ.

Gifted subscriptions are detected by WCS_Gifting::is_gifted_subscription(): true when _recipient_user exists or _recipient_user_email_address is present.

Gifting flow

1. Product page/cart/checkout collects recipient email when WCSG_Product::is_giftable() is true.
2. Cart item stores wcsg_gift_recipients_email; gifting is blocked for renewal and switch cart items.
3. Checkout uses recipient email in recurring cart keys so different recipients produce separate subscriptions.
4. woocommerce_checkout_subscription_created writes _recipient_user_email_address to the subscription.
5. On parent order processing/completion, recipient management finds or creates the recipient user, writes _recipient_user, adds wcsg_recipient to the matching parent order item, and updates shipping fields from recipient user meta.
6. Recipients are granted view/pay/suspend/cancel capabilities for gifted subscriptions, but cannot change payment method.
7. _recipient_user is not copied to renewal orders.

Product giftability:

• Global enablement comes from WCSG admin settings.
• Product-level override is _subscription_gifting: enabled, disabled, or empty for global.
• Variable subscription parent returns giftable to render UI; each variation decides final gifting variation data.
• Product page gifting UI is suppressed during switching (switch-subscription query arg).

Memberships integration for gifts

If WooCommerce Memberships is active and a giftable subscription product grants a plan:

• Membership access is granted to the recipient when order item meta has wcsg_recipient.
• Purchaser access is skipped unless the same product was also purchased for the purchaser.
• The created wc_user_membership still stores _subscription_id.
• Because one order can contain the same product for multiple recipients, link the membership to the recipient's subscription, not just the first subscription in the order.

Common mistakes

// WRONG: direct date meta write can desync Action Scheduler.
update_post_meta( $subscription_id, '_schedule_next_payment', '2026-06-01 00:00:00' );

// RIGHT:
$subscription = wcs_get_subscription( $subscription_id );
$subscription->update_dates( array( 'next_payment' => '2026-06-01 00:00:00' ), 'gmt' );

// WRONG: treating a switch as a product meta update.
$subscription->remove_item( $old_item_id );
$subscription->add_product( wc_get_product( $new_product_id ) );

// RIGHT: use WCS switch flow or reproduce its order payload deliberately.
$is_switch = wcs_order_contains_switch( $order );

// WRONG: gifted subscription recipient is not the subscription customer.
$recipient_id = $subscription->get_user_id();

// RIGHT:
$recipient_id = WCS_Gifting::get_recipient_user( $subscription );

Cross-references

• Use wcs-subscription-hooks for general lifecycle hook selection.
• Use wcs-renewal-scheduler for renewal dates, Action Scheduler, and payment retry timing.
• Use wcm-data-model-subscriptions-link for Memberships CPT/meta and the Memberships-to-Subscriptions relation.