Recurring Payments - Developer: EDD_Subscription

Properties
Method
Usage
Object Modification
Operational Methods
Getting Subscription Information
Subscription Conditionals
Status Methods

Recurring Payments comes with a new EDD class for managing subscriptions. The EDD_Subscription class allows a developer to work with subscriptions programmatically. This document will list the properties, methods, and suggested functionality of EDD_Subscription.

Properties

$id = 0;
$customer_id = 0;
$period = '';
$initial_amount = '';
$recurring_amount = '';
$bill_times = 0;
$parent_payment_id = 0;
$product_id = 0;
$created = '0000-00-00 00:00:00';
$expiration = '0000-00-00 00:00:00';
$status = 'pending';
$profile_id = '';
$gateway = '';
$customer;

Methods

create( $data = array() )
update( $args = array() )
delete()
get_original_payment_id()
get_child_payments()
get_total_payments()
get_lifetime_value()
add_payment( $args = array() )
renew()
complete()
expire()
failing()
cancel()
can_cancel()
get_cancel_url()
can_update()
get_update_url()
is_active()
is_expired()
get_expiration()
get_expiration_time()
get_status()
get_status_label()
payment_exists( $txn_id = '' )

Usage

Basic Instantiation

An "empty" EDD_Subscription object may be created with this code:

$subscription = new EDD_Subscription();

This will return an object with this structure:

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

    [id] => 0
    [customer_id] => 0
    [period] => 
    [initial_amount] => 
    [recurring_amount] => 
    [bill_times] => 0
    [parent_payment_id] => 0
    [product_id] => 0
    [created] => 0000-00-00 00:00:00
    [expiration] => 0000-00-00 00:00:00
    [status] => pending
    [profile_id] => 
    [gateway] => 
    [customer] => 
)

Instantiating An Existing Subscription

The EDD_Subscription constructor accepts 2 arguments. The first is either an integer representing a subscription ID, or if the second argument is true then the first may be a subscription profile_id.

You can find a subscription ID in the URL while viewing a subscription.

You can find the profile ID listed when viewing a subscription.

These two lines of code will return the same output, because they refer to the same subscription:

$subscription = new EDD_Subscription( 3 );

$subscription = new EDD_Subscription( 'sub_85YmWtzABSAWN7', true );

The above lines of code would each return an object like this:

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

    [id] => 1
    [customer_id] => 3
    [period] => month
    [initial_amount] => 50.00
    [recurring_amount] => 50.00
    [bill_times] => 0
    [parent_payment_id] => 87
    [product_id] => 85
    [created] => 2016-03-15 15:36:30
    [expiration] => 2016-04-15 23:59:59
    [status] => pending
    [profile_id] => paypal-363e3cc178dab152bb59b958024bce75
    [gateway] => paypal
    [customer] => EDD_Customer Object
        (
            [id] => 3
            [purchase_count] => 3
            [purchase_value] => 110.000000
            [email] => user@example.com
            [name] => Bob Smith
            [date_created] => 2016-03-08 15:01:02
            [payment_ids] => 54,63,87,88,91
            [user_id] => 2
            [notes] => Array
                (
                    [0] => March 16, 2016 14:37:22 - Subscription #3 cancelled admin
                )

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

        )

)

Object Modification

Using the included methods, almost anything may be done with a subscription.

Unless otherwise stated, every method example given will use this instantiation model:

$subscription = new EDD_Subscription();

Operational Methods

EDD_Subscription includes methods for creating, deleting, updating, and renewing subscriptions, as well as adding payments.

$subscription->create()

In order to properly create a subscription you need to pass in some information. These items are required:

$data = array(
    'customer_id'       => 0, // an integer, should be a valid customer_id
    'period'            => '', // accepts 'day', 'week', 'month', or 'year'; how often the subscription renews
    'initial_amount'    => '', // accepts a float
    'recurring_amount'  => '', // accepts a float
    'bill_times'        => 0, // accepts an integer; the number of times billing should happen, 0 means indefinite
    'parent_payment_id' => 0, // accepts an integer; the payment id returned by the initial payment
    'product_id'        => 0, // accepts an integer; the id of the product
    'created'           => '', // accepts a date string; formatted like 0000-00-00 00:00:00
    'expiration'        => '', // accepts a date string; formatted like 0000-00-00 00:00:00
    'status'            => '', // accepts 'Pending', 'Active', 'Cancelled', 'Expired', 'Failing', 'Completed'
    'profile_id'        => '', // accepts a string returned by the payment gateway as their subscription ID
);

Then you can call the create() method with that information.

$subscription->create( $data );

The create() method returns an object with the same data you would get by querying a specific subscription ID.

$subscription->update()

Updating a subscription uses the update() method any subset of the array options used for the create() method. The update() method also requires a subscription ID. Something like this would work:

$data = array(
    'expiration' => '2019-07-17 23:59:59',
);
$subscription->update( $data );

$subscription->delete()

The delete() method accepts a subscription ID and permanently removes the subscription from the EDD store. Note that this does not affect subscriptions registered on Payment Gateways. Those should be handled individually.

$subscription->renew()

This method renews a subscription, extending it by one period beyond the current expiration date.

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

This method allows you to make a payment. it accepts an array and requires these three array elements:

amount: the amount of money being paid
transaction_id : the transaction ID of the subscription from the payment gateway. Example: 'ch_17q04L4NqFpaKRwY8ucZjW3t'
gateway : the payment gateway used for the subscription. Example: 'stripe'

Upon success add_payment() returns true.

Getting Subscription Information

EDD_Subscription provides a number of methods for getting information about a subscription.

$subscription->get_original_payment_id()

This method returns an integer that is the ID of the original payment. In the User Interface this Payment can be found under Downloads → Payment History.

$subscription->get_child_payments()

The method returns an array of EDD_Payment objects where each object is a child payment. The objects will look something like this:

$subscription->get_total_payments()

This method returns an integer that is a count of the total number of payments made, including the initial payments plus all child payments.

$subscription->get_lifetime_value()

This method returns a float that is the monetary total of all payments ever made.

$subscription->get_cancel_url()

This method will return a URL for cancelling a subscription that gets processed by the gateway through which the subscription was purchased.

$subscription->get_update_url()

This method will return a URL for updating a subscription that gets processed by the gateway through which the subscription was purchased.

$subscription->get_expiration()

Returns the date and time that the subscription will expire in this format:

2016-04-15 23:59:59

$subscription->get_expiration_time()

This method returns an integer that is a Unix timestamp of the expiration.

$subscription->get_status()

This method returns the current status of a subscription in format useful for code. Options are 'pending', 'active', 'cancelled', 'expired', 'failing', 'completed'.

$subscription->get_status_label()

This method returns the current status of a subscription in format useful for presentation. Options are 'Pending', 'Active', 'Cancelled', 'Expired', 'Failing', 'Completed'.

Subscription Conditionals

EDD_Subscription offers a number of conditional methods.

$subscription->can_cancel()

This method returns boolean and is filtered by payment gateways in order to return true on subscriptions that can be cancelled with a profile ID through the merchant processor.

$subscription->can_update()

This method returns boolean and is filtered by payment gateways in order to return true if the subscription can have its payment method updated. It is only for determining if a payment method may be updated.

$subscription->is_active()

This method returns boolean, and is true if the subscription is not expired and the status is either 'active' or 'cancelled'.

$subscription->is_expired()

This method returns boolean, and is true if the subscription is expired.

$subscription->payment_exists( $txn_id = '' )

This method accepts a transaction ID that has been created by a payment gateway. Here's an example of a subscription transaction ID from Stripe:

ch_17q04L4NqFpaKRwY8ucZjW3t

This method returns boolean, true if it finds a transaction with the provided ID.

Status Methods

EDD_Subscription includes several methods for changing the status of a subscription.

$subscription->complete()

This method changes the status of a subscription to 'complete'.

$subscription->expire()

This method changes the status of a subscription to 'expired'.

$subscription->failing()

This method changes the status of a subscription to 'failing'.

$subscription->cancel()

This method changes the status of a subscription to 'cancelled'.