Developer Guide to Multiple Subscriptions

This Developer Guide to Multiple Subscriptions provides an overview of the technical implementation of multiple subscription handling for when multiple subscription products are purchased together in the one transaction.

For a more comprehensive overview of the system, including the decisions involved in choosing this implementation, refer to the Store Manager Guide to Multiple Subscriptions. If you have not already, you should read that guide before continuing with this document.

Note: We are unable to provide support for customizations under our Support Policy. If you need to customize a snippet or extend its functionality, we recommend working with a Woo Agency Partner or finding a WooCommerce developer on Codeable.

The way multiple subscriptions are handled is by grouping each subscription product with the same billing schedule into one subscription product.

For example, if a customer purchases 2 x monthly subscriptions and 3 x yearly subscriptions in the one transaction, only 2 x subscriptions would be created; one with line items for the monthly subscription products, and one with line items for the annual subscription products.

This allows shipping to be accurately calculated and displayed during sign-up, while also consolidating renewal orders, and reducing payment gateway fees for subscription products purchased in the same transaction.

To support the purchase of multiple subscriptions in the same transaction, the cart (WC_Cart) stores each subscription’s recurring totals in an array of carts (WC_Cart objects) in a new WC_Cart::$recurring_carts property.

The WC_Cart::$recurring_carts property includes an instance of WC_Cart for each distinct billing schedule. For example, if the cart contains 2 x products renewing each year, and 3 x products which renew each month, the WC_Cart::WC_Cart::$recurring_carts property will contain two WC_Cart objects; one for the items and totals of the annual products and one for the monthly products.

Recurring Cart Key

The grouping of items is handled by creating a key for each subscription product based on its:

• first payment date – this accounts for free trial periods, synchronised renewal dates and any prorated duration that results from switching a subscription.
• billing period and interval – a subscription’s billing period (e.g. month or week) and interval (i.e. every 2nd) is then added to group subscriptions based on their billing schedule.
• length – if a subscription expires at some time in the future, this is taken into account to avoid grouping subscriptions on the same schedule, that do not expire with subscriptions that do expire.

The recurring cart key is created by the method WC_Subscriptions_Cart::get_recurring_cart_key().

It can also be modified using the 'woocommerce_subscriptions_recurring_cart_key' filter.

Recurring Cart Key Examples

If purchasing a subscription on 18 December 2024, that has 1 month free trial and then is $50 / month for 12 months, its recurring cart key will be '2024_01_18_monthly_for_12_months'.

If purchasing a subscription on 21 December 2024 that has 4 weeks free trial and then is $50 every 2nd week, its recurring cart key will be '2024_01_18_every_2nd_week'.

By supporting multiple subscriptions in the one transaction, multiple different recurring periods needs to be displayed, so that the customer understands the commitment they are making. This is handled by the Recurring Totals section, which is the most concise method that still provides accurate information for each recurring amount.

Each groups of subscription products has a row in the Recurring Totals section for:

• subtotal
• shipping
• taxes
• discounts
• total

After purchasing multiple subscription products in the same transaction, the products with the same billing schedule are grouped together as line items on the one subscription object (as opposed to each subscription having only one product/line item associated with it).

For example, the 3 screenshots below show:

• an order used to purchase 4 subscription products – it has 4 line items;
• 2 subscriptions created to store data for the 4 subscription products – each has 2 line items.