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.
EDD_Recurring_Customer
In Recurring Payments 2.4, we have introduced two new classes for interacting with subscriptions and subscribers:
- EDD_Subscription
- EDD_Recurring_Subscriber
These classes replace the now-deprecated EDD_Recurring_Customer class. All methods within EDD_Recurring_Customer are also now deprecated. These include:
- set_as_subscriber()
- set_customer_id()
- get_customer_id()
- get_user_id_by_customer_id()
- set_customer_payment_id()
- get_customer_payment_id()
- set_customer_status()
- get_customer_status()
- is_customer_active()
- set_customer_expiration()
- get_customer_expiration()
- is_customer_expired()
- calc_user_expiration()
- get_user_id_from_customer_id()
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.
record_subscription_payment()
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.
payment_exists()
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.
Payment statuses
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.
User roles
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.
_edd_recurring_id
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.
_edd_recurring_user_parent_payment_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.
_edd_recurring_status
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.
_edd_recurring_exp
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.
Shortcodes
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:
- [edd_recurring_update]
- [edd_recurring_cancel]
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.
Hi Pippin. I was using EDD_Recurring_Customer to restrict the content of a shortcode to cancelled members, like so:
function mark_restrict_cancelled_members( $has_access ) {
$current_user = wp_get_current_user();
if ( EDD_Recurring_Customer::get_customer_status( $current_user->ID ) == ‘expired’ ) {
$has_access = false;
}
return $has_access;
}
add_filter( ‘edd_cr_user_can_access’, ‘mark_restrict_cancelled_members’ );
Is this going to work in 2.4?
Thanks!
Yes and no.
As long as a customer only has a single subscription, yes, it will still work.
If a customer has multiple subscriptions, it may not return the expected results since one subscription could be active and one expired.
Here’s an example of how I would recommend checking the access in the future:
That will return true if the customer has an active subscription for the specified post ID.
Great, thanks Pippin! And how should I do it for a shortcode restriction? So the client CAN see the post but not the content inside the edd_restrict shortcode?
If you’re on the latest version of the Content Restriction add-on, you can use the “edd_cr_user_can_access” filter. It takes 3 parameters the 3rd is the post ID that the content is restricted too.
Yeah, but the post is not restricted at all. I only use shortcodes to restrict videos, part of the post content.
Can you show me the exact shortcode configuration?
Sure, here you have the snippet you gave me (well, your team):
=====
function mark_restrict_cancelled_members( $has_access ) {
$current_user = wp_get_current_user();
if ( EDD_Recurring_Customer::get_customer_status( $current_user->ID ) == ‘expired’ ) {
$has_access = false;
}
return $has_access;
}
add_filter( ‘edd_cr_user_can_access’, ‘mark_restrict_cancelled_members’ );
=====
And the shortcode:
[edd_restrict id=”356″]
Here the video
[/edd_restrict]
Do you only have one subscription and just need to see if the customer has an active subscription? Any other nuances?
Thanks Pippin!
Yeah, now it’s exactly that. Only one subscription, and I have to know if it’s active. If it is, he can see the video inside the [edd_restrict id=”356″] shortcode. If the subscription expired or is cancelled, he shouldn’t be able to see the video. The post is always public.
Maybe in the future I’ll add more subscriptions, but now I only have one. A monthly fee.
Perfect. That’s easy then:
$subscriber = new EDD_Recurring_Subscriber( get_current_user_id(), true );
$has_access = $subscriber->has_active_subscription();
That will return true if the user has any active subscription.
We’ve decided to go ahead and add improved support for the [edd_restrict] short code.
In Recurring Payments 2.4 you will be able to do `[edd_restrict id=”any” subscription=”true”]` to require the customer have an active subscription.
Oh, really? That would be awesome! Thanks! That improvement will help so much! 😀 Thanks Pippin!! 😀
Great! Thanks Pippin! I really appreciate! 🙂
Have a nice weekend!
Hi Pipin can you tell me how can I check if a user has purchased any recurrent products of mine because I wanna put some if clause in my customer dashboard and only if the user has purchased any recurrent stuffs then only I wanna show up `[edd_subscriptions]` otherwise it doesnt make any sense to show this section to non subscribers.
Any help will be highly appreciated.
You can use this:
Really nice job guys.
Quick question – Can you now set the number of times a payment recurs with Stripe? (Before Stripe didn’t allow this option to be set).
And if so is 1 a valid entry for when you have e.g. Yearly subscriptions and want to utilize the “Only Active Subscribers” access rules to pages and content?
OK so installed now and did some tests – Answers for other people.
It no longer tells me that Stripe doesn’t allow values other than 0, so that’s good. However you cannot use 1 if you have Paypal Standard as 2 is the minimum (I wish that Software Licensing got the same checkbox as Recurring Payments for “Limit File Downloads”, but for active licenses only, and same behavior with content restriction).
You can use PayPal express.
Oh, I didn’t realize, the Paypal pro/express plugin says it’s not compatible with Recurring Payments on the plugin info page, but it is now? If so I’m off to buy it…
Whoops! We added support for it in 2.4 and forgot to update the product page. I’ve updated it.
Yes you can 🙂
Oh and another quick question – Does this now set the Software Licensing “License Key Duration” values? Or should I keep my snippet active for this?
That still requires the snippet.
Howdy, so I updated last night through the one-click option on the Plugins page. I just read that was supposed to be disabled. Would this have an affect at all on my upgrade? It went through one-database upgrade routine (looked like for each subscriber).
Were there any other upgrades like that which needed to occur?
Thanks, Justin
We re-enabled automatic updates yesterday, so that’s normal.
It’s just that one upgrade routine. If you were using the recurring shortcodes,you will want to update it to use [edd_subscriptions]
Thanks man, yeah I swapped those out where I had the cancellation shortcode before. Glad to hear I didn’t mess anything up. I posted elsewhere this morning, I’m sure you’ll see it in a moment, about something I couldn’t find (the new recurring-centric emails) so I got worried maybe I didn’t update all the way.
Hi Pippin! I’m wondering how to replace the shortcode [edd_recurring_cancel] with [edd_subscriptions]? I tried and it actually displayed a whole tabke. Is it possible to display only a cancellation button the way [edd_recurring_cancel] did?
I think that is the intended result. If you aren’t a subscriber to your own site, you might not see the cancel button in that table.
Thank you for your reply, Justin! I was hoping to have just a button and not the table but I’ve found a compromise to work with the new shortcode. So far so good!
At this time there is not a way to have a single button since customers could have multiple subscriptions.
Also, how to create NOT ONE TIME use discount code for subscription product? I can not find it anywhere.
If you create a coupon code that deducts from the price of a subscription, the subscription stays locked in at that price. So whatever it says when it gets to Paypal, is what it will always be. So for example, if the price is $99 yearly, and you give someone $20 off, when they checkout Paypal will say the terms are “$79 billed once yearly”. And thats not going to change, regardless of what your site does in the future (which makes sense, because otherwise a subscriber might agree to one price and be charged a different one later).
Nice thing though, is you can tell customers, “hey, lock in your subscription now at x amount, and you’ll always have that awesome discount”
There is a setting in Downloads > Settings > Extensions > Recurring Payments called “One Time Discounts”.
When that setting is enabled, discount codes will only affect the first payment in the subscription.
Oh wow. Didn’t know that! Thanks.
It was added in 2.4 🙂