License REST API

Endpoints for reading and managing the plugin’s license state programmatically. All endpoints require manage_options capability and a valid X-WP-Nonce header.

If you’re writing an add-on in PHP, you probably don’t need these. benecaster_get_license_plan() and benecaster_addon_is_active() read the same state in-process, with no HTTP round-trip and no nonce to manage — that’s the normal path for a plugin reacting to license state. Reach for the REST endpoints below when your code isn’t running as PHP inside the same WordPress request: your own JS/React admin screen (this is what powers the Settings → Account → Validate now button), or an external system talking to the site over HTTP — a multi-site monitoring dashboard, a deployment script confirming a connection came up, anything authenticating with an Application Password rather than running as the plugin itself.

Site connection to benecaster.com is managed through the OAuth flow (Benecaster → Settings → Account → Connect to Benecaster), not through REST endpoints. The endpoints below cover reading license state and triggering on-demand validation.

---

GET /benecaster/v1/license

Returns the current license status and all associated metadata.

Auth: manage_options + X-WP-Nonce

Response:

{
  "status": "active",
  "plan": "growth",
  "expires_at": "2027-05-17",
  "site_url": "https://yoursite.com",
  "activated_at": "2025-03-15T09:00:00",
  "last_validated_at": "2026-05-17T08:00:00",
  "validation_failure_count": 0,
  "subscriber_count": 41,
  "subscriber_limit": 250,
  "upgrade_scheduled_at": null,
  "upgrade_target_tier": null,
  "active_addons": ["email-editor", "analytics-dashboard"],
  "show_limit": 1,
  "active_show_count": 1,
  "all_addons_included": false,
  "priority_support": false,
  "beta_access": false
}

active_addons is correct on this page, and it is not the same field as the licence server’s addons. This page documents the plugin’s own GET /license endpoint — the one your site’s admin screen calls, authenticated with manage_options and a nonce. It returns active_addons, and src/REST/LicenseController.php is where that name comes from.

The licence server at benecaster.com returns the entitlement list as addons in its /validate response, which your site consumes and re-publishes here under the other name. Confusingly, active_addons is also the name of an inbound telemetry field the plugin sends to the licence server. Three surfaces, two names, and the overlap is easy to get wrong. If you are calling the plugin, read active_addons. If you are calling the licence server directly, read addons.

overage_up_count, downgrade_lock_active and downgrade_lock_until are not in this response, and not in GET /status either. They are named here because an integration reading them gets nothing back, which is easy to mistake for a licence in a clean state.

They are no loss. All three were permanently 0 / false / null, and two read options that nothing wrote — the reader looked for benecaster_license_downgrade_lock_* while the writer used benecaster_free_downgrade_lock_* — so they were silently wrong rather than merely dead, and no admin screen ever rendered them.

Downgrade eligibility is decided by the licence server on its own 30-day window and surfaced at benecaster.com — nothing in the plugin locks a plan change.

Field notes:

---

POST /benecaster/v1/license/validate

Forces an immediate validation check against the Benecaster license server. Validation normally happens on a daily WP-Cron schedule; this endpoint triggers it on demand.

Auth: manage_options + X-WP-Nonce

Response: Updated license status object — same shape as GET /benecaster/v1/license.

Use case: After upgrading a plan on benecaster.com, call this endpoint to pull in the updated plan details without waiting for the next daily cron run. The Settings → Account → Validate now button in the WordPress admin calls this endpoint.

---

WP-Option State

The license endpoints read from and write to the following wp_options. These are documented here for diagnostic and test purposes — external code should call the REST endpoints rather than reading options directly.