# Recurring Payments - Developer: EDD_Subscription

##### Table of Contents

- [Properties](#properties)
- [Method](#methods)
- [Usage](#usage)
- [Object Modification](#modification)
- [Operational Methods](#operational)
- [Getting Subscription Information](#getters)
- [Subscription Conditionals](#conditionals)
- [Status Methods](#status)



[Recurring Payments](https://easydigitaldownloads.com/downloads/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. ![](https://easydigitaldownloads.com/wp-content/uploads/2022/07/6184cdf1d52d8.png)

You can find the profile ID listed when viewing a subscription. ![](https://easydigitaldownloads.com/wp-content/uploads/2022/07/6184cdf22022e.png)

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:

```
Array
(
    [0] => EDD_Payment Object
        (
            [ID] => 1111111
            [_ID:protected] => 1111111
            [new:protected] =>
            [number:protected] => 1111111
            [mode:protected] => live
            [key:protected] => 8d6f842jkf66cb6312117b9ad417dc6be
            [total:protected] => 57.4
            [subtotal:protected] => 57.4
            [tax:protected] => 0
            [discounted_amount:protected] => 0
            [tax_rate:protected] =>
            [fees:protected] => Array
                (
                )

            [fees_total:protected] => 0
            [discounts:protected] => samplediscount
            [date:protected] => 2018-05-17 06:40:29
            [completed_date:protected] =>
            [status:protected] => edd_subscription
            [post_status:protected] => edd_subscription
            [old_status:protected] =>
            [status_nicename:protected] => Renewal
            [customer_id:protected] => 111111
            [user_id:protected] => 1nan1
            [first_name:protected] => Bob Smith
            [last_name:protected] => Smith
            [email:protected] => user@example.com
            [user_info:EDD_Payment:private] => Array
                (
                    [first_name] => Bob Smith
                    [last_name] => Smith
                    [discount] => samplediscount
                    [id] => 1nan1
                    [email] => user@example.com
                    [address] => Array
                        (
                            [line1] =>
                            [line2] =>
                            [city] =>
                            [country] =>
                            [state] =>
                            [zip] =>
                            [vat] =>
                            [notes] =>
                        )

                )

            [payment_meta:EDD_Payment:private] => Array
                (
                    [key] => 8d6f842jkf66cb6312117b9ad417dc6be
                    [email] => user@example.com
                    [date] => 2018-05-17 06:40:29
                    [user_info] => Array
                        (
                            [first_name] => Bob Smith
                            [discount] => samplediscount
                            [id] => 1nan1
                            [email] => user@example.com
                            [address] => Array
                                (
                                    [line1] =>
                                    [line2] =>
                                    [city] =>
                                    [country] =>
                                    [state] =>
                                    [zip] =>
                                    [vat] =>
                                    [notes] =>
                                )

                        )

                    [[downloads]] => Array
                        (
                            [0] => Array
                                (
                                    [id] => 1234
                                    [quantity] => 1
                                    [options] => Array
                                        (
                                            [quantity] => 1
                                            [price_id] => 0
                                        )

                                )

                        )

                    [cart_details] => Array
                        (
                            [0] => Array
                                (
                                    [name] => Sample Product
                                    [id] => 1234
                                    [item_number] => Array
                                        (
                                            [id] => 1234
                                            [quantity] => 1
                                            [options] => Array
                                                (
                                                    [quantity] => 1
                                                    [price_id] => 0
                                                )

                                        )

                                    [item_price] => 57.4
                                    [quantity] => 1
                                    [discount] => 0
                                    [subtotal] => 57.4
                                    [tax] => 0
                                    [fees] => Array
                                        (
                                        )

                                    [price] => 57.4
                                )

                        )

                    [fees] => Array
                        (
                        )

                    [currency] => USD
                )

            [address:protected] => Array
                (
                    [line1] =>
                    [line2] =>
                    [city] =>
                    [country] =>
                    [state] =>
                    [zip] =>
                    [vat] =>
                    [notes] =>
                )

            [transaction_id:protected] => 7M999999999999999
            [[downloads:protected]] => Array
                (
                    [0] => Array
                        (
                            [id] => 1234
                            [quantity] => 1
                            [options] => Array
                                (
                                    [quantity] => 1
                                    [price_id] => 0
                                )

                        )

                )

            [ip:protected] => 192.168.1.1
            [gateway:protected] => paypalexpress
            [currency:protected] => USD
            [cart_details:protected] => Array
                (
                    [0] => Array
                        (
                            [name] => Sample Product
                            [id] => 1234
                            [item_number] => Array
                                (
                                    [id] => 1234
                                    [quantity] => 1
                                    [options] => Array
                                        (
                                            [quantity] => 1
                                            [price_id] => 0
                                        )

                                )

                            [item_price] => 57.4
                            [quantity] => 1
                            [discount] => 0
                            [subtotal] => 57.4
                            [tax] => 0
                            [fees] => Array
                                (
                                )

                            [price] => 57.4
                        )

                )

            [has_unlimited_downloads:protected] =>
            [pending:EDD_Payment:private] => Array
                (
                )

            [parent_payment:protected] => 830936
        )
)
```

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