If you're shipping a commercial WordPress plugin, sooner or later you'll need a licensing system. Something that lets paying customers activate the plugin on their site, locks it to that domain, and stops people from sharing the same key across fifty sites.
The default answer in the WordPress world is Freemius or EDD Software Licensing. They're great. They're also a revenue share, a third-party dependency, and a black box you don't control.
When we built RideCab WP, a commercial WooCommerce taxi booking plugin, we decided to build our own. Here's the architecture, the code, and the gotchas we hit along the way.
What a Licensing System Actually Needs to Do
Before writing any code, get clear on the requirements. A real plugin licensing system needs to:
- Generate unique license keys when someone buys
- Let the customer activate the key on their site
- Bind that key to one (or N) domains
- Validate the key periodically so revoked or expired keys stop working
- Handle deactivation when a customer moves to a new domain
- Fail gracefully — never lock a paying customer out because your license server hiccuped
- Optionally: deliver plugin updates only to valid license holders
We'll cover 1 through 6 in this post. Update delivery is a separate beast and I'll write it up next.
The Architecture
The system has two halves that live in two different places.
The license server runs on your own infrastructure — for us, it's a WordPress must-use plugin (mu-plugin) on the same WordPress install that powers our marketing site. It:
- Stores license keys in a custom database table
- Exposes a small REST API for activate, deactivate, and validate calls
- Provides an admin dashboard to view, create, and revoke keys
The client is a PHP class shipped inside the commercial plugin (RideCab WP, in our case). It:
- Adds a license settings page to the plugin
- Calls home on activation
- Caches the validation result
- Re-validates quietly in the background
Two pieces, talking over HTTPS, with the customer's domain as the binding key.
Step 1: The License Server — Database Schema
On the server side, the simplest workable schema is one table:
`php
global $wpdb;
$table = $wpdb->prefix . 'plugin_licenses';
$sql = "CREATE TABLE $table (
id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
license_key VARCHAR(64) NOT NULL,
customer_email VARCHAR(191) NOT NULL,
product_slug VARCHAR(64) NOT NULL,
status ENUM('active','revoked','expired') DEFAULT 'active',
activations LONGTEXT NULL,
max_activations TINYINT UNSIGNED DEFAULT 1,
expires_at DATETIME NULL,
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
PRIMARY KEY (id),
UNIQUE KEY license_key (license_key)
) {$wpdb->get_charset_collate()};";
require_once ABSPATH . 'wp-admin/includes/upgrade.php';
dbDelta( $sql );
`
The activations column is a JSON-encoded array of { domain, activated_at } pairs. For more than a few products this should probably be a separate table — but for most plugin authors, JSON in one column is plenty.
Step 2: Generating License Keys
Keep them short enough to be typed if needed, long enough to be unguessable. A common pattern is four blocks of uppercase hex:
php
function generate_license_key() {
$blocks = [];
for ( $i = 0; $i < 4; $i++ ) {
$blocks[] = strtoupper( bin2hex( random_bytes( 4 ) ) );
}
return implode( '-', $blocks );
// Example: 9F3A2B71-C8D4E5F6-1A2B3C4D-5E6F7081
}
random_bytes() is cryptographically secure. Don't use rand() or uniqid() for license keys — they're predictable.
Hook key generation into your order completion flow. If you're using WooCommerce on the server side to sell the plugin, that's woocommerce_order_status_completed.
Step 3: The REST API
Three endpoints are enough. Register them on rest_api_init:
php
add_action( 'rest_api_init', function() {
register_rest_route( 'license/v1', '/activate', [
'methods' => 'POST',
'callback' => 'license_activate',
'permission_callback' => '__return_true',
] );
register_rest_route( 'license/v1', '/deactivate', [
'methods' => 'POST',
'callback' => 'license_deactivate',
'permission_callback' => '__return_true',
] );
register_rest_route( 'license/v1', '/validate', [
'methods' => 'POST',
'callback' => 'license_validate',
'permission_callback' => '__return_true',
] );
} );
The activate handler is the most important one:
`php
function license_activate( WP_REST_Request $req ) {
$key = sanitize_text_field( $req->get_param( 'license_key' ) );
$domain = sanitize_text_field( $req->get_param( 'domain' ) );
if ( ! $key || ! $domain ) {
return new WP_REST_Response( [ 'success' => false, 'message' => 'Missing parameters' ], 400 );
}
global $wpdb;
$table = $wpdb->prefix . 'plugin_licenses';
$license = $wpdb->get_row( $wpdb->prepare( "SELECT * FROM $table WHERE license_key = %s", $key ) );
if ( ! $license ) {
return new WP_REST_Response( [ 'success' => false, 'message' => 'Invalid license key' ], 404 );
}
if ( 'active' !== $license->status ) {
return new WP_REST_Response( [ 'success' => false, 'message' => 'License is ' . $license->status ], 403 );
}
if ( $license->expires_at && strtotime( $license->expires_at ) < time() ) {
return new WP_REST_Response( [ 'success' => false, 'message' => 'License expired' ], 403 );
}
$activations = json_decode( $license->activations, true ) ?: [];
$existing = array_filter( $activations, fn( $a ) => $a['domain'] === $domain );
if ( ! $existing && count( $activations ) >= (int) $license->max_activations ) {
return new WP_REST_Response( [ 'success' => false, 'message' => 'Activation limit reached' ], 403 );
}
if ( ! $existing ) {
$activations[] = [ 'domain' => $domain, 'activated_at' => current_time( 'mysql' ) ];
$wpdb->update( $table, [ 'activations' => wp_json_encode( $activations ) ], [ 'id' => $license->id ] );
}
return new WP_REST_Response( [
'success' => true,
'expires_at' => $license->expires_at,
], 200 );
}
`
The validate and deactivate handlers follow the same pattern: look up the license, check status, update activations as needed.
Step 4: The Client Class
This lives inside the commercial plugin. It's what calls the server.
`php
class Plugin_License_Client {
const OPTION_KEY = 'my_plugin_license_key';
const TRANSIENT = 'my_plugin_license_valid';
const API_BASE = 'https://yourdomain.com/wp-json/license/v1';
const CACHE_PERIOD = WEEK_IN_SECONDS;
public function is_valid() {
$cached = get_transient( self::TRANSIENT );
if ( false !== $cached ) {
return (bool) $cached;
}
$valid = $this->remote_validate();
set_transient( self::TRANSIENT, $valid ? 1 : 0, self::CACHE_PERIOD );
return $valid;
}
public function activate( $license_key ) {
$response = wp_remote_post( self::API_BASE . '/activate', [
'timeout' => 15,
'body' => [
'license_key' => $license_key,
'domain' => $this->current_domain(),
],
] );
if ( is_wp_error( $response ) ) {
return [ 'success' => false, 'message' => 'Could not reach license server' ];
}
$body = json_decode( wp_remote_retrieve_body( $response ), true );
if ( ! empty( $body['success'] ) ) {
update_option( self::OPTION_KEY, $license_key );
set_transient( self::TRANSIENT, 1, self::CACHE_PERIOD );
}
return $body;
}
private function remote_validate() {
$key = get_option( self::OPTION_KEY );
if ( ! $key ) {
return false;
}
$response = wp_remote_post( self::API_BASE . '/validate', [
'timeout' => 10,
'body' => [
'license_key' => $key,
'domain' => $this->current_domain(),
],
] );
if ( is_wp_error( $response ) ) {
// Fail open: don't punish customers for our server being down.
return true;
}
$body = json_decode( wp_remote_retrieve_body( $response ), true );
return ! empty( $body['success'] );
}
private function current_domain() {
return wp_parse_url( home_url(), PHP_URL_HOST );
}
}
`
Notice the // Fail open comment in remote_validate(). This is the single most important design decision in the whole system.
Step 5: Fail Open, Not Closed
When your license server is unreachable — and it will be unreachable sometimes, because the internet is the internet — what should happen?
Fail closed: the plugin disables itself until it can re-validate. Customers see a broken site. They email you. Your reputation craters.
Fail open: the plugin keeps working. A small percentage of bad actors might get a few extra hours of unlicensed use. So what.
Always fail open. Your paying customers are the ones you have to protect, and they're the ones who suffer most when validation calls fail. Pirates will pirate either way.
A reasonable middle ground: cache the last successful validation for a week. If the server is unreachable, keep working off the cache for up to 30 days. After 30 days of no successful validation, show a non-blocking admin notice. Never disable the plugin outright.
Step 6: The Settings Page
Customers need a place to enter their key. A minimal settings page does the job:
`php
add_action( 'admin_menu', function() {
add_options_page(
'My Plugin License',
'My Plugin License',
'manage_options',
'my-plugin-license',
'render_license_page'
);
} );
function render_license_page() {
$client = new Plugin_License_Client();
if ( isset( $_POST['license_key'] ) && check_admin_referer( 'my_plugin_license' ) ) {
$result = $client->activate( sanitize_text_field( wp_unslash( $_POST['license_key'] ) ) );
echo '<div class="notice notice-' . ( $result['success'] ? 'success' : 'error' ) . '"><p>'
. esc_html( $result['message'] ?? 'License activated.' ) . '</p></div>';
}
$current = get_option( Plugin_License_Client::OPTION_KEY );
?>
<div class="wrap">
<h1>License</h1>
<form method="post">
<?php wp_nonce_field( 'my_plugin_license' ); ?>
<input type="text" name="license_key" value="<?php echo esc_attr( $current ); ?>" class="regular-text" />
<?php submit_button( 'Activate License' ); ?>
</form>
</div>
<?php
}
`
In production you'll want better UX — show the activation status, the bound domain, a deactivate button. But this is the minimal viable settings page.
Common Mistakes to Avoid
A few things I've seen go wrong, both in our system and in others:
- Validating on every page load. Kills performance, multiplies failure modes. Cache it.
-
Hardcoding the license server URL with
http://. Use HTTPS. Always. - Storing license keys in plain options without sanitization. Treat them like passwords on input.
-
Not handling the staging/dev case. Customers will test on
staging.theirsite.com. Decide whether you grant a free extra activation for*.dev,*.local,staging.*, or whether you fail and document the workaround. Either is fine; just decide before you ship. - No way for customers to deactivate themselves. They will switch domains. They will rebuild sites. Give them a self-service deactivate button.
- Logging full license keys server-side. If your server is ever compromised, those logs become a treasure map. Log the last 4 characters only.
What's Next
This system covers everything except update delivery — letting valid license holders pull plugin updates from your server instead of WordPress.org. That's its own write-up because it involves WordPress's pre_set_site_transient_update_plugins filter and serving zipped plugin packages from your server. I'll cover it in a follow-up.
If you want to see this system running in production, it's what powers licensing for RideCab WP, our commercial WooCommerce taxi booking plugin. Same architecture as above, with a few extra layers for domain wildcards and team licenses.
Questions on any part of this? Drop them in the comments — happy to go deeper on the API design, the caching strategy, or the failure modes.
