License Lifecycle

A license is not a static yes/no. It is a key bound to a product, carrying a seat limit, with zero or more domains activated against it at any moment. This page covers the three operations that move a license through its life — activate, validate, deactivate — plus seat limits and the meaning of every status.

The shape of a license

license key: CH-7K2P-9XQ4-LM83
  product:   acme-forms-pro
  status:    valid
  expiresAt: 2027-06-04T00:00:00Z
  seatLimit: 3
  activations:
    - example.com         (activatedAt 2026-06-04T10:21:00Z)   seat 1
    - staging.example.com (activatedAt 2026-06-05T08:02:00Z)   seat 2
    -                                                          seat 3 free

A seat is one activated domain. seatLimit is how many seats the purchase bought. The activations array is the live list of domains currently holding seats.

Activate a domain

When a customer enters their key on a new site, claim a seat for that domain before unlocking anything.

curl -X POST https://api.code-heaven.com/v1/licenses/CH-7K2P-9XQ4-LM83/domains \
  -H "X-CH-Vendor-Key: $CH_VENDOR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "staging.example.com"}'

Success responds 201 with the refreshed activation list and seat limit:

{
  "activated": true,
  "domain": "staging.example.com",
  "activations": [
    { "domain": "example.com", "activatedAt": "2026-06-04T10:21:00Z" },
    { "domain": "staging.example.com", "activatedAt": "2026-06-05T08:02:00Z" }
  ],
  "seatLimit": 3
}

If every seat is already taken, you get 409:

{
  "error": {
    "code": "seat_limit_exceeded",
    "message": "All 3 seats for this license are in use. Deactivate a domain to free one."
  }
}

On 409, show the customer their active domains (you have them from the last validate call) and offer to deactivate one. Do not retry the activation — it will keep failing until a seat is freed.

Activating a domain that already holds a seat is idempotent: you get 201 and the existing activation, not a second seat. So a plugin that re-activates on every settings save will not burn seats.

Validate per domain

Activation claims the seat; validation confirms entitlement at runtime. Always validate against the current site's domain, because a license can be valid globally yet refused on a site that has no seat.

curl https://api.code-heaven.com/v1/licenses/validate \
  -H "X-CH-Vendor-Key: $CH_VENDOR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"licenseKey":"CH-7K2P-9XQ4-LM83","domain":"staging.example.com","product":"acme-forms-pro"}'

{
  "valid": true,
  "status": "valid",
  "product": "acme-forms-pro",
  "expiresAt": "2027-06-04T00:00:00Z",
  "activations": [
    { "domain": "example.com", "activatedAt": "2026-06-04T10:21:00Z" },
    { "domain": "staging.example.com", "activatedAt": "2026-06-05T08:02:00Z" }
  ],
  "seatLimit": 3
}

The natural order in a plugin is activate, then validate. If you validate first on a fresh site you will get domain_not_activated; treat that as "activate now, then re-validate," not as an error to show the customer:

<?php

$result = ch_validate_license($key, $domain, 'acme-forms-pro');

if ($result['status'] === 'domain_not_activated') {
    $activation = ch_activate_domain($key, $domain);   // POST .../domains
    if (($activation['activated'] ?? false) === true) {
        $result = ch_validate_license($key, $domain, 'acme-forms-pro'); // re-check
    }
}

$unlocked = ($result['status'] ?? '') === 'valid';

Deactivate a domain

When a customer retires a site, migrates to a new domain, or deactivates your plugin, release the seat so they can use it elsewhere.

curl -X DELETE \
  https://api.code-heaven.com/v1/licenses/CH-7K2P-9XQ4-LM83/domains/staging.example.com \
  -H "X-CH-Vendor-Key: $CH_VENDOR_KEY"

{
  "deactivated": true,
  "domain": "staging.example.com"
}

Hook this into your plugin's deactivation routine and into a "deactivate this site" button in your settings UI:

<?php

register_deactivation_hook(__FILE__, function () {
    $key    = get_option('acme_license_key', '');
    $domain = parse_url(home_url(), PHP_URL_HOST);
    if ($key) {
        ch_deactivate_domain($key, $domain); // DELETE .../domains/{domain}
    }
});

Releasing a seat the customer is done with is good citizenship: it prevents support tickets that begin with "I moved my site and now it says all seats are used."

Seat limits, summarized

• seatLimit comes back on every validate and every activate response. Read it to render "2 of 3 sites active."
• Activation past the limit returns 409 seat_limit_exceeded. The fix is always to deactivate a domain first.
• Re-activating an already-active domain is free (idempotent), so guard rails like "activate on save" are safe.
• A higher tier or an add-on purchase raises the limit; the change is reflected in the next validate response — your plugin does not need to do anything special.

What every status means

validate returns a status that fully describes the license's standing. Map each one to a clear plugin behaviour:

status	valid	Cause	Recommended plugin behaviour
valid	true	Paid, active, this domain activated	Unlock premium features
invalid	false	Key does not exist or is wrong	"Invalid license key" — prompt re-entry, don't retry
expired	false	The license term has lapsed	Lock premium features, prompt renewal, surface expiresAt
domain_not_activated	false	Key is fine but this site has no seat	Activate the domain, then re-validate
revoked	false	Cancelled by refund, chargeback, or abuse	Lock features, stop retrying, no renewal prompt

Status vs. HTTP code

The validate endpoint returns 200 even when the license is not usable — the status lives in the body. The dedicated error codes (403 license_invalid, 403 expired, 403 domain_not_activated) appear on the other endpoints (activate, updates, download) when you try to act on a license that is not entitled. So:

• On validate: read the body's status.
• On activate / updates / download: a 403 means the license is not entitled to that action; the error.code tells you which condition.

{
  "error": {
    "code": "domain_not_activated",
    "message": "This domain is not activated for the license. Activate it first."
  }
}

With the lifecycle handled, wire up updates and downloads so customers can stay current.