Subscriptions Filter Reference

You are here:
In this article

This documentation is written for WooCommerce developers who want to extend or integrate with the WooCommerce Subscriptions plugin. To follow this documentation, you will need an advanced understanding of PHP and WordPress development.

If you are looking for a guide to creating and managing subscription products in a WooCommerce store, please refer to the Store Manager Guide instead. If you need to extend WooCommerce Subscriptions and are not a developer, you can find a developer in the WooExperts directory.

 

This document provides a reference for a few of the more important filter hooks triggered by the WooCommerce Subscriptions extension.

It is not an exhaustive list of all filters applied in Subscriptions, of which there are over 400, nor is it intended to be instructive about when to use these hooks. It is provided as a reference for a few of the more useful hooks you can use to interact with Subscriptions from custom code.

Subscription Product Filters

Filter: 'woocommerce_is_subscription'

Parameters:
$is_subscription A boolean flag (true or false) to indicate whether a given product is a subscription product type.
$product_id The ID of the product to which the $is_subscription value relates.
$product An instance of a WC_Product to which the $is_subscription value relates.

Description:
Control whether a given product is seen as a subscription product or not by the rest of WooCommerce Subscriptions. This filter can be used to unlock a range of Subscriptions features for non-subscription products.

Filter: 'woocommerce_subscriptions_product_price_string'

Parameters:

$subscription_string
String of the form ${price} / {period} for {duration} with a ${price} sign-up fee.
$product
The WC_Product object for which the subscription string should be based on.
$include
An associative array of flags to indicate how to calculate the price and what to include in the string. Possible values:

 

  • 'tax_calculation': false to ignore tax, ‘include_tax’ or ‘exclude_tax’ To indicate that tax should be added or excluded respectively
  • 'subscription_length': true to include subscription’s length (default) or false to exclude it
  • 'sign_up_fee': true to include subscription’s sign up fee (default) or false to exclude it
  • 'price': a string or int price to use instead of the product’s actual recurring price value

Description:
Subscription products have a more complex pricing structure than standard WooCommerce products. Their price includes a billing period, like month, and billing interval, like 2 to bill every 2nd week. The price may also include a total length, like 12 months, and/or sign-up fee.

Wherever a product’s price is displayed, if the product is a subscription, it’s price will be derived from the WC_Subscriptions_Product::get_subscription_price_string() function, which passes its return value through this filter.

Filter: 'woocommerce_subscriptions_product_first_renewal_payment_time'

Parameters:
$first_renewal_timestamp A unix timestamp representing the date/time in the future in a user specified timezone.
$product_id The ID of the product to which the $first_renewal_timestamp value relates.
$from_date_param A MySQL formatted date/time string from which to calculate the date, or empty (default), which will use today’s date/time. Should be in UTC timezone.
$timezone The timezone for the returned date, either ‘site’ for the site’s timezone, or ‘gmt’. Default, ‘site’.

Description:
Change when a given product’s first renewal date should be scheduled to occur. This filter can be used to add custom lengths to the initial period of a subscription, for example, for synchronizing payments to a date not possible with the built-in synchronization feature.

The default value is based on the subscription product’s billing period and interval. However, it can be set to any valid date in the future.

Subscription Product Options Filters

Filter: 'woocommerce_subscription_periods'

Parameters:
$subscription_periods An associative array of $period_key => $period_labels used through out the Subscriptions extension.

Description:
The periods used throughout Subscriptions are all passed through this filter. The makes it possible to customise both the periods that are available and the labels associated with these periods.

Caveats:
If adding new periods, like bi-weekly or bi-annually, you will also need to ensure that only payment gateways which support these periods are available on the checkout page.

Filter: 'woocommerce_subscription_lengths'

Parameters:
$subscription_ranges (array) An associative array of the subscription lengths that can be set on subscription products. The first level of the array is indexed by period keys, i.e. 'day', 'week', 'month' and 'year'. The second level is indexed by an integer representation of the length and 0 for no limit on length.

Description: When creating a subscription product, the store manager can optionally set a length on the subscription (e.g $10 / month for 12 months, or $100 every 2 weeks for 52 weeks). This filter can be used to restrict the available lengths for subscription products in the store.

The example below demonstrates how to use this filter to prevent subscriptions with no length.

   function eg_do_not_allow_all_time_subscriptions( $subscription_lengths ) {

    foreach( $subscription_lengths as $period => $allowed_lengths ) {
        if ( isset( $subscription_lengths[ $period ][0] ) ) {
            unset( $subscription_lengths[ $period ][0] );
        }
    }

    return $subscription_lengths;
}
add_filter( 'woocommerce_subscription_lengths', 'eg_do_not_allow_all_time_subscriptions', 10 );

Filter: 'woocommerce_subscription_period_interval_strings'

Parameters:
$billing_intervals (array) An array of the billing intervals that can be set on subscription products.

Description: When creating a subscription product, the store manager can optionally set a custom billing interval on the product (e.g $10 / month, $10 every 2 months or $10 every 3 months). This filter can be used to restrict the available billing intervals for subscription products in the store.

The example below demonstrates how to use this filter to prevent subscription products with any billing interval other than every day, week or month (i.e. do not allow subscriptions products that renew every 2nd, 3rd, 4th or nth billing period).

   function eg_do_not_allow_non_single_billing_intervals( $billing_intervals ) {

    array_splice( $billing_intervals, 1 );

    return $billing_intervals;
}
add_filter( 'woocommerce_subscription_period_interval_strings', 'eg_do_not_allow_non_single_billing_intervals', 10 );

The default $billing_intervals allows up to every 6th period, as seen below:

$billing_intervals = Array
(
    [1] => per
    [2] => every 2nd
    [3] => every 3rd
    [4] => every 4th
    [5] => every 5th
    [6] => every 6th
)

Subscriber/User Filters

Filter: 'wcs_get_users_subscriptions'

Parameters:
$subscriptions The associative array of subscription details for a given user.
$user_id The ID of the user who these subscriptions belong to.

Description:
The return value of the wcs_get_users_subscriptions() function is passed through this filter. If you wish to dynamically add a subscription to a user, and for whatever reason do not want it stored in the database, perhaps because the subscription is stored on another store, you could use this filter.

Filter: 'wcs_user_has_subscription'

Parameters:
$has_subscription A boolen flag (true or false) to indicate whether a given user has a subscription to a certain product.
$user_id The ID of the user the $has_subscription value relates to.
$product_id The ID of the product the $has_subscription value checked for.
$status A status string to filter the check against only products of a certain status. Default 'any', which does not apply a status filter.

Description:
Indicate whether a given user has a subscription to a given product with an optional status filter.

Filter: 'wcs_users_change_status_link'

Parameters:
$action_link A URL based on the current page with status change parameters appended.
$subscription_id The ID of the subscription which the status change relates to.
$status The string representation of the new status that will be applied to the subscription when the user clicks this link.

Description:
A store’s customers can changed the status of their subscriptions from their My Account > View Subscription page using an action button.

The URL for these buttons comes from the wcs_get_users_change_status_link() function, which passes its return value through this filter. If the correct URL parameters are set on the link, including a valid status for the change_subscription_to parameter, _wpnonce & subscription_id, then the subscription will be changed for the currently logged in user, if it exists and belongs to that user.

Filter: 'wcs_view_subscription_actions'

Parameters:
$action_link A URL based on the current page with status change parameters appended.
$subscription_id The ID of the subscription which the status change relates to.
$status The string representation of the new status that will be applied to the subscription when the user clicks this link.

Description:
WooCommerce Subscriptions displays a number of buttons on the My Account > View Subscription page to allow a store’s customers to alter their subscriptions.

The values of these buttons comes from the wcs_get_all_user_actions_for_subscription() function, which passes its return value through this filter to allow 3rd party code to add additional buttons to this section of the View Subscription page.

Subscription Formatting Filters

Filter: 'woocommerce_subscription_price_string'

Parameters:

$subscription_string
String of the form ${price} up front then ${price} / {period} for {duration}.
$subscription_details
Array of name => value pairs for the subscription details to include in the string. Available keys:

 

  • 'initial_amount': The upfront payment for the subscription, including sign up fees, as a string from the @see woocommerce_price(). Default empty string (no initial payment)
  • 'initial_description': The word after the initial payment amount to describe the amount. Examples include “now” or “initial payment”. Defaults to “up front”.
  • 'recurring_amount': The amount charged per period. Default 0 (no recurring payment).
  • 'subscription_interval': How regularly the subscription payments are charged. Default 1, meaning each period e.g. per month.
  • 'subscription_period': The temporal period of the subscription. Should be one of {day|week|month|year}.
  • 'subscription_length': The total number of periods the subscription should continue for. Default 0, meaning continue indefinitely.
  • 'trial_length': The total number of periods the subscription trial period should continue for. Default 0, meaning no trial period.
  • 'trial_period': The temporal period for the subscription’s trial period. Should be one of {day|week|month|year}.

Description:
The price string with billing period, interval, length and sign-up fee is not just required for products. If the cart or an order contains a subscription, those pricing attributes also need to be displayed for the cart and order totals.

Wherever a subtotal or total for the cart or an order containing a subscription is displayed, it’s price will be derived from the WC_Subscriptions_Manager::get_subscription_price_string() function, which passes its return value through this filter.

Renewal and Resubscribe Filters

Filter: 'wcs_renewal_order_created'

Parameters:
$renewal_order An instance of a WC_Order.
$subscription An instance of a WC_Subscription for which the $renewal_order was created for.

Description:
WooCommerce Subscriptions stores all details of each subscription renewal in a standard WooCommerce order, only with a special meta flag linking it to a subscription.

These orders are always created through the wcs_create_renewal_order() function, regardless of whether they are created for a scheduled renewal event, manually via the WooCommerce > Edit Subscription administration screen, or via the Subscriptions endpoints for the WooCommerce REST API. Because of this, it’s possible to add, remove or update the value of anything on that renewal order using this filter.

For example, this can be used to add a discount to specific renewal orders, like the 12th order each year. It could also be used to add one-time fee for a certain renewal order, like a special annual extra fee on a monthly subscription.


Filter: 'wcs_renewal_order_meta_query'

Parameters:
$order_meta_query (string) The SQL query used to select which post meta data to copy from the original order to the renewal order.
$to_order (int) The order object meta data is being copied to. This will be the renewal order.
$from_order (int) The order object meta data is being copied from. This will be the subscription object.

Description: When creating a renewal order, Subscriptions copies almost all of an order’s meta data to renewal orders. The only exceptions are some known meta data added by WooCommerce core or Subscriptions that does not belong on the subscription.

For extensions, Subscriptions follows an opt-out policy to determine the meta data which should be copied. This improves compatibly with 3rd party extensions; however, your extension may use meta data which is unique to an order, like a payment token or shipment tracking code.

If your extension does not want certain meta data to be copied from the original order to renewal orders, use this hook to exclude the meta data. The hook requires valid SQL to indicate the meta data which should not be copied.

The example below demonstrates how to use this filter to prevent copying two pieces of custom meta data.

function eg_do_not_copy_meta_data( $order_meta_query, $to_order, $from_order ) {

    $order_meta_query .= " AND `meta_key` NOT IN ('_my_extensions_meta_key', '_my_extensions_other_meta_key')";

    return $order_meta_query;
}
add_filter( 'wcs_renewal_order_meta_query', 'eg_do_not_copy_meta_data', 10, 3 );


Filter: 'wcs_can_user_resubscribe_to_subscription'

Parameters:
$can_user_resubscribe A boolean flag (true or false) to indicate if a given user can resubscribe to a subscription.
$subscription A subscription object.
$user_id The user the check was run against. Defaults to currently logged in user, but can be specified as any user.

Description: A filter to control whether a given user can can resubscribe to a subscription.

By default, for it to be possible to resubscribe to a subscription, it must:

  • be inactive (expired or cancelled)
  • had at least one payment, to avoid circumventing sign-up fees
  • its parent order must not have already been superseded by a renewal order (to prevent displaying “Renew” links on subscriptions that have already been renewed)
  • the product to which the subscription was purchase must not have been deleted

This filter can be used to change those requirements.

Subscriptions Administration Filters

Filter: 'woocommerce_subscription_settings'

Parameters:
$settings An associative array of settings in the format required by the woocommerce_admin_fields() function.

Description:
This filter can be used to add custom settings to the WooCommerce > Settings > Subscriptions administration screen.

The settings for the Subscriptions tab on the WooCommerce settings page are passed through this filter. The settings returned from this filter are used to both output the settings fields, with woocommerce_admin_fields() and to save the values of these fields, with woocommerce_update_options().

Was this article helpful?
Dislike 0
Views: 13