On Woocommerce Subscriptions there two important strategies related to subscriptions, renewals vs resubscribing.
A renewal stands for a current subscription in active or on-hold status that can accept a payment to remain active or return to active. On the other side we have the resubscribe for subscriptions that are finished, on status like expired, cancelled or pending-cancel, this means we can not complete an existing order to pay this order and we need to create a new subscription copying the products under the previous subscription.
This two different strategies are described in the documentation here:
For code you can refer to:
- WCS_Cart_Renewal for Cart Renewal handle.
- WCS_Cart_Resubscribe extends WCS_Cart_Renewal for Resubscribe.
Some useful functions to query or alter subscriptions in Woocommerce Subscriptions plugin some of this functions are not documented or explained so I’m doing this post just to keep in mind and for future reference, hope this help someone.
Table of Contents
Subscription Functions
Get subscriptions with any of these products
Useful when you want to all the subscriptions with an specific product(s) under it.
/**
* Get subscriptions that contain a certain product, specified by ID.
*
* @param int|array $product_ids Either the post ID of a product or variation or an array of product or variation IDs
* @param string $fields The fields to return, either "ids" to receive only post ID's for the match subscriptions, or "subscription" to receive WC_Subscription objects
* @param array $args A set of name value pairs to determine the returned subscriptions.
* 'subscription_statuses' Any valid subscription status. Can be 'any', 'active', 'cancelled', 'on-hold', 'expired', 'pending' or 'trash' or an array of statuses. Defaults to 'any'.
* 'limit' The number of subscriptions to return. Default is all (-1).
* 'offset' An optional number of subscriptions to displace or pass over. Default 0. A limit arg is required for the offset to be applied.
* @return array
* @since 2.0
*/
function wcs_get_subscriptions_for_product($product_ids, $fields = 'ids', $args = array())Get all items under a subscription that are trial
This function allow to detect if the subscription contains any trial item and if it does return an array with the items.
/**
* Get all subscription items which have a trial.
*
* @param mixed WC_Subscription|post_id
* @return array
* @since 2.0
*/
function wcs_get_line_items_with_a_trial( $subscription_id )Resubscribe Functions
Check if a user is able to resubscribe to a subscription
This function allow to know if a user can resubscribe to a given subscription. Usually used together with wcs_get_users_resubscribe_link function.
/**
* Check if a user can resubscribe to an expired or cancelled subscription by creating a
* new subscription with the same terms.
*
* For it to be possible to resubscribe to a subscription, the user specified with $user_id must
* and the subscription must:
* 1. be be inactive (expired or cancelled)
* 2. had at least one payment, to avoid circumventing sign-up fees
* 3. its parent order must not have already been superseded by a new order (to prevent
* displaying "Resubscribe" links on subscriptions that have already been renewed)
* 4. the products to which the subscription relates must not have been deleted
* 5. have a recurring amount greater than $0, to avoid allowing resubscribes to subscriptions
* where the entire cost is charged in a sign-up fee
*
* @param int | WC_Subscription $subscription Post ID of a 'shop_subscription' post, or instance of a WC_Subscription object
* @param int The ID of a user
* @return bool
* @since 2.0
*/
function wcs_can_user_resubscribe_to( $subscription, $user_id = '' )Get resubscribe link for a given subscription
Get the URL to resubscribe for the current user.
/**
* Returns a URL including required parameters for an authenticated user to renew a subscription
*
* @param int | WC_Subscription $subscription Post ID of a 'shop_subscription' post, or instance of a WC_Subscription object
* @return string
* @since 2.0
*/
function wcs_get_users_resubscribe_link( $subscription ) {Renewal Functions
Create a new renewal order
Create a renewal order from a existing subscription. Returns a WC_Order.
/**
* Create a renewal order to record a scheduled subscription payment.
*
* This method simply creates an order with the same post meta, order items and order item meta as the subscription
* passed to it.
*
* @param int | WC_Subscription $subscription Post ID of a 'shop_subscription' post, or instance of a WC_Subscription object
* @return WC_Order | WP_Error
* @since 2.0
*/
function wcs_create_renewal_order( $subscription )Check if a order contains a renewal order
Return a boolean.
/**
* Check if a given order is a subscription renewal order.
*
* @param WC_Order|int $order The WC_Order object or ID of a WC_Order order.
* @since 2.0
*/
function wcs_order_contains_renewal( $order )Check if the current cart contains any subscription renewal
Useful to check if you are doing a renewal checkout. One case of use is to check if the current cart is doing a renewal and offer some kind of discount through coupon code.
/**
* Checks the cart to see if it contains a subscription product renewal.
*
* @param bool | Array The cart item containing the renewal, else false.
* @return string
* @since 2.0
*/
function wcs_cart_contains_renewal()It’s always good idea to check the deprecated functions documented in the official web site:
https://woocommerce.com/document/subscriptions-query-monitor-warning/