Skip to Content
SDKLicensing

Licensing

Sell a premium plugin and you need one question answered on every page load: is this site licensed? The SDK answers it locally, from a cached result, and only talks to the licence server when that cache has actually expired.

bootstrap() wires licensing for you. There is nothing to schedule and no cron to configure.

The one method you’ll call

if ( $sdk->license()->is_valid() ) { // premium feature }

is_valid() is safe to call on every page load, from anywhere, as many times as you like. That is a deliberate design guarantee, not a hopeful one:

  • It reads one autoloaded wp_options row. WordPress already fetches that row in the single query it makes at the start of every request, so the common path costs no extra database query at all.
  • It makes no network call unless the cached result is older than 24 hours and the server isn’t already known to be unreachable.
  • It never throws. Every failure path returns false or the cached answer; nothing escapes into the host site’s page load.
  • With no licence key stored, it returns false immediately and makes no request ever. A site that never entered a key generates no licensing traffic.

Activating and deactivating

Both are triggered by a human clicking a button — never on a page load. Each returns an Http\Response you can read for the reason.

$response = $sdk->license()->activate( $key_from_your_form ); if ( $response->ok() && true === $response->get( 'valid' ) ) { // Stored. is_valid() is now true, from cache. } else { // Show $response->get( 'reason' ) — see the table below. // Nothing was stored: a rejected key is never saved. }
$sdk->license()->deactivate( $key ); // frees this site's activation slot

Two rules worth knowing, because both prevent a support ticket:

  • A rejected key is not stored. Otherwise the site would spend the rest of its life re-validating a key the server has already refused.
  • A failed deactivation does not clear local state. If the request never reached the server, the server still counts this domain as holding a slot — forgetting the key locally would strand that slot with the customer holding nothing to release it with. Show them the error and let them try again.

The built-in settings panel

$sdk->license_form()->render();

Call it from your own settings page. It renders a key input and an Activate button when no licence is held, and the masked key, status, expiry, sites-used count and a Deactivate button when one is.

It prints nowhere until you call render(). A licence key input appearing unbidden on a screen the site owner didn’t associate with your product looks exactly like a phishing field, so the SDK never guesses where your settings live. The form posts to admin-post.php, is nonce-verified, and requires manage_options.

The complete license page — one call

Rather than building a fragment into a settings page you already have, you can ask the SDK to register and run a whole license screen:

$sdk->license_page( array( 'parent' => 'options-general.php', // null = its own top-level menu 'purchase_url' => 'https://example.com/pricing', 'renew_url' => 'https://example.com/account', 'support_url' => 'https://example.com/support', 'notice' => true, ) );

Every argument is optional — $sdk->license_page() alone registers a working “License” menu item. This is a separate thing from license_form() above, not a fancier version of it: license_form() is for a fragment inside a page you already built; license_page() is for when you want the SDK to own the whole page, including the menu registration.

parent accepts anything add_submenu_page() does, and for most plugins the right answer is your own menu rather than a core one. If your admin lives under a custom post type — the usual shape when a plugin’s menu is its CPT — parent it to that:

'parent' => 'edit.php?post_type=your_cpt',

Leaving parent as null gives the page its own top-level item in the sidebar, which is rarely what you want next to an existing plugin menu.

Call it before admin_menu fires — at your plugin’s top level or on plugins_loaded, never from inside an admin_menu callback. license_page() registers its own menu on admin_menu at the default priority; calling it from a later-priority admin_menu callback means WordPress has already passed that priority for the request, so the menu item silently never appears — no error, just a missing page.

What a customer sees, state by state:

StateWhat it shows
No licenseA key input, an Activate button, and a “buy one” link if you gave purchase_url.
ActiveMasked key (last 4 characters), who it’s licensed to, expiry as a real date and a relative phrase (“expires in 11 months”; a perpetual license reads “Lifetime”, never a blank), sites used (“2 of 5”, or “2 of Unlimited” on an unlimited plan), and a Deactivate button with a confirmation that explains the site loses its pro features.
ExpiredThe key stays visible — the customer needs it to renew — plus a plain statement that the plugin keeps working and only updates/support stop, and a Renew link if you gave renew_url.
SuspendedAn explanation that the publisher suspended it and that support can help — no Activate button, since retrying cannot fix this.
Cancelled / refunded / revokedWording specific to each, read from the server’s own reason rather than a single generic label.
Activation limit reachedThe result of a rejected Activate attempt, not a stored page state — says the plan’s limit is reached and to deactivate elsewhere or upgrade.
Unreachable, last known validThe last confirmed status, labelled as such, with when it was last confirmed — deliberately reassuring, not alarming, since this is almost always a transient blip on a paying customer’s site.
Unreachable, never confirmedA distinct message — there is no prior valid answer to fall back to, so it says the connection could not be verified rather than implying anything was ever working.

Gating a feature

if ( ! $sdk->license()->require_valid() ) { return; // prints its own notice; never exits }

Prints a notice (linking to the license page, once you’ve called license_page()) and returns false when the license isn’t valid; prints nothing and returns true otherwise. Never calls exit/wp_die — what the rest of the page does with a false is entirely your call.

The unlicensed nag

'notice' => true turns on a dismissible reminder — off by default, and even when on it appears in exactly two places: the license page’s own screen, and the Plugins screen, never site-wide. A dismissal persists for about a week. It never shows while the license is valid, and it stays silent while the license is merely unreachable but was last confirmed valid — a network blip must never nag a paying customer.

The SDK never hands you the raw key

Not from get_status(), not from license_form(), not from license_page(). It’s stored — it has to be, to sign later calls — but every public surface only ever returns it masked to the last 4 characters, and deactivating the stored license reads the raw key out of storage internally without ever handing it back to your code.

Reading the state yourself

$status = $sdk->license()->get_status();
KeyWhat it is
has_licenseWhether a key is stored at all.
license_keyMasked to the last 4 characters, e.g. ****a1b2.
statusactive, expired, suspended, cancelled, …
reasonWhy it isn’t valid, when it isn’t.
customer_nameWho it was issued to.
expires_atISO-8601, or null for a perpetual licence.
activation_limit / activations_usedSites allowed / sites in use.
validExactly what is_valid() would return right now.
last_checked_atUnix timestamp of the last successful check.
staleThe cache expired and the server was unreachable.
next_attempt_atWhen the next check will be attempted.
fail_modeopen or closed.

get_status() never makes a network call, so it is safe on a render path.

Common reason values: license_not_found, expired, not_activated_on_domain, activation_limit_reached, plus the licence’s own status (suspended, cancelled, refunded, revoked).

What happens when the licence server is down

By default, a valid customer keeps their features. This is called fail-open, and it is narrower than it sounds:

  • Unreachable → the SDK returns the last definitive answer, not a blanket true. If the last thing the server said was “invalid”, an outage does not upgrade that to valid.
  • A key that has never once validated successfully returns false. An unverified key is not a paying customer.
  • A definitive answer is always honoured, including a negative one. A 500, a 429, or an HTML error page from a firewall is not a definitive answer — none of those is the server saying anything about this licence.

To lock premium features when the server can’t be reached instead:

$sdk = \Appneck\Sdk\Sdk::bootstrap( 'pk_...', 'sk_...', 'https://appneck.com', __FILE__, null, null, null, null, array( 'license_fail_mode' => 'closed' ) );

Think carefully before choosing closed. It means a network problem you are having disables features on your customer’s site.

Why isn’t it retrying?

This is the question the SDK is hardest to answer from the outside, so: after a failed check, it deliberately waits before trying again.

Consecutive failuresWait before the next attempt
15 minutes
215 minutes
31 hour
46 hours
5 and after24 hours (never more)

Each wait has ±20% random jitter applied once, when the failure is recorded. During the wait, is_valid() answers instantly from the fail mode and makes zero network calls. Any successful call resets the counter to zero.

This is not caution for its own sake. Without it, a site whose licence server is unreachable would block for the request timeout on every page load — and every affected site retrying on every page load would turn an outage into a flood aimed at the server trying to recover from it. The jitter is what stops thousands of sites that lost contact in the same minute all coming back in the same second.

You can see both halves of the answer directly:

$sdk->license()->failure_count(); // consecutive failures $sdk->license()->next_attempt_at(); // unix timestamp, or 0

Configuration

Passed as the 9th argument to bootstrap():

OptionDefaultMeaning
license_fail_mode'open''closed' locks features when unreachable. Anything not exactly 'closed' is open.
license_cache_ttl86400Seconds before a cached result is re-checked.
license_domain(from home_url())Override the domain this site activates under — e.g. so a staging clone doesn’t consume the production slot.

Uninstall

Sdk::uninstall() already handles it: it makes one best-effort, short- timeout deactivation call so the customer’s activation slot is freed, then deletes the stored row regardless of whether that call succeeded. An uninstall never blocks or fails on a licensing request.

Domains

The domain is derived from home_url() and normalised the same way the server does: the scheme and any path are stripped and the host is lowercased.

www. is not stripped, and neither is a port. www.example.com and example.com are genuinely different hosts, and merging them would collapse a real multi-site setup into a single activation slot. If your customers move between the two, that is two activations — which is the correct answer, not a bug.

A customer who declines telemetry never registers an installation, and their licence still activates and validates normally. Licensing is authenticated at the product level and requires no installation at any point. A paying customer’s licence is never held hostage by an unrelated opt-in.

This covers the plugin’s own side of licensing. For the org’s side — configuring Plans and wiring your store to issue license keys in the first place — see Store Integration and Troubleshooting.

Next: Testing Your Integration →