Documentation »

Software Add-On developer reference

How your software activates, checks and deactivates Software Add-On license keys.

Beka Rice Avatar

Written by

Beka Rice

Last updated

Software Add-On answers license requests at your store’s address, so the software you sell can activate, check and deactivate its key. This page is for the developer of that software. Customizations like these aren’t covered by support, so test them on a staging site first.

For setting up products and managing keys in your store, see Get started with Software Add-On.

When you’d use this

  • Activate a key when a customer installs your software, and refuse it once the activation limit is reached.
  • Check a key on startup to see whether it’s still valid.
  • Free up an activation when the software is uninstalled or moved.
  • Create keys from your own system, such as a reseller’s store.

How requests work

Send each request to your store’s home URL with wc-api=software-api and a request name, as GET or POST parameters:

https://example.com/?wc-api=software-api&request=check&email=customer@example.com&license_key=MYAPP-0b7c3f0e-2f1a-4c8e-9a51-6c1d2e3f4a5b&product_id=MYAPP1
  • No API keys: requests don’t use WooCommerce REST API keys. The key, its activation email and the Product ID identify the license. Only generate_key needs the product’s Secret key.
  • Responses are JSON.
  • Every request except generate_key needs email, license_key and product_id to match one key exactly. The email is the key’s activation email, which is the order’s billing email unless you changed it.

Requests

activation

Activates one use of a key.

  • Required: email, license_key, product_id.
  • Optional:
    • instance: an ID for this installation, such as a machine or site ID. When left out, the current Unix timestamp is used.
    • platform: any text describing the platform, shown on the order screen.
    • secret_key: any value you choose, used only to sign the response.

If the key’s order isn’t Completed, the request fails with error 102. When the key has no activations left, it fails with error 103. Send the same instance each time the software starts; repeating an active instance doesn’t use another activation.

The response has activated (true), instance, message (such as "2 out of 3 activations remaining"), timestamp and sig.

check

Checks a key and lists its active activations.

  • Required: email, license_key, product_id.

If the key’s order isn’t Completed, the request fails with error 102.

The response has success (true), timestamp, remaining (activations left; 999999999 for a key with no limit), activations and sig. Each item in activations has activation_id, instance, activation_platform and activation_time. Deactivated activations aren’t listed.

deactivation

Deactivates one use of a key.

  • Required: email, license_key, product_id.
  • Optional: instance or activation_id (from a check response) to choose the activation.

With neither, one of the key’s active activations is deactivated. If no active activation matches, the request fails with error 104. The response has reset (true), timestamp and sig.

activation_reset

Deactivates every activation of a key and clears their platforms.

  • Required: email, license_key, product_id.

The response has reset (true), timestamp and sig. If the key has no active activations, the request fails with error 100.

generate_key

Creates a key, for example when you sell through another system.

  • Required: product_id, secret_key (the product’s Secret key) and email, which becomes the key’s activation email.
  • Optional: order_id to tie the key to an order, and version, key_prefix and activations to override the product’s Version, License key prefix and Activation limit.

The response has key (the new key, with its prefix) and key_id. Call generate_key only from your own server, never from software you ship, so the secret key stays private.

Errors

A failed request returns error, code, a timestamp, a sig and, depending on the request, activated, success or reset set to false. With WP_DEBUG on, an additional info field explains the error.

CodeError
100Invalid Request (a missing or unknown request, a missing parameter or an invalid email)
101Invalid License Key (no key matches the email, key and product ID)
102Software has been deactivated (the key’s order isn’t Completed)
103Exceeded maximum number of activations
104Invalid Instance ID (nothing to deactivate)
105Invalid security key (from generate_key)

Keep orders that have license keys. If a key’s order is deleted, activation and check requests for that key fail with a server error instead of a JSON response.

Response signature

Responses other than generate_key include sig, a checksum of the response. It’s the MD5 hash of secret=<value> followed by the response’s fields as name=value pairs, in the order they’re returned, joined with & (sig itself and the activations list aren’t included, and true and false are written as words). For a successful activation, the secret is the secret_key your request sent, or null if it sent none. For every other response, including errors, it’s null. With WP_DEBUG on, sig is the unhashed string, which helps you compare.

Test with Postman

The plugin includes a Postman collection at data/postman_collection.json in its folder, with a request for each call. Import it into Postman, then set the collection’s base_url to your store’s address, wc_api to software-api, and email, license_key, product_id and secret_key to test values. The consumer_key and consumer_secret variables can stay empty.

Keep learning