Subscription Function & Property Reference

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

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

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()

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()

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()

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()

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

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

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

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()

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()

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::update_manual()

Set whether a subscription should require manual renewal payments.

Usage

<?php WC_Subscription::update_manual( $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

(bool)

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

WC_Subscription::set_payment_method()

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()

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

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()

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_completed_payment_count()

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_completed_payment_count() ?>

Return Values

(float)

The total number of related orders marked with a status representing a completed payment.

WC_Subscription::get_failed_payment_count()

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

WC_Subscription::is_one_payment()

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()

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_one_payment()

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::is_manual()

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.

WC_Subscription::update_manual()

Set whether the subscription requires manual renewal payments.

Usage

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

Parameters

$is_manual

(bool) (optional) Whether the subscription requires manual renewal or not, true to require manual renewal false to not require it. Default: true.

Return Values

(bool)

Flag indicating whether the subscription requires manual renewal or not.