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