Software Licensing – Usage Instructions

This document will walk you through the setup instructions for the Software Licensing add-on.

Supported Software

While this add-on has been built specifically for WordPress plugin and theme authors, due to the included API, most software can take advantage of the features it provides.

Once installed & activated, settings will exist in:

1. EDD Settings: Downloads → Settings → Extensions → Software Licensing

2. Product Settings: Downloads → All Downloads → Edit

Software Licensing Extension Settings

Disable Unique Activations: Check this setting if you do not require a unique identifier when activating a license key. When enabled, each activation counts against your limit and deactivating does not increase your activation limit. When disabled, customers can deactivate on a site (or system ID) and activate on a new site (or system ID), which would count as a single activation. This will remove the Manage Sites options from your Order History page.

Ignore Local Host URLs?: Allow local development domains and IPs to be activated without counting towards the activation limit totals. The URL will still be logged. See How can I ignore Local Host URLs for Activation? for details.

Selling WordPress Plugins?: Check this box if you are selling WordPress plugins and wish to enable advanced ReadMe.txt file parsing. Checking this will add a metabox to each download which allows for plugin data to be auto filled based on the included ReadMe.txt file in your plugin. Note that this is optional even if you are selling WordPress plugins.

Display Inline Upgrade Links: Check this box if you want to display inline upgrade links for customers who have upgradable purchases.

Proration Method: Specify if you want to use Cost-Based or Time-Based to calculate proration for license upgrades. See more about proration below.

Allow Renewals: Check this box if you want customers to be able to renew their license keys. They’ll also get renewal reminders to their email, and can also renew from their account page (if that page uses the [edd_license_keys] shortcode). NOTE: If the product is a Recurring product and the customer’s subscription is still active, it will automatically renew even if this option is disabled.

Enforce Email Matching: Check this box if you want to enforce email matching on license renewals. Email matching restricts renewal of licenses to the email address used to originally purchase the license. This prevents license keys from being renewed by a different customer than purchased it.

Renewal Discount: Enter a discount amount as a percentage, such as 10. Or enter 0 (or blank) for no discount. When the user is on the checkout page renewing their license, this discount will be automatically applied to their renewal purchase. NOTE: If the product is a Recurring product and the customer’s subscription is still active, it will automatically renew with this discount applied.

Disable Discount Codes on Renewals: Check this box if you want to prevent customers from using non-renewal discounts in conjunction with renewals. This will disable the option to redeem discount codes when the cart contains a license renewal.

Configuring the Product Options

License key generation is set up on a product-by-product basis, so not all products sold through your store are required to have license key generation. To set up a product to generate license keys when purchased, go to your Downloads page, then click Edit on the download you wish to configure.

Below is a screenshot of part of the user interface inside a single download for setting up software licensing for that product.

On the Download product edit screen, there will be a new “Licenses” meta box added. All setup for the license specific to the current product will be done in this box.

Note: Bundled products have slightly different options. For details on bundle product configuration, see here.

1. Check to enable license creation

Checking this box will cause license keys to be generated anytime someone purchases this product. When a license key is generated, you will be able to see it on the Downloads → Licenses page.

2. Enter the Activation Limit

This is the maximum number of times each license key can be activated. If you’d like to limit a license key to 10 uses per customer, enter 10. If you do not want to impose any limit restrictions, leave this blank or enter 0.

3. Enter the current version number

This corresponds to the current version number of your software that is available. If you are selling version 1.0, then enter 1.0 here. If the current version available is 1.5, then enter 1.5 here. This version number is used specifically for WordPress plugins and themes that have implemented the automatic upgrade system, but can also be used by any other kind of software by utilizing the included API.

4. Choose the source file to be used for automatic upgrades

This lets you set the .zip file (or perhaps other format) that is sent to users when performing an automatic upgrade. This option is used specifically for WordPress plugins and themes that have implemented the automatic upgrade system, but can also be used by any other kind of software by utilizing the included API.

If you are selling a WordPress plugin or theme, this option should be set to a .zip that contains only the necessary plugin or theme files. This .zip file is set up through the main Download Files configuration section.

5. Changelog

This is a documentation of the changes that have been made with each version of the software. Anytime a new version is released, you should add notes about what changed here. These notes will be displayed in the “What’s New” upgrade notices that users can view when upgrading their WordPress plugins or themes. If you are not selling a WordPress plugin or theme, this changelog can still be utilized via the included API.

See Software Licensing – Changelogs for more details on using the changelog.

6. License Keys

By default, Software Licensing will generate a unique 32-digit license key for the completed purchase of a licensed product. There is no limit to the number of keys that can be created.

Providing your own preset license keys

The Preset License Keys textarea will allow you to list your own available license keys, one per line.

You can enter your own keys that each purchase will pull from. Each key will be pulled from the top of the list and will no longer be available to purchasers once issued. Your list could look something like this:

customkey1
customkey2
customkey3
customkey4
customkey5

It is important to note that once your custom license keys have been exhausted, Software Licensing will automatically begin generating its own license keys again. There are only two ways to prevent this from happening:

1. Keep adding custom keys to the list so that they do not run out.
2. Use our Purchase Limit extension to ensure that the number of keys you have remaining always matches the number of remaining purchases allowed.

With the information covered in this article, you can use Software Licensing just for distributing custom license keys at the time of purchase.

Managing Sold License Keys

The Downloads → Licenses page provides an overview of all the license keys you have sold. Clicking the key will open the License Details. Several pieces of information are listed with each key:

• Key – This is the actual license key sent to the user.
  • You can generate a replacement key by clicking the reload icon next to the key in the manage details.
• Customer – This shows the product the key was purchased for and contains a link
• Status – This indicates one of these possible license statuses:
  • Active: An active status means the key has been activated by a customer, and is valid. A key is set to active only by being activated by a customer.
  • Inactive: Inactive is the default status for keys. These are keys that either have never been used or have been made available and reset to inactive manually.
  • Expired: Each key is given an expiration date when it is generated. When that date passes, the key is marked as Expired.
  • Disabled: A key will be set as Disabled when a purchase is Revoked or Refunded, or may be set so manually.
• Activation Limit – This is the number of sites (or times) the license can be activated on.
• Expiration Date – This is the date that the license expires. All license keys are (by default) valid for 1 year.
• Purchase Date – This is the date the license was purchased.
• Term – Length of time the license is available to the customer
• Related Payments – List of all payments (initial and renewal) for the license
• Upgrade Path – This shows the available upgrades, upgrade price and direct link to add to cart
• Renewal URL – This is a direct link to add the download / license to cart to renew
• Unsubscribe URL – This URL will unsubscribe the customer from renewal notices for the license

NOTE: Newly created licenses are always set as inactive. They’re not set as active until the customer activates them.

There are four filters at the top of the page, just below the page title, that let you view license keys by status.

You can Manage, Extend (renew), Disable, or Delete a license at anytime by hovering over the license and clicking the appropriate link.

Note: Deleting a license key is irreversible.

License Logs

You can also view the activation log for any license by clicking “Logs” tab in the Manage License Details. This log will show you the URL, IP, and date each time this license has been activated.

Activated Site URLs

Activated site URLs can be managed by both the store admin and/or customer via the account page.

Admins can manually manage the Site URLs on a per-license basis from the Manage License Details screen. If you wish to add or remove a site URL from the license, you can do it on this page:

Customers can also manage active sites via the account page.

License Renewals

License renewals must be enabled from Downloads → Settings → Extensions → Software Licensing.

Customers can renew licenses via Email Renewal Notices, the Checkout page or entering a license in the Renewal Form:

Sending Email License Renewal Notices

Software Licensing can automatically send renewal notice emails when license keys are within the specified expiration period set in the renewal notice options. See License Renewal & Expiration Reminder Emails for instructions on how to configure.

License key renewal notices can be manually resent on a key-by-key basis, or via a bulk action ( Downloads → Licenses). To send renewal notices for multiple keys at once, select the licenses to send a renewal for, then select “Send Renewal Notice” from the dropdown menu at the top left.

Checkout Page

If renewals are enabled, there will be a section added to your checkout screen that allows customers to enter an existing license key in order to renew it:

Renewal Form

You can add the shortcode [edd_renewal_form] to any page on your site to allow customers to input a license key that they wish to renew. Submitting the key will add the product/key to cart.

License Key History

Customers’ license keys can be shown in their account page using the [edd_license_keys] shortcode. This will display all license keys that belong to a customer (requires that they are logged in) along with relevant information about the license, such as expiration date, status, renewal options, upgrade options, and a link to view the purchase record for the license.

License Upgrades

If desired, upgrade paths can be configured for products that permit customers to upgrade their license keys.

Upgrade paths are configured on the product edit screen and look like this:

To create an upgrade path, first select the Download product that customers can upgrade to. This can be the same product or another product in your store’s catalog that has licensing enabled. If the Download you have chosen has variable prices enabled, a Price Option drop down field will appear that lets you select the price option the upgrade is for.

After selecting the product and the price option (if any), you can choose whether to prorate the license upgrade and whether to offer an additional discount.

Proration

Site admins can configure the Proration settings in Downloads → Settings → Extensions → Software Licensing. Two options are available for the Proration Method – Cost-Based Calculations and Time-Based Calculations.

Cost-Based Proration

Cost-Based Proration will charge customers the difference between the Download they currently have a subscription for, and the price of the Download they wish to upgrade to.

Example: A customer purchased a Single Site license for Product A for $89 on October 1, 2017. On March 1, 2018 the customer upgrades their license to 2-5 Sites which is $129. The customer will pay $40 to upgrade. On October 1, 2018, the subscription will renew and the customer will pay $129 for Product A (2-5 Sites) and have an active license key until October 1, 2019.

Time-Based Proration

When a customer chooses to upgrade and you’ve selected Time-Based Proration, the amount the customer will be charged to upgrade is based on the price difference between the two options, and the time left in their current subscription before it renews.

Example: A customer purchased a Single Site license for Product A for $89 on October 1, 2017. On March 1, 2018 the customer upgrades their license to 2-5 Sites which is $129. The price difference is $40 and there are 6 months left in their current subscription. The customer will pay $20 to upgrade. On October 1, 2018, the subscription will renew and the customer will pay $129 for Product A (2-5 Sites) and have an active license key until October 1, 2019.

Upgrading to a Lifetime License

For lifetime licenses, proration applies a discount to the cost of the lifetime license. Cost-Based Proration will discount the full cost of the original license form the lifetime license cost. Time-Based will calculate a pro-rated discount based on the amount of time left in the license’s term.

The expiration date of the license will not change; an upgraded license will still expire on the original expiration date whether prorated or not. An exception is if the upgrade is for a different term, in that case, the expiration date will change.

How a customer upgrades their license

When a customer wishes to upgrade their license key, they can log into their account (user accounts are required to upgrade a license) and go to their purchase history. From there, they will click on View Licenses and then on View Upgrades. Once an upgrade has been chosen, the customer will click Upgrade License to proceed to the checkout screen where they can complete their purchase.

Expiration Date

Software Licensing upgrades will not affect/change the original expiration date of the license unless the term is different.

Upgrade Revenue

Site admins can view revenue generated by license upgrades in Downloads → Reports → License Upgrades.

Adding License Keys to the Emailed Purchase Receipt

The Software Licensing add-on will make a new template tag available for the purchase receipts: {license_keys}

In order to send the license key to the buyer, this template tag must be included with the purchase receipt.

Generating License Keys on Past Purchases

If you have been selling for some time before activating Software Licensing and you wish to go back and generate license keys for those orders, you can do that by going to Downloads → Tools and using the Retroactive Licensing Processor.

You can also generate licenses on a per order basis in the Order Details:

Reports & Exports

Software Licensing provides reporting for License Renewals & License Upgrades. As well as the ability to export licenses to a csv file.

Reports

Software Licensing reports are located under Downloads > Reports > License Renewals or License Upgrades.

Export Licenses

Licenses are exported under Downloads > Tools > Import / Export instead of being located under the reports export, in order to limit what roles can access licenses. You can export all licenses or export licenses by status. The file includes license key, status, customer information, product name, dates and activation information.

Implementing With Your Software

Software Licensing can be implemented with:

• WordPress Plugins
• WordPress Themes
• Most software languages (Web and Desktop software).

Adding Automatic Upgrades to Your WordPress Product

See our documentation about how to integrate automatic upgrades for your WordPress plugins.

See our documentation about how to integrate automatic upgrades for your WordPress themes.

Steps to release a new version

1. Replace the download file with the new one by clicking “Upload a File”.
2. Then enter appropriate text into the Changelog field in the Licensing meta box.
3. Increment the version number and save the download.
4. Click Update to save changes.
5. Select the filename in the “Update File” dropdown, if the correct file is not already selected.
6. Your customer’s sites will be notified that there’s a new version, and they will be able to click Update.

ReadMe.txt Configuration for WordPress Plugins

ReadMe.txt files can be parsed to appear in the plugin update information. See Parsing ReadMe.txt files in WordPress Plugins for more information on these settings.

Working with the API for Other Kinds of Software

This add-on provides a complete API that you can use for activating and validating license keys. You can also use the API for checking if new versions of the software are available, and for downloading install files for the latest version.

For documentation for working with the API, click here.