Licensing API

Overview

The public Licensing API lets plugins, themes, and other clients activate and validate WooNooW product licenses.

Base URL: https://your-store.com/wp-json/woonoow/v1

All public license endpoints in this guide use JSON POST requests. Authentication is provided by the license key and its product entitlement; no WordPress login is required for these three endpoints.

Required website identity

A website is identified by this pair:

persistent installation UUID + normalized domain

Both values are required for activation and public validation. There is no domain-only, UUID-only, or machine_id fallback. Read Website Identity before implementing a client.

Activate a license

POST /wp-json/woonoow/v1/licenses/activate
Content-Type: application/json

Request

{
  "license_key": "XXXX-YYYY-ZZZZ-WWWW",
  "domain": "https://customer-site.com",
  "installation_id": "550e8400-e29b-41d4-a716-446655440000"
}

Success response

{
  "success": true,
  "activation_id": 123,
  "activations_remaining": 2
}

Save activation_id when possible so the installation can later be deactivated precisely.

Repeating this request with an already-active UUID + domain pair is idempotent. WooNooW returns the existing activation without creating another record or consuming another slot.

OAuth-required response

The merchant configures the activation method globally or per product. A client does not force OAuth with an activation_mode request field.

When the license requires account approval, the endpoint returns:

{
  "success": false,
  "code": "oauth_required",
  "message": "This license requires account verification...",
  "redirect_url": "https://your-store.com/my-account/license-connect/..."
}

Open redirect_url in the user's browser and follow the OAuth Activation Flow.

Validate a license

POST /wp-json/woonoow/v1/licenses/validate
Content-Type: application/json

Request

{
  "license_key": "XXXX-YYYY-ZZZZ-WWWW",
  "domain": "https://customer-site.com",
  "installation_id": "550e8400-e29b-41d4-a716-446655440000"
}

Valid response (200)

{
  "valid": true,
  "error": null,
  "message": null,
  "effective_status": "valid",
  "license_key": "XXXX-YYYY-ZZZZ-WWWW",
  "status": "active",
  "activation_limit": 3,
  "activation_count": 1,
  "activations_remaining": 2,
  "expires_at": null,
  "is_expired": false,
  "subscription_status": null,
  "subscription_active": true,
  "domain_active": true
}

Do not decide validity from status === "active" alone. Use valid and effective_status; expiry, subscription state, and website activation are separate lifecycle dimensions.

A correctly formatted identity that is not activated returns 403 with:

{
  "valid": false,
  "error": "domain_not_activated",
  "effective_status": "domain_not_activated",
  "message": "License is not activated for this installation_id and domain pair."
}

A missing or malformed identity returns a REST error with HTTP 400.

Deactivate a license

POST /wp-json/woonoow/v1/licenses/deactivate
Content-Type: application/json

Use one of the following request forms.

By activation ID

{
  "license_key": "XXXX-YYYY-ZZZZ-WWWW",
  "activation_id": 123
}

The activation ID must belong to the supplied license.

By website identity

{
  "license_key": "XXXX-YYYY-ZZZZ-WWWW",
  "domain": "https://customer-site.com",
  "installation_id": "550e8400-e29b-41d4-a716-446655440000"
}

Domain-only deactivation is not supported. When activation_id is omitted, both identity fields are required.

Success response

{
  "success": true
}

Deactivating an already-deactivated activation is idempotent and frees no additional slots.

License status model

The stored base status is intentionally small:

• active — the license has not been revoked;
• revoked — the merchant revoked the license.

Effective status also evaluates expiry and subscription state:

Activation limits

An activation limit of 0 means unlimited. Positive values are the maximum number of active combined identities for the license.

For variable products, entitlement is resolved in this order:

variation override → parent product value → global default

An empty variation value inherits from the parent. A variation value of 0 explicitly means unlimited.

Error codes

Handle the machine-readable error code instead of matching the human-readable message.

Client rules

• Persist one UUID per installation; never generate one per request.
• Send the same UUID and current domain on every operation.
• Do not log full license keys or OAuth activation tokens.
• Treat network/server failures as temporary; do not erase the key or replace the UUID automatically.
• Deactivate the old identity before a planned domain migration when the old activation slot should be released.