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 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.4.1.3
            [primary_key] => id
        )

    [id] => 11111
    [purchase_count] => 19
    [purchase_value] => 2173.3
    [email] => user@example.com
    [emails] => Array
        (
            [0] => user@example.com
        )

    [name] => Bob Smith
    [date_created] => 2015-06-15 16:38:08
    [payment_ids] => 
    [user_id] => 1nan1
    [notes:protected] => 
    [raw_notes:EDD_Customer:private] => 
    [db:protected] => EDD_DB_Customers Object
        (
            [meta_type] => customer
            [date_key] => date_created
            [cache_group] => customers
            [table_name] => wp_edd_customers
            [version] => 1.0
            [primary_key] => id
        )
)

Available Methods

Each of the methods below assumes that you 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 canceled, 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 an 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 customer IDs created by payments gateways for the customer. An 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.

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 record 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.