1. Documentation /
  2. License Manager for WooCommerce - Store Owner's Guide

License Manager for WooCommerce – Store Owner’s Guide

  • Open your WordPress Dashboard
  • Navigate to Plugins → Add new
  • At the top of the screen click on Upload plugin
  • Click on Browse… and select the plugin file you previously downloaded, then click on Install Now
  • Click on Activate plugin if you wish to activate it immediately

Setup

↑ Back to top

Cryptographic secrets

↑ Back to top

The plugin stores all license keys in an encrypted fashion inside the database. During activation the plugin will create the following directory.

wp-content/uploads/lmfwc-files

Inside this directory, the plugin creates two files (defuse.txt and secret.txt). The contents of these files are used to encrypt, decrypt, and hash all license keys.

Before doing anything else, please create a backup of these two files and store them somewhere safe. If anything happens, and these files are deleted or overwritten, you will permanently lose all license keys stored in your database!

Security

↑ Back to top

The plugin will also create a .htaccess file in the above-mentioned directory. This file is used to disable direct browser access to the folder, preventing unwanted visitors from seeing your cryptographic secrets.

However, if your server is running NGINX instead of Apache, then the file is completely ignored. In this case you can either manually create a NGINX directive, or follow the guide in the optimization subsection (recommended).

We recommend that you move the cryptographic secrets into the configuration file of your WordPress website, also known as „wp-config.php“. This will reduce the amount of requests to the server file system and move the cryptographic secrets to a safer place.

To do this, open the wp-config.php file and add the following lines to it:

[php] define('LMFWC_PLUGIN_SECRET', 'secret.txt');
define('LMFWC_PLUGIN_DEFUSE', 'defuse.txt'); [/php]

Replace secret.txt and defuse.txt with their file contents, respectively. Afterwards, create a backup of these two files somewhere safe (if you haven’t already) and delete the lmfwc-files directory completely.

If your license keys are not visible anymore, then something went wrong. You can always restore the files and remove the two added lines to revert the changes.

Plugin Settings

↑ Back to top

General

↑ Back to top

The general settings section has been divided into three sub-sections: License keys, My account, and REST API.

Go to WooCommerce > Settings > License Manager > General

LICENSE KEYS

↑ Back to top

The “license keys” settings section

The “Obscure licenses” setting allows the user to configure whether license keys will be hidden in the administrator interface (backend). This will prevent anyone from taking a direct look at the plain-text, decrypted license keys.

Backend Configuration:

Obscure licenses impact:

The “Allow duplicates” setting allows the user to add duplicate license keys to the database. When adding a license key, the plugin will no longer check if said license key is already present inside the database.

The Product downloads allows you to enter change log, product version from settings (Pro)

The Download expires  allows you to download the digital/virtual products when the license has expired (Pro)

The License Expiration Format  allows you to format the date time of license expiry shown on order and my account pages.

REST API

↑ Back to top

The “REST API” settings section

The “API & SSL” setting determines whether the REST API will be accessible over insecure HTTP connections, instead of the secure HTTPS channel. This should only be used in development or testing/staging environments, never in a productive environment. Leaving this setting on, on a productive website, exposes your API calls to man-in-the-middle attacks.

The “Enable/disable API routes” setting allows the user to individually enable and disable API routes. Always turn off the REST API routes which your application does not use.

WooCommerce

↑ Back to top

The WooCommerce settings section has been divided into three sub-sections: License key delivery, Branding and My account.

Go to Dashboard > WooCommerce > Settings > License Manager > WooCommerce

License Key Delivery

↑ Back to top

The “license key delivery” settings section

The “Automatic delivery” setting determines whether license keys will be automatically delivered after the order delivery has been triggered. This is great if you want to run manual checks on the orders before sending out your licenses, however in most scenarios you will probably want to have this setting turned on.

The “Define license key delivery” setting allows the user to individually enable order status on which the license key would be delivered.

The “Stock management” setting enables automatic stock management for WooCommerce products 

Backend Configuration:

Stock Synchronize in Products:

Go to Dashboard > Products > Inventory Tab and enable track stock quantity option.

Go to License Manager Tab, enable sell license keys for this product and sell license keys from available stock option to enable automatic sync of stock.

Branding

↑ Back to top

The “Company Logo” setting allows the user to upload an image which will be displayed on a License Certificate, when it is downloaded by the end-user.

Company Logo impact:

Navigate to My Account > License keys and click on view

Click on the Download button next to certificate, to download the product license certificate.

Now your Company Logo will appear inside the pdf certificate downloaded

My Account

↑ Back to top

The “Enable License keys” setting allows the user to display License Keys tab on WooCommerce My Account page

Enable License keys impact:

The “User activation” setting allows the user to determine whether the customers should be able to activate their license keys from the “My account” page.

The “User deactivation” setting allows the user to determine whether the customers should be able to deactivate their license keys from the “My account” page.

User activation / deactivation impact:

Click on view button, this will open single license key and show activations table from where you can activate / deactivate your licenses.

The “Enable Certificates” setting allows the user to display the Download button inside the License Keys section in WooCommerce My Account page

Enable Certificates impact:

Click on view then click Download from certificate section to download your license certificate.

License Certificate

REST API

↑ Back to top

Follow the navigation to License Manager → Settings → REST API  to open this settings tab. Here you can manage all of your REST API keys. This includes:

  • Adding new REST API keys
  • Editing existing REST API keys
  • Revoking (deleting) REST API keys

Tools

↑ Back to top

Follow the navigation to License Manager → Settings → Tools to open this settings tab. On this page you will find all settings which relate to the license key export.

The “License key export” settings section

Database Migration

↑ Back to top
  • Admin can do a one-click migration of License Key from Digital License Manager to License Manager.
  • Go to Dashboard => WooCommerce => Settings => License Manager.
  • Navigate Tools => Database Migration
  • Select plugin Digital License Manager from the drop-down menu.
  • Select the checkbox below the Select plugin drop-box, if admin wants to wipe out the License Keys present in License Manager while migration of all existing License Keys in Digital License Manager, otherwise click on Migrate button without clicking on check-box.

Note: Preserve old IDs. If checked, your existing Digital License Manager database will be wiped to remove/free used IDs. Use this ONLY if you are absolutely sure what you are doing and if your app depends on the existing license/generator IDs.

Past Orders License Generator

↑ Back to top
  • Admin can generate licenses for all past orders that do not have a license assigned.
  • Go to Dashboard => WooCommerce => Settings => License Manager.
  • Navigate Tools => Past Orders License Generator
  • Search and select Generator in the Search by generator drop-down menu.
  • Click on Process.
  • Admin can check the license keys assigned to the product’s past orders placed in Orders.
  • Navigate Dashboard => WooCommerce => License keys.

BEFORE

AFTER

Application (Pro)

↑ Back to top

Overview

↑ Back to top

Admin can sell the digital application with licenses by attaching the zip file of the application to be sold along with the license. Admin also has the option to add versions of the application. On the Dashboard, navigate to WooCommerce → Applications and click on the Add New button.

This will open the Application Page, enter the name of the application and select the application type from the drop-down menu. Click on Save.

Note: Once users have selected and saved the settings, then the further options will be displayed. 

  • Navigate to the Application Releases on the right sider-bar.
  • Click on the ➕ sign.
  • Enter the Version in the Version text-box.
  • Enter a file by clicking on the Choose File button of Release file.
  • Enter a short description of amendments in this version in the text-box of Changelog. 
  • Enter the version on which your application is tested within the text-field of Test up to.
  • Enter the minimum WordPress version required to run your application in the text-field of the Minimum WordPress version.
  • Enter the minimum PHP version required to run your application in the text-field of the Minimum PHP version.
  • Select the Stable Release from the drop-down menu text-box.
  • Enter short description of the application in the Short Description text-box.
  • Enter the documentation of the application in the Documentation text-box.
  • Enter the support information about the application in the Support text-box.
  • Click on the ➕ Add button to upload the File image and Description in the Gallery.

Note: Admin can Add more than one screenshot in the Gallery option.

The saved application will appear in the Applications table.

In the Products section, go to All Products, click on the Add New button to create a new product or Edit any existing product.

  • Navigate to the Product Data → License Manager.
  • Navigate to the Select Application.
  • Select the application from the drop-down menu.
  • Click on the Update button.

Impact On Product page

All the other descriptions will be displayed in sections below

  • After the user placed the order successfully.
  • Navigate to the My Account → License Key.
  • Click on the View button.
  • Navigate to the Downloads section , where the user can see the Version and Release Date of the application and can download them by clicking on the Download button.

Activation

↑ Back to top

Overview

↑ Back to top

Go to Dashboard → WooCommerce → Activations
Here under the Status, you can see the current status of your License.

Note: Admin cannot create an Activation. It can only be done by the User-end and will display on the Admin-end in the Activations tab.

In order to Activate your license, go to My Account > License Keys, click on View on the license which you want to activate or you can also activate a license key via our API

Scroll down to Activations and click on Activate button. Your license will be Activated.

On Admin-End

Admin can check the activated licenses in the Activations table.

License Keys

↑ Back to top

Overview

↑ Back to top

You can view all of your license keys when navigating to the License Manager → License keys page. Here you can also perform a variety of actions on your license keys. Below you’ll find a table explaining the individual fields of the license key overview table.

The “License keys” table

Column Description
License key The license key string
Order The WooCommerce Order to which this license key belongs
Product The WooCommerce Product to which this license key belongs
Customer` The WooCommerce Customer to which this license key belongs
Activation Current number of license activations
Activation Maximum number of arrived license activations
Created at Timestamp of the license key creation date
Expires at Timestamp of the license key expiry date (if available)
Valid for Number of days for which the license key is valid after purchase.
Status The current license key status

Adding License Keys

↑ Back to top

There are two ways of adding license keys to the database, either one-by-one or in bulk. Both options can be found when navigating to the License Manager → License keys page.

Options for adding license keys

ADDING A SINGLE LICENSE KEY

↑ Back to top

By clicking the “Add new” button displayed in Figure 1, you will be redirected to the form for adding a single license key. Please read through the field descriptions to understand what each of them represent.

Adding a single license key

IMPORTING LICENSE KEYS

↑ Back to top

If you already have a list of license keys in a compatible format (CSV or TXT), you can add those license keys in bulk, using the „Import” button shown in Figure 3.

Adding license keys in bulk

**Note*  When importing license keys from csv include only license keys in csv not all data, see the screenshot of csv

Editing License Keys

↑ Back to top

It is possible to edit any and all license keys, even the ones already delivered to customers – so be careful! First, navigate to the License Manager → License keys page and find the license key you wish to edit. Afterwards, hover and click the „Edit” action link as shown below.

The „Edit“ license key action link

By clicking the action link you will be redirected to a new page, containing the form with the data of the license key as it currently is. Make your changes and click the „Save“ button.

Exporting License Keys

↑ Back to top

You can export your license keys in two formats: CSV and PDF. To do so, navigate to the License Manager → License keys page, mark the license keys you wish to export (by ticking their checkboxes) and select either “Export (CSV)” or “Export (PDF)” from the bulk-actions dropdown, shown below.

Available bulk actions

Generators

↑ Back to top

Overview

↑ Back to top

You can view your generators when navigating to the License Manager → Generators page. Here you can also perform a variety of actions on them. Below you’ll find a table explaining the individual fields of the license key overview table.

The “Generators” table

Column Description
Name Short generator description/name
Character map The characters used for license key generation
Number of chunks Number of individual character chunks
Chunk length The length of an individual character chunk
Maximum activation count Number of times the license key can be activated via the API
Separator The separator between the chunks
Prefix Special character added at the beginning of the license key
Suffix Special character added at the end of the license key
Expires in Number of days the license key expires in when bought

Adding Generators

↑ Back to top

Navigate to the License Manager → Generators page and click the “Add new” button at the top of the page. You will be redirected to the form. Please read the description of every field, so that you understand how each one of them affects the license key.

The “Add generator” form

Editing Generators

↑ Back to top

Navigate to the License Manager → Generators page and hover with your mouse over an existing generator. Click the „Edit” action link to open the form.

Editing a generator

Generating License Keys

↑ Back to top

By clicking the Generate button at the top of the Generators page, you will be redirected to the Generate license keys page, where you can use a specific generator to freely generate a chosen number of licenses.

The “Generate license keys” form

WooCommerce Products

↑ Back to top

Simple Product

↑ Back to top

While editing a simple WooCommerce product, a new data tab inside the product data box will appear. This tab lets you do the following:

  • Set the product to sell license keys
  • Set the amount of license keys to be delivered upon purchase
  • Choose whether to use a generator or not
  • Assign a previously created generator to the product
  • Choose whether to sell license keys from the available stock
  • View the available stock amount
  • Select the application option

The new “License Manager” WooCommerce product data tab and its options

Variable Product

↑ Back to top

The same options for simple products will also appear for each variation of a variable product. Clicking the “Variations” tab will display the currently available product variations. Simply expand the variation you wish to edit and scroll a bit down, you will find a “License Manager for WooCommerce” section as show below.

The “License Manager for WooCommerce” options for variable products

Simple Subscription(PRO)

↑ Back to top

While editing a simple WooCommerce product, a new data tab inside the product data box will appear. This tab lets you do the following:

  • Set the product to sell license keys.
  • Specify the number of license keys to be delivered upon purchase.
  • Decide whether to use a generator or not.
  • Assign a previously created generator to the product.
  • Choose whether to sell license keys from the available stock.
  • View the available stock amount.
  • Select the application to sell with license .
  • Select subscription renewal options.
  • Issue a new license upon each subscription renewal.
  • Extend the existing license with each renewal.
  • Set the license extension to the WooCommerce subscription interval.
  • Set the license extension to your custom interval.

Variable Subscription(PRO)

↑ Back to top

The same options for simple products will also appear for each variation of a variable product. Clicking the “Variations” tab will display the currently available product variations. Simply expand the variation you wish to edit and scroll a bit down, you will find a “License Manager for WooCommerce” section as show below.

  • Select the application to sell with license .
  • Select subscription renewal options.
  • Issue a new license upon each subscription renewal.
  • Extend the existing license with each renewal.
  • Set the license extension to the WooCommerce subscription interval.
  • Set the license extension to your custom interval.

WooCommerce Orders

↑ Back to top

Order License Keys

↑ Back to top

If a WooCommerce order contains licensed products, then the corresponding license keys will be used/generated once the order status is set to “Completed”. These license keys will then be visibly marked as sold/delivered in the license key overview, and inside their corresponding orders. An example of this is shown below; an order which contains two licensed products.

License keys sold by a WooCommerce order are displayed inside the order itself

Resend License Keys

↑ Back to top

If you had to edit or replace the license keys for an existing order you can easily email the customer their new license keys. When editing an order, check out the “Send license key(s) to customer” order action on the right-hand side of the screen, as shown below.

License keys sold by a WooCommerce order are displayed inside the order itself

REST API

↑ Back to top

Validating Custom Request Data

↑ Back to top
This tutorial will demonstrate how you can perform additional request data validation, and abort a REST API call if your validation did not pass. In this specific tutorial we will pass an additional UUID to the license activation request, then check if the license has previously been activated using that UUID, if that’s the case we will return an error. To sum everything up, we will demonstrate the following:
  1. Adding additional parameters to the activation request
  2. Validating the additional parameters on server-side
  3. Returning an error if validation did not pass
The first thing you need to do, is to modify your REST API license activation request. Simply add a JSON object with a key named uuid and its value. It’s also important to set the Content-Type header to application/json. Then, you will need to pass a function to the lmfwc_rest_api_validation filter. This filter takes 3 arguments. The function in that filter will look something like this: 
[php]function lmfwc_tutorial_check_uuid($result, $server, $request) {
    // Not our route, nothing to do...
    if (strpos($request->get_route(), '/lmfwc/v2/licenses/activate') === false) {
        return true;
    }
​
    // Retrieve the body parameters
    $body = $request->get_json_params();
​
    // The request body was empty, or the "uuid" property is missing.
    if (!$body || !array_key_exists('uuid', $body)) {
        return new WP_Error(
            'lmfwc_rest_data_error',
            'The UUID is missing from the request.',
            array('status' => 400)
        );
    }
​
    // Obtain the license key from the request URL
    $licenseKey = explode('/lmfwc/v2/licenses/activate/', $request->get_route())[1];
​
    // Retrieve the license object
    $license = lmfwc_get_license($licenseKey);
​
    // The license was not found
    if (!$license) {
        return new WP_Error(
            'lmfwc_rest_validation_error',
            'The license was not found.',
            array('status' => 404)
        );
    }
​
    // Check if the license key already has this UUID
    $previousActivation = lmfwc_get_license_meta($license->getId(), 'activation_uuid', true);
​
    // Throw an error if that's the case
    if ($previousActivation && $previousActivation === $body['uuid']) {
        return new WP_Error(
            'lmfwc_rest_validation_error',
            'The license was already activated using this UUID.',
            array('status' => 403)
        );
    }
​
    // Hasn't been used before, proceed
    return true;
}
add_filter('lmfwc_rest_api_validation', 'lmfwc_tutorial_check_uuid', 10, 3);[/php]
We first must check if we are on the correct route. If so, the function will then retrieve all needed variables and check if they are correct. Lastly, we obtain the activation_uuid meta key from the license, and check its value against the value provided in the request body. Please note, that the meta key name can be anything, it’s up to you to define it.

Modifying Response Data

↑ Back to top
This tutorial will demonstrate how you can modify the REST API response. In this example, we will create an activation object consisting of an ID, the client proxy (should the client be using one), and the client IP address. This activation object will be stored in the license meta when the “Activate license” request has been made. The same methods and techniques shown here can be used to modify any other response. You can even remove response data, by using the PHP unset() method. To sum everything up, we will demonstrate the following:
  1. Hooking into the lmfwc_rest_api_pre_response filter.
  2. Creating an activation object
  3. Storing our activation object inside the license meta
  4. Adding our activation object back to the response.
The process is rather simple, you need to hook into the lmfwc_rest_api_pre_response filter by using the WordPress method add_filter(). This filter takes 3 arguments. Your code would then look something like this:   
[php]function lmfwc_tutorial_modify_response($method, $route, $data) {
    // First check if we are on the correct route
    if ($route !== 'v2/licenses/activate/{license_key}') {
        return $data;
    }
​
    // Now we will save an activation object for this license/activation. The
    // activation object will be an array consisting of an ID, the proxy (if
    // The remote party is using a proxy), and the user's remote address (IP).
    // Please note that we're just using the PHP "uniqid()" method for the ID,
    // you can of course use something more appropriate.
    $activation = array(
        'id' => uniqid(),
        'http_x_forwarded_for' => $_SERVER['HTTP_X_FORWARDED_FOR'],
        'remote_addr' => $_SERVER['REMOTE_ADDR']
    );
​
    // Save to the license meta
    lmfwc_add_license_meta($data['id'], 'activation', $activation);
​
    // Add the $activation variable to the response
    $data['activation'] = $activation;
​
    // Return the result
    return $data;
}
add_filter('lmfwc_rest_api_pre_response', 'lmfwc_tutorial_modify_response', 10,

Theming

↑ Back to top

Template Structure & Overriding Templates via Theme

↑ Back to top
License Manager for WooCommerce template files contain the markup and template structure for frontend and HTML emails of your store.

How to Edit Tempalte Files

Edit files in an upgrade-safe way using overrides. Copy the template into a directory within your theme named /woocommerce keeping the same file structure but removing the /templates/ subdirectory. Example: To change the Your license key(s) heading text in the license delivery email, copy: wp-content/plugins/license-manager-for-woocommerce/templates/emails/lmfwc-email-order-license-keys.php to wp-content/themes/yourtheme/woocommerce/emails/emails/lmfwc-email-order-license-keys.php The copied file is safe to edit and will now override the default template file.
Do not edit these files within the core plugin itself as they are overwritten during the upgrade process and any customizations will be lost.

REST API

↑ Back to top

Getting Started

↑ Back to top

Requirements

↑ Back to top
WordPress permalinks must be enabled at: Settings > Permalinks

API Keys

↑ Back to top
To access the REST API routes, you will first need to create a pair of API keys. These API keys are used to access the REST API routes as a specific user. Navigate to the  WooCommerce >  Settings > License Manager  > REST API keys. Here you will be presented with the following screen: Overview of REST API keys On this screen, press the “Add key” button at the top of the page. From here on, you will be redirected to the following form: “Create REST API keys” form All fields are required. The “Description” field provides a name for this REST API key pair, which should summarize what it is the keys are being used for. The “User” field is a searchable dropdown field which determines to whom these keys will be assigned to. The “Permissions” field grants the REST API keys either read, write, or read/write permissions. After filling out the form and pressing the “Generate API key” button, you will be redirected to the following page: REST API keys have been created As the success message instructs, you should now store these keys somewhere safe, as this is the last time you will see the secret key. If you do not save the REST API keys, or lose them, you will not be able to recover them. Because the consumer secret is stored as a hash inside the database, it is impossible to revert. Should this occur, you will need to generate a pair of new REST API keys.

Test if the API is working

↑ Back to top

Making a basic request

The request URL we’ll test is wp-json/lmfwc/v2/generators. On localhost the full URL may look something like this: http://dev.wordpress.local/wp-json/lmfwc/v2/orders. Modify this to use your own site URL. In Postman, you need to set the fields for request type, request URL, and the settings on the authorization tab. For Authorization, choose basic auth and enter your consumer key and consumer secret keys from the License Manager for WooCommerce into the username and password fields. Once you’re done, hit send, and you’ll see the JSON response from the API if everything went well. The response should look like this:

POSTMAN window

That’s it! The API is working. If you have problems connecting, you may need to disable SSL verification – see the connection issues section below.

401 Unauthorized

↑ Back to top
Your API keys or signature is wrong. Ensure that:
  • The user you generated API keys for actually has access to those resources.
  • The username when authenticating is your consumer key.
  • The password when authenticating is your consumer secret.
  • Make a new set of keys to be sure.
If your server utilizes FastCGI, check that your authorization headers are properly read.

Consumer key is missing

↑ Back to top
If you are receiving the 403 HTTP status, coupled with the lmfwc_rest_no_ssl_error error message, the plugin is refusing the request because you are not using a secure (SSL) connection. You can use the plugin settings to allow the REST API to function on insecure HTTP connections. To do so, go to License Manager > Settings
Do not disable this setting on a productive environment. Allowing the REST API to be used on insecure connections will expose your license keys to Man-in-the-Middle attacks.