Recurring Payments - Developer: EDD_Subscription
Table of Contents
Recurring Payments comes with a new EDD class for managing subscriptions. The EDD_Subscription class allows a developer to work with subscriptions programatically. 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 fine:
$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 → Payments.
$subscription->get_child_payments()
The method returns an array of WordPress Post objects where each object is a child payment. The objects will look something like this:
Array
(
[0] => WP_Post Object
(
[ID] => 105
[post_author] => 2
[post_date] => 2016-03-21 15:20:48
[post_date_gmt] => 2016-03-21 15:20:48
[post_content] =>
[post_title] => user@example.com
[post_excerpt] =>
[post_status] => edd_subscription
[comment_status] => closed
[ping_status] => closed
[post_password] =>
[post_name] => userexample-com-2
[to_ping] =>
[pinged] =>
[post_modified] => 2016-03-21 15:20:48
[post_modified_gmt] => 2016-03-21 15:20:48
[post_content_filtered] =>
[post_parent] => 87
[guid] => http://edd.dev/?post_type=edd_payment&p=105
[menu_order] => 0
[post_type] => edd_payment
[post_mime_type] =>
[comment_count] => 1
[filter] => raw
)
}
$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()
$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
$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'.