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
| Entity |
Name/key |
Notes |
| Subscription order type |
shop_subscription |
Registered with wc_register_order_type(), class WC_Subscription. In CPT storage it is a post type; in HPOS it is an order type. |
| Simple subscription product type |
subscription |
WC_Product_Subscription::get_type(). |
| Variable subscription product type |
variable-subscription |
WC_Product_Variable_Subscription::get_type(). |
| Subscription variation product type |
subscription_variation |
WC_Product_Subscription_Variation::get_type(). |
| Action Scheduler group |
wc_subscription_scheduled_event |
Used for subscription scheduled events. |
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.
| Meta key |
Prop/date key |
Purpose |
_billing_period |
billing_period |
day, week, month, or year. |
_billing_interval |
billing_interval |
Billing interval integer. |
_suspension_count |
suspension_count |
Customer/admin suspension count. |
_cancelled_email_sent |
cancelled_email_sent |
Cancellation email guard. |
_requires_manual_renewal |
requires_manual_renewal |
Manual renewal flag. |
_trial_period |
trial_period |
Trial period unit. |
_last_order_date_created |
last_order_date_created |
Last related parent/renewal order created date used by WCS. |
_schedule_start |
start / schedule_start |
Subscription start datetime. |
_schedule_trial_end |
trial_end / schedule_trial_end |
Trial end datetime. |
_schedule_next_payment |
next_payment / schedule_next_payment |
Next renewal datetime. |
_schedule_cancelled |
cancelled / schedule_cancelled |
Cancellation datetime. |
_schedule_end |
end / schedule_end |
End/expiration datetime. |
_schedule_payment_retry |
payment_retry / schedule_payment_retry |
Retry datetime. |
_subscription_switch_data |
switch_data |
Switch order execution payload. |
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.
| Meta key |
Purpose |
_subscription_price |
Recurring price. |
_subscription_sign_up_fee |
Sign-up fee. |
_subscription_period |
Billing period. |
_subscription_period_interval |
Billing interval. |
_subscription_length |
Subscription length. |
_subscription_trial_period |
Trial period unit. |
_subscription_trial_length |
Trial length. |
_subscription_gifting |
Product-level gifting override: enabled, disabled, or empty for global setting. |
_subscription_one_time_shipping |
One-time shipping flag. |
_subscription_payment_sync_date |
Renewal synchronization setting. |
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.
| Meta key |
Relation |
_subscription_renewal |
Renewal order to subscription. |
_subscription_switch |
Switch order to subscription. |
_subscription_resubscribe |
Resubscribe order to subscription. |
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.
- A user clicks the switch link printed in My Account by
WC_Subscriptions_Switcher::print_switch_link().
- The link points to the product/grouped product URL with
switch-subscription, item, and _wcsnonce query args.
subscription_switch_handler() validates ownership, nonce, and item switchability.
validate_switch_request() blocks non-subscription products and identical product/variation/quantity switches.
set_switch_details_in_cart() adds cart item data under subscription_switch.
WCS_Switch_Totals_Calculator calculates proration, switch direction, first payment timestamp, and possible prepaid-term changes.
- Checkout line item meta records prorated amounts on the switch order and switched item links on subscription items.
process_checkout() creates _subscription_switch_data on the switch order and may create pending switch items on the existing subscription.
- When the switch order is paid/completed,
complete_subscription_switches() applies the payload to the subscription.
- 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:
- Verify the current user can switch the exact subscription item with
WC_Subscriptions_Switcher::can_item_be_switched_by_user().
- Build a temporary cart/session context for the current user and add the replacement product with
subscription_switch cart item data.
- Let
WCS_Switch_Totals_Calculator calculate prorations, first_payment_timestamp, end_timestamp, force_payment, and switch direction.
- Return preview totals from the calculated cart/order data, not from hand-written price math.
- On confirmation, create the switch order with the same
_subscription_switch_data shape WCS checkout writes.
- 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.
- 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.
| Item type |
Meaning |
line_item_pending_switch |
New line item staged on a subscription before switch completion. |
line_item_switched |
Old subscription line item archived after replacement. |
line_item_removed |
Removed subscription line item. |
coupon_pending_switch, fee_pending_switch, shipping_pending_switch |
Staged recurring coupon/fee/shipping items. |
coupon_switched, fee_switched, shipping_switched |
Archived old recurring coupon/fee/shipping items. |
Important item meta:
| Item meta |
Stored on |
Purpose |
_switched_subscription_item_id |
New subscription line item |
Old subscription item ID. |
_switched_subscription_new_item_id |
Old subscription line item |
New subscription/order line item ID. |
_switched_subscription_sign_up_fee_prorated |
Switch order line item |
Portion of order line total from prorated sign-up fee. |
_switched_subscription_price_prorated |
Switch order line item |
Portion of order line total from prorated recurring price. |
_has_trial |
Pending switch item |
Marks new item with trial. |
Switch extension points
| Need |
Hook/filter |
Args |
| Check product switchability |
wcs_is_product_switchable |
$is_switchable, $product, $variation |
| Check item switchability |
woocommerce_subscriptions_can_item_be_switched |
$can, $item, $subscription |
| Check user can switch item |
woocommerce_subscriptions_can_item_be_switched_by_user |
$can, $item, $subscription |
| Switch URL |
woocommerce_subscriptions_switch_url |
$url, $item_id, $item, $subscription |
| Switch link markup/text/classes |
woocommerce_subscriptions_switch_link, woocommerce_subscriptions_switch_link_text, woocommerce_subscriptions_switch_link_classes |
Link context. |
| Retain coupons |
woocommerce_subscriptions_retain_coupon_on_switch |
$retain, $coupon_code, $coupon, $subscription |
| Switch added to cart |
woocommerce_subscriptions_switch_added_to_cart |
$subscription, $existing_item, $cart_item_key, $cart_item |
| Proration price/day |
wcs_switch_proration_old_price_per_day, wcs_switch_proration_new_price_per_day |
Calculator context. |
| Switch type |
wcs_switch_proration_switch_type |
$type, $subscription, $cart_item, $old_price_per_day, $new_price_per_day |
| Prorate recurring/sign-up fee |
wcs_switch_should_prorate_recurring_price, wcs_switch_should_prorate_sign_up_fee |
$bool, $switch_item |
| Extra amount |
wcs_switch_proration_extra_to_pay |
$extra, $subscription, $cart_item, $days_in_old_cycle |
| Completion |
woocommerce_subscriptions_switch_completed |
$order |
| Item switched |
woocommerce_subscriptions_switched_item |
$subscription, $new_order_item, $old_subscription_item |
| Subscription item switched |
woocommerce_subscription_item_switched |
$order, $subscription, $new_item_id, $old_item_id |
Gifting storage
Gifting is included in Subscriptions. It lets purchaser and recipient differ.
| Storage |
Key |
Purpose |
| Cart item data |
wcsg_gift_recipients_email |
Recipient email before checkout/subscription creation. |
| Subscription meta |
_recipient_user_email_address |
Recipient email captured at subscription creation before a user is resolved. |
| Subscription meta |
_recipient_user |
Recipient user ID after account lookup/creation. Primary gifted-subscription marker. |
| Parent order item meta |
_wcsg_cart_key |
Links checkout order item to the recurring cart/subscription item. |
| Parent order item meta |
wcsg_recipient |
Value format wcsg_recipient_id_{user_id}. |
| Parent order item meta |
wcsg_deleted_recipient_data |
JSON snapshot used after recipient deletion. |
| User meta |
wcsg_update_account |
Recipient account setup/update flag. |
| User meta |
wcsg_recipient_just_reset_password |
Recipient onboarding flag. |
Gifted subscriptions are detected by WCS_Gifting::is_gifted_subscription(): true when _recipient_user exists or _recipient_user_email_address is present.
Gifting flow
- Product page/cart/checkout collects recipient email when
WCSG_Product::is_giftable() is true.
- Cart item stores
wcsg_gift_recipients_email; gifting is blocked for renewal and switch cart items.
- Checkout uses recipient email in recurring cart keys so different recipients produce separate subscriptions.
woocommerce_checkout_subscription_created writes _recipient_user_email_address to the subscription.
- 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.
- Recipients are granted view/pay/suspend/cancel capabilities for gifted subscriptions, but cannot change payment method.
_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.
1---2name: wcs-data-model-switching-gifting3description: WooCommerce Subscriptions data model, switcher, and gifting4 reference for exact order type names, product type slugs, subscription5 meta keys, schedule/date keys, related-order relation meta, switch cart6 data, switch order data, switched item types/meta, proration hooks, and7 WCS Gifting recipient storage. Use when code reads or writes8 shop_subscription, subscription, variable-subscription,9 subscription_variation, _billing_period, _schedule_next_payment,10 _subscription_switch_data, _subscription_switch, subscription_switch,11 _switched_subscription_item_id, wcsg_gift_recipients_email,12 _recipient_user, _recipient_user_email_address, wcsg_recipient, or when13 an agent needs the full WooCommerce Subscriptions switcher/gifting flow.14author: Soczo Kristof15contact: mailto:lonsdale201@hotmail.com16plugin: woocommerce-subscriptions17plugin-version-tested: "8.6.0"18php-min: "7.4"19last-updated: "2026-05-01"20source-refs:21 - wp-content/plugins/woocommerce-subscriptions/includes/core/class-wc-subscriptions-core-plugin.php22 - wp-content/plugins/woocommerce-subscriptions/includes/core/class-wc-subscription.php23 - wp-content/plugins/woocommerce-subscriptions/includes/core/data-stores/class-wcs-subscription-data-store-cpt.php24 - wp-content/plugins/woocommerce-subscriptions/includes/core/data-stores/class-wcs-orders-table-subscription-data-store.php25 - wp-content/plugins/woocommerce-subscriptions/includes/core/class-wc-subscriptions-product.php26 - wp-content/plugins/woocommerce-subscriptions/includes/core/wcs-functions.php27 - wp-content/plugins/woocommerce-subscriptions/includes/core/wcs-switch-functions.php28 - wp-content/plugins/woocommerce-subscriptions/includes/switching/class-wc-subscriptions-switcher.php29 - wp-content/plugins/woocommerce-subscriptions/includes/switching/class-wcs-switch-totals-calculator.php30 - wp-content/plugins/woocommerce-subscriptions/includes/gifting/class-wcs-gifting.php31 - wp-content/plugins/woocommerce-subscriptions/includes/gifting/class-wcsg-product.php32 - wp-content/plugins/woocommerce-subscriptions/includes/gifting/class-wcsg-cart.php33 - wp-content/plugins/woocommerce-subscriptions/includes/gifting/class-wcsg-checkout.php34 - wp-content/plugins/woocommerce-subscriptions/includes/gifting/class-wcsg-recipient-management.php35metadata:36 source: https://skillmd.com/skills/vikingokft/wcs-data-model-switching-gifting37---3839# WooCommerce Subscriptions: data model, switching, gifting4041Use 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.4243## Core names4445| Entity | Name/key | Notes |46|---|---|---|47| Subscription order type | `shop_subscription` | Registered with `wc_register_order_type()`, class `WC_Subscription`. In CPT storage it is a post type; in HPOS it is an order type. |48| Simple subscription product type | `subscription` | `WC_Product_Subscription::get_type()`. |49| Variable subscription product type | `variable-subscription` | `WC_Product_Variable_Subscription::get_type()`. |50| Subscription variation product type | `subscription_variation` | `WC_Product_Subscription_Variation::get_type()`. |51| Action Scheduler group | `wc_subscription_scheduled_event` | Used for subscription scheduled events. |5253Subscription 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.5455## Subscription meta keys5657These keys map to `WC_Subscription` props in both CPT and HPOS subscription data stores.5859| Meta key | Prop/date key | Purpose |60|---|---|---|61| `_billing_period` | `billing_period` | `day`, `week`, `month`, or `year`. |62| `_billing_interval` | `billing_interval` | Billing interval integer. |63| `_suspension_count` | `suspension_count` | Customer/admin suspension count. |64| `_cancelled_email_sent` | `cancelled_email_sent` | Cancellation email guard. |65| `_requires_manual_renewal` | `requires_manual_renewal` | Manual renewal flag. |66| `_trial_period` | `trial_period` | Trial period unit. |67| `_last_order_date_created` | `last_order_date_created` | Last related parent/renewal order created date used by WCS. |68| `_schedule_start` | `start` / `schedule_start` | Subscription start datetime. |69| `_schedule_trial_end` | `trial_end` / `schedule_trial_end` | Trial end datetime. |70| `_schedule_next_payment` | `next_payment` / `schedule_next_payment` | Next renewal datetime. |71| `_schedule_cancelled` | `cancelled` / `schedule_cancelled` | Cancellation datetime. |72| `_schedule_end` | `end` / `schedule_end` | End/expiration datetime. |73| `_schedule_payment_retry` | `payment_retry` / `schedule_payment_retry` | Retry datetime. |74| `_subscription_switch_data` | `switch_data` | Switch order execution payload. |7576Use `WC_Subscription::update_dates()`, `delete_date()`, setters like `set_billing_period()`, and `save()`. Directly updating these meta keys can desync validation and scheduled actions.7778## Product subscription meta7980Subscription product data lives on `product` or `product_variation` posts.8182| Meta key | Purpose |83|---|---|84| `_subscription_price` | Recurring price. |85| `_subscription_sign_up_fee` | Sign-up fee. |86| `_subscription_period` | Billing period. |87| `_subscription_period_interval` | Billing interval. |88| `_subscription_length` | Subscription length. |89| `_subscription_trial_period` | Trial period unit. |90| `_subscription_trial_length` | Trial length. |91| `_subscription_gifting` | Product-level gifting override: `enabled`, `disabled`, or empty for global setting. |92| `_subscription_one_time_shipping` | One-time shipping flag. |93| `_subscription_payment_sync_date` | Renewal synchronization setting. |9495Use `WC_Subscriptions_Product` helpers such as `get_price()`, `get_period()`, `get_interval()`, `get_length()`, `get_trial_length()`, `get_sign_up_fee()`, and `get_gifting()`.9697## Related order relation meta9899WCS relates ordinary orders to subscriptions with order meta and relation stores. Do not infer relation from parent ID alone.100101| Meta key | Relation |102|---|---|103| `_subscription_renewal` | Renewal order to subscription. |104| `_subscription_switch` | Switch order to subscription. |105| `_subscription_resubscribe` | Resubscribe order to subscription. |106107Use `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()`.108109## Switcher flow110111Switching replaces or adds subscription line items through checkout. It is not a simple product ID update.1121131. A user clicks the switch link printed in My Account by `WC_Subscriptions_Switcher::print_switch_link()`.1142. The link points to the product/grouped product URL with `switch-subscription`, `item`, and `_wcsnonce` query args.1153. `subscription_switch_handler()` validates ownership, nonce, and item switchability.1164. `validate_switch_request()` blocks non-subscription products and identical product/variation/quantity switches.1175. `set_switch_details_in_cart()` adds cart item data under `subscription_switch`.1186. `WCS_Switch_Totals_Calculator` calculates proration, switch direction, first payment timestamp, and possible prepaid-term changes.1197. Checkout line item meta records prorated amounts on the switch order and switched item links on subscription items.1208. `process_checkout()` creates `_subscription_switch_data` on the switch order and may create pending switch items on the existing subscription.1219. When the switch order is paid/completed, `complete_subscription_switches()` applies the payload to the subscription.12210. WCS fires `woocommerce_subscriptions_switch_completed` and item-level switch actions after completion.123124## Custom switch flows125126WCS 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.127128Safe pattern:1291301. Verify the current user can switch the exact subscription item with `WC_Subscriptions_Switcher::can_item_be_switched_by_user()`.1312. Build a temporary cart/session context for the current user and add the replacement product with `subscription_switch` cart item data.1323. Let `WCS_Switch_Totals_Calculator` calculate prorations, `first_payment_timestamp`, `end_timestamp`, `force_payment`, and switch direction.1334. Return preview totals from the calculated cart/order data, not from hand-written price math.1345. On confirmation, create the switch order with the same `_subscription_switch_data` shape WCS checkout writes.1356. 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.1367. Let `complete_subscription_switches()` apply the change and let WCS fire its normal hooks.137138Do 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.139140For 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.141142## Switch cart data143144The cart item key is `subscription_switch`. Typical shape:145146```php147$cart_item['subscription_switch'] = array(148 'subscription_id' => 123,149 'item_id' => 456,150 'next_payment_timestamp' => 1770000000,151 'upgraded_or_downgraded' => 'upgraded', // or downgraded/crossgraded, after calculation152 'first_payment_timestamp' => 1771000000, // after proration calculation153 'end_timestamp' => 1780000000, // when length changes154 'recurring_payment_prorated' => true,155 'force_payment' => true,156);157```158159`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.160161## Switch order data162163Switch orders store `subscription_switch_data`, persisted as `_subscription_switch_data` on the order. Shape by subscription ID:164165```php166$switch_data[ $subscription_id ] = array(167 'switches' => array(168 $switch_order_item_id => array(169 'remove_line_item' => 456,170 'add_line_item' => 789,171 'switch_direction' => 'upgrade',172 ),173 ),174 'billing_schedule' => array(175 '_billing_period' => 'month',176 '_billing_interval' => 1,177 ),178 'dates' => array(179 'update' => array(180 'next_payment' => '2026-06-01 00:00:00',181 'trial_end' => 0,182 'end' => '2027-06-01 00:00:00',183 ),184 'delete' => array( 'trial_end' ),185 ),186 'coupons' => array( 111 ),187 'fee_items' => array( 222 ),188 'shipping_line_items' => array( 333 ),189);190```191192WCS can cancel older unpaid switch orders for the same subscription when a new switch order is created.193194## Switched item types and meta195196WCS uses custom order item types during and after switch execution.197198| Item type | Meaning |199|---|---|200| `line_item_pending_switch` | New line item staged on a subscription before switch completion. |201| `line_item_switched` | Old subscription line item archived after replacement. |202| `line_item_removed` | Removed subscription line item. |203| `coupon_pending_switch`, `fee_pending_switch`, `shipping_pending_switch` | Staged recurring coupon/fee/shipping items. |204| `coupon_switched`, `fee_switched`, `shipping_switched` | Archived old recurring coupon/fee/shipping items. |205206Important item meta:207208| Item meta | Stored on | Purpose |209|---|---|---|210| `_switched_subscription_item_id` | New subscription line item | Old subscription item ID. |211| `_switched_subscription_new_item_id` | Old subscription line item | New subscription/order line item ID. |212| `_switched_subscription_sign_up_fee_prorated` | Switch order line item | Portion of order line total from prorated sign-up fee. |213| `_switched_subscription_price_prorated` | Switch order line item | Portion of order line total from prorated recurring price. |214| `_has_trial` | Pending switch item | Marks new item with trial. |215216## Switch extension points217218| Need | Hook/filter | Args |219|---|---|---|220| Check product switchability | `wcs_is_product_switchable` | `$is_switchable, $product, $variation` |221| Check item switchability | `woocommerce_subscriptions_can_item_be_switched` | `$can, $item, $subscription` |222| Check user can switch item | `woocommerce_subscriptions_can_item_be_switched_by_user` | `$can, $item, $subscription` |223| Switch URL | `woocommerce_subscriptions_switch_url` | `$url, $item_id, $item, $subscription` |224| Switch link markup/text/classes | `woocommerce_subscriptions_switch_link`, `woocommerce_subscriptions_switch_link_text`, `woocommerce_subscriptions_switch_link_classes` | Link context. |225| Retain coupons | `woocommerce_subscriptions_retain_coupon_on_switch` | `$retain, $coupon_code, $coupon, $subscription` |226| Switch added to cart | `woocommerce_subscriptions_switch_added_to_cart` | `$subscription, $existing_item, $cart_item_key, $cart_item` |227| Proration price/day | `wcs_switch_proration_old_price_per_day`, `wcs_switch_proration_new_price_per_day` | Calculator context. |228| Switch type | `wcs_switch_proration_switch_type` | `$type, $subscription, $cart_item, $old_price_per_day, $new_price_per_day` |229| Prorate recurring/sign-up fee | `wcs_switch_should_prorate_recurring_price`, `wcs_switch_should_prorate_sign_up_fee` | `$bool, $switch_item` |230| Extra amount | `wcs_switch_proration_extra_to_pay` | `$extra, $subscription, $cart_item, $days_in_old_cycle` |231| Completion | `woocommerce_subscriptions_switch_completed` | `$order` |232| Item switched | `woocommerce_subscriptions_switched_item` | `$subscription, $new_order_item, $old_subscription_item` |233| Subscription item switched | `woocommerce_subscription_item_switched` | `$order, $subscription, $new_item_id, $old_item_id` |234235## Gifting storage236237Gifting is included in Subscriptions. It lets purchaser and recipient differ.238239| Storage | Key | Purpose |240|---|---|---|241| Cart item data | `wcsg_gift_recipients_email` | Recipient email before checkout/subscription creation. |242| Subscription meta | `_recipient_user_email_address` | Recipient email captured at subscription creation before a user is resolved. |243| Subscription meta | `_recipient_user` | Recipient user ID after account lookup/creation. Primary gifted-subscription marker. |244| Parent order item meta | `_wcsg_cart_key` | Links checkout order item to the recurring cart/subscription item. |245| Parent order item meta | `wcsg_recipient` | Value format `wcsg_recipient_id_{user_id}`. |246| Parent order item meta | `wcsg_deleted_recipient_data` | JSON snapshot used after recipient deletion. |247| User meta | `wcsg_update_account` | Recipient account setup/update flag. |248| User meta | `wcsg_recipient_just_reset_password` | Recipient onboarding flag. |249250Gifted subscriptions are detected by `WCS_Gifting::is_gifted_subscription()`: true when `_recipient_user` exists or `_recipient_user_email_address` is present.251252## Gifting flow2532541. Product page/cart/checkout collects recipient email when `WCSG_Product::is_giftable()` is true.2552. Cart item stores `wcsg_gift_recipients_email`; gifting is blocked for renewal and switch cart items.2563. Checkout uses recipient email in recurring cart keys so different recipients produce separate subscriptions.2574. `woocommerce_checkout_subscription_created` writes `_recipient_user_email_address` to the subscription.2585. 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.2596. Recipients are granted view/pay/suspend/cancel capabilities for gifted subscriptions, but cannot change payment method.2607. `_recipient_user` is not copied to renewal orders.261262Product giftability:263264- Global enablement comes from WCSG admin settings.265- Product-level override is `_subscription_gifting`: `enabled`, `disabled`, or empty for global.266- Variable subscription parent returns giftable to render UI; each variation decides final `gifting` variation data.267- Product page gifting UI is suppressed during switching (`switch-subscription` query arg).268269## Memberships integration for gifts270271If WooCommerce Memberships is active and a giftable subscription product grants a plan:272273- Membership access is granted to the recipient when order item meta has `wcsg_recipient`.274- Purchaser access is skipped unless the same product was also purchased for the purchaser.275- The created `wc_user_membership` still stores `_subscription_id`.276- 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.277278## Common mistakes279280```php281// WRONG: direct date meta write can desync Action Scheduler.282update_post_meta( $subscription_id, '_schedule_next_payment', '2026-06-01 00:00:00' );283284// RIGHT:285$subscription = wcs_get_subscription( $subscription_id );286$subscription->update_dates( array( 'next_payment' => '2026-06-01 00:00:00' ), 'gmt' );287288// WRONG: treating a switch as a product meta update.289$subscription->remove_item( $old_item_id );290$subscription->add_product( wc_get_product( $new_product_id ) );291292// RIGHT: use WCS switch flow or reproduce its order payload deliberately.293$is_switch = wcs_order_contains_switch( $order );294295// WRONG: gifted subscription recipient is not the subscription customer.296$recipient_id = $subscription->get_user_id();297298// RIGHT:299$recipient_id = WCS_Gifting::get_recipient_user( $subscription );300```301302## Cross-references303304- Use `wcs-subscription-hooks` for general lifecycle hook selection.305- Use `wcs-renewal-scheduler` for renewal dates, Action Scheduler, and payment retry timing.306- Use `wcm-data-model-subscriptions-link` for Memberships CPT/meta and the Memberships-to-Subscriptions relation.