Staging sites are important to the workflow of any site, and as such, Software Licensing does not count local or staging environments towards a license’s activation count. To help Plugin and Theme creators, we support a number of staging environment configurations.

Hosting Service Staging Environments

Many hosts provide Staging environments, allowing site owners to test updates and new plugins before they add them to their live website. The Software Licensing extension for Easy Digital Downloads recognizes and supports several of the most popular hosting services in the WordPress ecosystem. Below is a list of specifically supported hosting services that provide custom staging environments.

• WP Engine
• InstaWP
• Cloudways
• Kinsta
• GoDaddy
• FlyWheel
• BlueHost
• HostGator
• SiteGround

If your host is not listed here, they may be using a more standard way of creating staging sites, allowing our Standard Detection rules to apply without specific rules.

If you are a hosting service and want to be added to this list, reach out to us through our support team and we will contact you about allowing your customers to activate Plugin & Theme licenses in your staging environments.

Standard Staging Environments

If the hosting provider does not provide a tool to generate a staging environment or is using a more standard URL for their staging environments, EDD supports the following subdomain patterns as WordPress Staging Site URLs.

• *.staging.example.org
• *.test.example.org
• staging-*.example.org
• dev.example.org

WP Environment Type

The Plugin Updater class included with Software Licensing’s sample plugin and theme supports the wp_get_environment_type()function that was added in WordPress 5.5.0. If the hosting service or custom staging environment sets the WP_ENVIRONMENT_TYPE constant accurately, Software Licensing will handle the detection of a staging environment automatically, regardless of the domain being used.

The post WordPress Staging Site Support first appeared on Easy Digital Downloads.

1. Percentage rollouts – where a percentage of sites are given access to the update.
2. Version rollouts – where the update is only made available to sites currently using a lower or higher version than what you specify.

Note: These features only apply to updates given through the Software Licensing API. They do not apply to customers who are manually downloading the latest version through their account area.

Percentage rollouts

When enabled, you can choose what percent of sites should be given access to the new version. For example, if set to 50% then half of sites that check in for an update will be given the new version, and the other half will not see that an update is available (they will keep their existing version).

This can be useful if you want to test a major release with a smaller pool of sites before making it available to everyone. You can initially set the percentage lower, and slowly raise it until you’re comfortable making it available to your entire customer base (at which point you would disable staged rollouts completely).

Version rollouts

This option allows you to set version requirements for a new update.

• If you choose less than or equal to, then customers will only be given access to this new version if they are currently on a version less than or equal to what you specify in the “Version Number” box. If you enter “2.5”, then a customer who’s on version “2.1” will see the update, but a customer who’s on version “2.6” will not.
• If you choose greater than or equal to, then customers will only be given access to this new version if they are currently on a version greater than or equal to what you specify in the “Version Number” box. If you enter “2.5”, then a customer who’s on version “2.1” will not see the update, but a customer who’s on version “2.6” will see it.

The post Software Licensing – Staged Rollouts first appeared on Easy Digital Downloads.

Request

use strict;
use warnings;

use LWP::UserAgent;
use CGI;

my $edd_action = 'check_license'; # Valid actions are activate_license, deactivate_license, get_version, check_license
my $license    = '';
my $item_name  = '';
my $url        = 'example.org'; # If you have disabled URL checking in the settings, you do not need this value

my $api = 'http://domain.com/';

my $ua       = LWP::UserAgent->new();
my $response = $ua->post( $api, { 'edd_action' => $edd_action, 'license' => $license, 'item_name' => $item_name, 'url' => $url } );
my $content  = $response->decoded_content();

my $cgi = CGI->new();
# This prints the resposne from the API, you'll need to validate the data from there using the
# HTTP status headers and the `success` response from the API
print $content;

Response

A response to the above query would be a JSON formatted string that would look something like this:

{
	"license": "valid",
	"item_name": "EDD Product name",
	"expires": "2014-10-23 00:00:00",
	"payment_id": 54224,
	"customer_name": "John Doe",
	"customer_email": "john@sample.com"
}

The post Software Licensing API – Example using Perl first appeared on Easy Digital Downloads.

Request

require 'net/http'

uri = URI('http://domain.com/')
req = Net::HTTP::Post.new(uri)

edd_action = 'check_license' # Valid actions are activate_license, deactivate_license, get_version, check_license
license    = ''
item_name  = ''
url        = 'example.org' # If you have disabled URL chaecking in the settings, you do not need this

req.set_form_data('edd_action' => edd_action, 'license' => license, 'item_name' => item_name, 'url' => url)

res = Net::HTTP.start(uri.hostname, uri.port) do |http|
  http.request(req)
end

case res
when Net::HTTPSuccess, Net::HTTPRedirection
  # check res.code for a 200 response, and then the response from the Software Licenseing API
  # will be located in res.body as a string of JSON
  puts res.body
else
  res.value
end

Response

A response to the above query would be a JSON formatted string that would look something like this:

{
	"license": "valid",
	"item_name": "EDD Product name",
	"expires": "2014-10-23 00:00:00",
	"payment_id": 54224,
	"customer_name": "John Doe",
	"customer_email": "john@sample.com"
}

The post Software Licensing API – Example using Ruby first appeared on Easy Digital Downloads.

API prerequisites

In order for this feature to work properly, the customer’s platform versions need to be sent along with the API request that checks for an update.

If you’re using our plugin updater, that means your product needs to be bundling version 1.9 or greater of the EDD_SL_Plugin_Updater class file.

If you’re using our theme updater, your product needs to be bundling version 1.2 or greater.

If you’ve built a custom integration, you need to make sure to include “php_version” and “wp_version” in your API request. Consult our API documentation for more details.

If a customer’s site does not include the platform version(s) in the API request then those requirements will not be checked and the user may still receive the update.

Configuring requirements for a product

To configure requirements for a product, edit the product via Downloads > Edit. On the right sidebar, search for a metabox called “Download Requirements”. It looks like this:

Simply enter your minimum required versions and save. Any versions left blank will not be checked or required.

Adding custom requirements

By default Software Licensing supports PHP and WordPress versions, though your own dependencies can be added with some custom code. Two steps are required:

1. Add your dependency to the metabox

Adding a new dependency is done with a simple filter like this, which needs to be added to your own site:

add_filter( 'edd_sl_platforms', function( $platforms ) {
	$platforms['your-platform-id'] = 'Your Platform Display Name';
	
	return $platforms;
} );

Replace your-platform-id with a unique, slug-friendly version of your dependency name, and replace Your Platform Display Name with the display-friendly version. Here’s an example of adding Easy Digital Downloads as a requirement:

add_filter( 'edd_sl_platforms', function( $platforms ) {
	$platforms['easy-digital-downloads'] = 'Easy Digital Downloads';

	return $platforms;
} );

Once added, your platform will appear in the metabox:

2. Include the dependency version in your API request

When checking for a new update via the API (within your product), you need to send the dependency’s current version number in the API request. To do that, you simply have to append a new argument: {your platform ID}_version.

A version check request normally looks like this:

https://YOURSITE.com/?edd_action=get_version&item_id=8&license=cc22c1ec86304b36883440e2e84cddff&url=http://licensedsite.com

But with our new argument, it would look like this:

https://YOURSITE.com/?edd_action=get_version&item_id=8&license=cc22c1ec86304b36883440e2e84cddff&url=http://licensedsite.com&easy-digital-downloads_version=1.0

Note the addition of &easy-digital-downloads_version=1.0 at the end.

If you’re using a custom updater, you can add the new argument directly to the API parameters sent with the request:

$api_params = array(
	'edd_action'                     => 'get_version',
	'license'                        => ! empty( $data['license'] ) ? $data['license'] : '',
	'item_name'                      => isset( $data['item_name'] ) ? $data['item_name'] : false,
	'item_id'                        => isset( $data['item_id'] ) ? $data['item_id'] : false,
	'version'                        => $this->version,
	'slug'                           => $data['slug'],
	'author'                         => $data['author'],
	'url'                            => home_url(),
	'beta'                           => ! empty( $data['beta'] ),
	'php_version'                    => phpversion(),
	'wp_version'                     => get_bloginfo( 'version' ),
	'easy-digital-downloads_version' => defined( 'EDD_VERSION' ) ? EDD_VERSION : '', // current version number
);

If you’re using our plugin updater class (version 1.9 or greater), then you can add this argument to the API request by using a filter. This filter needs to be part of your plugin, as it runs on your customers’ sites:

add_filter( 'edd_sl_plugin_updater_api_params', function( $api_params, $api_data, $plugin_file ) {
	/*
	 * Make sure $plugin_file matches your plugin's file path. You should have a constant for this
	 * or can use __FILE__ if this code goes in your plugin's main file.
	 */
	if ( __FILE__ === $plugin_file ) {
		// Dynamically retrieve the current version number.
		$api_params['easy-digital-downloads_version'] = defined( 'EDD_VERSION' ) ? EDD_VERSION : '';
	}

	return $api_params;
}, 10, 3 );

Be sure to replace easy-digital-downloads with the unique ID you’ve chosen for your dependency, and defined( 'EDD_VERSION' ) ? EDD_VERSION : '' with the current version number. This value needs to be able to be dynamically retrieved by the customer site.

The post Software Licensing – Minimum Requirements first appeared on Easy Digital Downloads.

Request

var data = {
		edd_action: 'check_license', // Valid actions are activate_license, deactivate_license, get_version, check_license
		license:    '',
		item_id:  encodeURIComponent(''),
		url: 'domain.com' // If you Disable URL Checking, you do not need this entry
};

// The url to the site running Easy Digital Downloads w/ Software Licensing
var postUrl = 'http://example.com/';

var requestSettings = {
	type: 'POST',
	data: data,
	dataType: 'jsonp'
};

var request = jQuery.ajax( postUrl, requestSettings );

request.always( function(response) {

var slData = jQuery.parseJSON( response.responseText );

if ( slData.success && slData.success == true ) {
	// License check returned data
	// Parse the request for the necessary action requested above
} else {
	// License check did not return successfully
}

Response

A response to the above query would be a JSON object that would look something like this:

{
	"license": "valid",
	"item_name": "EDD Product name",
	"expires": "2014-10-23 00:00:00",
	"payment_id": 54224,
	"customer_name": "John Doe",
	"customer_email": "john@sample.com"
}

The post Software Licensing API – Example using jQuery first appeared on Easy Digital Downloads.

Creating a changelog

When editing a Download in the admin area, find the Licensing meta box.  Make sure licenses are created for this Download by checking the checkbox.

One of the features that will appear when licensing is enabled is a large WYSIWYG text box. Create your changelog in this box.

As your changelog grows in length, you may find that it would be beneficial to reduce the length of the changelog when providing it via the `get_version` API request. As of Software Licensing 3.6.10, changelogs now support the ‘Read More’ tag, which will truncate the changelog when viewed over the API only. A URL to the full changelog will be placed at the end of the truncated changelog. Just insert following at the appropriate point in your changelog:

Viewing a changelog

To view the changelog of a Download that has one, first visit the product page for that Download.

Then add this to the end of the URL:

?changelog=1

And then the page will show the changelog.

The post Software Licensing – Changelogs first appeared on Easy Digital Downloads.

Table of Contents

• Instantiating Objects
• Available Properties
• Available Methods

Just like Easy Digital Downloads core, the Software Licensing extension includes a variety of action and filter hooks that you can use to tweak the behavior of the extension to better suit your needs. This documentation is written for advanced users who are already familiar with the WordPress Plugins API.

License Creation

License Length

By default, every license key is given a one year expiration date. This expiration length can easily be changed by using the edd_sl_license_exp_length filter. There are four parameters passed to the filter:

• $length (string) – The expiration length for this license. “+1 year” is default
• $payment_id (int) – The payment ID of the purchase this license was generated with
• $download_id (int) – The download/product ID this license is connected to
• $license_id (int) The ID of the newly created license

Here’s a quick example of how you might change the expiration length:

function pw_edd_sl_license_length( $length, $payment_id, $download_id, $license_id ) {
	return '+2 years'; // set length to two years from creation date
}
add_filter( 'edd_sl_license_exp_length', 'pw_edd_sl_license_length', 10, 4 );

Execute Functions After License Creation

The edd_sl_store_license action is fired just after the license key is created and all meta data is attached to it. The action takes three parameters:

• $license_id (int) – The ID of the newly created license
• $download_id (int) – The ID of the download/product this license is connected to
• $payment_id (int) – The ID of the purchase this license was created with

A sample function you might attach to this action could look something like this:

function pw_edd_sl_custom_admin_alert( $license_id, $download_id, $payment_id ) {
	
	// send admin alert

	wp_mail( get_bloginfo( 'admin_email' ), 'License Created', 'A new license key with the ID of ' . $license_id . ' has been created.' );

}
add_action( 'edd_sl_store_license', 'pw_edd_sl_custom_function', 10, 3 );

Execute Functions During License Activation

The edd_sl_activate_license action runs just after a license is activated via the API.

do_action( 'edd_sl_activate_license', $license_id, $download_id );

Execute Functions During License Checking

The edd_sl_check_license action runs just after a license is checked via the API.

do_action( 'edd_sl_activate_license', $license_id, $download_id );

Other Filters

edd_sl_license_response – applied to the response sent when remotely checking a download/product version.

edd_sl_get_license_logs – applied when the log entries for a license are retrieved.

edd_sl_encoded_package_url – applied when the encoded package URL for download packages is retrieved.

edd_sl_download_package_url – applied when the download package file for auto updates is retrieved.

edd_license_labels – applied to the post type labels when registering the edd_license post type.

Other Actions

edd_sl_before_package_download – executes just before the download file for auto upgrades is served to the browser.

Software Licensing version 3.5 and later includes an EDD_SL_License class for interacting with license key records. The EDD_SL_License class allows you to interact with license key data, update existing license keys, and create new license key records.

Instantiating Objects

To improve performance when accessing a license object you should use the wrapper method, which uses the WordPress core object caching layer. You can use either the License ID or License Key to instantiate an object. If no license exists for the provided information the wrapper method will return `false`:

// Instantiate a license via ID
$license = edd_software_licensing()->get_license( 2326422 );

// Instantiate a license via the license key
$license_by_key = edd_software_licensing->get_license( '9e21e9a885212f96cccb4d6186541332', true );

// If you pass in an invalid license ID or key you will get 'false' as a response.
$invalid_license = edd_software_licensing()->get_license( -1 );

EDD_SL_License can be instantiated with a license ID or no value when creating a new license. Here are some examples:

$license = new EDD_SL_License( 2326422 );

If you wish to create a new license:

$license = new EDD_SL_License();
$license->create( $download_id = 0, $payment_id = 0, $price_id = false, $cart_index = 0, $options = array() );

While you can directly instantiate a license with EDD_SL_License, it’s preferred to use the wrapper function for performance reasons.

The arguments necessary to create a new license will be covered below.

Available Properties

The EDD_SL_License class includes numerous accessible properties that hold information related to the license key record.

• ID – The ID number of the license record. This corresponds to the WP_Post object’s ID.
• parent – The post ID of the parent license, if any.
• name – The name of the license. This is a concatenation of the customer’s email address and the name of the product the license key is associated with.
• key – The license key itself. This is typically a 32 character string but can be anything.
• user_id – The ID of the WP_User the license key belongs to, if any.
• customer_id – The ID of the EDD_Customer the license belongs to.
• payment_id – The ID of the EDD_Payment that the license was created for.
• payment_ids – An array of payment IDs related to the license. Includes renewals and upgrades.
• cart_index – The numerical index in the cart items array of the product the license key is associated with.
• download – An EDD_SL_Download instance of the download product the license key is associated with.
• download_id – The post ID of the download product the license key is associated with.
• price_id – The ID of the price option of the download product assigned to the license key.
• activation_limit – The number of unique URLs / machines the license key can be activated on.
• sites – An array of the site URLs (or machine IDs) the license key is activated on.
• activation_count – The number of unique URLs / machines the license key is currently activated on.
• expiration – The expiration date of the license key.
• is_lifetime – Boolean flag indicating if the license is a lifetime (never expires) license.
• status – The current status of the license (active, inactive, expired).
• post_status – The post_status of the WP_Post object for the license.
• child_licenses – An array of child license keys, if any.

Each property can be accessed directly, like this:

// Access the price ID of the license
$price_id = $license->price_id;

Each property can also be updated by setting the value of the property, like so:

// Set the license activation limit
$license->activation_limit = 100;

Changes to object properties will be saved immediately without any need to call a save or update method.

Available Methods

The EDD_SL_License class includes public methods for accessing the object properties and several other help methods that may be used to access and interact with the license data.

$license->create( $download_id = 0, $payment_id = 0, $price_id = false, $cart_index = 0, $options = array() )

This method allows you to create a new license record for an existing download product and payment record.

• $download_id – This must be the ID of an existing download product
• $payment_id – This must be the ID of an existing payment record that included a purchase of $download_id
• $price_id – This is an optional price ID for $download_id if variable prices are enabled
• $cart_index – This is optional cart item index that identifies exactly which cart item this license corresponds to
• $options – An array of options for the license. Can include the following keys
  • parent_license_id
  • activation_limit
  • license_length
  • expiration_date
  • is_lifetime

The create() method can be used to create a new license key but typically will not be used manually except in very custom implementations.

$license->update( $data = array() )

This method allows you to update meta data for a license in bulk. The $data array should be a key/value pair of meta_key/meta_value.

$license->renew()

This method will trigger a renewal of a license key, extending the expiration date by one period and resetting the license status to either inactive or active.

$license->enable()

This method will re-enable a disabled license key.

$license->disable()

This method will disable a license key.

$license->get_meta( $meta_key = ”, $single = true )

This method will retrieve metadata for a license.

$license->update_meta( $meta_key = ”, $value = ”, $old_value = ” )

This method will update metadata for a license.

$license->get_renewal_url()

This method will retrieve the renewal URL for a license.

$license->is_site_active( $url )

This method will determine if the supplied URL is registered on the license.

$license->is_at_limit()

This method will check if the license has reached its activation limit.

$license->license_length()

This method will return the length of a single period for the license, such as lifetime or +1 year.

$license->add_site( $url )

This method can be used to register a new site URL on a license.

$license->remove_site( $url )

This method can be used to remove a site URL from a license.

$license->reset_activation_limit()

This method can be used to reset the activation limit on a license according to the settings on the download product.

The post Software Licensing – Developer Customizations first appeared on Easy Digital Downloads.

1. Not having version numbers in sync.

There are three places you must increment your software when releasing a new version.

A. The Licensing meta box in your download page

B. In your Updater file. Themes have a file called theme-updater.php and plugins have some code right in the main plugin file.

Themes have something like this:

	$config = array(
		'remote_api_url' => 'https://easydigitaldownloads.com', // Site where EDD is hosted
		'item_name' => 'Theme Name', // Name of theme
		'item_id' => 123, // ID of download
		'theme_slug' => 'theme-slug', // Theme slug
		'version' => '1.4', // The current version of this theme
		'author' => 'Easy Digital Downloads', // The author of this theme
		'download_id' => '', // Optional, used for generating a license renewal link
		'renew_url' => '' // Optional, allows for a custom license renewal link
	),

Note the ‘version’ in there.  It must match what you have in the Meta Box above.

Plugins have something like this:

$edd_updater = new EDD_SL_Plugin_Updater( EDD_SAMPLE_STORE_URL, __FILE__, array(
			'version' 	=> '1.4', 			// current version number
			'license' 	=> $license_key, 		// license key (used get_option above to retrieve from DB)
			'item_name'     => EDD_SAMPLE_ITEM_NAME, 	// name of this plugin
			'item_id'     => EDD_SAMPLE_ITEM_ID, 	// download ID on your site
			'author' 	=> 'Pippin Williamson'  // author of this plugin
		)
	);

Note the version number in that code as well.

C. The plugin header.

Just like every other plugin there’s a version number in the header. Example:

 <!--?php
/**
 * Plugin Name: Easy Digital Downloads
 * Plugin URI: https://easydigitaldownloads.com
 * Description: Serve Digital Downloads Through WordPress
 * Author: Pippin Williamson
 * Author URI: https://pippinsplugins.com
 * Version: 1.4

Important: All three of these version numbers must match.

2. Download name mismatch and no item_id specified

In order for the license updater to receive updates from the correct download on your site, the item_name and item_id keys are included in the array demonstrated above. It is not necessary to include both. If both are present, the item_id value will be used and item_name will be disregarded.

If only item_name is used, it is critical that the value matches exactly the download’s actual title. If the title is not an exact match, update notifications will not be shown. For this reason, we recommend using item_id instead.

3. Using a security plugin or htaccess rules that blocks the ?edd_action=get_version/activate_license requests

Some plugins and htaccess rules block get variables like the one above because they’re commonly used by attackers.  Look for these settings and make sure they’re off.

4. Why isn’t it working on my multisite setup?

The plugin needs to be activated either via the multisite network or via one of the individual sites. The custom updater only works when the plugin is activated; otherwise, the code cannot run.

The Network Admin will only see updates via the Network Admin Dashboard, if the plugin is Network Activated OR the plugin is activated on the Main site. Note, the main site is the WordPress site on the network labeled Main:

Note: The Network Admin will not see an update notice from the Network Admin Dashboard if the plugin is active on any of the other sites on the network. But the network admin can see and update the plugin via the site’s plugin list where the plugin is activated.

Only Network Administrators will see the update notice, as that is the only user level which can update plugins on multisite.

That means in order to get updates to appear on the Network Admin Dashboard, without Network Activating the plugin, the following needs to happen: 

1. Activate plugin on the Main site 
2. Activate license key on the Main site 
3. Visit Plugins page on site (or Network Admin → Home → Updates). Note, although a site admin visiting the Plugins screen will trigger the check for an update, the notice will only appear to Network Admins.
4. This caches the available plugin updates in a network-wide transient.
5. As a Network Admin, you can visit Network → Plugins and see the update.

Why do some plugins show an update notification when they are not activated on any of the multisite sites?
Plugins on wp.org will show that an update is available without being activated.

5. Why does my plugin always show there’s an update?

The updater class in your plugin had a bug before version 1.6. Update to 1.6 or higher and this issue will be resolved.

You may get the latest version of the the updater class from the sample plugin available in your purchase history at  https://easydigitaldownloads.com/your-account/.

6. Incorrect __FILE__ parameter provided to updater class

If you are extending the updater class from a file other than the main plugin file, add a define(‘YOUR_PREFIX_PLUGIN_FILE’, __FILE__ ); to the main plugin file, and then instead of calling __FILE__ as the second parameter of the new EDD_SL_Plugin_Updater class, call YOUR_PREFIX_PLUGIN_FILE there.

The post Software Licensing – Update notifications not showing first appeared on Easy Digital Downloads.

cURL is an open source command line tool and library for transferring data with URL syntax. cURL comes installed on modern versions of Mac OS X, and by default in most Linux distributions. You can test simply by typing

curl

on the command line and pressing enter. If cURL is installed you’ll see a message similar to this:

curl: try 'curl --help' or 'curl --manual' for more information

To ask cURL to make an http request for you, tell it your variables and the URL you’d like to send it to, like this:

curl
-d edd_action=check_license 
-d item_name="EDD Product Name" 
-d license=cc22c1ec86304b36883440e2e84cddff 
-d url=http://licensedsite.com 
http://YOURSITE.com/

In the above example we prefixed each variable with -d so the contents will be urlencoded. A response to the above query would be a JSON formatted string that would look something like this:

{
	"license": "valid",
	"item_name": "EDD Product name",
	"expires": "2014-10-23 00:00:00",
	"payment_id": 54224,
	"customer_name": "John Doe",
	"customer_email": "john@sample.com"
}

Flags

cURL accepts many flags to change its behavior. A full tutorial of cURL is out of the scope of this document, but take a look at these flags that may interest you:

• -u, –user USER[:PASSWORD] Server user and password
• -A, –user-agent STRING Send User-Agent STRING to server (H)
• -d, –data DATA HTTP POST data (H)
• -s, –silent Silent mode (don’t output anything)
• -o, –output FILE Write to FILE instead of stdout
• -k, –insecure Allow connections to SSL sites without certs (H)
• -K, –config FILE Read config from FILE

bash scripting

bash is a common Unix shell and allows for scripting actions. The following is a simple bash script that will prompt for several things and then run the cURL request and render the output to the screen.

#!/bin/bash

# This script accepts arguments for accessing the Easy Digital Downloads
# Software Licensing REST API, then runs cURL to get the results.

read -p "Item Name: " item_name;
read -p "EDD Action: " edd_action;
read -p "License: " license;
read -p "URL: " url;

exec curl --data-urlencode "item_name=$item_name" --data-urlencode "edd_action=$edd_action" --data-urlencode "license=$license" --data-urlencode "url=$url" http://YOURSITE.com/;

The above example could get changed to ask more questions, have different cURL flags, or anything you wish.

The post Software Licensing API – Example using cURL first appeared on Easy Digital Downloads.

To enable readme.txt parsing, first go to Downloads → Settings → Extensions → Software Licensing and enable the “Selling WordPress Plugins?” option:

This will enable a new section in the Download Edit screens that looks like this:

First you will need to upload your readme.txt file to a public location on your server (or use a Github URL). Once you’ve done that, simply enable each of the options you wish to be enabled in the update dialog.

Note, your readme.txt must follow the WordPress.org readme.txt file guidelines. If you need to test whether your readme.txt file is valid, you can use the readme.txt validation tool. WordPress.org also offers a sample readme.txt file with guidelines.

The post Software Licensing – Parsing readme.txt files in WordPress Plugins first appeared on Easy Digital Downloads.

To release a beta version, you first need to enable a beta on your download product. This can be done from the product edit screen.

Once enabled, you will be asked to provide the version number, the beta download file, and the beta changelog.

The source file is what will be given to customers when they install the beta. If selling WordPress plugins or themes, this is the file that will be delivered via the EDD_SL_Plugin_Updater and EDD_SL_Theme_Updater classes. If selling non-WordPress software, this is the download package that will be delivered in the get_version API call.

The version number should be set to your latest version number with a beta indicator. For example, if you are releasing a beta for version 3.5 of your software, set this version to 3.5-beta1. If you need to release a second beta, set the version to to 3.5-beta2 and so on. If you wish, you may also use alpha version numbers to release pre-beta versions. Version numbers should follow conventional versioning in order to ensure new version checks work as expected.

The beta changelog field allows you to specify the information that will be made available in update notifications. When selling WordPress plugins or themes, this is the update information that will be displayed through the EDD_SL_Plugin_Updater and EDD_SL_Theme_Updater classes. If selling non-WordPress software, this is the information that will be included in the changelog portion of the get_version API call.

Beta versions are made available by appending &beta=1 to the get_version API call. This means that you will need to provide some mechanism for your customers to opt into beta versions if they wish to install / download the betas.

In our own usage of Software Licensing in Easy Digital Downloads, we have added a settings screen to our Tools menu that allows customers to opt into beta versions of our extensions. Here’s a screenshot of what that looks like:

For WordPress themes and plugins, the beta=1 parameter will be added to the get_version requests automatically if the beta flag is passed to the plugin and theme updaters. Also note that the version of the plugin or theme in the code itself (the plugin header or theme header) should reflect the beta version. For example, use “2.8-beta1” instead of “2.8”. See the plugin and theme implementation guides for more information:

• Software Licensing – Updater Implementation for WordPress Themes
• Software Licensing – Updater Implementation for WordPress Plugins

The post Software Licensing – Releasing Beta Versions first appeared on Easy Digital Downloads.

When selling licensed products in a bundle, there are two options for how license keys can be generated:

1. Each product in the bundle and the bundle itself receive a license key when purchased. This connects all license keys together and synchronizes the activation limit and expiration date for all license keys in the bundle. This also permits customers to renew the entire bundle at one time. Adjusting the activation limit or expiration date on the bundle updates the expiration date and activation limit on all keys in the bundle.
2. Each product in the bundle receives a license key but the bundle does not. With this option, all activation limits and expiration dates are set separately from the individual product edit screens. Each product must be renewed separately.

If you wish to generate license keys for bundles and keep all expiration dates and activation limits synchronized (option 1 above), continue with the instructions below. Disabling licenses on bundles will cause your bundles to behave like option 2.

Enabling Licenses for Bundles

To enable license key generation on bundles, which will also cause all products in the bundle to share activation limits and expiration dates, check the box in the Licensing meta box.

Setting the activation limit and length options for the bundle will also set the limit and length for license keys generated for products in the bundle.

If you wish to set the activation limit on a per-price option basis, you can do that by enabling Variable Pricing and configuring the Price ID’s advanced settings:

After a bundle is purchased, license keys will show up like this:

Clicking “View child licenses” will show this view:

Notice how the item keys under the Bundle key are indented. This indicates that they are “child” license keys. Adjusting the activation limit or expiration date on the bundle will automatically update all child keys as well, as will renewing and disabling the license.

NOTE: Please note that currently, Bundle (or Parent) Licenses are only useful for bulk-changing license expiration dates on the Admin/Seller side. On the customer side, they are only useful for renewals. A Bundle License can be used by the customer for renewing their Bundle purchase.

A Bundle License cannot currently be used to activate “child” products contained in that Bundle. For activating “child” products, customers must use the license key that was generated for that specific product upon purchase.

Renewing Bundles

If you have license renewals enabled, bundles will also be able to be renewed at the same discount as set on the Downloads > Settings > Extensions screen.

Bundles are renewed the same way as stand alone license keys. The customer simply adds the bundle to their cart and then enters their license key in the Renewing a License field.

Note: if a customer attempts to renew a child license key of a bundle, the items in the cart will be automatically swapped with the appropriate bundle and the license key being renewed will be updated with the bundle’s key.

Generating License Keys for Bundles Sold Prior to Version 3.2

License keys for bundled products was introduced in Software Licensing version 3.2. If you have been selling bundles since before version 3.2 was released, you may wish to upgrade all past purchases to generate license keys for those bundles, making it possible for your bundle customers to easily renew their bundle purchases.

After installing the 3.2 update, you will be presented with a notice that looks like this:

This notice provides you with two options:

1. Make no changes.

If this option is selected, no changes will be made to existing bundles or past bundle purchases.

2. After your enable licensing for bundles of your choice, generate license keys for bundles with licensing enabled.

If this option is selected, you must first go through and configure the licensing options for each bundle product you have. This means following the directions above to enable licensing and setting the activation limit and length on all bundle products you wish to have bundle licensing.

Once you have enabled licensing on the bundles you want, click the generate licenses for bundles with licensing enabled link.

The post Software Licensing – Product Bundle Licensing first appeared on Easy Digital Downloads.

Request

Python 3:

import requests

payload = {
    'edd_action': 'activate_license',  # Valid actions are activate_license, deactivate_license, get_version, check_license
    'license': '', 
    'item_name': '',
    'url': 'domain.com' # If you have disabled URL checking in the settings, you do not need this
}

# Domain to send the request to.
r = requests.post("https://yoursite.com/", data=payload)

# Response JSON available via r.json()
print(r.json())

Python 2:

import httplib, urllib

params = urllib.urlencode({
    'edd_action' : 'activate_license', # Valid actions are activate_license, deactivate_license, get_version, check_license
    'license' : '',
    'item_name' : '',
    'url' : 'domain.com' # If you have disabled URL checking in the settings, you do not need this
    })

headers = {"Content-type": "application/x-www-form-urlencoded", "Accept": "text/plain"}
conn = httplib.HTTPConnection("domain.com:80") # You can use 80 (http) or 443 (https)
conn.request("POST", "/", params, headers) # /edd-sl is the Software Licensing API endpoint
response = conn.getresponse()
# You should check response.status for a `200` before proceeding with parsing the data for
# a Software Licensing response
slData = response.read()
# slData now contains a string in JSON format, to handle with however prefer
print slData
conn.close()

Response

A response to the above query would be a JSON formatted string that would look something like this:

{
	"license": "valid",
	"item_name": "EDD Product name",
	"expires": "2014-10-23 00:00:00",
	"payment_id": 54224,
	"customer_name": "John Doe",
	"customer_email": "john@sample.com"
}

The post Software Licensing API – Example using Python first appeared on Easy Digital Downloads.

Setup

In your Software Licensing extension is a directory called /samples/edd-sample-theme/updater/. This folder needs to be copied into your theme’s main folder.

Then place the following code into your theme’s functions.php:

/**
 * Load theme updater functions.
 * Action is used so that child themes can easily disable.
 */

function prefix_theme_updater() {
    require( get_template_directory() . '/updater/theme-updater.php' );
}
add_action( 'after_setup_theme', 'prefix_theme_updater' );

Please change the prefix to something that matches your theme. This code includes the updater code.

Configure Updater

Edit /updater/theme-updater.php and put in the proper values for these array elements:

$config = array(
    'remote_api_url' => 'https://easydigitaldownloads.com', // Site where EDD is hosted
    'item_name'      => 'Theme Name', // Name of theme
    'theme_slug'     => 'theme-slug', // Theme slug
    'version'        => '1.0.0', // The current version of this theme
    'author'         => 'Easy Digital Downloads', // The author of this theme
    'download_id'    => '', // Optional, used for generating a license renewal link
    'renew_url'      => '', // Optional, allows for a custom license renewal link,
    'beta'           => false, // Optional, set to true to opt into beta versions
    'item_id'        => '', // The ID of the download on the storefront site
),

Additionally, in the same file, change the edd-theme-updater text-domain to match that of your theme. Example:

    // Strings
    $strings = array(
        'theme-license'             => __( 'Theme License', 'edd-theme-updater' ),

Packaging and Sale

Your theme should be zipped just like any other theme, there’s no difference. Then create a new Download in Easy Digital Downloads.

Complete everything as you would a normal product, uploading your theme and giving it a price etc.

Then be sure to check the box to enable licensing. This is key to the update process.

Most of the settings in the Licensing meta box can be set to whatever you like, but the version number is important. When you increment the version number it will alert your customer’s sites that there’s a new version. For your initial version pick something and then only make it larger when it’s time for a new version. Example: start at 1.0 and then only go to 1.1 when you want everyone to get a new version.

Updating your theme

When you choose to release a new version, replace the old file with the new one. Then enter some text into the Changelog field in the Licensing meta box. Lastly, increment the version number and save the download. Then your customer’s sites will be notified that there’s a new version, and they will be able to click Update.

Beta versions

As of version 3.5 of Software Licensing, it is possible to release beta versions of your theme. See the documentation on how to release beta versions.

In order for customers to receive beta version notifications, ‘beta’ => true must be supplied in the $config array shown above. If you wish for your customers to have a way to opt into beta version, you will need to supply an interface for that. We recommend adding a checkbox to your theme settings page that allows customers to opt into beta versions. You can then set the beta flag in the config array dynamically based on the checked state of that checkbox.

Important notes

• The code shown on this page is purely for demonstrative purposes and is not meant to be used as is. Do not copy and paste it into your plugin and expect it to work as is.
• All function names added to your plugin need to get a unique prefix. We have used edd_sample_ throughout this example. Do not keep edd_sample_ in your own plugin, replace it with your own unique prefix.
• The names of the constants must be changed. Do not keep them as EDD_SL_ITEM_ID and EDD_SL_STORE_URL. Use your own unique constants.
• If you have issues with SSL verification when requesting updates, you can use the `edd_sl_api_request_verify_ssl` filter to disable the SSL Verification flag.

Updating Child Themes

When using automatic updating with EDD’s Software Licensing you must have an /updater/ folder in your theme folder, and it must contain a theme-updater-class.php file.

For child themes that theme-updater-class.php file needs a minor adjustment. On line 24 you’ll find 'theme_slug' => get_template(),

get_template() must be changed to get_stylesheet() for Child Themes, so that it looks like this:

Inside your child theme functions.php file you will also have to make a change:

function prefix_theme_updater() {
    require( get_template_directory() . '/updater/theme-updater.php' );
}
add_action( 'after_setup_theme', 'prefix_theme_updater' );

Change get_template_directory to get_stylesheet_directory

The post Software Licensing – Updater Implementation for WordPress Themes first appeared on Easy Digital Downloads.

If you’re using jQuery, see our jQuery example.

Sample GET Request

const url = new URL( 'https://yoursite.com/' ); // Site with Software Licensing activated.
const urlParams = new URLSearchParams( {
	edd_action: 'check_license',
	license: '59cc77ea94a2d867069a9d96142a35b8', // License key
	item_id: '356', // Product ID
	url: 'domain.com' // Domain the request is coming from.
} );
url.search = urlParams.toString();
fetch( url.toString() )
	.then( response => {
		if ( response.ok ) {
			return response.json();
		} else {
			return Promise.reject( response );
		}
	} ).then( data => {
		// Software Licensing has a valid response to parse
		console.log( 'Successful response', data );
	} ).catch( error => {
		// Error handling.
		console.log( 'Error', error );
	} );

Sample POST Request

const formData = new FormData();
formData.append( 'edd_action', 'check_license' ); // Valid actions are activate_license, deactivate_license, get_version, check_license
formData.append( 'license', '59cc77ea94a2d867069a9d96142a35b8' ); // License key
formData.append( 'item_id', '356' ); // Product ID
formData.append( 'url', 'domain.com' ); // If you disable URL checking you do not need this entry.

// Site with Software Licensing activated.
fetch( 'https://yoursite.com/', {
	method: 'POST',
	body: formData
} ).then( response => {
	if ( response.ok ) {
		return response.json();
	} else {
		return Promise.reject( response );
	}
} ).then( data => {
	// Software Licensing has a valid response to parse
	console.log( 'Successful response', data );
} ).catch( error => {
	// Error handling.
	console.log( 'Error', error );
} );

Response

A response to the above queries would be a JSON object that would look something like this:

{
    "success": true,
    "license": "valid",
    "item_id": 12534,
    "item_name": "Your Product Name",
    "expires": "2022-02-26 23:59:59",
    "payment_id": 123456,
    "customer_name": "Jane Doe",
    "customer_email": "jane@sample.com",
    "price_id": 0,
}

Sample request for older browsers

The above examples are written with modern browsers in mind. If you require IE support then you may prefer to use an XMLHttpRequest object:

// Handling a Software licensing request without jQuery in pure JavaScript. Support for older browsers.
var xhttp = new XMLHttpRequest();

// The url to the site running Easy Digital Downloads w/Software Licensing
var postUrl = 'http://yoursite.com/';

xhttp.onreadystatechange = function() {
    if (xhttp.readyState == 4 && xhttp.status == 200) {
        var slData = JSON.parse(xhttp.responseText);
        handleSoftwareLicensingResponse( slData );
    }   
}

var data = {
	edd_action: 'check_license', // Valid actions are activate_license, deactivate_license, get_version, check_license
	license: '59cc77ea94a2d867069a9d96142a35b8', // License key.
	item_id: '356', // Product ID
	url: 'domain.com' // If you Disable URL Checking, you do not need this entry
};

xhttp.open("POST", postUrl, true);
xhttp.setRequestHeader("Content-type", "application/x-www-form-urlencoded");
xhttp.setRequestHeader("Access-Control-Allow-Origin", "http://local.dev");

var values = '';
for (var key in data){
    values += key + '=' + data[ key ] + '&';
}
values = values.substring(0, values.length - 1);

xhttp.send(values);


function handleSoftwareLicensingResponse( slData ) {
    if ( slData.success == true ) {
        console.log(slData);
        // Software Licensing has a valid response to parse
    } else {
        // Invalid request was made to software licensing
    }
}

The post Software Licensing API – Example using JavaScript first appeared on Easy Digital Downloads.

Request

using System;
using System.IO;
using System.Net;
using System.Text;

namespace Rextester
{
    public class Program
    {
        public static void Main(string[] args)
        {
            // Create a request using a URL that can receive a post.
            WebRequest request = WebRequest.Create ("https://yoursite.com/");


            // Set the Method property of the request to POST.
            request.Method = "POST";


            // Create POST data and convert it to a byte array. Do not include the URL if you do URL verification in the EDD SL settings
            string postData = "edd_action=check_license&license=&item_name=&url=";
            byte[] byteArray = Encoding.UTF8.GetBytes (postData);
            request.ContentType = "application/x-www-form-urlencoded";
            request.ContentLength = byteArray.Length;
            Stream dataStream = request.GetRequestStream ();
            dataStream.Write (byteArray, 0, byteArray.Length);
            dataStream.Close ();


            // Get the response.
            WebResponse response = request.GetResponse ();
            dataStream = response.GetResponseStream ();
            StreamReader reader = new StreamReader (dataStream);


            // Read the content. This is the response from the Software Licensing API
            string responseFromServer = reader.ReadToEnd ();


            // Display the content
            Console.WriteLine (responseFromServer);


            // Clean up the streams.
            reader.Close ();
            dataStream.Close ();
            response.Close ();
        }
    }
}

Response

A response to the above query would be a JSON formatted string that would look something like this:

{
	"license": "valid",
	"item_name": "EDD Product name",
	"expires": "2014-10-23 00:00:00",
	"payment_id": 54224,
	"customer_name": "John Doe",
	"customer_email": "john@sample.com"
}

The post Software Licensing API – Example using C# first appeared on Easy Digital Downloads.

FAQs

How do you contact customers when an update is available?

It’s recommended you utilize an email marketing, like Mailchimp or ConvertKit. Wordpress is not reliable at sending mass emails, so contacting users needs to be done external to EDD/WordPress.

Is it possible to sell custom / enterprise licenses?

While there is no built-in support for selling custom or enterprise licenses that can be activated on a larger number of sites, there are workarounds to make this work. The easiest option is to bill the customer via a Stripe or PayPal invoice. Once paid, manually create an order and update the license activation limit to the number of activations you want the customer to have available.

Does Software Licensing work with Amazon S3?

Yes, it’s fully compatible with no issues and no special settings.

Do local / development environments impact activation count?

If you choose to limit the number of license activations a customer may have, it’s still possible to allow them to activate a license on their local development environment without impacting their activation count.

This allows your users to easily stay up to date in their testing and development environments while not getting free license activations.

In order for this to work two things need to happen:

1) Ignore Local Host URLs

In your WordPress admin, under
Downloads → Settings → Extensions → Software Licensing look for a checkbox that says Ignore Local Host URLs.  Make sure that’s checked.

2) Educate Customers

See this guide on how to ignore activations for development sites.

How do you create custom license key formats?

EDD License Keys are by default an md5 sum like this:

e0c7ccc47b2613c82d1073a4214deecc

If you wish to have something else, with
Software Licensing it’s as easy as making a function to create consistent unique keys and hooking into a filter called edd_sl_generate_license_key.

License key formats can really be anything you wish, as long as they’re unique and consistent. If you want keys in this format:

username_timestamp_licensekey

sdavis2702_20151015120022_e0c7ccc47b2613c82d1073a4214deecc

You can use this function:

// Example shown how to base the MD5 off of the user's email and purchase date
function pw_edd_license_md5_user_and_date( $key, $license_id, $download_id, $payment_id, $cart_index ) {

    $name      = get_user_by( 'email', edd_get_payment_user_email( $payment_id ) );
    $date      = get_post_field( 'post_date', $payment_id );
    $timestamp = strtotime($date);
    $nice_date = date( 'Yndhis', $timestamp );
    $license   = md5( $license_id );
    $key       = $name->user_nicename . '_' . $nice_date . '_' . $license;

    return $key;
}
add_filter( 'edd_sl_generate_license_key', 'pw_edd_license_md5_user_and_date', 10, 5 );

A simpler function uses only username and license key:

// prepend user's username to license key
function sd_edd_license_username_md5( $key, $license_id, $download_id, $payment_id, $cart_index ) {
    $name      = get_user_by( 'email', edd_get_payment_user_email( $payment_id ) );
    $license   = md5( $license_id );
    $key       = $name->user_nicename . '_' . $license;

    return $key;
}
add_filter( 'edd_sl_generate_license_key', 'sd_edd_license_username_md5', 10, 5 );

The most important thing to take from this document is that you can use any code that produces consistent unique strings and use those strings as license keys.

Plugin Option

There’s also a free plugin which provides a meta box on each Download, allowing you to set a custom format for each Download without having to write code. It’s called
EDD License Key Template.  Here’s a screenshot of the meta box in the admin area.

Showing a list of Customer’s license keys

The following code will allow you to retrieve and display a list of license keys for a specific Customer.

Note: The “$customer->id” should be replaced with the actual Customer ID.

$licenses = edd_software_licensing()->licenses_db->get_licenses( array(
		'number'      => -1,
		'customer_id' => $customer->id,
		'orderby'     => 'id',
		'order'       => 'ASC',
	) );

What happens if the domain of my store goes down?

Software Licensing includes which has a class named EDD_SL_Plugin_Updater. If you are including the latest version of this class it has a built in ‘health check’, so that if your site is not responding to the API requests made by your software, plugin, or theme it will not try again for a few hours later. If you intend to change domains or shut down a domain name, it would be best to release an update that uses the new domain or removes the calls to the API all together.

Common Issues

Customize Sample Code

The sample code that comes with Software Licensing has function prefixes like edd_ and edd_sl_. These should be changed to match your own plugin, and search-and-replace is an excellent way to do it, but you need to be careful of your search string.

There are functions with prefixes like edd_action_ that should not be changed. Make sure you’re only changing your own function name prefixes, and not EDD core prefixes.

Icons not showing on the Plugin Update screen

In version 3.6.5 of Software Licensing, we bundled a new version of the EDD_SL_Plugin_Updater that contained support for plugin icons in WordPress 4.9 or greater. The main reasons these icons would not show are:

1. The latest version of the Updater class has not been included in your distributed software. Learn more on integrating the updater with your plugin.
2. The product does not have a featured image.
3. The product has not had the proper thumbnail sizes created. This would happen if the featured image was uploaded prior to Software Licensing supporting plugin icons. To fix this you can use WPCLI or the Regenerate Thumbnails plugin, which will contain the proper sizes for the icon.

Troubleshooting Update Issues

If you are seeing errors when attempting to update plugins and themes from your Software Licensing store here are a few things you can check, depending on what error is being reported.

Customize your Updater

As more and more plugin developers use the Software Licensing extension to deliver updates to their products, there is a risk of a “conflict” if another plugin includes a different version of the EDD_SL_Plugin_Updater class than you are packaging with your plugin. You can rename this class to something unique to your plugin, so that it avoids conflicts. For instance, if my plugin name is “My Custom Ads”, I could rename `EDD_SL_Plugin_Updater` to `MCA_Plugin_Updater` and change any references to it.

SSL Errors

There are many errors that can be caused by SSL connectivity issues, the following are commonly seen with Software Licensing.

SSL: certificate subject name does not match

This error means that the SSL certificate installed on your site does not match your primary domain name. This can typically happen in shared hosting environments and the most commonly solution is to request a dedicated IP address from your hosting provider. If your hosting provider does not support dedicated IP addresses, then you will need to work with your hosting provider to configure a proper SSL chain that matches your primary domain, instead of a shared wildcard SSL certificate.

SSL23_GET_SERVER_HELLO:sslv3 alert handshake failure

This SSL Handshake error occurs when the OpenSSL version on the server of the site requesting the update is outdated and does not support the SSL Protocols that the store delivering the update requires. There are two ways to resolve this issue. The ideal solution is to have the site requesting the update verify that their OpenSSL software us up to date for their platform. OpenSSL is a server software that facilitates the communication over the HTTPS protocol. If this is not a possible solution, you can work with your hosting provider or server administrator to configure your web-server to accept these outdated SSL versions, but this is not ideal as it allows less secure connections to your server.

cURL error 35: SSL connect error

This specific error with Software Licensing delivering updates is usually seen when using Cloudflare’s Flexible SSL option. This option causes a chain issue with some cURL versions that exist on the client server requesting the update. There are a couple ways to fix this from the server side (without having to request the client to update their cURL version). The first is to upgrade to a paid Cloudflare SSL. The paid tier SSL Certificates from Cloudflare typically do not pose this problem. The other solut§ion is to purchase an SSL Certificate from a 3rd party and install it directly on your server.

Download failed. SSL: no alternative certificate subject name matches target host name

An error occurred while updating Resurrect: Download failed. SSL: certificate subject name '*.example.com' does not match target host name 'anotherexample.com'

This occurs when the customer’s site has an old version of either OpenSSL or cURL. The two sites then can’t communicate securely and the update fails.

The only fix is for the site with the older version of the software on their server to update to the latest versions.

Download failed. SSL peer certificate or SSH remote key was not OK

If your customers are seeing this error when updating their products, you will need to contact your web host to let them know that your SSL certificate is improperly configured:

Download failed. Service Unavailable

You’ll see this error when you are attempting to update a plugin or theme on a site that also hosts this plugin or theme. Due to the way that Software Licensing integrates with the WordPress Update API, it is not currently possible to update your own themes or plugins from the site that sells them. When WordPress installs an update, it temporarily puts your site into maintenance mode, and during that process your site cannot install its own update. To update a plugin or theme from a site that also sells it, you’ll need to manually install the update.

Download failed. Unauthorized / Too many redirects

This error occurs when updating your plugin or theme to a new version. When uploading your new version, if you add a new file with your new version and then delete the previous file row, as opposed to replacing the current version, it’s possible for this error to occur. Currently we are aware of this bug and are working to resolve it, however the simple solution in the meantime is to click the ‘Update’ button a 2nd time, to rewrite the file keys, or always replace the current file instead of adding your new files on a second file row.

Update Package Unavailable

When this error comes up, it typically means:

1. There is an issue with the license activation on the customer’s site. There are few things to check if a customer reports this error. The first is that the domain they are trying to update has been activated for the license. You can determine this by going to Downloads → Licenses. You can then search for the license key the user is trying to update and click on ‘Manage Sites’ to be sure that the domain they are on is in the list. If it’s not, you can either add it yourself from the admin, or have the customer visit their License management page and activate it themselves.
2. The other result is that a license is either expired or disabled. If this is the case the customer needs to either renew their license, or a site admin has disabled it manually.

Weird, long folder name after updater

This happens when the .zip file is created improperly. When creating the final .zip archive, it is important to zip the folder and its contents rather than just the contents of the folder.

The zip file structure should look something like this:

filename.zip

– product-name/

— file here

— another file here

In other words, the files must be in a folder and not at the top of the zip file. Repackage your file to include the folder name inside and that will fix it.

CloudFlare Integration

If you are using CloudFlare as a CDN, Caching Layer, or SSL provider, we recommend you configure CloudFlare to bypass cache for all URLs that contain the following string:

/edd-sl

This is the API endpoint for checking the license status and delivering update packages. If these endpoint URLs are cached it can cause issues with properly delivering updates to your customers.

PCLZIP_ERR_BAD_FORMAT

This error isn’t unique to the EDD Software Licensing platform but has a couple solutions that you might check. The first is that there is an adequate amount of disk space for the file to be downloaded and unpacked (assume you’ll need 2x the size of the .zip file in order to process the update). If your .zip file is 1MB you will need just over 2MB available to properly process an update. These numbers are not exactly 2x but it’s a good measure to start with.

The other thing to verify is that the .zip file is not corrupt. You can test this by transferring the .zip file to another computer (attached in an email, or via USB) and attempting to unpack it there as well. If it does not unpack on a different computer there is likely an issue with the creation of the .zip file on the original computer.

This error can also be caused by a plugin or a script that is throwing an error. When the Software Licensing API tries to create the zip package, the error is added to the zip file, breaking its structure. Normally this means your website has WP_DEBUG set to TRUE in the wp-config.php file. While it’s a good way to check for any errors, it’s best to have it set to FALSE on a live website. Alternatively, you can keep it enabled but log the errors to a file on your server, in the wp-contents/debug.log file. Do this by adding the following lines to the wp-config.php file:

define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_display', false );

The post Software Licensing – Common Issues and FAQs first appeared on Easy Digital Downloads.

There are two components to the updater:

1. The EDD_SL_Plugin_Updater.php file. This contains the class that makes the magic happen.
2. The code snippet that you place somewhere in your plugin that loads the updater provided by the EDD_SL_PLugin_Updater.php class file. This code is in the edd-sample-plugin.php file.

Step 1 – Define the updater constants

In your main plugin file, preferably near the top, or where you have other constants defined, add the following code:

// this is the URL our updater / license checker pings. This should be the URL of the site with EDD installed
define( 'EDD_SAMPLE_STORE_URL', 'https://yoursite.com' ); // IMPORTANT: change the name of this constant to something unique to prevent conflicts with other plugins using this system
// the download ID. This is the ID of your product in EDD and should match the download ID visible in your Downloads list (see example below)
define( 'EDD_SAMPLE_ITEM_ID', 123 ); // IMPORTANT: change the name of this constant to something unique to prevent conflicts with other plugins using this system

EDD_SAMPLE_STORE_URL must be set to the URL of your site that has Easy Digital Downloads installed.

EDD_SAMPLE_ITEM_ID must be set to the ID of your product in EDD. Every product has a unique number ID in your admin area. You can find this in your WordPress dashboard when editing products:

Step 2 – Include the updater class

Recommended: As more and more plugin developers use the Software Licensing extension to deliver updates to their products, there is a risk of a “conflict” if another plugin includes a different version of the EDD_SL_Plugin_Updater class than you are packaging with your plugin. You can rename this class to something unique to your plugin so that it avoids conflicts. For instance, if my plugin name is “My Custom Ads”, I could rename `EDD_SL_Plugin_Updater` to `MCA_Plugin_Updater` and change any references to it.

The update system itself is contained within the file called “EDD_SL_Plugin_Updater.php”. This file can be found in the Software Licensing plugin folder inside samples/edd-sample-plugin/. You need to copy this file into your own plugin’s folder. It can be in the same main folder as your plugin file, or in a sub-directory like /includes/. Either way, you need to refer to it properly in the code, like so:

if ( ! class_exists( 'EDD_SL_Plugin_Updater' ) ) {
	// load our custom updater if it doesn't already exist 
	include dirname( __FILE__ ) . '/EDD_SL_Plugin_Updater.php';
}

You may need to adjust the file path, depending on where you have decided to place the file within your plugin’s folder structure.

Step 3 – Instantiate the updater class

We now instantiate our updater class like this:

// retrieve our license key from the DB
$license_key = trim( get_option( 'edd_sample_license_key' ) ); 
// setup the updater
$edd_updater = new EDD_SL_Plugin_Updater( EDD_SAMPLE_STORE_URL, __FILE__, array(
	'version' 	=> '1.0',		// current version number
	'license' 	=> $license_key,	// license key (used get_option above to retrieve from DB)
	'item_id'       => EDD_SAMPLE_ITEM_ID,	// id of this plugin
	'author' 	=> 'Author Name',	// author of this plugin
        'beta'          => false                // set to true if you wish customers to receive update notifications of beta releases
) );

The license key in this example is stored in an option called “edd_sample_license_key”. You will need to adjust this to retrieve the license key from the option you have set up for your plugin. If you need help setting up an option to store the license key, take a look at the sample plugin, as it includes a fully functional settings page.

There are several parameters we pass to the EDD_SL_Plugin_Updater class:

• $api_url – this is the URL of your site that is running Easy Digital Downloads (and the Software Licensing add-on). Pass the EDD_SAMPLE_STORE_URL constant we defined earlier here.
• $plugin_file – this is the main plugin file. We suggest you use the __FILE__ magic constant provided by PHP. Note, that to do this, you must have this snippet placed in your main plugin file.
• $api_args – this is an array of options to pass to the updater:
  • version – this is the current version of the plugin that is installed. It is not the latest available version.
  • license – this is the license key retrieved from the database.
  • item_id – this is the ID of our product in Easy Digital Downloads. Just pass the EDD_SAMPLE_ITEM_ID constant we defined earlier here.
  • author – this is the name of the person or company that wrote the plugin (you!)
  • beta – this allows you to indicate if customers should receive update notifications for beta version. See Releasing beta versions for more information.

Note: beginning with Software Licensing version 3.6.12, the plugin updater class is at version 1.8, and includes documented support for auto updates, which WordPress added in version 5.5. To support auto updating, you will need to make sure your updater call is loaded on the `init` hook. Previously, the sample code recommended using `admin_init`.

The sample plugin/theme within the Software Licensing extension should be considered the authoritative source for sample code.

Step 4 – Create a settings page

For a plugin to receive updates, the license key needs to be activated. To activate a license key, the customer will need to enter the key in a field within your plugin settings; then that key needs to be sent to the Software Licensing API on your store’s site.

The sample plugin included with Software Licensing uses a settings page with a single input field. This can work quite well but is meant primarily for demonstrative purposes. It is recommended that you integrate the license key field on your existing settings pages.

This code sets up a submenu page called “Plugin License” under the Plugins menu.

There are two lines at the top of the edd_sample_license_page function:

$license = get_option( 'edd_sample_license_key' );
$status  = get_option( 'edd_sample_license_status' );

The first is the license itself and the second is the status of the license. Once we have activated our license, we will change the status (on our local site) to “active”. This is so that we can show an “Activate License” button if the license has not yet been activated, and hide the button if it has. See the screenshot below:

The idea here is that we first enter a license key and click “Save Changes”, which causes the license key to be stored in our plugin/theme options. Once the option is stored, we click the “Activate License” button to trigger the API call.

The activate button is just a simple input field with a type of “submit” and a name attribute that is different than our save button. The names must be different so that we can know when the activate license button was clicked.

Step 5 – Activate the license key

To activate a license key, we “listen” for the Activate License button to be clicked then grab the value entered in the license key field and send an activation request to the API.

If everything runs correctly after clicking the “Activate License” button, the activate button will be replaced with the word “active”, and the license status will reflect the newly activated state in your EDD store’s dashboard. If there is an error when activating the license key, the page will be reloaded and an error and message parameter will be added to the URL. We can then use the admin_notices hook (or any other applicable method) to display the error to the customer.

For example, if a customer enters an invalid license key, an error message will be displayed:

That’s it!

Important notes

• The code shown on this page is purely for demonstrative purposes and is not meant to be used as is. Do not copy and paste it into your plugin and expect it to work as is.
• All function names added to your plugin need to get a unique prefix. We have used edd_sample_ throughout this example. Do not keep edd_sample_ in your own plugin, replace it with your own unique prefix.
• The names of the constants must be changed. Do not keep them as EDD_SAMPLE_ITEM_ID and EDD_SAMPLE_STORE_URL. Use your own unique constants.
• If you are extending the updater class from a file other than the main plugin file, add a define( ‘YOUR_PREFIX_PLUGIN_FILE’, __FILE__ ); to the main plugin file, and then instead of calling __FILE__ as the second parameter of the new EDD_SL_Plugin_Updater class, call YOUR_PREFIX_PLUGIN_FILE there.
• If you have issues with SSL verification when requesting updates, you can use the `edd_sl_api_request_verify_ssl` filter to disable the SSL Verification flag.
• WordPress 5.5 introduced auto-updates for themes and plugins. If you would like to prevent your users from enabling auto-updates for your theme or plugin, you can add a snippet to your distributed code to disable auto-updates:

add_filter( 'auto_update_plugin', 'edd_sample_disable_plugin_autoupdates', 10, 2 );
function edd_sample_disable_plugin_autoupdates( $update, $plugin ) {
	if ( 'my-plugin/my-plugin.php' === $plugin->plugin ) {
		return false;
	}

	return $update;
}

add_filter( 'auto_update_theme', 'edd_sample_disable_theme_autoupdates', 10, 2 );
function edd_sample_disable_theme_autoupdates( $update, $theme ) {
	if ( 'my-theme' === $theme->theme ) {
		return false;
	}

	return $update;
}

The post Software Licensing – Updater Implementation for WordPress Plugins first appeared on Easy Digital Downloads.

Recurring Payment Emails: When a license is associated with a Recurring Payments Subscription, the Recurring Payments emails will be used in lieu of the Software Licensing renewal emails.

To set up renewal/expiration reminders, go to Downloads > Emails > Add New Email > Add License Renewal Notice.

Email Editor

See the email settings for details on editing emails.

Email Send Periods

Software Licensing comes with a standard set of send periods to allow a very customizable set of emails to be sent to customers. You can send emails with any of the following send periods:

• One Day Before/After Expiration
• Two Days Before/After Expiration
• Three Days Before/After Expiration
• One Week Before/After Expiration
• Two Weeks Before/After Expiration
• One Month Before/After Expiration
• Two Months Before/After Expiration
• Three Months Before/After Expiration
• At the time of Expiration

The License renewal email unsubscribe Feature

From time to time a customer may not want to renew their license. The {unsubscribe_url} email tag gives you the ability to provide a link in the reminder emails that allows the customer to easily unsubscribe from receiving any further emails related to that specific license. They will still receive renewal notices for any other licenses. As an administrator, you can view an unsubscribe URL for a specific license by viewing the License Details card.

The post Software Licensing – License Renewal & Expiration Reminder Emails first appeared on Easy Digital Downloads.

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.

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

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.

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.

The post Software Licensing – Usage Instructions first appeared on Easy Digital Downloads.

In This Article

Available API Requests & Parameters
WordPress Plugin & Theme Intregration
Activate a License Key
Check if a License is Valid / Active
Getting version information
Retrieving versions for multiple products at once
API examples in other languages
FAQ / Troubleshooting

There are four API request types available:

• activate_license – Used to remotely activate a license key
• deactivate_license – Used to remotely deactivate a license key
• check_license – Used to remotely check if a license key is activated, valid, and not expired
• get_version – Used to remotely retrieve the latest version information for a product

Each of the methods below works in the same way. The website URL that you have Easy Digital Download + Software Licensing installed on will act as the API endpoint. All requests to the API are done as either GET or POST requests and follow this form:

https://YOURSITE.com/?edd_action={request type}&item_id={download ID here}&license=cc22c1ec86304b36883440e2e84cddff&url={url of the site being licensed}

The request requires three parameters and has one optional parameter:

• edd_action – This is the type of request (see below)
• item_id – Use the Download ID of your download product. This is more accurate than using item_name.
  • Instead of item_id you can also use item_name, which is the name of the download instead of the ID. Passing item_id is preferred, as that’s less likely to change. If the item_name changes, your software need to be update and past referencing the old name will no longer work.
• license – This is the license key you are performing an action for
• url – (optional) This is the site URL that the API request is coming from

URL Tip Desktop Software:
The url parameter is not limited to URLs. For example desktop software could use the url parameter for a System ID or any unique text.

WordPress Plugins & Theme Intrigration:
Refer to the following documents on integrating Software Licensing API with WordPress Plugins & Themes:
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

Activate a License Key

To activate a license remotely, the URL you will use is:

https://YOURSITE.com/?edd_action=activate_license&item_id=8&license=cc22c1ec86304b36883440e2e84cddff&url=http://licensedsite.com

The item_id parameter (item_id=8) will be replaced with the actual ID of your product. You can find this in your dashboard beside the product:

The license parameter is set to the license key you wish to activate.

The response for this request will be a JSON object. If the license has been successfully activated, the response will be:

{
    "success": true,
    "license": "valid",
    "item_id": false (or Item ID if passed)
    "item_name": "EDD Product Name",
    "license_limit": 0,
    "site_count": 2,
    "expires": "2020-06-30 23:59:59",
    "activations_left": "unlimited",
    "checksum": "<md5 checksum>",
    "payment_id": 12345,
    "customer_name": "John Doe",
    "customer_email": "john@sample.org",
    "price_id": "2"
}

If the license is invalid and failed to activate, the response will be:

{
    "success": false,
    "license": "invalid",
    "item_id": false (or Item ID if passed)
    "item_name": "EDD Product Name",
    "error": "expired",
    "expires": "2020-04-28 23:59:59",
    "license_limit": 0,
    "site_count": 1,
    "activations_left": "unlimited",
    "checksum": "<md5 checksum>",
    "payment_id": 12345,
    "customer_name": "John Doe",
    "customer_email": "john@sample.com",
    "price_id": "2" 
  } 
  

Possible errors:

"missing" - License doesn't exist
"missing_url" - URL not provided
"license_not_activable" - Attempting to activate a bundle's parent license
"disabled" - License key revoked
"no_activations_left" - No activations left
"expired" - License has expired
"key_mismatch" - License is not valid for this product
"invalid_item_id" - Invalid Item ID
"item_name_mismatch" - License is not valid for this product
"site_inactive" - Site is not active for this license
"invalid" - License key does not match
"valid" - License is valid

Check if a License is Valid / Active

Checking if a license is valid and not expired is very similar to activating. This request is usually done if you need to confirm that a license is still valid after it has been activated. Licenses expire after one year (by default), so this is what you will use to check if the license has expired.

To check a license remotely, the URL you will use is:

https://YOURSITE.com/?edd_action=check_license&item_id=8&license=cc22c1ec86304b36883440e2e84cddff&url=http://licensedsite.com

The item_id parameter (item_id=8) will be replaced with the actual ID of your product. You can find this in your dashboard beside the product:

The license parameter is set to the license key you wish to check.

The response for this request will be a JSON object. If the license is active and still valid, the response will be:

{
    "success": true,
    "license": "valid",
    "item_id": false, (or Item ID if passed)
    "item_name": "EDD Product Name",
    "checksum": "",
    "expires": "2020-06-30 23:59:59",
    "payment_id": 12345,
    "customer_name": "John Doe",
    "customer_email": "john@example.org",
    "license_limit": 0,
    "site_count": 2,
    "activations_left": "unlimited",
    "price_id": "2"
}

If the license is invalid the response will be:

{
    "success": false,
    "license": "invalid",
    "item_id": false, (or Item ID if passed)
    "item_name": "EDD Product Name",
    "expires": "2014-10-23 00:00:00",
    "license_limit": 0,
    "site_count": 1,
    "activations_left": "unlimited",
    "checksum": "checksum",
    "payment_id": 54224,
    "customer_name": "John Doe",
    "customer_email": "john@sample.com",
    "price_id": "2"
}

Possible license statuses:

"disabled" - License key revoked
"expired" - License has expired
"key_mismatch" - License is not valid for this product
"invalid_item_id" - Invalid Item ID
"item_name_mismatch" - License is not valid for this product

Getting version information

Retrieving the version information allows you to remotely retrieve data about the latest version number, including changelogs and download links for update files.

To get version information for a license key:

https://YOURSITE.com/?edd_action=get_version&item_id=8&license=cc22c1ec86304b36883440e2e84cddff&url=http://licensedsite.com

The item_id parameter (item_id=8) will be replaced with the actual ID of your product. You can find this in your dashboard beside the product:

Notes regarding the request:

• If using item_name instead of item_id, enter the title of the product in Easy Digital Downloads exactly. Using item_id is more accurate.
• The license and url parameters are optional. If they are omitted, the latest version information will be retrieved but no download link will be included.
• As of Software Licensing 3.8, you can include platform versions in the request. If the platform version does not meet the minimum requirements set for the product in Easy Digital Downloads, the new_version in the response will be false instead of the new version number. php_version and wp_version are supported by default.

The response will be a JSON object that looks something like this:

{
  "new_version": "2.0",
  "stable_version": "2.0",
  "name": "Restrict Content Pro",
  "slug": "restrict-content-pro",
  "url": "https://edd.com/downloads/restrict-content-pro/?changelog=1",
  "last_updated": "2017-01-03 11:59:46",
  "homepage": "https://edd.com/downloads/restrict-content-pro/",
  "package": "",
  "download_link": "",
  "sections": "a:2:{s:11:"description";s:793:"<p>Placerat porta in enim, urna cras, adipiscing augue dis lorem, pulvinar, natoque phasellus eu tincidunt, dictumst nunc ut dignissim turpis ac, pulvinar! Massa! Sed, enim, eu ac augue placerat scelerisque! Eu cursus, ridiculus cum nec lorem, natoque lorem dictumst amet! Nunc placerat dapibus enim dignissim, nunc mattis vel? Dolor nascetur placerat ridiculus augue massa porttitor turpis auctor, etiam et nisi pid ridiculus nisi duis ac. Turpis et non, dapibus diam! Placerat vel? Et, velit turpis mus sociis arcu, vel magna. Habitasse elementum elit cum nec est, eu, montes egestas est mattis lacus, turpis urna parturient, egestas, integer augue, penatibus natoque elit, rhoncus mid elementum, integer vut turpis. Et? Nisi pid. Nec, placerat ut tristique lorem a nunc velit nunc est.</p>n";s:9:"changelog";s:0:"";}",
  "banners": "a:2:{s:4:"high";s:0:"";s:3:"low";s:0:"";}"
}

Notes regarding the response:

• If no license key is provided in the get_version request, the version information is still returned; however, the package and download values will be empty. Conversely, if a license key is provided but it does not belong to the item_id or item_name in the request, an error response will be returned with a reason as the msg value.
• A download_link will be included if a file exists regardless of the state of the license. However, the download will not work unless the license is active. This allows sites that have an expired license, to renew it, but not have to wait for the update caching to clear before getting the update.
• The sections property is a serialized array that includes the full product description and changelog. If using ReadMe.txt parsing for WordPress plugins, it will also include additional information provided through the readme file.

If you wish to retrieve information about a beta version, append &beta=1 to your API request URL, like so:

https://YOURSITE.com/?edd_action=get_version&item_id=8&license=cc22c1ec86304b36883440e2e84cddff&url=http://licensedsite.com&beta=1

Retrieving versions for multiple products at once

Retrieve versions for multiple products in one request, using the products argument. This argument accepts an array of items. Each item should contain the same arguments sent in a single request.

Here’s an example using cURL:

curl -d edd_action=get_version -d products[0][item_id]=356 -d products[0][license]=59cc77ea94a2d867069a9d96142a35b8 -d products[0][url]="https://licensedsite.com" -d products[1][item_id]=46 -d products[1][license]=5cdd12a966c498fc6e423e261fe05303 -d products[1][url]="https://licensedsite.com" https://YOURSITE.com

And here’s an example using the WordPress
wp_remote_post() function:

$response = wp_remote_post( 'https://YOURSITE.com', array(
	'body' => array(
		'edd_action' => 'get_version',
		'products'   => array(
			'my-first-plugin' => array(
				'item_id' => 356,
				'license' => '59cc77ea94a2d867069a9d96142a35b8',
				'url'     => 'https://licensedsite.com'
			),
			'my-second-plugin' => array(
				'item_id' => 46,
				'license' => '5cdd12a966c498fc6e423e261fe05303',
				'url'     => 'https://licensedsite.com'
			)
		)
	)
) );

The response will be a JSON object containing results for each of the provided products. The product keys you provided in the request will be retained in the response. Here’s an example:

{
  "my-first-plugin": {
    "new_version": "2.0",
    "stable_version": "2.0",
    "name": "My First Plugin",
    "slug": "my-first-plugin",
    "url": "https://edd.com/downloads/my-first-plugin/?changelog=1",
    "last_updated": "2021-01-03 11:59:46",
    "homepage": "https://edd.com/downloads/my-first-plugin/",
    "package": "",
    "download_link": "",
    "sections": "a:2:{s:11:"description";s:793:"<p>Placerat porta in enim, urna cras, adipiscing augue dis lorem, pulvinar, natoque phasellus eu tincidunt, dictumst nunc ut dignissim turpis ac, pulvinar! Massa! Sed, enim, eu ac augue placerat scelerisque! Eu cursus, ridiculus cum nec lorem, natoque lorem dictumst amet! Nunc placerat dapibus enim dignissim, nunc mattis vel? Dolor nascetur placerat ridiculus augue massa porttitor turpis auctor, etiam et nisi pid ridiculus nisi duis ac. Turpis et non, dapibus diam! Placerat vel? Et, velit turpis mus sociis arcu, vel magna. Habitasse elementum elit cum nec est, eu, montes egestas est mattis lacus, turpis urna parturient, egestas, integer augue, penatibus natoque elit, rhoncus mid elementum, integer vut turpis. Et? Nisi pid. Nec, placerat ut tristique lorem a nunc velit nunc est.</p>n";s:9:"changelog";s:0:"";}",
    "banners": "a:2:{s:4:"high";s:0:"";s:3:"low";s:0:"";}"
  },
  "my-second-plugin": {
    "new_version": "1.3",
    "stable_version": "1.3",
    "name": "My Second Plugin",
    "slug": "my-second-plugin",
    "url": "https://edd.com/downloads/my-second-plugin/?changelog=1",
    "last_updated": "2021-03-08 11:59:46",
    "homepage": "https://edd.com/downloads/my-second-plugin/",
    "package": "",
    "download_link": "",
    "sections": "a:2:{s:11:"description";s:793:"<p>Placerat porta in enim, urna cras, adipiscing augue dis lorem, pulvinar, natoque phasellus eu tincidunt, dictumst nunc ut dignissim turpis ac, pulvinar! Massa! Sed, enim, eu ac augue placerat scelerisque! Eu cursus, ridiculus cum nec lorem, natoque lorem dictumst amet! Nunc placerat dapibus enim dignissim, nunc mattis vel? Dolor nascetur placerat ridiculus augue massa porttitor turpis auctor, etiam et nisi pid ridiculus nisi duis ac. Turpis et non, dapibus diam! Placerat vel? Et, velit turpis mus sociis arcu, vel magna. Habitasse elementum elit cum nec est, eu, montes egestas est mattis lacus, turpis urna parturient, egestas, integer augue, penatibus natoque elit, rhoncus mid elementum, integer vut turpis. Et? Nisi pid. Nec, placerat ut tristique lorem a nunc velit nunc est.</p>n";s:9:"changelog";s:0:"";}",
    "banners": "a:2:{s:4:"high";s:0:"";s:3:"low";s:0:"";}"
  }
}

Accessing the API in other languages

Because the API uses simple HTTP POST requests, it can be accessed in just about any language. Here are some examples.

• Software Licensing API – Example using cURL
• Software Licensing API – Example using Perl
• Software Licensing API – Example using Python
• Software Licensing API – Example using Ruby
• Software Licensing API – Example using C#
• Software Licensing API – Example using JavaScript
• Software Licensing API – Example using jQuery

FAQ / Troubleshooting

Can I create Custom Formatted Keys?

The default key format is a simple md5 sum.
You may change that format to just about anything you want.

How do I prevent access to my software, plugin, or theme if the license is expired or disabled?

This license’s status does not affect the software, it merely indicates the status of the key. It’s up to the developer to read that status to do something. For example, if a key is Expired the software could choose to stop working or could choose to pop up a warning.

One exception to this is that when EDD sees an expired or disabled key attached to a download, download links, including the get_version link, will not work. Therefore, updates will no longer work via the get_version response.

If you are having trouble getting license keys to activate in your implementation of
Software Licensing, here are some tips to help resolve common issues.

Requests blocked by a security plugin

Security plugins for WordPress often have features that interfere with the license key API requests. These features tend to make the activation (and other API requests) return an unexpected response, causing the activation routine to fail.

For example, you might get a response like this from the server if you have a security plugin that is interfering:

[response] => Array
	(
		[code] => 403
		[message] => Forbidden
)

The iThemes Security plugin is known to have a setting that can cause this issue. The setting is called
Filter Suspicious Query Strings in the URL

To resolve the issue, simply disable the
Filter Suspicious Query Strings in the URL setting. If you’re not using iThemes Security, it will be named something different, though similar.

Requests blocked by special .htaccess rules

Some sites will add special rules to the .htaccess file in order to block certain IP addresses or add additional protection to the site.

If you have any special .htaccess rules in place and license keys are not activated, try removing the rules and then activating license keys. If the license keys activate properly now, you will need to adjust the rules to allow the licensing API routines to function.

Requests blocked by a coming soon or maintenance plugin

If you are using a coming soon or maintenance mode plugin, it’s likely that license keys will not be able to be activated, since the coming soon / maintenance mode plugin will block the requests. To resolve the issue, simply deactivate the maintenance mode or the coming soon plugin. If you need to leave it active, deactivate it temporarily to test the license key activation process and then reactivate the plugin.

The post Software Licensing API first appeared on Easy Digital Downloads.

Important Note

This documentation is not needed if using the Software Licensing API Updater. Only refer to this document if you are not using the updater or if this is for reference:
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.

Activating

With Software Licensing, in order for a license key to be fully utilized, it must be activated. This can happen in one of two ways:

1. A site admin can manually click the “Activate” link for the license from the Downloads → Licenses page
2. The buyer can remotely activate the license via a system in your plugin/theme/software that uses the API to trigger the activation

Note: the sample plugin and the implementation shown in this document are purely samples. The best implementations of Software Licensing take these samples and integrate them seamlessly into the existing settings page of your plugin.

In this documentation, we’re going to show you how to activate a license remotely via a system added to your WordPress plugin. The sample code we’re showing you in this example is the same exact code that is included with the sample plugin and themes, available for download after purchasing the extension.

There are two main components to activating a license remotely:

1. Saving the license key in the data (a theme or plugin option)
2. Sending the stored license key through the API to the store website for verification and activation

When a license is remotely activated, the status of the license in your site’s dashboard will be updated from “inactive” (the default state) to “active”.

Let’s first look at creating a simple options page to store our license.

This code sets up a sub-menu item in the Plugins menu called “Plugin License”. We’re using a plugins page in this example, but the code is identical for themes.

There are two lines at the top of the code:

The first is the license itself and the second is the status of the license. Once we have activated our license, we will change the status (on our local site) to “active”. This is so that we can show an “Activate License” button if the license has not yet been activated, and hide the button if it has. See the screenshot below:

The idea here is that we first enter a license key and click “Save Changes”, which causes the license key to be stored in our plugin/theme options. Once the option is stored, we click the “Activate License” button to trigger the API call.

The activate button is just a simple input field with a type of “submit” and a name attribute that is different than our save button. The names must be different so that we can know when the activate license button was clicked.

In order to activate the license, we just need to “watch” for when the activate button is clicked. The way that we do this is by setting up a function that is hooked to the “admin_init” hook, like so:

If everything runs okay after clicking the “Activate License” button, the activate button will be replaced with the word “active”, and the license status will reflect the newly activated state in your EDD store’s dashboard. If there is an error when activating the license key, the page will be reloaded and an error and message parameter will be added to the URL. We can then use the admin_notices hook (or any other applicable method) to display the error to the customer:

For example, if a customer enters an invalid license key, an error message will be displayed:

Checking

With Software Licensing you can easily check if a license key is valid at any time. You may want to do this in order to limit certain functionality in the theme or plugin to only users with a valid license key.

Checking a license key’s validity is quite simple; all it requires is that we perform a remote request to our store website with a couple of specific parameters. See the function below:

function edd_sample_theme_check_license() {
	$store_url = 'http://yoursite.com';
	$item_name = 'Your Item Name';
	$license = '834bbb2d27c02eb1ac11f4ce6ffa20bb';
	$api_params = array(
		'edd_action' => 'check_license',
		'license' => $license,
		'item_name' => urlencode( $item_name ),
		'url' => home_url(),
                'environment' => function_exists( 'wp_get_environment_type' ) ? wp_get_environment_type() : 'production',

	);
	$response = wp_remote_post( $store_url, array( 'body' => $api_params, 'timeout' => 15, 'sslverify' => true ) );
  	if ( is_wp_error( $response ) ) {
		return false;
  	}

	$license_data = json_decode( wp_remote_retrieve_body( $response ) );

	if( $license_data->license == 'valid' ) {
		echo 'valid';
		exit;
		// this license is still valid
	} else {
		echo 'invalid';
		exit;
		// this license is no longer valid
	}
}

Note: if you are consistently checking the validity of a license key, perhaps to block usage of the plugin or theme when the license expires, you MUST cache the results of the check so that the request is not performed with every page load. The Transients API is a great way to cache API responses.

Deactivating

With Software Licensing, after a license has been activated, it can also be deactivated remotely (since v1.3). Usually, the reason to deactivate a license is to permit a license to be activated on an additional site once the activation limit has been reached.

The deactivation process is nearly identical to the activation process. We perform a remote request and send the details of the license key we are deactivating. The remote request is done like so:

// data to send in our API request
$api_params = array(
	'edd_action' => 'deactivate_license',
	'license'    => '2ec66bae356be570236531ccba06a45b',
	'item_name'  => 'Sample Plugin', // the name of our product in EDD
	'url'        => home_url(),
        'environment' => function_exists( 'wp_get_environment_type' ) ? wp_get_environment_type() : 'production',
);
// Send the remote request
$response = wp_remote_post( 'http://yoursite.com', array( 'body' => $api_params, 'timeout' => 15, 'sslverify' => true ) );

The $response var will be a json object that tells us whether the deactivation request was successful or not. If it is successful, the response will be:

Note: The date/time is a timestamp unlike other json responses which will be date time.

{
	"success": true,
	"license": "deactivated",
	"item_name": "Sample Plugin",
	"expires": 1556150399,
	"payment_id": 2444,
	"customer_name": "John Doe",
	"customer_email": "john@sample.com"
}

If the license fails to be deactivated, the response will be:

{
	"success": false,
	"license": "failed",
	"item_name": "Sample Plugin",
	"expires": 1556150399,
	"payment_id": 2444,
	"customer_name": "John Doe",
	"customer_email": "john@sample.com"
}

Once a license has been successfully deactivated, the Site Count column in Downloads → Licenses will be decremented and an entry will be recorded in the log so that admins can see where a license was deactivated from.

The post Software Licensing – Activating, Checking and Deactivating License Keys in WordPress Plugins first appeared on Easy Digital Downloads.