Licensing

Overview

WooNooW Licensing generates product license keys from qualifying WooCommerce orders, enforces activation limits per license key, and authorizes website installations using persistent installation UUIDs paired with normalized domains.

This page is written for merchants and operators configuring a WooNooW store. Customers who activate licenses on their websites interact with the client-facing activation flow and do not access WooNooW's internal module settings.

Enable the module

1. Open WooNooW → Settings → Modules.
2. Enable Software Licensing.
3. Open the Licensing module settings card.
4. Configure the site defaults described below.

Licensing is disabled by default. Protected software releases require Licensing to be enabled; if Licensing is disabled, requests to check or download protected packages fail closed with HTTP 503 licensing_unavailable.

Site-wide settings

Activation methods

WooNooW supports two merchant-selected activation methods.

Simple API

The client product asks the customer for their license key and activates directly through the public Licensing API (POST /wp-json/woonoow/v1/licenses/activate). This is the lowest-friction method and is appropriate for most software products.

The client sends its combined website identity:

persistent installation UUID + normalized domain

Secure OAuth

The product redirects the customer to the merchant's WooNooW store to sign in to their account and approve the installation. Use this method when account-level verification is preferred over distributing raw license keys.

The client does not determine the activation method and cannot supply an activation_mode override. WooNooW resolves the site default and any allowed per-product override. See OAuth Activation Flow for the client protocol specification.

Entitlement dimensions

WooNooW evaluates customer permissions across independent entitlement dimensions rather than reducing a license to a single monolithic status:

1. Product Usage right (license_active, usage_expires_at): Reports the effective permission to use the software after evaluating base status (active vs revoked), usage expiry, and linked subscription state. WooNooW enforces this on its license/distribution APIs; the distributed client decides how that state affects already-installed functionality.
2. Software Updates right (update_entitled, updates_expires_at): Controls whether the license is authorized to receive newly published software releases. Supported modes include:
   • license: Update access mirrors the usage duration and expiration.
   • days: Updates expire after a fixed number of days from issuance (e.g. 365 days), independent of ongoing usage validity.
   • unlimited: Update access has no independent cutoff while the underlying usage license remains active. It does not imply unlimited product usage or lifetime license terms.
   • none: No software update access is granted.
3. Technical Support right (support_active, support_expires_at): Governs helpdesk or ticket support eligibility. Supported modes include unspecified (null), days, unlimited, or none.
4. Historical Downloads right (historical_downloads, history_access): A boolean policy flag. When enabled, an active license whose update window has elapsed may still download historical releases that were published on or before its updates_expires_at cutoff date.

For architectural and mathematical details on how these dimensions interact during validation, see the Entitlements Concept Overview.

Immutable issuance snapshot

To protect customers from retroactive policy changes, WooNooW implements immutable policy snapshots:

• Catalog policy: Configured per parent product or variation through the authenticated REST API: GET|PUT /wp-json/woonoow/v1/licensing/products/{product_id}/entitlement-policy (requires manage_woocommerce). WooNooW P0 does not currently expose the structured update/support/history policy as a standard product-editor form; custom administrative integrations may use the same _woonoow_entitlement_policy metadata contract.
• Order snapshot: When a qualifying order is completed, WooNooW snapshots the effective catalog policy directly into the newly created license record (version: 1, issued_at, exact cutoff timestamps).
• Immutability: Subsequent catalog modifications never silently alter or truncate rights on existing customer licenses. For recurring subscriptions, the entitlement snapshot is automatically renewed and advanced upon each successful billing cycle (LicenseManager::renew_entitlement_snapshot()).
• Legacy licenses: Pre-existing licenses without an explicit snapshot evaluate in legacy mode (update rights follow effective usage validity, support is unspecified, and historical downloads are disabled).

Configure licensing on a product

When creating or editing a WooCommerce product:

1. Enable Enable Licensing (_woonoow_licensing_enabled).
2. Set an Activation Limit or leave it empty to inherit the global default.
3. Set License Expiry (Days) or leave it empty to inherit the default.
4. Optionally select an Activation Method when per-product override is enabled on the site.
5. Save the product.

A completed qualifying order automatically generates a license for the purchased product with an immutable entitlement snapshot.

Variable products

Activation limit, usage-expiry duration, and entitlement policies can be tailored for each variation. They use different fallback chains:

activation limit / usage expiry: variation → parent product → global default
update/support/history policy:  variation → parent product → legacy behavior

Value semantics:

For example, a parent product may default to 1 activation slot, while an "Agency" variation explicitly overrides the limit to 10.

Website identity and activation slots

Each activated website is identified by a persistent installation UUID paired with a normalized domain. A retry using the same identity pair is idempotent: it returns the existing activation record and does not consume additional activation slots.

The following combinations represent distinct identities:

• The same UUID on a different domain.
• A different UUID on the same domain.

When migrating a site to a new domain, customers should deactivate the old identity before activating the new domain to free their activation slot. Read Website Identity for the full identity specification.

License lifecycle

The stored base status in the database is strictly limited to:

• active — Valid license, not administratively revoked.
• revoked — Explicitly revoked by the merchant.

Usage expiration and linked subscription statuses are evaluated dynamically against WooNooW native subscriptions (woonoow_subscriptions table). A license with base status active can have an effective state of expired or subscription_inactive.

Always inspect effective status, usage expiration, linked WooNooW subscription status, and active installation identities when diagnosing customer access.

Manage customer licenses

Open the Licenses screen in the WooNooW administration SPA at route /products/licenses (and license details at /products/licenses/:id) to:

• Customer & order identification: Inspect customer name, email address, WordPress customer ID (user_id), and associated WooCommerce order (order_id).
• Product identity: Review the parent product ID (product_id), purchased variation ID (variation_id), product name, and variation name.
• Seat allocation & unlimited limits: View current activations versus limit (activation_count / activation_limit). When activation_limit is configured as 0, the interface displays the limit as ∞ and remaining seats as Unlimited.
• License lifecycle dates: View license creation timestamp (created_at) and usage expiration date (expires_at or Never).
• Activation history snapshots: Review an authoritative table of all active and deactivated installations, detailing:
  • Target website domain (domain) or client machine identifier (machine_id).
  • Client IP address (ip_address).
  • Initial activation timestamp (activated_at) formatted in local time.
  • Current status badge (Active or Deactivated).
• Stateless validation policy: Validation requests evaluate license standing on the fly without writing to the database. WooNooW records the original activation timestamp (activated_at), but does not maintain or display an unimplemented last_validated_at timestamp.
• Administrative controls:
  • Revoke a license when necessary (sets base status to revoked, immediately invalidating update access and download tokens).
  • Deactivate specific installations to release seats during customer site migrations or troubleshooting.

Customer self-service

When Allow Deactivation is enabled, customers can sign in to their store account and access My Account → Licenses (backed by GET /woonoow/v1/account/licenses and POST /woonoow/v1/account/licenses/{id}/deactivate). Customers can inspect their own active installations and release activation slots directly without contacting store support.

Software distribution access

To distribute versioned software binaries or updates to licensed customers, enable the Software Distribution module and configure a release stream on the same parent product.

Before issuing a short-lived download token or granting access to a release, WooNooW's distribution engine evaluates:

1. Effective license lifecycle (base status and subscription standing).
2. Active installation identity (matching UUID and normalized domain).
3. Entitlement authorization (LicenseEntitlements::authorize_release()) against the release's publication date and update cutoff.
4. Immutable version-to-artifact binding in the private vault.

For full release publishing, vault security, and packaging procedures, continue to the Software Distribution Guide.