Recurring Payments – Easy Digital Downloads Documentation

Recurring Payments – Defining a Specific Stripe API Version

Chris Klosowski — Mon, 24 Jan 2022 19:56:00 +0000

As of Recurring Payments 2.7.18, you have the ability to define the version of the Stripe API you would like to use. This can be useful when you do not have the ability to roll back or change your API version from within your Stripe Dashboard.

Defining your Stripe API Version

In your wp-config.php file, find this line:

/* That's all, stop editing! Happy blogging. */

Place the following right above it:

define( 'EDD_STRIPE_API_VERSION', '2020-03-02' );

You can see a complete list of API Versions over at Stripe: https://stripe.com/docs/upgrades#api-changelog

Please Note: If possible, it is always best to define your API version from within your Stripe Dashboard. This method of defining it is for edge cases where it is not possible to use a specific version of the API via the provided methods within Stripe. You can see full documentation on the Stripe API versions within their docs.

The post Recurring Payments – Defining a Specific Stripe API Version first appeared on Easy Digital Downloads.

Recurring Payments – Authorize.net Gateway Configuration

Mon, 24 Jan 2022 19:55:11 +0000

Recurring Payments integrates fully with Authorize.net. The Authorize.net payment gateway is available for Easy Digital Downloads via the Authorize.net extension.

See Documentation for installing, configuring, and using the extension for details on the configuration of Authorize.net.

The post Recurring Payments – Authorize.net Gateway Configuration first appeared on Easy Digital Downloads.

Recurring Payments – Developer: EDD_Recurring_Subscriber

danielgoldak — Mon, 24 Jan 2022 19:55:09 +0000

Creating Objects
Available Methods
Conditional Methods
Getting Subscriber Information
Setting Subscriber Options
Managing Subscriptions

Recurring Payments comes with a new EDD class for managing subscribers. The EDD_Recurring_Subscriber class allows you to interact with subscription customers and the subscriptions on their accounts.

Creating Objects

EDD_Recurring_Subscriber should be called with an identifier for an EDD customer or WordPress user on the site. This could be an email address or a WordPress user ID or an EDD Customer ID. Here are some examples:

$subscriber = new EDD_Recurring_Subscriber( 'user@example.com' );

If you pass an integer it will look for an EDD customer with that customer_id.

$subscriber = new EDD_Recurring_Subscriber( 3 );

If you pass an integer with a second argument of true then it will look for a WordPress user with that user_id.

$subscriber = new EDD_Recurring_Subscriber( 3, true );

Any of the above will return an object that looks like this:

EDD_Recurring_Subscriber Object
(
    [subs_db:EDD_Recurring_Subscriber:private] => EDD_Subscriptions_DB Object
        (
            [table_name] => wp_edd_subscriptions
            [version] => 1.4.1.3
            [primary_key] => id
        )

    [id] => 11111
    [purchase_count] => 19
    [purchase_value] => 2173.3
    [email] => user@example.com
    [emails] => Array
        (
            [0] => user@example.com
        )

    [name] => Bob Smith
    [date_created] => 2015-06-15 16:38:08
    [payment_ids] => 
    [user_id] => 1nan1
    [notes:protected] => 
    [raw_notes:EDD_Customer:private] => 
    [db:protected] => EDD_DB_Customers Object
        (
            [meta_type] => customer
            [date_key] => date_created
            [cache_group] => customers
            [table_name] => wp_edd_customers
            [version] => 1.0
            [primary_key] => id
        )
)

Available Methods

Each of the methods below assumes that you have an object associated with a specific customer, and will refer to that customer as “the customer”.

Conditional Methods

$subscriber->has_active_subscription()

This method checks to see if the customer has a subscription that is either active or canceled, but not expired.

Returns boolean, filtered this way:

apply_filters( 'edd_recurring_has_active_subscription', $ret, $this );

$subscriber->has_product_subscription( $product_id = 0 )

This method checks to see if the customer has any kind of subscription on a specific EDD product ID.

Accepts an integer that is an EDD product ID.

Returns boolean filtered this way:

return apply_filters( 'edd_recurring_has_product_subscription', $ret, $product_id, $this );

$subscriber->has_active_product_subscription( $product_id = 0 )

This method checks to see if the customer has an active subscription on a specific EDD product ID.

Accepts an integer that is an EDD product ID.

Returns boolean filtered this way:

return apply_filters( 'edd_recurring_has_active_product_subscription', $ret, $product_id, $this );

Getting Subscriber Information

$subscriber->get_subscription_by_profile_id( $profile_id = ” )

This method accepts a payment profile_id and returns an EDD_Subscription object with all of the information about that subscription.

Accepts a payment gateway profile ID. You can find profile IDs for specific subscriptions on the details page for a specific subscription under Downloads → Subscriptions.

Returns an EDD_Subscription object. An example may be found in the EDD_Subscription docs.

$subscriber->get_subscription( $subscription_id = 0 )

This method accepts a subscription returns an EDD_Subscription object with all of the information about that subscription, similar to $subscriber->get_subscription_by_profile_id()

$subscriber->get_subscriptions( $product_id = 0, $statuses = array() )

This method will get all subscriptions for the customer that meet the input requirements. It accepts two arguments, the first being a product_id and the second being an array of statuses. Here are some examples:

// gets all subscriptions for the customer
$subscriber->get_subscriptions();

// gets all subscriptions for the customer for product ID 85
$subscriber->get_subscriptions( 85 );

// gets all active subscriptions for the customer for product ID 85
$subscriber->get_subscriptions( 85, array( 'active' ) );

// gets all active subscriptions for the customer, regardless of product
$subscriber->get_subscriptions( '', array( 'active' ) );

// gets all active and cancelled subscriptions for the customer, regardless of product
$subscriber->get_subscriptions( '', array( 'active', cancelled' ) );

$subscriber->get_new_expiration( $download_id = 0, $price_id = null )

This method determines the expiration date of a subscription one period beyond the current expiration date. For example, if the expiration date were 2017-01-01 23:59:59 and the period was one month, then this method would return 2017-02-01 23:59:59.

Accepts an integer for download_id as the first argument required.

Accepts an integer for price_id in the case of variable prices, optional

Returns a date formatted like Y-m-d H:i:s.

$subscriber->get_recurring_customer_ids()

This method returns an array containing all of the customer IDs created by payments gateways for the customer. An example would be

Array
(
    [stripe] => cus_85YmUU1QuH5yxY
)

Output is filtered this way:

apply_filters( 'edd_recurring_customer_ids', $ids, $this );

$subscriber->get_recurring_customer_id( $gateway = false )

This method accepts a gateway name and returns a string containing the customer ID associated with the customer and that gateway.

Accepts a string containing a gateway name like stripe.

Returns a string containing a customer ID like cus_85YmUU1QuH5yxY

Output is filtered this way:

apply_filters( 'edd_recurring_get_customer_id', $customer_id, $this );

Setting Subscriber Options

$subscriber->set_as_subscriber()

This method takes the customer and creates an EDD Customer with their information.

$subscriber->set_recurring_customer_id( $recurring_id = ”, $gateway = false )

This method accepts a payment gateway recurring ID and a payment gateway name and associated them with the customer.

Accepts a string containing a payment gateway recurring ID like cus_85YmUU1QuH5yxY. Required.

Accepts a string containing a gateway name like
stripe. Required

Managing Subscriptions

$subscriber->add_subscription( $args = array() )

This method adds a subscription to an EDD customer. If there is no customer_id included it creates one from the WordPress customer.

This method uses EDD_Subscription::create(), and therefore has all of the same requirements. Full documentation for EDD_Subscription::create().

Accepts an array of data required by EDD_Subscription::create().

Returns a subscription object.

$subscriber->add_payment( $args = array() )

This method adds a payment record to a specific subscription for the customer. It accepts an array like this:

$args = array(
    'subscription_id' => 0,
    'amount'          => '0.00', 
    'transaction_id'  => '',  
);

The subscription_id array key must not be empty and should be an integer.

This method uses EDD_Subscription::add_payment() and therefore has all of the same requirements. Full documentation for EDD_Subscription::add_payment().

Returns true.

The post Recurring Payments – Developer: EDD_Recurring_Subscriber first appeared on Easy Digital Downloads.

Recurring Payments – REST API Endpoint

Mon, 24 Jan 2022 19:55:06 +0000

Recurring Payments extends the existing RESTful API built into Easy Digital Downloads. It can be accessed at

http://example.com/edd-api/subscriptions/?key=YOUR_API_KEY&token=YOUR_API_TOKEN

Note: make sure to replace example.com with your own address and the key and token values with your own.

The above example will return a list of all existing subscriptions in the store.

Input

The Recurring Payments REST API accepts 3 options besides key and token: customer, number, and paged.

Customer

The input for a customer can either be an integer representing a customer_id or an email address. The resulting URL will look similar to this:

http://example.com/edd-api/subscriptions/?key=YOUR_API_KEY&token=YOUR_API_TOKEN&customer=2

http://example.com/edd-api/subscriptions/?key=YOUR_API_KEY&token=YOUR_API_TOKEN&customer=user@example.com

Number

The number option accepts an integer and returns that many results. An example would look like this:

http://example.com/edd-api/subscriptions/?key=YOUR_API_KEY&token=YOUR_API_TOKEN&number=5

Paged

The paged option allows you to choose a slice of a larger number. For example, if you have 100 entries, and you use number=10 you could pass paged=2 and you could get rows 11-20. That would look like this:

http://example.com/edd-api/subscriptions/?key=YOUR_API_KEY&token=YOUR_API_TOKEN&number=10&paged=2

Output

The output for each subscription contains all information about that subscription as well as about the customer and each renewal (child) payment. Additionally, there’s a value indicating the time spent getting the information for all results. Example:

{
    "subscriptions": [
        {
            "info": {
                "u0000EDD_Subscriptionu0000subs_db": {
                    "table_name": "wp_edd_subscriptions",
                    "version": "1.0",
                    "primary_key": "id"
                },
                "id": "1",
                "customer_id": "2",
                "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": "active",
                "profile_id": "paypal-363e3cc178dab152bb59b958024bce75",
                "gateway": "paypal",
                "customer": {
                    "id": "2",
                    "purchase_count": "2",
                    "purchase_value": "20.000000",
                    "email": "support@easydigitaldownloads.com",
                    "name": "Jane Doe",
                    "date_created": "2016-03-07 22:33:44",
                    "payment_ids": "16",
                    "user_id": "3",
                    "notes": [

                    ]
                }
            },
            "payments": [
                {
                    "id": 106,
                    "amount": 10.36,
                    "date": "March 21, 2016",
                    "status": "Renewal"
                },
                {
                    "id": 105,
                    "amount": 10,
                    "date": "March 21, 2016",
                    "status": "Renewal"
                },
                {
                    "id": 104,
                    "amount": 10,
                    "date": "March 21, 2016",
                    "status": "Renewal"
                }
            ]
        }
    ],
    "request_speed": 0.076335906982422
}

The post Recurring Payments – REST API Endpoint first appeared on Easy Digital Downloads.

Recurring Payments – Content Restriction Integration

Mon, 24 Jan 2022 19:54:59 +0000

The Content Restriction extension for Easy Digital Downloads makes it easy to require a purchase before allowing access to some content. With Recurring Payments integration you can require an active subscription in order to access restricted content.

There are two ways to implement the integration:

Full Content Restriction

When activated, Content Restriction creates a meta box on every post type except Downloads (e. g. Pages, Posts, and any custom post types). With Recurring Payments integration it also includes a checkbox to require an active subscription.

Partial Content Restriction

Content Restriction provides a shortcode that you can wrap around segments of content to restrict that content. With Recurring Payments it accepts a new variable like this: [edd_restrict subscription="true"] Content [/edd_restrict]

This will allow you to restrict access to any fragment of information where shortcodes work to only customers with active subscriptions.

FAQs

Does this setting apply to non-subscription purchases?

The “Active Subscribers Only?” option is ignored for One-time Purchases. Therefore, if the product or product option does not have recurring enabled, a one time purchase will still have access to the restricted content, regardless of whether “Active Subscribers Only?” is enabled or not.

Note: If Recurring is enabled for an existing product that was previously a one time purchase, existing customers without a subscription will NOT have access to “Active Subscriptions Only?” content.

The post Recurring Payments – Content Restriction Integration first appeared on Easy Digital Downloads.

Recurring Payments – Template Files

Mon, 24 Jan 2022 19:54:56 +0000

Recurring Payments comes with four template files, all stored in the templates/ directory in the Recurring Payments plugin folder. They are:

paypal-express-confirm.php
paypal-commerce-processing.php
shortcode-subscription-receipt.php
shortcode-subscription-update.php
shortcode-subscriptions.php

Customizing Template Files

The template files in the Recurring Payments plugin may be copied to your theme directory in the same way that EDD core templates may be copied. Full documentation on how to copy your template files is found here.

The post Recurring Payments – Template Files first appeared on Easy Digital Downloads.

Recurring Payments – Manually Create Subscriptions

danielgoldak — Mon, 24 Jan 2022 19:54:20 +0000

Add New subscription fields
How to Manually Create Subscriptions
Recreating a Subscription and Order
Recreating a Subscription for an existing order
Manually Migrating Subscriptions
Creating a Stripe Subscription

This document covers manually creating subscriptions and migrating subscriptions from another platform. It will not create a payment or subscription record at the payment gateway, this is for the purpose of adding a subscription to EDD that already exists at the payment gateway or for testing purposes.

About the Add New subscription fields

Price and Billing Cycle: Fields for Initial Price, Recurring Price, and Billing Cycle. In most cases, the initial and recurring amounts are the same.

Times Billed: This specifies how many payments should occur. 0 is default and allows the subscription to run indefinitely until the store or customer cancels. If a number is entered here, then the user will be billed that many times after the initial purchase. Example: If “Times Billed” is set to 1, then the user will be billed twice – once for the initial purchase and once more for the “Times Billed” setting.

Customer Email: This allows you to select an existing customer or specify an email address to create a new customer.

Product: The Product this subscription applies to.

Initial Purchase ID: A new subscription will either create a new payment record or an existing Order can be specified.

Gateway: If creating a new payment record, the gateway needs to be specified. This has to match the gateway that the subscription exists on or renewals and cancelations may not work properly.

Profile ID: This is the unique ID of the subscription in the payment gateway. Typically referred to as a Subscription ID.

Transaction ID: The initial purchase ID from the payment gateway. This is mostly for the store owner’s reference and is not actually utilized by the EDD subscription.

Date Created: The date the subscription was created. This field is optional.

Expiration Date: The date the subscription expires and/or the date of the next renewal.

Subscription Status: Current status of the subscription.

Required fields: Price and Billing Cycle, Customer, Product, and Expiration Date.

How to Manually Create Subscriptions

Navigate to Dashboard → Downloads → Subscriptions → Add New
Set the Initial, recurring, and billing cycle. Most likely the initial and recurring price is the same.
Leave Times Billed set to 0 unless the subscription is to end after a set number of payments. Such as a payment plan.
Set customer or input a new email address if the customer doesn’t already exist.
Select the Product that the subscription is tied to.
If no order already exists in your EDD store, keep “Create new payment record” selected and choose the Gateway. If an order does exist, select “Enter existing payment ID” and input the Payment ID.
If a transaction ID exists for the initial purchase, input the ID. This field is optional.
Input the Date Created, otherwise, today’s date will be used, if left empty.
Input the Expiration Date, which should match the expiration/renewal date of the subscription at the merchant processor.
Set the Subscription Status.

Recreating a Subscription and Order

This might be used if you need to exchange a product tied to a software license or in the event both the subscription and order needed to be recreated.

Navigate to Dashboard → Downloads → Subscriptions → Add New
Set price and billing cycle to match the current subscription
Times Billed should be 0 if the subscription was set up to run indefinitely.
Select the customer. Since the subscription is being recreated, the customer should already exist.
Select Download and variable option
Leave “Initial Purchase ID” set to “Create new payment record”
Use the Profile ID from the existing subscription
Use the Transaction ID from the existing subscription
Use the Date Created from the original subscription
Use the Expiration Date from the original subscription
Set the subscription status Active
Click “Add Subscription”
Once you confirm the newly created subscription and the order is set up as expected, update the Profile ID from the original subscription by setting it to blank or 0. This confirms upcoming renewals will only renew the new subscription in EDD, not the original you are replacing.

Recreating a Subscription for an existing order

In a rare instance, you might have to re-create a subscription for an existing order. Most commonly if the subscription’s price was updated at the payment gateway and you want it to reflect in EDD. Follow all steps to make sure the original subscription is properly handled.

Navigate to Dashboard → Downloads → Subscriptions → Add New
Set price and billing cycle to match the current subscription
Times Billed should be 0 if the subscription was set up to run indefinitely.
Select the customer. Since the subscription is being recreated, the customer should already exist.
Select Download and variable option.
Set “Initial Purchase ID” to Enter existing payment ID” and enter the Order ID.
Use the Profile ID from the existing subscription
Use the Transaction ID from the existing subscription
Use the Date Created from the original subscription
Use the Expiration Date from the original subscription
Set the subscription status Active
Click “Add Subscription”
Once you confirm the newly created subscription is set up as expected, update the Profile ID from the original subscription by setting it to blank or 0. This confirms upcoming renewals will only renew the new subscription in EDD, not the original you are replacing.

Manually Migrating Subscriptions

If you have existing Subscriptions in PayPal, Stripe, or another Payment Gateway and want to migrate them over to work with the EDD Recurring Payments extension, follow these steps to make it work.

1. Navigate to Dashboard → Downloads → Subscriptions → Add New.

2. Enter all of the data on the form there until you get to the field titled Profile ID.

3. Each Payment Gateway has a unique ID for each customer’s subscription. To connect the user’s subscription to the gateway, you need to obtain the Profile ID (Subscription ID) and Transaction ID from your Payment Gateway. Find your gateway below and follow the specific steps for that Gateway:

Stripe Subscription ID and Transaction ID:

1. Log into your Stripe Account and navigate to Customers → Subscriptions in the left sidebar.

2. Click on the subscription in question.

3. Copy the subscription ID and paste it into the Profile ID field in your WordPress dashboard (see first steps on this page).

4. Now, we need the Transaction ID. In your Stripe account, click on Payments (or click the customer’s email address in the Subscription details) on the left sidebar. Find the first payment which started the customer’s subscription. Click on it, and scroll down to the Connections section and copy the ID, beginning with “ch_”:

5. Paste the Transaction ID and fill out the rest of the fields and click Add Subscription.

6. If you haven’t already when you initially set up EDD Recurring, set the Stripe Webhook to point to your website so that it can tell Easy Digital Downloads when new recurring payments come in. Follow the guide for setting up Recurring and Stripe webhooks here.

Paypal Subscription / Recurring ID and Transaction ID:

1. Log into your PayPal account and go to the Transaction you want to migrate by going to Activity > All Transactions in the menu at the top.

2. Find the Payment in question and click on the customer name to open.

3. The Transaction ID and Recurring or Subscription ID (Profile ID in EDD) will be listed there. Copy and paste them to the EDD Subscription you are creating.

4. Finally, make sure you set your Paypal IPN to point to your website so that it notifies Easy Digital Downloads when a recurring payment has gone through. This way, a new Payment will be generated in Easy Digital Downloads to match up with the recurring payment in Paypal. You can follow the Paypal IPN Guide to set up your IPN for Easy Digital Downloads.

Creating a Stripe Subscription

There might be an instance where you want to create a new subscription in Stripe. Maybe an error occurred or the customer cancelled inadvertently and you need to re-create the subscription.

Note, if there is an existing subscription in Stripe, Stripe does allow you to change the pricing of the subscription, so you can utilize an existing subscription if you need to make changes. You can add or remove products, add a coupon code to update the pricing or add a trial to extend the renewal date.

1. From your Stripe Dashboard, go to Customer and open the customer in question.

2. From the customer details in Stripe, click the + to create a subscription

3. Add a product. If you need a unique price, any product will work as the price is what matters, the customer does not see what product is added to this subscription. You can also apply a coupon to lower the price for one payment or indefinitely depending how the coupon is configured.

4. Configure Free Trail Days. If you want the subscription to bill today, skip this step. If a payment already exists or you don’t want the amount to bill until a later date, set the “Free trial days”.

When you input a number of days, Stripe will present the “Ends” date, the customer will get charged on this date.

5. Click, Create subscription. Review the summary on the right side, to confirm the amount due today is correct and the “ends” date is correct if you added a trial date.

6. Open the new subscription in Stripe and copy the Subscription ID. Use that when creating or re-creating the subscription in EDD using the instructions in this documentation.

The post Recurring Payments – Manually Create Subscriptions first appeared on Easy Digital Downloads.

Recurring Payments – Software Licensing Integration

Mon, 24 Jan 2022 19:54:08 +0000

Software Licensing works seamlessly with Recurring Payments. Here are some of the highlights:

It fully integrates with software upgrades.
Renewal discounts are applied properly.
Canceling a subscription partway through the subscription period does NOT expire the license key, it remains valid for as long as was paid for.
It supports upgrading to a one-time fee lifetime subscription, which ends the recurring billing.

Frequently Asked Questions

What happens if a license key is renewed early?

If a license key is renewed early, a “subscription” (which is created by EDD Recurring immediately upon renewal) is created and the license key expiration date is extended by one period, where a period is whatever the store owner has set (12 months, 6 months, etc). This can cause the subscription and license key expiration dates to become out of sync. This isn’t an issue, when this happens the customer is essentially pre-paying for their license key.

For example, assume a store is set up with annual licenses:

A customer purchases a license on January 1, 2022, setting the expiration date to January 1, 2023.
The store owner changes that product to include a recurring subscription on June 1, 2022.
The customer decides to renew their license early on July 1, 2022.
The license will now expire on January 1, 2024.
The subscription payment will be automatically processed one year from the early renewal, on July 1, 2023.
The expiration date of the license will now, after the automatic payment is processed, be set to January 1, 2025.

What happens if a license key was purchased without a subscription but then renewed with the purchase of a subscription? Do expiration and renewal dates get synced?

When renewing a license and converting it to a subscription, the expiration of the license and renewal date of the subscription do not synchronize. The subscription will extend the license’s expiration date in accordance with the license length configuration. The subscription will also set a renewal date for itself, in accordance with its own configuration. For example:

A yearly license purchased on January 1, 2022, will expire on January 1, 2023.
On June 1st, 2022 the license is renewed early and converted to a subscription:
1. The license will have its expiration date extended by 1 year to be January 1, 2024
2. The subscription will have a renewal date of June 1st, 2023
On June 1st, 2023, when the subscription renews, the license key will again have its expiration date extended by a year, to January 1, 2025. This 3rd step will continue to happen yearly, so long the subscription on step 2 remains active and is not canceled or expired (due to failed payment)

Can you sync a license key and subscription expiration dates?

If the customer or store owner wants to re-sync the license and subscription, the subscription can be canceled and manually renewed when the license is set to expire. This may not be in the best interest of the customer if the license key price has increased. Manually renewing would create a subscription at the new price.

What happens if renewal discounts are enabled? How will the subscription be charged?

Renewal discounts are applied to renewals only, not the initial payment. If a product costs $100 with a 50% renewal discount, the initial payment will be $100, and every renewal after that will cost $50.

Renewal discounts are created in the Software Licensing extension under Settings → Extensions → Software Licensing.

How do discount codes affect renewal discounts?

In Recurring payments, there is a setting for One-Time Discounts. If this box is checked, the discount code will only apply to the initial subscription, and all renewals will be processed at their normal amount. When unchecked, a discount applied to the initial subscription purchase will continue to be applied to all automatically renewed payments.

With Software Licensing renewal discounts, they will apply as they normally do to automatic renewals, so if the One-Time Discount is unchecked, and there is a Software Licensing renewal discount, both will be applied to the automatically renewed amount.

What if a customer upgrades a license key?

Upgrading license keys are fully supported. The upgrade cancels the original subscription purchased and creates a new subscription record. All license keys retain their original expiration date, and any prorated and additional discounts associated with the Software Licensing upgrade path are applied to the purchase. Not only do the upgraded license keys retain their expiration date, but the new subscription’s expiration will match the license’s original expiration as well, regardless of the date the upgrade was done by the customer.

How do site admins find the license key associated with a subscription?

To see the license key associated with a subscription, you can go to Downloads → Subscriptions, and click on the View link next to the subscription. The license key associated with the subscription will be located in its own section on the Subscription Details view.

What about bundle products that use a subscription?

Bundles that are subscriptions and have licensing enabled work just like a single product. A single subscription is created for the customer, that contains the bundle product. The recurring renewal of that subscription will maintain access to all the bundled products. See Product Bundle Licensing for details.

How are email notifications for license keys with subscriptions handled?

When both Recurring Payments and Software Licensing are activated, there are two sets of email notifications that can be configured, one in the Software Licensing settings and one in the Recurring Payments settings. When a license key is associated with a recurring subscription, the renewal/expiration notices configured in the Recurring Payments settings will be used. Those notices configured in the Software Licensing settings will be ignored for license keys that are connected to a subscription so long as the subscription remains Active. If a subscription for a license key is canceled or becomes expired, the emails configured in the Software Licensing settings will be used.

How do renewal discounts work with free trials?

When using free trials and renewal discounts, the renewal discount will be applied to the first payment processed after the free trial is completed.

For example, if you sell a $100 / year product with a 1 month free trial and a 20% renewal discount, the payments will be as follows:

$0.00 for the first month
$80 for the first payment after the trial is completed
$80 for each year following

If you sell a $100 / year product without renewal discounts, the payments will be as follows:$0.00 for the first month

$100 for the first payment after the trial is completed
$100 for each year following

The post Recurring Payments – Software Licensing Integration first appeared on Easy Digital Downloads.

Recurring Payments – Subscription Emails

danielgoldak — Mon, 24 Jan 2022 19:53:54 +0000

Recurring Payments has the ability to send a number of emails to customers related to events such as payments made, payments failed, and subscription cancellations. This article will cover them all, as well as how to use them.

Recurring Payments emails are setup under Downloads > Emails. Use the Sender filter and select Recurring Payments from the dropdown to only see Recurring Email.

Click an email to edit and/or toggle the status to enable or disable each email.

Subscription Reminder emails can be added by clicking Add New Email > Add Subscription Reminder. Multiple reminder emails can be created to remind at different periods of time. For example, 30 days before the subscription is renewed.

None of the emails are required, each can be enabled individually.

Note for stores using Software Licensing
If you are using both Recurring Payments and Software Licensing, while the subscription is active, only Recurring Subscription emails are sent. See How are email notifications for license keys with subscriptions are handled? for more details.

Email Editor

See the email settings for details on editing emails.

Renewal Payment Received

This email can be sent to customers each time a recurring payment is made. The store owner can set a subject and the message body.

Payment Failed

This email can be sent to customers when a recurring payment fails to be processed. The store owner can set a subject and the message body.

Subscription Cancelled

This email can be sent to customers when their subscription is canceled. Without this email, it’s possible they may not realize it has been canceled, if it has been canceled because of payment failure, etc. The store owner can set a subject and the message body.

Reminder Emails

The store owner may also set up some scheduled reminder emails to go to the customer, alerting them to either impending expiration or renewals.

Renewal Reminders can be emailed to customers as a courtesy to alert them that their renewal date is approaching.
Expiration Reminders work exactly like Renewal Reminders but are intended to alert the customer that their subscription has expired, and include information on how they can renew.

Emails may be scheduled with these options:

The day of the renewal/expiration
One day before renewal/expiration
Two days before renewal/expiration
Three days before renewal/expiration
One week before renewal/expiration
Two weeks before renewal/expiration
One month before renewal/expiration
Two months before renewal/expiration
Three months before renewal/expiration
One day after expiration
Two days after expiration
Three days after expiration
One week after expiration
Two weeks after the expiration
One month after expiration
Two months after the expiration
Three months after the expiration

Subscription Cancelled Email for Admins

Emails can be sent to the site owner/admin when a subscription is canceled.

The post Recurring Payments – Subscription Emails first appeared on Easy Digital Downloads.

Recurring Payments – Adjusting Pricing

danielgoldak — Mon, 24 Jan 2022 19:53:53 +0000

When you create a subscription, once it’s created, it’s managed by the payment gateway so EDD is limited on what changes can be made once the subscription is created. With that said, some payment gateways do allow you to make certain changes. This article covers what’s possible via Stripe and PayPal. It’s possible some of these methods will work with other payment gateways but we can’t guarantee it nor do we have details for those payment gateways at this time.

Note: Each of the options is different for each payment gateway. If instructions are not provided for a specific gateway, it means that option does not exist.

Adjust the price of your subscription (for all customers):

Subscription pricing can only be adjusted on a per customer basis, see options below.

Decrease the price of your subscription (for a single customer):

Stripe

It’s possible to decrease the price of a subscription for a period of time or indefinitely, by following these steps.

In Stripe, create a Coupon.
1. For a one time discount, set the Duration to Once
2. For a permanent price reduction, set the Duration to Forever
3. You can also specify a specific number of months (for example 6 month price reduction).
Navigate to the subscription in Stripe (Click the Profile ID in EDD’s subscription details).
Click “Edit Subscription”.
Click “Add coupon” to add the coupon created in Step 1.
Once the price is set, click “Update Subscription”.

The next renewal will charge at the newly adjusted rate.

PayPal

Navigate to the subscription in PayPal (Click the Profile ID in EDD’s subscription).
Click “Change” at the bottom of the subscription details.
Set the new price in the Amount Due option.
Save when complete

The next renewal will be charged at the newly adjusted rate.

Increase the price of an upcoming renewal payment

Stripe

Stripe does allow you to alter the price of an active subscription. This is done by replacing the product added to the Stripe subscription or adding additional product(s) to the subscription to make the renewal amount the desired price. Note, the products tied to the Stripe subscription are not customer-facing, so all that matters is the final, renewal price.

Navigate to the subscription in Stripe (Click the Profile ID in EDD’s subscription details).
Click “Update Subscription”.
Click “Add product” to add a new product. If you’ve sold your product at the new price, it will appear as an option. You could select any available product to get the desired new pricing.
Remove the old product from the subscription.
Deselect “Prorate charges”.
Once the price is set, review the Preview Summary to confirm the next invoice amount is correct.
Click “Update Subscription”.

The next renewal charge is at the newly adjusted rate.

PayPal

In the event you need to increase a subscription’s price, you should be able to do so through a customer’s PayPal subscription. Please refer to PayPal support for details, but in most cases, you should be able to increase pricing by up to 20%.

Navigate to the subscription in PayPal (Click the Profile ID in EDD’s subscription).
Click “Change” at the bottom of the subscription details.
Set the new price in the Amount Due option and/or Tax box.
Save when complete.

The next renewal will charge at the newly adjusted rate.

Skip a renewal payment / extend a license

Stripe

There is not a specific option to skip a payment, however, you can add a 100% discount (duration of once or a specific number of months – see Decrease the price of your subscription above for instructions).

Pause a subscription

Pausing a subscription is not currently possible through EDD or directly through the payment gateway. With Stripe you can apply a coupon code for the duration that you want the pause the subscription for. Once Stripe successfully renews, the subscription and license will update. Note, this may not prevent your customer from accessing their product.

FAQ

Why doesn’t EDD have these features built into the plugin?

There are a number of reasons for this. What features we can develop depends on the payment gateway’s API, and some are more limited than others. Additionally, in most cases we only include features that work for the majority of payment gateways so if a particular feature only works with one payment gateway, it will likely not get implemented.

The post Recurring Payments – Adjusting Pricing first appeared on Easy Digital Downloads.

Recurring Payments – Developer: EDD_Subscription

Mon, 24 Jan 2022 19:53:41 +0000

Properties
Method
Usage
Object Modification
Operational Methods
Getting Subscription Information
Subscription Conditionals
Status Methods

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.

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:

$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:

$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’.

The post Recurring Payments – Developer: EDD_Subscription first appeared on Easy Digital Downloads.

Recurring Payments – Setup & Overview

danielgoldak — Mon, 24 Jan 2022 19:53:40 +0000

Recurring Payments make it possible for your customers to purchase subscriptions via your EDD store. A subscription product is simply a normal product with the recurring subscription setting enabled. This documentation provides instructions on how to create, sell and manage subscription products.

Requirements
Setup
Download Settings
Single Priced Products
Variable Priced Products
Recurring Settings
Managing Subscriptions
FAQs

Once the extension is installed and activated, Downloads will have Recurring options in the Pricing Options.

You may enable recurring payments for any existing product that you are selling, but it will have no impact on existing sales – the changes will apply only to future purchases. If your product requires customers to repurchase, a subscription will be created upon the next purchase.

Requirements

The gateway used at checkout must support Recurring Payments. A list of supported gateways can be found here.
Follow the specific setup process for your gateway. Failing to do so will cause problems at the time of renewal.
- Stripe (Standard or Pro)
- PayPal (Standard or Pro)
- Authorize.net
- For 3rd Party gateways that support recurring payments, refer to the developer for specific documentation.
Purchases that contain a recurring product require customers to create an account at checkout or be logged in. Auto Register can be used to streamline the account creation process at checkout.

Setup

1. Navigate to a new or existing Download product: Download → All Downloads → Add New (or Edit)

2. Within the Download Prices section, set Recurring to Yes. Once the product is updated, a subscription will be created upon purchase.

Recurring Product Settings

Price
Amount applied to the initial and recurring payments.

Period
How often do renewals occur? Options are Daily, Weekly, Monthly, Quarterly, Semi-Yearly, and Yearly.

Times
This specifies how many payments should occur. 0 is default and allows the subscription to run indefinitely until the store or customer cancels.

The number chosen includes the initial payment on checkout. Once the set number of payments occurs, EDD will set the subscription status to “Completed” and cancel the subscription at the payment gateway.

This is typically used if you want to offer a payment plan.

Note: A value of 1 is not supported.

Signup Fee
A one-time signup fee to be charged upon checkout.

Negative Signup Fees
If the signup fee is a negative number it will actually discount the initial payment. For example, let’s say you have a $10/mo subscription. Normally the first payment of $10 is due immediately. If you set a signup fee of -5, the first payment would be $5.

Negative Signup Fees should not be set to match the recurring price of the product, which would result in an initial payment of $0.00. A cart total of $0.00 will not send the customer to a payment processor regardless of your available payment methods. EDD will treat the cart as free and upon completion of the transaction, the customer will receive access to the product with a subscription created in EDD only. The customer will not be charged for the product at all during the subscription term. A minimum subscription amount is always required. That amount depends on the payment processor. For example, Stripe will require a minimum of $0.50 for a subscription to be valid. Please refer to the knowledge base of your chosen payment processors to confirm the amounts.

Enable free trial for subscriptions

Check this box to include a free trial with subscriptions for this product. When signing up for a free trial, the customer’s payment details will be taken at checkout but the customer will not be charged until the free trial is completed.

Note: This only applies when purchasing a subscription. If a price option is not set to recurring, this free trial will not be used.

Here is an example of how purchasing a free trial appears during checkout:

If a customer does not wish to continue using your product or service, they can cancel the subscription at any time during or after the free trial. By adding the [edd_subscriptions] shortcode to a page accessible by the customer, they will then have the option to cancel a subscription if needed.

Single Priced Products

When you create a new product or edit an existing one, look next to the pricing field for the recurring settings:

Variable Priced Products

Recurring Payments supports variable-priced products. Variable options can include recurring and/or single purchase options within the same product.

Click “Show advanced settings” to see the Recurring Payment settings within the Price ID settings.

Recurring Payments Settings

Recurring Payments settings are located under Downloads → Settings → Payments → Recurring Payments:

Limit File Downloads
Check this if you’d like to require users have an active subscription in order to download files associated with a recurring product.

Allow “Completed” subscriptions to download files
Enable to allow users with “Completed” subscriptions to be able to download their files, despite their subscription technically not being “Active”. This applies to subscriptions with the “Times” options set to a non-zero value.

Display Subscription Terms
When selected, the billing times and frequency will be shown below the purchase link.

Display Signup Fee
When selected, any signup fee associated with a subscription will be shown below the purchase link.

Signup Fee Label
This is shown on checkout and on individual purchase options if “Display Signup Fee” above is checked.

Cancel Subscription Text
This text is shown to the customer when managing their subscriptions.

One Time Discounts
By default discount codes will apply to both the initial and recurring payments. Check this if you’d like discount codes to apply only to the initial subscription payment and not all payments.

Note:

One Time Discounts are not supported with Discounts Pro. Whether settings is enabled or disabled, Discounts Pro discounts will apply to both initial and renewal payments.
One-time discount codes will not apply to free trials. For free trials, discount codes will always apply to all payments made for the subscription.

One Time Trials
Check this if you’d like customers to be prevented from purchasing a free trial multiple times.

Email Settings
Detailed Recurring email settings can be found here.

Managing Subscriptions

Subscriptions can be managed by the store owner and customers. See Managing Subscriptions for details on how this works.

Troubleshooting / FAQs

See Common Questions and Problems doc for more Recurring Payments FAQs.

Why can’t I disable or change the Free Trial length in Variable Options?

Most likely a Free Trial was enabled prior to enabling variable options. To fix this, first, disable Variable pricing on the product, then disable the “free trial” option, then re-enable Variable pricing. Example below:

What’s the renewal date after the first payment when the trial ends?

After the trial ends and the first payment is collected, the new renewal date will be based on the date of payment and not the date the trial started. For example, if you have a monthly subscription and a 7 day trial. Once the trial ends, the new renewal date will be one month from the date of the payment.

The post Recurring Payments – Setup & Overview first appeared on Easy Digital Downloads.

Recurring Payments – Stripe Gateway Configuration

danielgoldak — Mon, 24 Jan 2022 19:53:34 +0000

Canceling Subscriptions
Subscription Statement Descriptors
Common issues

This document explains how the Recurring Payments extension works with Stripe.

Configuring Stripe

It’s important to follow all steps laid out in the Stripe Setup Documentation.

Important Setup Note: If Webhooks are not properly configured, subscriptions will not work properly!

Canceling Subscriptions

When using Stripe, a cancellation may be initiated either from within EDD or from the Stripe Dashboard.

Canceling as a Customer

Customers can cancel their own subscriptions from your store’s account page.

Canceling as a Site Administrator

To cancel a subscription from the EDD admin go to Downloads → Subscriptions and click “View” on the item you want to cancel.

Then in the bottom of the next screen click on “Cancel Subscription”.

When you set a subscription’s status to cancelled it’s cancelled immediately, but the customer will still have access to their purchased material for as much time as they’ve paid for.

For example, if they’ve paid $10/mo, and you cancel halfway through the month they still have access to their material for the rest of the month, but they won’t be re-billed, and access will stop at the end of the month.

From The Stripe Dashboard

To cancel a subscription from the Stripe Dashboard, log in to Stripe and find the search bar at the top of the page.

You may find customers by searching for:

the charge ID
the subscription profile ID
the EDD customer ID number
the customer email

Once you’ve found and selected your Customer in Stripe you’ll see a list of subscriptions.

If you click Cancel (X icon to the of the subscription name) you’ll be given three options; to cancel Immediately, at the end of the current period, or on a custom date. For the purposes of EDD it doesn’t matter which you choose immediately or at the end of the current period, your customer won’t experience any difference between the two. If you choose a custom date, that’s after the end of the current period, they will continue to get billed until the custom date passes.

Canceling Summary

It doesn’t matter if you cancel a subscription in EDD or in Stripe, the effect is exactly the same and the customer won’t notice a difference.

Updating Credit/Debit Card Information

Customers can update their card information for their specific subscription(s) from your store’s account page.

Statement Descriptors

When a product is configured as a subscription, the descriptor behavior is slightly different than non-subscription purchases. When a subscription is purchased for the first time on your site, a “Product” is created in Stripe that will be used for all subsequent purchases of that particular subscription. You can see your current list of Products by logging into your Stripe account and navigating to Products.

When this Product is created, a statement descriptor is created based on the name of your product, regardless of the aforementioned setting in your WordPress dashboard. The descriptor will also be made lowercase and will separate words using hyphens. Understandably, this doesn’t look friendly on a bank statement. There are two ways to change this behavior that are best used together if you do not like the default behavior:

1. Edit the Plan details

By going to Products in your Stripe account, you can click on any Product to see its details. Once you’re on the details page, click the Edit details button. You will be presented with a modal that allows you to set the statement descriptor for that particular Product.

What you set here will be used for all payments of that subscription plan on your site.

2. Filter the Statement Descriptor default for Stripe plans

The above method allows you to control the statement descriptor for a specific subscription that already exists. But if a new subscription is created from the first-time purchase of a different subscription on your site, the default behavior will apply. That means the new subscription will still have a statement descriptor based on the product name by default.

To create a new default statement descriptor for all subscriptions created in the future (this will not affect existing subscription), use the following filter:

function custom_edd_recurring_stripe_plan_statement_descriptor( $args, $subscription ) {
   $args['statement_descriptor'] = 'New Statement Desc';
   return $args;
}
add_filter( 'edd_recurring_create_stripe_plan_args', 'custom_edd_recurring_stripe_plan_statement_descriptor', 10, 2 );

Replace New Statement Desc with your preferred default statement descriptor (remember the 22 character limit).

In summary, use the first method to edit the statement descriptor for an existing subscription. Use the second method to set a new default statement descriptor for all future subscriptions.

Common issues relating to webhooks

Customers get charged too many times

If you don’t set up your Stripe webhooks correctly prior to a customer making a purchase and you are using the “Times” option in EDD Recurring to charge the customer a set amount of times (for example, 5 times), they will get charged too many times.

This is because, without the webhook, Stripe is not able to tell EDD that the payments went through successfully so EDD doesn’t know. Because of this, EDD thinks the customer has not yet been charged – even though they may have already been charged 5 times (or more).

EDD sends a “cancel subscription” to Stripe automatically when the number of times has been reached. But since there is no webhook, EDD doesn’t know that the customer has been charged at all and never cancels the subscription. This results in the customer continuing to be charged even after the set amount of times has been reached. This is why it is important to set up a webhook immediately after installing the Stripe extension.

The post Recurring Payments – Stripe Gateway Configuration first appeared on Easy Digital Downloads.

Recurring Payments – Common Questions and Problems

mihaijoldis — Mon, 24 Jan 2022 19:53:33 +0000

Below are common questions related to Recurring Payments.

Subscription is Pending in EDD but active at the payment gateway.

The EDD subscription can be manually set to Active if the payment gateway subscription is active. Confirm that the EDD subscription’s Profile ID matches the Subscription ID at the payment gateway.

If the payment was made with Stripe, confirm that Webhooks are configured per our documentation. If webhooks are configured correctly, confirm there are no errors reported via Stripe. If there are errors, this could be due to a webhost issue or a plugin blocking the webhooks.

If this doesn’t explain the issue, reach out to support for assistance.

Can a discount only apply to the renewal payment, not the initial payment?

No, discounts can apply to the initial payment only or all payments (initial and renewal payments). As a workaround, you can apply a fee to the purchase, which will only apply to the intial payment. The only way for a discount to apply to renewal payments, without applying to the initial payment, is with Software Licensing Renewal Discounts.

Can a discount apply to the first payment after a trial?

No, discounts on the initial payment or one-time discounts do not apply to trials. In EDD, the $0 trial is considered the initial payment. Only discounts that apply to all payments can be applied to a trial order.

How do the RBI regulations on recurring payments in India affect EDD?

Note, this only applies to customers who paid with an Indian credit / debit card for a recurring payment. One time payments are not affected.

Updated October 13, 2021

Support for RBI regulations on recurring payments has to come from the payment gateways (Stripe, PayPal, etc) in order for recurring payments to work. At this time, they are still developing integration for RBI. Once their API is updated, EDD will make any required updates possible to support RBI regulations. Unfortunately, it is not known when the payment gateways have this functionality ready.

For active subscriptions paid with an Indian card, it is expected that the renewal payment will fail to renew. PayPal and Stripe have made the following recommendations:

PayPal: Currently, PayPal is recommending using a one time payment since recurring payments will fail to process. See this PayPal FAQ for details.

Stripe: Stripe recommends enabling Customer Emails, within Stripe’s settings, so customers can pay renewals directly via Stripe. See this Stripe guide for details.

What happens to an existing subscription if I change the price?

The price for existing subscriptions remains the same for as long as the subscription remains active. New subscriptions will be created using the new/current price that is set.

Subscription renewal processed in merchant but not recorded in Easy Digital Downloads, why?

If your subscription renewals are being processed in your merchant account (Stripe, PayPal, 2Checkout, Authorize.net, etc) but the renewals are not showing up in Easy Digital Downloads, this is typically due to an issue with the setup at the payment gateway.

Subscription renewals are processed by your payment gateway and then the gateway communicates to Easy Digital Downloads to instruct EDD that a subscription renewal needs to be recorded. When renewals are not being recorded, it is because this communication from your gateway is not being received by EDD.

PayPal: If your subscriptions are processed by PayPal, you need to configure the PayPal IPN. Refer to the documentation below for the version of PayPal that you use:

Stripe: If your subscriptions are processed by Stripe, you need to configure your Stripe webhooks. See the Stripe Standard or Stripe Pro for Recurring Payments for more information.

2Checkout: If your subscriptions are processed by 2Checkout, you need to configure your 2Checkout INS. See the for Recurring Payments for more information.

Authorize.net: If your subscriptions are processed by Authorize.net, you need to configure your Authorize.net Silent Post. See the Authorize.net setup documentation for Recurring Payments for more information.

How do I manually process a renewal payment in EDD?

If the renewal was processed at the gateway but EDD didn’t record the renewal payment, this can be done manually.

1. Navigate to the subscription details for the subscription in question: Downloads → Subscriptions → View

2. Locate the Renewal Payments section. You can manually input the Total amount, Transaction ID (optional).

Is it possible for a user to put a subscription on hold rather than cancel?

This depends on the gateway. See Recurring Payments – Adjusting Pricing for possible options. If your gateway is not mentioned, you can reach out directly to the gateway to confirm.

Can customers cancel subscriptions?

Yes, customers can cancel their subscriptions at any time from their account management page. If the subscription includes access to content or license keys, through Content Restriction and Software Licensing, the customer will retain access until the expiration date of the subscription is reached.

Can the customer reactivate their subscription(s) later?

Depending on the gateway you are using, it’s possible the subscription can be reactive. If it’s possible, an option will exist for the admin and customer when managing the subscription. If the subscription is tied to a license, the license can be renewed which will reactivate the subscription.

Can subscriptions be upgraded?

Yes, but it requires the Software Licensing add-on to provide the upgrade paths. Full documentation on Software Licensing upgrades here.

Does Recurring Payments support Buy Now buttons?

Not at this time but we may consider supporting this in the future.

Does Recurring Payments work with the Software Licensing extension?

Yes, it does! See our documentation here for more information.

What happens when I refund a customer’s recurring payment?

When setting a payment (initial or renewal) to Refunded status, options to Refund and Cancel Subscription will appear. This allows you to decide if the subscription should be canceled or not, when refunding.

Why are quantities disabled if a recurring product is in the cart?

Currently, this is a known limitation in the EDD Recurring extension and how each payment gateway handles multiple recurring payments. If you have “Cart Item Quantities” enabled so that your customers can adjust their quantity on the checkout page, but they have a recurring-enabled product in their cart, quantities will be disabled for the entire cart. However, note that your customers can purchase more than one recurring-enabled product at one time. To do so, they simply have to add the item to their cart more than one time, so that it appears twice (on two lines) in their cart. To make this possible you could use something like the free “Keep Add To Cart” extension. Note, PayPal does not support purchasing multiple subscriptions during a single checkout process.

If a customer’s credit card is declined, how many times will a renewal payment be re-tried before being set to “expired”?

It depends on which payment gateway you are using. For Stripe, you can set the number of retries in your Stripe account’s settings. For Paypal, it automatically tries based on Paypal’s settings for your account. To find out for sure, you’ll need to confirm with your Payment Gateway.

What is the EDD Subscriber WordPress User role?

The role EDD Subscriber is a legacy role that is no longer used by EDD. Older stores may come across a user with the EDD Subscriber role, which would have been added to the user when EDD utilized the role. Since the role is no longer used, any users with the role can be left as is or the role can be removed from the user once confirmed any customizations or 3rd party integrations are not using it.

What Does “Needs Attention” Mean for a Subscription?

The Needs Attention status indicates a potential issue with a subscription that requires manual review. Common reasons include:

Gateway Communication Issues: The subscription was marked as cancelled in EDD, but cancellation at the payment gateway (e.g., Stripe, PayPal) could not be confirmed. This can happen if the cancel action fails in the admin or via customer self-service, potentially resulting in continued charges at the gateway.
Failed Subscription Creation: An EDD subscription was created, but the corresponding subscription could not be set up at the payment gateway.
Payment Method Update Failure: An attempt to update the payment method (such as with Stripe) failed, leaving the subscription in an inconsistent state. This is typically noted in the subscription notes.
Data Mismatch: The subscription status in EDD does not match the status at the payment gateway, often due to a failed or incomplete action.

Recommended Actions:

Review the subscription notes and the original order notes for details about the issue.
Compare the subscription’s status and data in EDD with the information at the payment gateway.
Take corrective action as needed to ensure both systems are in sync.

The post Recurring Payments – Common Questions and Problems first appeared on Easy Digital Downloads.

Recurring Payments – Managing Subscriptions

danielgoldak — Mon, 24 Jan 2022 19:53:25 +0000

Recurring Payments has a complete interface for viewing and managing subscriptions, their payments, and the customer information for those payments. Shortcodes are also available for customers to self-manage their subscriptions.

Admin Management
Subscription Status
Manually Renew
Customer Management
Update Payment Method
Revenue Report
FAQs

Subscription Management for Administrators

The management panel can be found by navigating to Downloads → Subscriptions in the WordPress admin area, and looks like this:

The Customer column lists the customer’s name, with a link to the customer details page.
The Status column lists the subscription status, see option below under “Usage.”
The Billing Cycle column contains the billing cycle. Options are Daily, Weekly, Monthly, Yearly.
The Initial Amount column lists the initial amount paid.
The Times Billed column lists how many times the customer has been billed.
The Renewal Date lists the renewal date or the date the subscription will complete.
The Payment column lists the Payment ID number and links to the original payment record; the one that created the subscription(s).
The Download column lists the download that was purchased with a link directly to the product admin page.
The Actions column lists a link to the details page for this particular subscription.

Single Subscription Management

When you click View on the list of subscriptions you’ll be taken to a page that looks like this:

Usage

This page provides methods to accomplish three key tasks:

You may change the Expiration Date of the subscription, effectively adjusting the term of the subscription. This does not update the payment gateway, so this should always match the payment gateway’s renewal date.
Cancel the subscription. When a subscription is canceled, it updates the subscription status within EDD as well as stopping the payment process at the payment gateway (Stripe, PayPal, etc).

NOTE: Changing the status back to Active in EDD will not turn recurring billing back on. If the payment gateway supports Reactivating a subscription, a Reactivate button will exist in place of the Cancel Subscription button. Otherwise, the customer must purchase a new subscription.
You may change the status of the subscription. Your options for status are:
- Pending: This status means the subscription is awaiting successful payment verification
- Active: This status is reserved for subscriptions with payments being actively collected.
- Completed: The subscription has run its course and is now marked as complete. Some gateways, such as PayPal, refer to completed subscriptions as “expired”. However, in EDD we refer to them as “Completed” for better clarity.
- Failed: The subscription has missed multiple payments, most likely due to payment failures. This can happen when a card expires or a customer changes payment information.
- Canceled: The subscription has been canceled and is no longer processing payments. Subscriptions may be canceled by a user or site owner. When a subscription is canceled by the site owner via the Payment Gateway, it will update in EDD if the proper webhook is set according to that gateway’s documentation. In the event that access is granted with a subscription, a “Cancelled” subscription will still have access and will only be denied once the subscription is past the expiration date.

Information

In addition to the above tasks, this page gives us this information:

Initial Purchase ID: links to the payment record under Payments
Billing Period: options are Daily, Weekly, Monthly, Yearly
Times Billed: the number of times the customer has been billed
Product: the title of the product linked to the Download editing page
Profile ID: the id of the transaction provided by the merchant processor
Date Created
Expiration Date
Subscription Status: see status options above

Renewal Payments

Each payment made is listed with a Payment ID, Amount, Date, Status, and an Actions link. The “View Details” link in the “Actions” column takes you to the Payment page for that record.

Manually Record Payments

Renewal payments may be manually entered using the form below the Renewal Payments table. This may sometimes be necessary if a renewal has been processed manually or there was a technical error that resulted in the renewal not getting processed by the payment gateway.

Total: Total amount of the renewal payment

Transaction ID: Renewal payment transaction ID. This field is optional and can be left blank.

Record Payment Only: This option added the renewal payment to EDD’s Purchase History and records to the Subscription’s Renewal Payments list.

Record Payment and Renew Subscription: In addition to recording the renewal payment (described above), it updates the Subscription’s Expiration Date. This can also update a connected license and/or All Access pass expiration date if either extension is used.

Note: If a subscription is manually renewed late, then the expiration date for the subscription and/or license may need to be manually updated to match the actual renewal date.

Subscription Management for Customers

Recurring Payments includes a Subscriber Account Dashboard which allows customers to view and manage their subscriptions. To make this dashboard you can create a page with the [edd_subscriptions] shortcode on it.

This will render a listing of subscriptions with details and several actions:

Actions:

View Invoice

The View Invoice action shows the invoice for the initial subscription purchase with details about the subscription and product purchased.

Update Payment Method

The Update Payment Method allows the customer to change their credit card information (if they used one) and their billing address information. This option is typically used if a customer wants to change their card or if their payment fails and the card needs to be updated. This does not apply to purchases made via PayPal, as the customer manages the payment source via their PayPal account.

To update the payment method, click Update Payment Method:

The customer will see a form where they can update their credit card information. If the setting “Show Previously Used Cards” is enabled within the Stripe gateway settings (Downloads → Settings → Payments → Stripe) then the customer will be able to see the credit card that is linked to the membership and they can choose to add another one if they would like to change it.

Revenue Reports

When the Recurring Payments extension is activated, it adds a new option to the Reports page under Downloads → Reports. Once on that page, make sure you’re on the Reports tab at the top, and then select Subscription Renewals from the report drop-down menu.

Report Data

This report renders Renewals and Earnings for subscription payments only. This means initial payments are not included. For example, if someone subscribes and the initial payment is $40, with $10/mo after that, the $40 will not be included in this report.

The Renewals and Earnings report allows for tax exclusion, and offers these time filters:

Today
Yesterday
This Week
Last Week
This Month
Last Month
This Quarter
Last Quarter
This Year
Last Year
Custom

FAQs

See the Common Questions and Problems doc for more Recurring Payments FAQs.

What happens when a subscription payment fails?

When a recurring payment fails, it will automatically retry over a couple days or weeks depending on your payment gateway. By default, customers should get an email from your EDD store that the payment failed and they should update their payment method. No action is required as the store owner, as the payment will automatically retry. With PayPal, it will retry the renewal payment 2 times, every 5 days. Stripe depends on your account settings. If all retry attempts fail, the subscription with be in a Failed state and the customer will have to re-purchase if they want to re-subscribe.

Can customers switch payment methods? For example, from PayPal to credit card?

A customer cannot change their subscription from one payment gateway to another. However, a customer could cancel their existing subscription and then complete a new purchase, choosing a different payment gateway at checkout. This will create a new subscription for them using the newly selected gateway.

For example, if a customer is using Stripe and they want to switch to PayPal, they would cancel their current subscription set up through Stripe, then complete a new purchase, this time selecting PayPal at checkout. This may happen if a customer opened a new PayPal account and wants to disconnect their current credit card, or vice versa to switch from PayPal to a credit card.

The post Recurring Payments – Managing Subscriptions first appeared on Easy Digital Downloads.

Recurring Payments – PayPal Gateway Configuration

danielgoldak — Mon, 24 Jan 2022 19:53:22 +0000

Set up PayPal
Cancelling Subscription as a Customer
Cancelling Subscriptions as an Admin
Updating Credit/Debit Card Information
PayPal Commerce Pro (Onsite Credit Card Forms) Support
Multiple Subscription Support
Legacy PayPal Setup

PayPal is included with Easy Digital Downloads, so no installation is necessary. If you wish to use it with Recurring Payments follow the instructions below.

Legacy PayPal integrations including PayPal Standard, PayPal Express, PayPal Pro, or PayPal Payments Advanced are being deprecated and will no longer receive updates. If you are not able to upgrade to EDD 2.11 or later, you can refer to the legacy setup steps.

Set up PayPal Integration

It’s important to follow all steps laid out in the PayPal Gateway you are using.

PayPal Documentation (new in EDD 2.11)

Important Setup Note: If using the new PayPal integration in EDD 2.11, you must make sure your webhook is valid. Subscriptions will not work properly otherwise.

If you’re using the new PayPal integration included with EDD 2.11, then the first thing you should do is double-check that your webhook is fully configured. Navigate to Downloads → Settings → Payments → PayPal and wait for your account information to load. Your webhook might be missing events, like this:

Just click the “Sync Webhook” button to update it with the new events required by Recurring. It should now look like this:

You should only have to do this once.

Canceling Subscriptions

Canceling subscriptions is done in a variety of ways depending on your site setup and situation.

Canceling as a Customer

There are two ways a customer can cancel a subscription.

1. From your store’s account page.

2. From a customer’s PayPal account. Click here for PayPal’s instructions.

Canceling as a Site Administrator

There are two ways to cancel PayPal subscriptions as a store administrator.

1. Within Easy Digital Downloads

Navigate to the subscription in question.

Go to Downloads → Subscriptions.
Locate the correct subscription and click View.

Click Cancel Subscription button on subscription pages within Easy Digital Downloads.

2. Within PayPal

The page for managing subscriptions in PayPal is here: https://www.sandbox.paypal.com/billing/subscriptions

Or, from your PayPal Dashboard, go to Pay & Get Paid → Subscriptions.

Then click “Subscriptions” to see your PayPal Subscriptions.

Click the Subscription ID to view the subscription details, then click Update. Update options will appear with Cancel being one of the options.

Updating Credit/Debit Card Information

The payment information needs to be updated via the customer’s PayPal account. Click here for instructions.

PayPal Commerce Pro (Onsite Credit Card Forms) Support

When an item that is a recurring payment is in the cart, the Credit Card / Debit Card button will open a PayPal window to complete the purchase, instead of showing card fields on your checkout page. Subscription payments are required to be completed on PayPal’s site instead of on your store’s website.

Multiple Subscription Support

Only one subscription may be purchased per transaction with all PayPal products. The customer may have as many subscriptions as they wish, but each must be purchased in a separate transaction.

If the customer attempts to put more than one subscription into the cart and check out, they’ll see a notice explaining that this does not work.

Important Note: As of November 1, 2019, PayPal no longer supports creating multiple subscriptions in a single purchase. See our blog post for more information.

PayPal (Legacy)

Note: This section is only intended for stores that cannot run Easy Digital Downloads version 2.11 or later.

PayPal should be configured per the documentation for your specific gateway.

PayPal Standard Documentation or PayPal Pro / Express Documentation

Note: If using PayPal Standard/Express/Website Payments Pro, your IPN and API credentials must be configured. Subscriptions will not work properly otherwise.

Website Payments Pro Account Requirements:

Using PayPal Website Payments Pro (Legacy) with Recurring Payments requires some specific configurations in your PayPal account.

Make Sure You Have PayPal Pro: Installing the PayPal Pro extension for Easy Digital Downloads does not mean you’re automatically using PayPal Pro. PayPal Pro costs $30/month; you can set it up by calling them.
PayPal Legacy Account: In order to use PayPal Pro with Recurring Payments your PayPal account must be a “legacy” account. There isn’t a perfect way to determine if your account is Legacy, but one clue is to look for a menu item in PayPal called “PayPal Manager”. If you have this, then you are NOT a Legacy account. If unsure contact PayPal’s support team by phone.
Enable Direct Payment Recurring Payments (DPRP): This is required and you must call PayPal’s support team to enable it for your account. DPRP costs an additional $30/month.

Common issues with legacy integrations:

For the cancel button to work, IPN and API have to be properly configured and working. Most often with PayPal Standard, the cancel button will not appear if your API Username, Password and Signature are missing or incorrect. Review all steps laid out in our PayPal Standard documentation to confirm API and all other settings are properly configured.
Renewals not updating due to having an older PayPal Account: Check the Profile ID field on a subscription’s details screen, if it’s starts with an “S” (ie S-nnnnnnnnnnnnnn ) you will need to contact PayPal Merchant Technical Services and notify them that your account is still using out of date subscription IDs and request they update your account.
Pending or Failed payments from PayPal Express In-Context purchases: Mostly like the customer navigated to a new tab while the pop-up was loading. The customer must not navigate to a new browser tab while the payment is loading. Unfortunately, this is a limitation in the way Paypal Express In-Context works.

The post Recurring Payments – PayPal Gateway Configuration first appeared on Easy Digital Downloads.

Recurring Payments – Easy Digital Downloads Documentation

Recurring Payments – Defining a Specific Stripe API Version

Defining your Stripe API Version

Recurring Payments – Authorize.net Gateway Configuration

Recurring Payments – Developer: EDD_Recurring_Subscriber

Table of Contents

Creating Objects

Available Methods

Conditional Methods

$subscriber->has_active_subscription()

$subscriber->has_product_subscription( $product_id = 0 )

$subscriber->has_active_product_subscription( $product_id = 0 )

Getting Subscriber Information

$subscriber->get_subscription_by_profile_id( $profile_id = ” )

$subscriber->get_subscription( $subscription_id = 0 )

$subscriber->get_subscriptions( $product_id = 0, $statuses = array() )

$subscriber->get_new_expiration( $download_id = 0, $price_id = null )

$subscriber->get_recurring_customer_ids()

$subscriber->get_recurring_customer_id( $gateway = false )

Setting Subscriber Options

$subscriber->set_as_subscriber()

$subscriber->set_recurring_customer_id( $recurring_id = ”, $gateway = false )

Managing Subscriptions

$subscriber->add_subscription( $args = array() )

$subscriber->add_payment( $args = array() )

Recurring Payments – REST API Endpoint

Input

Customer

Number

Paged

Output

Recurring Payments – Content Restriction Integration

Full Content Restriction

Partial Content Restriction

FAQs

Does this setting apply to non-subscription purchases?

Recurring Payments – Template Files

Customizing Template Files

Recurring Payments – Manually Create Subscriptions

Table of Contents

About the Add New subscription fields

How to Manually Create Subscriptions

Recreating a Subscription and Order

Recreating a Subscription for an existing order

Manually Migrating Subscriptions

Creating a Stripe Subscription

Recurring Payments – Software Licensing Integration

Frequently Asked Questions

What happens if a license key is renewed early?

What happens if a license key was purchased without a subscription but then renewed with the purchase of a subscription? Do expiration and renewal dates get synced?

Can you sync a license key and subscription expiration dates?

What happens if renewal discounts are enabled? How will the subscription be charged?

How do discount codes affect renewal discounts?

What if a customer upgrades a license key?

How do site admins find the license key associated with a subscription?

What about bundle products that use a subscription?

How are email notifications for license keys with subscriptions handled?

How do renewal discounts work with free trials?

Recurring Payments – Subscription Emails

Email Editor

Renewal Payment Received

Payment Failed

Subscription Cancelled

Reminder Emails

Subscription Cancelled Email for Admins

Recurring Payments – Adjusting Pricing

Adjust the price of your subscription (for all customers):

Decrease the price of your subscription (for a single customer):

Stripe

PayPal

Increase the price of an upcoming renewal payment

Stripe

PayPal

Skip a renewal payment / extend a license

Stripe

Pause a subscription

FAQ

Why doesn’t EDD have these features built into the plugin?

Recurring Payments – Developer: EDD_Subscription

Table of Contents