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_optionsrow. 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
falseor the cached answer; nothing escapes into the host site’s page load. - With no licence key stored, it returns
falseimmediately 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 slotTwo 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:
| State | What it shows |
|---|---|
| No license | A key input, an Activate button, and a “buy one” link if you gave purchase_url. |
| Active | Masked 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. |
| Expired | The 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. |
| Suspended | An explanation that the publisher suspended it and that support can help — no Activate button, since retrying cannot fix this. |
| Cancelled / refunded / revoked | Wording specific to each, read from the server’s own reason rather than a single generic label. |
| Activation limit reached | The 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 valid | The 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 confirmed | A 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();| Key | What it is |
|---|---|
has_license | Whether a key is stored at all. |
license_key | Masked to the last 4 characters, e.g. ****a1b2. |
status | active, expired, suspended, cancelled, … |
reason | Why it isn’t valid, when it isn’t. |
customer_name | Who it was issued to. |
expires_at | ISO-8601, or null for a perpetual licence. |
activation_limit / activations_used | Sites allowed / sites in use. |
valid | Exactly what is_valid() would return right now. |
last_checked_at | Unix timestamp of the last successful check. |
stale | The cache expired and the server was unreachable. |
next_attempt_at | When the next check will be attempted. |
fail_mode | open 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, a429, 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 failures | Wait before the next attempt |
|---|---|
| 1 | 5 minutes |
| 2 | 15 minutes |
| 3 | 1 hour |
| 4 | 6 hours |
| 5 and after | 24 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 0Configuration
Passed as the 9th argument to bootstrap():
| Option | Default | Meaning |
|---|---|---|
license_fail_mode | 'open' | 'closed' locks features when unreachable. Anything not exactly 'closed' is open. |
license_cache_ttl | 86400 | Seconds 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.
Licensing works without analytics consent
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.