The platform guides show a complete licensed plugin in one file, including update filters. This page goes into the choices that decide whether it behaves on real hosting: when to call the API, where the result lives, and what happens on a staging copy. The signed-token fallback is in offline verification in a WordPress plugin. PHP was not available for testing, so none of the code here was run. It follows the documented WordPress functions, and the API behavior it relies on was checked against the live service.
Do not call the API on page views
WordPress runs your plugin on every request. A license call there adds the API’s latency to every page and fails whenever the host cannot reach the network. Call it in three places only: when the customer saves the key, from a daily WP-Cron event, and after a manual “Check again” button. Normal requests read the stored result.
function inkwell_post( string $action, array $body ): ?array {
$res = wp_remote_post( 'https://clavem.io/v1/licenses/' . $action, array(
'timeout' => 8,
'headers' => array( 'Content-Type' => 'application/json' ),
'body' => wp_json_encode( $body ),
) );
if ( is_wp_error( $res ) ) {
return null; // offline, DNS failure, timeout, or blocked by the host
}
$decoded = json_decode( wp_remote_retrieve_body( $res ), true );
return array(
'status' => (int) wp_remote_retrieve_response_code( $res ),
'body' => is_array( $decoded ) ? $decoded : array(),
'retry_after' => (int) wp_remote_retrieve_header( $res, 'retry-after' ),
);
}
wp_remote_post returns an array or a WP_Error. A 404 or 429 is not an error: it comes back as a normal array with the status. wp_remote_retrieve_header reads Retry-After, which is 60 seconds for a 429 and 5 for a 503.
Refresh once a day
register_activation_hook( __FILE__, function () {
if ( ! wp_next_scheduled( 'inkwell_daily_license_check' ) ) {
wp_schedule_event( time() + HOUR_IN_SECONDS, 'daily', 'inkwell_daily_license_check' );
}
} );
register_deactivation_hook( __FILE__, function () {
wp_clear_scheduled_hook( 'inkwell_daily_license_check' );
} );
add_action( 'inkwell_daily_license_check', 'inkwell_refresh_license' );
/** Returns 'licensed', 'invalid', 'needs-network', 'moved' or 'unlicensed', and stores it. */
function inkwell_refresh_license(): string {
$saved = get_option( 'inkwell_license' );
if ( ! is_array( $saved ) ) {
return inkwell_store_state( 'unlicensed' );
}
if ( ( $saved['site'] ?? '' ) !== hash( 'sha256', home_url() ) ) {
return inkwell_store_state( 'moved' ); // a copied database, or a changed address
}
$r = inkwell_post( 'validate', array( 'license_key' => $saved['key'], 'instance_id' => $saved['instance'] ) );
if ( $r && 200 === $r['status'] && isset( $r['body']['valid'] ) && is_bool( $r['body']['valid'] ) ) {
$saved['token'] = $r['body']['token'] ?? $saved['token']; // also when not valid: offline, the token then says so
update_option( 'inkwell_license', $saved, false );
return inkwell_store_state( $r['body']['valid'] ? 'licensed' : 'invalid' );
}
if ( $r && 404 === $r['status'] ) {
delete_option( 'inkwell_license' ); // unknown key, or this site's seat was removed
return inkwell_store_state( 'invalid' );
}
// No answer, 429 or 503: trust the stored token while it is fresh (see the offline page).
$claims = clavem_verify_token( $saved['token'], INKWELL_PUBLIC_KEY );
return inkwell_store_state( clavem_is_licensed( $claims, INKWELL_PRODUCT_ID ) ? 'licensed' : 'needs-network' );
}
function inkwell_store_state( string $state ): string {
update_option( 'inkwell_state', $state, false );
return $state;
}
function inkwell_is_licensed(): bool {
return 'licensed' === get_option( 'inkwell_state' );
}
Two cautions. WP-Cron documentation says it works by checking its task list on every page load, so on a quiet site the daily event runs late, and a day is a target and not a promise. And the false third argument to update_option keeps the license and state out of the autoloaded options that WordPress reads on every request.
Where the license lives
The key, the instance id and the token go in one option, autoload off. An option is stored in the database in plain text, so anyone with database access, and other plugins, can read it. Do not print the full key in the admin screen. Show the last five characters, as …-H5RB8, and a Remove button. For a result that is cheap to rebuild, WordPress’s Transients API is the usual tool, but its documentation says a transient can expire early with an external object cache. That is harmless for a cache and wrong for the only copy of a license, so keep the license in an option and use a transient only for a “checked recently” flag.
Activate when the key is saved
Activation needs a device name and a fingerprint. A site has no hardware, so the address stands in: home_url() as the name, a hash of it as the fingerprint, and the same hash saved with the license to detect clones:
function inkwell_activate( string $key ) {
$site = hash( 'sha256', home_url() );
$r = inkwell_post( 'activate', array( 'license_key' => $key, 'instance_name' => home_url(), 'fingerprint' => $site ) );
if ( ! $r ) {
return new WP_Error( 'inkwell_unreachable', 'Could not reach the license server.' );
}
if ( 200 !== $r['status'] || empty( $r['body']['instance']['id'] ) ) {
return new WP_Error( 'inkwell_refused', $r['body']['error'] ?? 'Activation failed.' );
}
update_option( 'inkwell_license', array(
'key' => $key, 'instance' => $r['body']['instance']['id'], 'token' => $r['body']['token'], 'site' => $site,
), false );
inkwell_store_state( 'licensed' );
return true;
}
Call it from a settings form handler that checks current_user_can( 'manage_options' ) and a nonce, and sanitizes the key with sanitize_text_field( wp_unslash( ... ) ). A “moved” site, after a clone, shows a notice asking for the key again. Activating with the new address takes a seat for the staging site, which is correct if staging needs the premium features, so offer a way to skip it.
Hosting problems you will meet
- Blocked outgoing HTTP. WordPress documents
WP_HTTP_BLOCK_EXTERNALandWP_ACCESSIBLE_HOSTS. When a host sets the first, only listed hosts get through. Show theWP_Errormessage in the admin screen, and tell customers to addclavem.iotoWP_ACCESSIBLE_HOSTS. - Multisite. For a network-activated plugin, use
get_site_optionandupdate_site_option, andnetwork_home_url()as the fingerprint source, so one network holds one seat. - Caching plugins do not matter here, because admin and cron requests are not page-cached.
- WordPress.org directory. The directory’s guidelines list “Trialware is not permitted” as rule 5. A plugin with license-gated features is normally sold from your own site, so check the guidelines before you list one.
Doing this with Clavem
The License API needs no secret, so nothing sensitive ships in the plugin. Plan limits never block validation. See the API reference for every field.
Questions
Should a WordPress plugin check its license on every page load?
No. A remote call on every request adds latency and fails when the network does. Check when the key is saved and once a day from WP-Cron, store the result in an option, and read that on normal requests.
Why does my license check fail only on some hosts?
Some hosts block outgoing HTTP with WP_HTTP_BLOCK_EXTERNAL and allow only hosts listed in WP_ACCESSIBLE_HOSTS. wp_remote_post then returns a WP_Error. Tell customers to add clavem.io to that list, and show the error message you get.
What happens when a site is copied to a staging server?
The database copy carries the saved license and instance id, so staging would run on the live site's seat. Save a hash of home_url with the license and compare it, and treat a mismatch as unlicensed until the key is entered again.
Sources
- WordPress Developer Resources, wp_remote_post (checked November 2026)
- WordPress Developer Resources, Transients API (checked November 2026)
- WordPress Developer Resources, Cron (checked November 2026)
- WordPress Advanced Administration, wp-config.php, blocking external requests (checked November 2026)
- WordPress Plugin Directory, detailed plugin guidelines (checked November 2026)