Subscription Function & Property Reference

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.

This guide introduces some of the functions available for working with subscription data. It is not intended to provide tutorials on how to achieve certain tasks with a subscription, or as a comprehensive reference of all the subscription methods.

If you have not already, you should read the Subscription Developer Overview and the Subscription Data Structures and Storage guides. This guide assumes you are familiar with the Subscriptions plugin architecture and WC_Subscription object.

WC_Subscription Function Overview

↑ Back to top

The functions provided by WC_Subscription class can be split into the following groups:

• methods inherited from WC_Abstract_Order;
• methods inherited from WC_Order;
• methods for managing the subscriptions schedule: next payment date, trial end date etc.
• methods for managing renewal payment method;
• methods for working with related orders; and
• other subscription methods

The first of these are documented in the WC API docs, some of the more important methods in the other groups are documented below.

Subscription Schedule Functions

↑ Back to top

As explained in depth in the Subscription Product vs Subscription Guide, subscriptions have a billing schedule made up of:

• Start date
• Trial end date
• Next payment date
• End date

To calculate, set and get the values of this schedule, subscriptions provides the following methods.

WC_Subscription::get_date()

↑ Back to top

Get the MySQL formatted date for a specific piece of the subscription’s schedule.

Usage

<?php WC_Subscription::get_date( $date_type, $timezone ) ?>

Parameters

$date_type

(string) (required) The type of date to get, can be 'start', 'trial_end', 'next_payment', 'last_payment' or 'end'. Default: None

$timezone

(string) (optional) The timezone to use for the returned date, either ‘gmt’ or ‘site’. Default ‘gmt’.

Return Values

(string)

MySQL formatted date/time string.

WC_Subscription::update_dates()

↑ Back to top

Set the dates on the subscription. Because dates are interdependent on each other, this function requires an array of dates, make sure that all dates are valid based on the other dates in the array or stored on the subscription.

Usage

<?php WC_Subscription::update_dates( $dates, $timezone ) ?>

Parameters

$dates

(array) (required) Array containing dates with keys: 'start', 'trial_end', 'next_payment', 'last_payment' or 'end'. Values are MySQL formatted date/time strings.

$timezone

(string) (optional) The timezone to use for the returned date, either ‘gmt’ or ‘site’. Default ‘gmt’.

Return Values

(null)

No return value.

WC_Subscription::calculate_date()

↑ Back to top

Calculate a given date for the subscription based on its billing interval and period in GMT/UTC timezone.

Usage

<?php WC_Subscription::calculate_date( $date_type ) ?>

Parameters

$date_type

(string) (required) The type of date to get, can be 'trial_end', 'next_payment', 'end_of_prepaid_term' or 'end'.

Return Values

(string)

MySQL formatted date/time string.

WC_Subscription::can_date_be_updated()

↑ Back to top

Check if a given date type can be updated for this subscription.

Usage

<?php WC_Subscription::can_date_be_updated( $date_type ) ?>

Parameters

$date_type

(string) (required) The type of date to get, can be 'start', 'trial_end', 'next_payment', 'last_payment' or 'end'.

Return Values

(bool)

true if the date can be updated, false if it can not.

Subscription Billing Period and Interval Properties

↑ Back to top

In addition to the function provided by WC_Subscription, you can also access other aspects of its billing schedule through special properties.

The recurring billing period for an subscription can be found using the $billing_period property like so: $subscription->get_billing_period() (where $subscription is an instance of a WC_Subscription object).

The same can be with the $billing_interval property: $subscription->get_billing_interval().

Subscription Length and Trial Length

↑ Back to top

To get the trial end date for a subscription, it’s possible to use:

$subscription->get_date( 'trial_end' );

But what about a subscription’s trial length and period?

A WC_Subscription has a $trial_period property similar to the $billing_period property, so you can access a subscriptions trial period via: $subscription->get_trial_period().

A subscription has no $subscription->trial_length property like a subscription product. Instead, you need to use the trial end date on the subscription.

To do this, use the wcs_estimate_periods_between() helper function along with the trial end date and the $subscription->get_trial_period() property to find the trial length value:

$subscription_trial_length = wcs_estimate_periods_between( $subscription->get_time( 'start' ), $subscription->get_time( 'trial_end' ), $subscription->get_trial_period() );

Step 2.2.3: Subscription Length

To get the end date or time for a subscription, it’s possible to call:

$subscription->get_time( 'end' );

If you need to know the number of periods between the start and end of a subscription, you can then use:

$subscription_length = wcs_estimate_periods_between( $subscription->get_time( 'start' ), $subscription->get_time( 'end' ), $subscription->get_billing_period() );

Alternatively, if you need to know the number of payments for a subscription, you can instead use:

if ( WC_Subscriptions_Synchroniser::subscription_contains_synced_product( $subscription->id ) ) {
    $length_from_timestamp = $subscription->get_time( 'next_payment' );
} elseif ( $trial_end_timestamp > 0 ) {
    $length_from_timestamp = $subscription->get_time( 'trial_end' );
} else {
    $length_from_timestamp = $subscription->get_time( 'start' );
}

$subscription_length = wcs_estimate_periods_between( $length_from_timestamp, $subscription->get_time( 'end' ), $subscription->get_billing_period() );

Basing the $length_from_timestamp on the appropriate date ensures the correct number of payments, instead of the total length of the subscription from sign-up to finish.

Renewal Payment Method Functions

↑ Back to top

Subscriptions can use either automatic or manual renewal payments methods. They can also support a variety a different features, depending on the payment gateway used to process payments.

That’s why the WC_Subscription object provides a number of functions for access and updating information about a subscription’s payment method.

WC_Subscription::get_total()

↑ Back to top

The get_total() method is inherited from WC_Abstract_Order::get_total().

In the case of a WC_Subscription, this method returns the recurring total that will be applied to renewal orders by default. From Subscriptions v2.1 onwards, the actual amount charged for renewal payments will be based on the most recent renewal order rather than the WC_Subscription::get_total() value to allow 3rd party code to customise the amounts for each renewal; however, the default amount will still be the same as the value returned by WC_Subscription::get_total().

Usage

<?php WC_Subscription::get_total() ?>

Return Values

(float)

The amount total amount that should be charged on future recurring payments.

WC_Subscription::is_manual()

↑ Back to top

Checks if the subscription requires manual renewal payments.

Usage

<?php WC_Subscription::is_manual() ?>

Return Values

(bool)

true if the subscription requires manual renewal payments, false if it is automatic.

WC_Subscription::set_requires_manual_renewal()

↑ Back to top

Set whether a subscription should require manual renewal payments.

Usage

<?php WC_Subscription::set_requires_manual_renewal( $is_manual ) ?>

Parameters

$is_manual

(bool) (required) Boolean true if the subscription should use manual renewal payments, false if it should use automatic renewals.

Return Values

(null)

No return value.

WC_Subscription::set_payment_method()

↑ Back to top

Store a new payment method, and payment meta data, against a subscription to use for processing future automatic renewal payments.

Usage

<?php WC_Subscription::set_payment_method( $payment_gateway, $payment_meta ) ?>

Parameters

$payment_gateway

(WC_Payment_Gateway) (required) An instance of the WC_Payment_Gateway object representing the new payment method to store against the subscription. Note: although this value has a default value of an empty string, it is still required. The default value is set to comply with the function definition in the parent WC_Abstract_Order class

$payment_meta

(array) (optional) An array of payment meta data, like credit card token or customer token, to use for processing future renewal payments.

Return Values

(null)

No return value.

WC_Subscription::payment_method_supports()

↑ Back to top

Check if the subscription’s payment method supports a certain subscription feature, like recurring date or amount modifications.

If the subscription uses manual renewals as the payment method, it supports all features. Otherwise, the feature will only be supported if the payment gateway set as the payment method on the subscription supports for the feature.

Usage

<?php WC_Subscription::payment_method_supports( $payment_gateway_feature ) ?>

Parameters

$payment_gateway_feature

(string) (required) A subscription gateway feature, like subscription_suspension, subscription_reactivation, subscription_cancellation, subscription_suspension, subscription_date_changes or subscription_amount_changes.

Return Values

(bool)

true if the subscription’s payment method supports the feature or the subscription is using manual renewals, false if it does not.

Related Order Functions

↑ Back to top

A subscription can be purchased in an order, have an order created when it renews, and have an order created to record an upgrade or downgrade.

To access information about these related orders, the WC_Subscription provides a few functions.

WC_Subscription::get_related_orders()

↑ Back to top

Get the orders which have some relationship to the subscription, including renewal orders and the initial order (if any).

Usage

<?php WC_Subscription::get_related_orders( $return_fields, $order_type ) ?>

Parameters

$return_fields

(string) (optional) The columns to return, either 'all' or 'ids'. Default: 'ids'.

$order_type

(array|string) (optional) The type of orders to return, either 'parent', 'renewal', 'resubscribe', 'switch' or 'any'. Multiple order type values can also be provided in an array. Default array( 'parent', 'renewal' ).

Return Values

(array)

An array of either the IDs (int) of the related orders or WC_Order objects.

WC_Subscription::get_payment_count()

↑ Back to top

Get the number of payments completed for a subscription.

Completed payments include all renewal orders and potentially an initial order (if the subscription was created as a result of a purchase from the front end rather than manually by the store manager).

Usage

<?php WC_Subscription::get_payment_count( $payment_type, $order_types ) ?>

Parameters

$payment_type

(string) (optional) Type of count ('completed'|'refunded'|'net'). Default completed.

$order_types

(array|string) (optional) Type of order relation(s) to count.'parent' and/or 'renewal'. Multiple order type values can also be provided in an array. Default array( 'parent', 'renewal' ).

Return Values

(int)

The total number of related orders marked with a status representing a 'completed'|'refunded'|'net' payment depending on the first parameter.

WC_Subscription::get_failed_payment_count()

↑ Back to top

Get the number of failed payments completed for a subscription, based on the number of orders with the wc-failed status.

Usage

<?php WC_Subscription::get_failed_payment_count() ?>

Return Values

(float)

The total number of related orders marked with a failed status.

Other Functions

↑ Back to top

WC_Subscription::is_one_payment()

↑ Back to top

Determine if the subscription is for one payment only, for example $100 for 1 year instead of $100 per year.

Usage

<?php WC_Subscription::is_one_payment() ?>

Return Values

(bool)

true if the subscription requires only one payment, false if it does not.

WC_Subscription::get_sign_up_fee()

↑ Back to top

Get the total sign-up fee amount charged at the outset of the subscription, if any.

Usage

<?php WC_Subscription::get_sign_up_fee() ?>

Return Values

(float)

The total sign-up fee amount charged at the time of sign-up for the line items on the subscription.

WC_Subscription::is_manual()

↑ Back to top

Check if the subscription requires manual renewal payments.

Usage

<?php WC_Subscription::is_manual() ?>

Return Values

(bool)

Boolean flag indicating whether the subscription requires manual renewal or not, true if it does require manual renewal false if it does not.