Recurring Payments 2.4 is very, very close to being released. A few days ago we showed a preview of some of the improvements that have been added to this version. Due to the scale of this update, there are several significant changes that we have made that could result in adverse effects if not properly accounted for. To help developers prepare for the update, we will cover each of those breaking changes here.
Deprecated classes and methods
With the drastic changes and improvements being introduced with Recurring Payments 2.4, it has been necessary to deprecate some classes and methods.
In Recurring Payments 2.4, we have introduced two new classes for interacting with subscriptions and subscribers:
These classes replace the now-deprecated EDD_Recurring_Customer class. All methods within EDD_Recurring_Customer are also now deprecated. These include:
If used, these methods will now throw a deprecated notice if WP_DEBUG is enabled and the current user is a site administrator.
All of these methods have a replacement of some form inside of the EDD_Recurring_Subscriber class. I say “in some form” because it is not a direct transfer from one method to the other.
Prior to 2.4, Recurring Payments stored subscriber information (status, expiration date, profile ID, etc) inside of the wp_usermeta table and customers were limited to a single subscription. Now, however, with Recurring Payments 2.4, subscription data is stored in a custom table and customers can have multiple subscriptions. All of the methods in EDD_Recurring_Customer (the deprecated class), assume a single subscription. For this reason, they can no longer be reliably used.
We have updated each method within EDD_Recurring_Customer to still return a value. When used, the methods will retrieve the information from the first subscription found for the customer record. If the customer has only a single subscription on their account, the returned results should be as expected. If, however, there are multiple subscriptions on the account, the results could be unexpected.
It is strongly recommended that you cease using the EDD_Recurring_Customer immediately after updating to 2.4 to ensure proper behavior.
Inside of the main EDD_Recurring class is a method called record_subscription_payment(). This method was previously used for inserting a renewal payment into the database anytime a renewal was processed. This method has been deprecated and should no longer be used.
If you need to record renewal payments manually, please use the add_payment() method within the EDD_Subscription class.
The payment_exists() method inside of EDD_Recurring has been deprecated. There is no replacement for it as it’s entirely unneeded as of Recurring Payments 2.4.
In Recurring Payments 2.4 there are some changes to payment statuses.
Cancelled status is no more
Prior to 2.4, when a subscription was cancelled, the payment record that originated the subscription was given a status of cancelled. In 2.4, this is no longer the case. What happens, instead, is the payment record remains as complete and the subscription record is given a status of cancelled. This makes reporting more accurate and more logical.
Subscription Payment renamed
In versions before 2.4, subscription renewal payments were given a status of Subscription Payment. The status itself is unchanged, but we have changed the label to just Renewal.
Removed admin screens
The most apparent changes in Recurring Payments 2.4 are within the administration area. As should be apparent from the preview post, the administration options in Recurring Payments 2.4 have been completely revamped. Along with the new interface options, we have also removed some that were available in previous versions.
Downloads > Reports > Subscribers
This screen is no longer available. To view a list of subscribers, go to Downloads > Subscriptions.
Subscription status on Downloads > Customers
There used to be an expiration date and subscription status columns in the Downloads > Customers table. These have been removed as customers are no longer limited to a single subscription. The subscription details for a customer can be viewed on the customer’s individual details screen.
In all versions before Recurring Payments 2.4, subscribers were given a user role of EDD Subscriber. This role could be used to control access and viewing capabilities of subscribers.
In 2.4, we recommend not using this user role as a way to determine if a user account has a subscriber. While the user role is still present and will continue to be set on subscriber accounts, it is not an accurate representation of a customer’s subscription (or subscriptions) status.
Please use the methods available in the EDD_Recurring_Subscriber class if you need to check a customer’s access programmatically.
User meta values
Before version 2.4, we stored several pieces of information related to a customer’s subscription in the wp_usermeta table. As mentioned above, we now use a custom database table for storing subscription data. With the move to the custom table, several pieces of usermeta have been discontinued and/or modified and should no longer be relied upon.
The _edd_recurring_id meta key was previously used to store the ID of the customer assigned from the merchant processor. For example, for customers that purchased a subscription through Stripe, this would be set as something like cus_7qInEioCfgPA6b. This meta key is still used and is used for the same purpose, but as customers can now have more than just one subscription, it was necessary to change the meta_value for this key from a single string to an array. It will now contain an array of key value pairs where the key is the ID of the payment gateway and the value is the customer’s recurring ID.
The _edd_recurring_user_parent_payment_id meta key was used to store the ID number of the payment record that originated the customer’s subscription. This meta key is no longer used in any way. Customers can now have multiple subscriptions and if you need to retrieve a list of the payment IDs, they may be accessed through the EDD_Recurring_Subscriber class.
The _edd_recurring_status meta key was used to store the status of the customer’s subscription. As subscriptions are now stored in a custom database table, this meta key is no longer used nor updated. If you are checking against or setting this value, please use the EDD_Subscription or EDD_Recurring_Subscriber classes instead.
The _edd_recurring_exp meta key was used to store the expiration date of the customer’s subscription. As subscriptions are now stored in a custom database table, this meta key is no longer used nor updated. If you are checking against or setting this value, please use the EDD_Subscription or EDD_Recurring_Subscriber classes instead.
In Recurring Payments 2.4, we are introducing a new shortcode, [edd_subscriptions], that provides customers with complete details and controls for all subscriptions on their account.
Due to the nuances of adding support for multiple subscriptions, we have decided that the following two shortcodes are no longer relevant nor can they be adequately used:
These two shortcodes have been discontinued in Recurring Payments 2.4. Technically the shortcodes are still registered with WordPress, but they will not display any content; they simply return an empty string.
Please update your sites to use [edd_subscriptions] instead.
Updating to 2.4
As should be apparent, Recurring Payments 2.4 is a large release. It is so large, in fact, that we considered for quite a long time the possibility of launching it as a brand new plugin. While we did not break it off into a new plugin, we have decided that it is in the best interest of all customers that we not permit automatic updates from 2.3.x to 2.4.
Installing version 2.4 for sites that have been running 2.3.x, will require a manual update. One-click updates from within WordPress have been disabled between 2.3.x and 2.4. We decided that this was the best option so as to not adversely affect the front-end display of websites without the site owner being immediately aware of the changes about to be applied.
We have built a complete migration routine that will allow site owners to migrate their 2.3.x data to the new 2.4 data schema. This upgrade routine has been tested successfully numerous times on sites with more than 20,000 subscription records.
Once 2.4 is released, there will be a complete walkthrough guide to assist site owners with updating from earlier versions to 2.4.
If you have any questions, comments, or concerns about the upcoming release, please let us know as soon as possible.