Recurring Payments - Developer: EDD_Recurring_Subscriber

Recurring Payments comes with a new EDD class for managing subscribers. The EDD_Recurring_Subscriber class allows you to allows you to interact with subscription customers and the subscriptions on their accounts.

Creating Objects

EDD_Recurring_Subscriber should be called with an identifier for an EDD customer or WordPress user on the site. This could be an email address or a WordPress user ID or an EDD Customer ID. Here are some examples:

$subscriber = new EDD_Recurring_Subscriber( 'user@example.com' );

If you pass an integer it will look for an EDD customer with that customer_id.

$subscriber = new EDD_Recurring_Subscriber( 3 );

If you pass an integer with a second argument of true then it will look for a WordPress user with that user_id.

$subscriber = new EDD_Recurring_Subscriber( 3, true );

Any of the above will return an object that looks like this:

EDD_Recurring_Subscriber Object
(
    [subs_db:EDD_Recurring_Subscriber:private] => EDD_Subscriptions_DB Object
        (
            [table_name] => wp_edd_subscriptions
            [version] => 1.0
            [primary_key] => id
        )

    [id] => 4
    [purchase_count] => 1
    [purchase_value] => 10.000000
    [email] => user@example.com
    [name] => Bob Smith
    [date_created] => 2016-03-17 12:17:37
    [payment_ids] => 95
    [user_id] => 4
    [notes] => Array
        (
        )

    [db:protected] => EDD_DB_Customers Object
        (
            [table_name] => wp_edd_customers
            [version] => 1.0
            [primary_key] => id
        )

)

Available Methods

Each of the methods below assumes that your have an object associated with a specific customer, and will refer to that customer as "the customer".

Conditional Methods

$subscriber->has_active_subscription()

This method checks to see if the customer has a subscription that is either active or cancelled, but not expired.  

Returns boolean, filtered this way:

apply_filters( 'edd_recurring_has_active_subscription', $ret, $this );
$subscriber->has_product_subscription( $product_id = 0 )

This method checks to see if the customer has any kind of subscription on a specific EDD product ID.

Accepts an integer that is an EDD product ID.

Returns boolean filtered this way:

return apply_filters( 'edd_recurring_has_product_subscription', $ret, $product_id, $this );
$subscriber->has_active_product_subscription( $product_id = 0 )

This method checks to see if the customer has active subscription on a specific EDD product ID.

Accepts an integer that is an EDD product ID.

Returns boolean filtered this way:

return apply_filters( 'edd_recurring_has_active_product_subscription', $ret, $product_id, $this );

Getting Subscriber Information

$subscriber->get_subscription_by_profile_id( $profile_id = '' )

This method accepts a payment profile_id and returns an  EDD_Subscription object with all of the information about that subscription.

Accepts a payment gateway profile ID. You can find profile IDs for specific subscriptions on the details page for a specific subscription under Downloads → Subscriptions.

Returns an EDD_Subscription object.  An example may be found in the EDD_Subscription docs.

$subscriber->get_subscription( $subscription_id = 0 )

This method accepts a subscription returns an  EDD_Subscription object with all of the information about that subscription, similar to $subscriber->get_subscription_by_profile_id()

$subscriber->get_subscriptions( $product_id = 0, $statuses = array() )

This method will get all subscriptions for the customer that meet the input requirements. It accepts two arguments, the first being a product_id and the second being an array of statuses. Here are some examples:

// gets all subscriptions for the customer
$subscriber->get_subscriptions();
// gets all subscriptions for the customer for product ID 85
$subscriber->get_subscriptions( 85 );
// gets all active subscriptions for the customer for product ID 85
$subscriber->get_subscriptions( 85, array( 'active' ) );
// gets all active subscriptions for the customer, regardless of product
$subscriber->get_subscriptions( '', array( 'active' ) );
// gets all active and cancelled subscriptions for the customer, regardless of product
$subscriber->get_subscriptions( '', array( 'active', cancelled' ) );
$subscriber->get_new_expiration( $download_id = 0, $price_id = null )

This method determines the expiration date of a subscription one period beyond the current expiration date. For example, if the expiration date were 2017-01-01 23:59:59 and the period was one month, then this method would return 2017-02-01 23:59:59.

Accepts an integer for download_id as the first argument, required.

Accepts an integer for price_id in the case of variable prices, optional

Returns a date formatted like  Y-m-d H:i:s.

$subscriber->get_recurring_customer_ids()

This method returns an array containing all of the the customer IDs created by payments gateways for the customer. And example would be 

Array
(
    [stripe] => cus_85YmUU1QuH5yxY
)

Output is filtered this way:

apply_filters( 'edd_recurring_customer_ids', $ids, $this );
$subscriber->get_recurring_customer_id( $gateway = false )

This method accepts a gateway name and returns a string containing the customer ID associated with the customer and that gateway.

Accepts a string containing a gateway name like stripe.

Returns a string containing a customer ID like cus_85YmUU1QuH5yxY

Output is filtered this way:

apply_filters( 'edd_recurring_get_customer_id', $customer_id, $this );

Setting Subscriber Options

$subscriber->set_as_subscriber()

This method takes the customer and creates an EDD Customer with their information.

$subscriber->set_recurring_customer_id( $recurring_id = '', $gateway = false )

This method accepts a payment gateway recurring ID and a payment gateway name and associated them with the customer.

Accepts a string containing a payment gateway recurring ID like cus_85YmUU1QuH5yxY. Required.

Accepts a string containing a gateway name like stripe. Required

Managing Subscriptions

$subscriber->add_subscription( $args = array() )

This method adds a subscription to an EDD customer.  If there is no customer_id included it creates one from the WordPress customer.

This method uses EDD_Subscription::create(), and therefore has all of the same requirements. Full documentation for EDD_Subscription::create().

Accepts an array of data required by EDD_Subscription::create().

Returns a subscription object.

$subscriber->add_payment( $args = array() )

This method adds a payment to a specific subscription for the customer. It accepts an array like this:

$args = array(
    'subscription_id' => 0,
    'amount'          => '0.00', 
    'transaction_id'  => '',  
);

The subscription_id array key must not be empty, and should be an integer.

This method uses EDD_Subscription::add_payment() and therefore has all of the same requirements.  Full documentation for EDD_Subscription::add_payment().

Returns true.