1. Documentation /
  2. Software Add-On for WooCommerce

Software Add-On for WooCommerce

Software Add-On for WooCommerce by Kestrel gives you the ability to manage license keys and activation via your store.

To use this extension, you need to:

  • Create software products
  • Integrate your software/web app with the API (optional)

Installation

↑ Back to top
  1. Download the .zip file from your WooCommerce account.
  2. Go to: WordPress Admin > Plugins > Add New and Upload Plugin with the file you downloaded with Choose File.
  3. Install Now and Activate the extension.

More information at: Install and Activate Plugins/Extensions.

Requirements

↑ Back to top
  • WooCommerce 3.7+
  • PHP 5.6+

Creating a software product

↑ Back to top

WooCommerce Software Add-On introduces a new product type called Software that lets you sell license keys. Use this in conjunction with the downloadable type, allowing the user to download the product. When this product type is selected, a new tab called Software opens in Product data meta box menu.

Fields in this panel:

  • Product ID – A string to identify this product. This is used by the API and should be unique to the software you sell.
  • License key prefix – Optionally prefix generated license keys with this string.
  • Secret key – A random string that acts as the secret key. When creating keys via the API, you need to provide this string.
  • Version – Version number for your software.
  • Activation limit – How many times the user can activate this software. Leave blank to impose no limits.

Options specific to upgrades:

  • Upgradable product – Name of the product this software is upgrading from.
  • Upgrade price – Price for the upgrade, if it differs from the main product price.
  • Valid upgrade keys – Valid license keys that can be used for the upgrade, separated by a comma.
  • Used upgrade keys – Used keys are added here, separated by a comma.

Management tools

↑ Back to top

To manage all licenses, there are new screens and meta boxes available in the WooCommerce backend.

Software reports

↑ Back to top

Two new reports are available via WooCommerce > Reports in the admin panel. The first, ‘Overview’ in the Software tab, shows numbers of the software sales from your store.

The second report in the Software tab called ‘Activations’, shows the activation status of your software within a certain timeframe.

Screen Shot 2016-04-13 at 5.34.59 PM

License Keys Overview

↑ Back to top

This screen is available via WooCommerce > License Keys in the admin panel. It provides an overview of all licenses in the system and to which product they belong. You can see all data stored within a license.

Order License Keys

↑ Back to top

The edit order screen has a new meta box that shows all licenses bought in this order. You can also add new licenses to existing orders.

Activations per order

↑ Back to top

The edit order screen displays a new meta box that shows all license activations bought in this order. You can also toggle the status of a single activation from here.

Addon

API

↑ Back to top
This is a Developer level section. If you are unfamiliar with code and resolving potential conflicts, select a WooExpert or Developer for assistance. We are unable to provide support under our  Support Policy.

A WooCommerce-powered shop using the Software Add-On is listening for API requests via the GET parameter wc-api set to software-api.

For example:

http://woocommerce.test?wc-api=software-api&request=generate_key&…

To test the different API endpoints, the extension includes a Postman collection. Just install the Postman app on your computer, and import the collection from the file data/postman_collection.json.

Postman collection for WooCommerce Software Add-on
Postman collection for WooCommerce Software Add-on

After that, set up the request variables, including the consumer_key, consumer_secret, and the base_url.

Postman collection request variables
Postman collection request variables

Note: To obtain the values of consumer_key, and consumer_secret, you must generate an API key in your store.

Now you are ready to perform API requests to your store. For more info about Postman, visit its documentation.

The available API endpoints are the followings:

generate_key

↑ Back to top

The request_key API call can be used to generate a new license for a specific product. It returns the key and a key_id in which the license is stored in the database.

Required parameters:

  • Request = generate_key
  • secret_key
  • email
  • product_id

Optional parameters:

  • order_id
  • version
  • key_prefix
  • activations

activation

↑ Back to top

The activation API call is used to activate a single use of a license. The call must contain the email address of the license, the license key and the product ID linked to the license.

Required parameters:

  • request – Must be activation
  • email – Email in license property (not necessarily the same as billing email in the order)
  • license_key 
  • product_id – Software Product ID associated with license

Optional parameters:

  • instance – Pass to activate existing uses (previously deactivated). If empty, new activation record is created. When empty, its value is timestamped when the request made. Note that instance is not guaranteed to be unique.
  • platform – Decided by user.
  • secret_key – Not used internally. Same value is sent in response.

activation_reset

↑ Back to top

The activation_reset API call deactivates all uses of a single license. The call must contain the email address of the license, the license key and the product id linked to the license.

Required parameters:

  • request = activation_reset
  • email
  • license_key
  • product_id

deactivation

↑ Back to top

The deactivation API call deactivates a single use of a license. The call must contain the email address of the license, the license key and the instance (set by activation call) of the activation. If the instance is left blank, activation for this license is deactivated.

Required parameters:

  • request – Must be deactivation
  • email – Email in license property (not necessarily the same as billing email in the order)
  • license_key 
  • product_id – Software Product ID associated with license

Optional parameters:

  • instance – Pass to deactivate existing uses (previously activated)
  • activation_id – Pass to only deactivate a single use. In an activation request, activation_id is returned in the JSON response

check

↑ Back to top

The check API call is used to check if a license has been activated. The call must contain the email address of the license, the license key and the product id linked to the license. It will return information about the current activations.

Required parameters:

  • request = check
  • email
  • license_key
  • product_id

FAQ

↑ Back to top

Can you import your own license keys with the Software Add-On extension?

↑ Back to top

Yes! As of Version 1.6, you can now import your own license keys! Here is a CSV sample file. To import, go to Tools > Import and select the WooCommerce Software License Keys (CSV) importer.

Note this only imports licenses keys against existing orders and requires the order ID and email address to attach the license key to. It does not allow you to provide a list of license keys available for new orders.

What happens if you buy multiple copies of a software product?

↑ Back to top

You get one license for each software product purchased. If you buy two copies of a software product, you get two licenses. Each license is good for the number of activations you specify in product settings.

Can a customer access their own license keys?

↑ Back to top

There are two ways for customers to get their keys:

  • Via the Lost License page, which is automatically created and appears at /lost-license. This uses the [woocommerce_software_lost_license] shortcode to provide an email form to receive lost licenses.
  • A custom built interface that programmatically needs to integrate WordPress My Account with the Software Add-Ons API

Otherwise, only the Admin can view them.

Can I use this for downloadable digital products?

↑ Back to top

Yes!

Customer is purchasing a software-enabled product; why aren’t licenses aren’t being generated?

↑ Back to top

The order must be set to completed for the license to be generated. For products which are related to physical products, this happens after shipping fulfillment. If you want your orders to auto-complete, then the product must be virtual and downloadable.

Is it possible to sell the software for an initial price, then charge a smaller fee annually for renewals?

↑ Back to top

Yes. To do this, you need to use WooCommerce Subscriptions (separate purchase).

Is there an API test script I can look at?

Yes, there is a test script in the /examples folder. This plugin allows you to post data to the API for testing purposes.

Questions and Feedback

↑ Back to top

Have a question before you buy? Please fill out this pre-sales form.

Already purchased and need some assistance? Get in touch with a Happiness Engineer via the Help Desk.