Subscriptions v2.0: Database Upgrade Process for v1.5 to v2.0

To migrate stores using Subscriptions v1.5 to the new architecture of v2.0, Subscriptions uses a database upgrade script.

This script will create a new 'shop_subscription' post for each subscription on the site and then migrate all meta data relating to a subscription from the original order used to purchase the subscription to the new 'shop_subscription' post.

As seen the interface screenshot below, this script upgrades all subscriptions on the site in batches of 50 subscriptions at a time via series of synchronous Ajax requests to avoid memory exhaustion or script timeouts on stores with large numbers of subscriptions.

The data migrated includes:

• Billing schedule, including recurring interval and period, and trial end, next payment and end dates
• Subscription product line item
• Download permissions for the subscription product
• Order notes which contain any of the words subscription, recurring or renewal, as these are deemed to relate to the subscription not the original order
• Recurring tax, shipping and coupon order items and their associated meta data
• Switch, renewal and resubscribe meta data linking switch, renewal and resubscribe orders to the new subscription instead of the original order
• All post meta data not excluding with the 'wcs_upgrade_subscription_meta_to_copy' filter

Specific details of the data upgraded during the process can be seen in the WCS_Upgrade_2_0 class found in /includes/upgrades/class-wcs-upgrade-2-0.php file.

Subscriptions uses an opt-out approach to migrating meta data to the new subscriptions during the upgrade. This is to achieve compatibility by default rather than requiring all developers to opt-in to have their code be compatible.

This is especially important for payment gateways which historically attached billing data, like customer tokens, to the original order. It ensures that this data is copied to the new subscription, which is where we recommend developers store it from v2.0 onwards.

It also allows the data to be relied upon to exist on the subscription for all old and new subscriptions, instead of just new subscriptions. As well as saving if/else statements, this ensures the payment method meta data can be changed by store managers on both old and new subscriptions if the extension supports this new feature.

However, if your extension attaches meta data to an order that should not be copied to 'shop_subscription' objects, you can use the 'wcs_upgrade_subscription_meta_to_copy' filter to prevent it being copied to the subscription. An example of the kind of data may not need to be copied to new subscriptions is a shipment tracking number specific to the original order.

The example below shows how to make sure meta data with the meta key of '_my_shipment_tracking_code' is not copied to new subscription on upgrade.

function eg_do_not_copy_tracking_code( $order_meta ) {
    if ( isset( $order_meta ) ) {
        unset( $order_meta['_my_shipment_tracking_code'] );
    }
    return $order_meta;
}
add_filter( 'wcs_upgrade_subscription_meta_to_copy', 'eg_do_not_copy_tracking_code' );