Home›Extensions›Software Licensing: sell plugins and themes with license keys

Software Licensing: sell plugins and themes with license keys

Software Licensing turns a TitanCart store into a place to sell your own WordPress plugins or themes. Each sale issues a license key, the customer receives it by e-mail and on the order page, activates it on a set number of sites, your plugin checks the key against your store, and updates are delivered to the customer’s WordPress dashboard from the releases you upload. It is a separately purchased extension (it is not in the TitanCart Pro bundle) and it needs TitanCart Pro on the store that runs it. This guide, written for version 3.2.6, takes you from installing it to a customer updating your plugin from their own dashboard, and is honest about what this release does not do yet.

Who this is for: you are the developer or seller of the software. If you bought a TitanCart extension and want to know where your own key goes, read Activating a license key instead.

1. What it does, and what you need

  • Keys per sale. When an order containing a licensed product reaches Processing or Completed, one key is created per licensed line. The keys go out in the order confirmation e-mail and appear on the order-received page and the order’s page in My Account; for a signed-in customer they are also attached to the account.
  • Seats. Each key allows a number of site activations you choose per product (or unlimited). Customers can release a site themselves to move to a new domain.
  • Terms. A key never expires, or expires after one or two years, with an optional reminder e-mail before the date. With the Subscriptions extension, a key follows the subscription instead (section 8).
  • Updates. You upload each new version of your plugin to the store; a small drop-in class inside your plugin asks the store for updates and shows them under Dashboard → Updates on the customer’s site.
  • Downloads. The customer downloads the current release from My Account → Licenses through single-use links.

Requirements: TitanCart Pro, WordPress 6.0 or newer and PHP 8.0 or newer. The extension works on any TitanCart product; it marks the product as a digital download for you (section 4). Customers do not need an account to receive a key, but only an account gives them the My Account page where they release sites and download later releases (section 5).

2. Install it and enter its key

  1. Download the ZIP from your purchase on the TitanCart Marketplace and install it under Plugins → Add New Plugin → Upload Plugin, then activate it. If TitanCart is not active you will see “Software Licensing requires TitanCart to be installed and active.”
  2. Go to TitanCart → Extensions → Installed Extensions, find Software Licensing in the purchased-extensions card, enter the key from your purchase and click Activate. The key is what entitles the store to updates of the extension itself; see Activating a license key.

A new top-level Licensing menu appears in the WordPress sidebar, with Dashboard, Product Settings, Plugins, Versions, Licenses and Settings. Only administrators see it.

3. Register your plugin and upload a release

A licensed product is linked to a registered plugin, and the plugin is what holds the releases. Do this before you touch the product.

  1. Open Licensing → Plugins. Under Upload New Plugin or Theme, choose the ZIP of your plugin exactly as a customer would install it and click Upload & Register. The name, slug, author and version are read from the plugin header inside the ZIP, and that first upload becomes the first release, numbered from the header. Theme ZIPs are accepted too.
  2. The plugin now appears in the table (Name, Slug, Author, Releases, Latest, Created) with Versions and Delete actions.
  3. For every later release open Licensing → Versions, pick the plugin and fill in Upload New Version: Version Number, the ZIP File, a Changelog (shown to customers in the update details) and optionally Min WP and Min PHP. Click Upload Release. The changelog is required: an empty one is refused with “Please enter a changelog — it is what every store sees on its Updates screen. Nothing was uploaded.”
  4. To correct a changelog after the fact, click Edit on the release in the table; the form opens above the table, and an empty changelog is refused here too.

Uploaded ZIPs are stored under the WordPress uploads folder in a directory that is blocked from direct web access; customers only ever receive them through single-use download links. The Versions table shows whether each release’s ZIP is still on disk, so you can spot a file that was deleted by hand.

The slug matters. The slug recorded here must equal the folder name your plugin installs into (for a plugin at wp-content/plugins/my-plugin/my-plugin.php the slug is my-plugin). The update check and the product link both match on it.

Note: “latest” is the release with the highest version number (3.2.10 is newer than 3.2.9), whatever order they were uploaded in; two releases with the same number are told apart by their upload date. Earlier versions of the extension went by upload date instead.

4. Turn on licensing for a product

Create the product in TitanCart as usual (name, price, description, image; see Adding your first product). There is no Licensing tab in the product editor; licensing is switched on from its own page.

  1. Open Licensing → Product Settings. Every product in the store is listed; click Configure on yours.
  2. Tick Enable Licensing (“Generate license keys when this product is purchased”).
  3. Max Site Activations — how many sites one key may be active on. 0 means unlimited.
  4. License Expiration — Never, 1 Year, 2 Years or Lifetime. Never and Lifetime behave identically. A dated term is counted from the moment the key is issued, which is when the order reaches Processing or Completed.
  5. Plugin Slug — the folder name again; it must match the registered plugin.
  6. Linked Plugin — pick the plugin you registered in section 3. Without a link the customer gets a key but no download and no updates.
  7. Click Save Settings.

Saving with licensing enabled also sets the product to a digital download with no shipping, and tells you so: “This product was set to digital (downloadable, no shipping) to match licensing.” You can sell several licensed products from one plugin (for example a single-site and a five-site edition) by giving them different activation limits and the same Linked Plugin.

5. What your customer gets

The customer buys the product at your normal checkout and pays with any gateway. Once the order is Processing or Completed (see Order statuses for which payments move an order there automatically), the key exists. Keys look like A1B2-C3D4-E5F6-0789: four groups of four characters. An order with nothing to pay — a 100 % coupon, say — moves to Processing on its own (TitanCart 0.2.79 or newer), so it issues its keys like a paid one.

The keys reach the customer three ways, account or not:

  • In the order confirmation e-mail, as a Your License Keys table (product, key, expiry) followed by a one-line To activate: made of your activation steps (section 10). For card and wallet payments the key is issued before the confirmation is composed, so it is in that e-mail. For an order paid offline (Cash on Delivery, Bank Transfer, Check) the confirmation goes out at placement, before any key exists; when you move that order to Processing, the keys are sent in a separate e-mail, Your license keys for order ….
  • On the order-received page, as a Your License Keys card under the payment details.
  • On the order’s page under My Account → Orders, the same card, for a signed-in customer.

Signed in, the customer also opens My Account → Licenses (the item is added after Orders). The page is headed My Licenses and shows one card per key:

  • the product name and current version, and the status badge (Active, Inactive or Expired);
  • License Key with a copy button;
  • Activations as used / allowed (an unlimited key shows the infinity sign), Expires (or Never) and Purchased;
  • Active sites, each with when it was last seen and a Release button. The hint reads “Moved to a new domain? Release the old site to free its seat.” Releasing frees the seat immediately.
  • Download Plugin, shown while the key is active and unexpired and the product is linked to a plugin. Each click issues a fresh link that works once and for five minutes; the download is recorded against the order (section 9).

An inactive or expired key shows “License is inactive. Renew to download updates.” (or expired) instead of the download button. There is no renew button in this release; see section 8 for what renewal looks like. Under the list, a How to activate your license box prints the activation steps you write under Licensing → Settings (section 10).

Guest orders. A guest gets the keys by e-mail and on the order-received page, and can activate them from your plugin’s settings screen like anyone else. What a guest does not get is the My Account page: no list of keys, no Release button and no Download Plugin button, so a lost e-mail or a change of domain means contacting you (you can release a seat for them under Licenses → Sites, section 7). If you would rather every buyer had that page, tick Disable anonymous checkout under Settings → General Settings → Checkout, or say in the product description that an account is recommended.

6. Make your plugin talk to the store

Two things happen on the customer’s site: the key is activated against your store, and updates are fetched from it. The extension ships a drop-in for the second part only; you write the first.

Updates: the drop-in

Copy includes/class-pp-update-client.php from the extension into your plugin and initialise it with the slug you registered, your main plugin file, the customer’s key and your store’s API base URL:

require_once __DIR__ . '/class-pp-update-client.php';

PluginPress_Update_Checker::init( array(
    'slug'        => 'my-plugin',
    'plugin_file' => __FILE__,
    'license_key' => get_option( 'my_plugin_license_key' ),
    'api_url'     => 'https://yourstore.com/wp-json/pluginpress/v1/',
) );

The class hooks WordPress’s plugin update check, asks your store’s update-check endpoint whether a newer release exists for that slug and key, caches the answer for six hours, and shows the update with your changelog under Dashboard → Updates. When the key is invalid, inactive or expired, or was issued for a different product than the slug being checked (wrong_product), the store answers with an error and the update is not offered. The drop-in handles plugins only; it does not update themes, and it does not activate or deactivate keys.

Activation: your settings screen

Add a settings field for the key to your plugin and, when the customer saves it, call the store:

  • POST /wp-json/pluginpress/v1/license/activate with license_key and site_url (the customer’s home URL; scheme, www. and trailing slash are ignored when matching). A success reply includes activations, max and expires_at. Errors come back with an error code: invalid_key (“License key not found.”), inactive_key, expired_key (“License key has expired.”) or activation_limit (“Activation limit reached (N).”). Activating the same site twice reuses its seat (“Already activated on this site.”).
  • POST /license/deactivate with the same two fields when the customer removes the key or deactivates your plugin, so the seat is freed.
  • GET /license/check?license_key=…&site_url=… to re-validate on a schedule. It returns valid (true or false), status (active, inactive, expired, invalid or limit_reached), the product name, the current plugin_version, expires_at, activation counts and whether this site is activated.

The activate and deactivate endpoints are rate-limited per caller address (30 requests a minute, and eight wrong keys a minute); over the limit they return HTTP 429 with a Retry-After header. While Enable REST API is unticked under Licensing → Settings (section 10), every one of these endpoints answers HTTP 503 api_disabled, and the customer download links answer 503 with “The licensing API is switched off on this store.” The full endpoint list with one-line descriptions is on Licensing → Dashboard under API Endpoints, and the store’s base URL is shown on Licensing → Settings as API Base URL.

7. Manage keys

Licensing → Licenses lists every key with the customer, product, status, activations used, expiry and actions. Search by key or e-mail address (“Search key or email…”) and filter by All, Active, Inactive or Expired.

  • Revoke sets a key to inactive; the customer’s plugin fails its next check and loses updates. Re-activate reverses it. A key whose expiry date has passed cannot be re-activated: the row reads Expiry date passed instead, because its date is unchanged and it would expire again at the next check. There is no screen to edit a key’s expiry or seat count after it is issued.
  • Sites expands the key’s active sites with when each was activated and last seen; Release seat frees one after you type RELEASE to confirm.
  • + Issue licence creates a key by hand: pick the Product (licensing-enabled products only), a Customer by e-mail or username (an existing WordPress user), Seats (blank uses the product’s default, 0 is unlimited), an Expires date or Never expires, and optionally a Custom key (8 to 64 characters, capitals, digits and hyphens). A hand-issued key never renews and is not e-mailed (there is no order to put it in); the customer finds it under My Account → Licenses, or you send it yourself.

The Dashboard page shows three counters: Active Licenses, Active Site Activations and Registered Plugins.

8. Terms, subscriptions and renewals

With a fixed term (1 Year or 2 Years) the key expires on its anniversary. With Expiry Reminder Email on (section 10), the customer is e-mailed once per key, the set number of days before that date, with the subject Your [product] license expires on [date]; a guest order’s reminder goes to its billing address. In this release there is no renewal purchase for a term key: the customer sees “Renew to download updates” but nothing to click, so you either sell terms as Never (lifetime updates) or sell the product as a subscription.

With the Subscriptions extension installed, a licensed product sold on a plan behaves differently and renewal works end to end:

  • the seat count comes from the plan’s site limit when the plan defines one;
  • the key expires three days after the subscription’s next billing date (a short grace period), and each successful renewal order pushes the expiry on by one billing period; a key on a live subscription gets no expiry reminder, since the renewal is automatic;
  • the subscription’s status drives the key: on hold or cancelled makes it inactive, expired makes it expired, active makes it active again;
  • switching plans resizes the seats, but never below the number of sites currently active.

9. Downloads and refunds

Every download is logged against the order. Once a customer has downloaded the software, a refund of that order is refused automatically with: “Not eligible for refund: the purchased software was downloaded on …. Per the refund policy, orders are only refundable if the product has never been downloaded. An exchange or store credit may be offered instead.” This guard has no switch. Say so in your refund policy; the [pp_refund_policy] shortcode prints the Refunds section of each active agreement under Settings → Download Agreements, which is where that policy text lives. A refund before any download goes through as normal (see Refunds and cancellations).

10. Settings

Licensing → Settings has four rows.

  • Enable REST API (“Allow external API access for license checks and updates”) — on by default. Unticked, every customer site stops validating its keys and receiving updates from this store until you tick it again (the page says so under the box), and the customers’ download links stop working too. It is an emergency switch, not something to leave off.
  • Expiry Reminder Email (“Email customers before license expires”) with Days before: (1 to 365, default 7) — one e-mail per key, sent by a daily task once the key is inside the window, to the customer or to a guest order’s billing address. Keys renewed automatically by a subscription are not reminded.
  • Activation steps — one step per line, shown under “How to activate your license” on My Account → Licenses and under the keys in the order e-mail. Write the steps for your plugin here (where the key field is, what to click). Leave it empty to restore the default four lines, which describe a TitanCart extension rather than your product.
  • API Base URL — the address to give your plugin (section 6).

11. Not in this release

  • A My Account page for guest orders (section 5), and keys in the e-mail that Revoke the current download links and email a fresh set sends from the order page in Sales — that e-mail carries download links only.
  • Renewing a fixed-term key without Subscriptions.
  • Editing a key’s seats or expiry after it is issued; notes on a key; exporting keys.
  • Theme updates through the drop-in (theme ZIPs can be registered and downloaded, but the update client handles plugins only).
  • Rolling back to an earlier release, outbound webhooks on license events, and a download-history view. Developers can hook the actions pp_license_created, pp_license_activated, pp_license_deactivated, pp_license_renewed and pp_license_issued_manually inside PHP.

Troubleshooting

  • The order is paid but no key appears. Keys are created when the order reaches Processing or Completed. Check the order’s status under Sales, and that the product has Enable Licensing ticked under Licensing → Product Settings.
  • The customer has a key but no Download Plugin button. The product has no Linked Plugin, or the key is inactive or expired.
  • The customer never got the keys e-mail. Ask them to check spam first. Then open the order under Sales: if it is still Pending, the key does not exist yet; if it was paid offline and you moved it to Processing, the keys went out in their own e-mail at that moment. The keys are also on the order-received page and, for a signed-in customer, on the order’s page in My Account.
  • Updates never show on the customer’s site. The slug in the drop-in, the registered plugin and Product Settings must all be the plugin’s folder name; the customer’s key must be active and issued for that product (a key for another of your products is refused); Enable REST API must be ticked; and the drop-in caches for six hours, so a just-uploaded release can take that long to appear (the customer can force it from Dashboard → Updates → Check again).
  • “Activation limit reached”. The customer can free a seat under My Account → Licenses → Release, or you can under Licenses → Sites → Release seat.
  • A customer bought as a guest and wants to manage the key. They have the key (e-mail and order-received page) but no My Account list. Release a seat for them under Licenses → Sites, or issue a replacement with + Issue licence to the account they create afterwards.
  • Refund refused. The customer downloaded the software; the guard cannot be overridden. Offer store credit or an exchange.

See also

Previous
Installing, updating and removing extensions
Next
How the Extensions Marketplace works