Store Owner Guide

Overview

WooNooW can sell licenses and distribute updates for WordPress plugins, themes, and other software installed on a website with a stable URL.

The default workflow keeps cryptographic operations out of the store owner's release process while still providing:

• product-scoped license entitlement;
• controlled website activation limits;
• exact release-to-file binding;
• automatic package SHA-256 metadata;
• short-lived, single-use download tokens.

Your software client must perform the final SHA-256 check before installing a downloaded package.

1. Enable the required modules

1. Open WooNooW → Settings → Modules.
2. Enable Licensing.
3. Configure the Licensing defaults.
4. Enable Software Distribution.

Software Distribution depends on Licensing and cannot be used as an unauthenticated generic file server.

2. Configure licensing defaults

Under the Licensing module settings, choose:

• license key format and optional prefix;
• default activation limit (0 means unlimited);
• customer deactivation policy;
• expiry defaults and expired-activation policy;
• Simple API or Secure OAuth activation;
• whether products may override the activation method.

See Licensing Configuration for the complete setting semantics.

3. Create a licensed software product

Create or edit a WooCommerce product, then:

1. mark it Downloadable and, when appropriate, Virtual;
2. enable licensing for the product;
3. set the product activation limit and license duration, or leave them empty to inherit store defaults;
4. enable Software Distribution;
5. assign a stable, unique software slug;
6. enable WordPress metadata when the product is a plugin or theme;
7. add the release package to the product's WooCommerce downloadable files;
8. save or publish the product.

The software slug is part of the client contract. Changing it after distribution requires a coordinated client update.

4. Configure variations

For variable products, each variation may override activation limit and license expiry.

Resolution order:

variation override → parent product value → global default

An empty value means inherit. 0 is explicit: unlimited activations or no expiry, depending on the field.

This supports product tiers such as a one-site standard variation and a multi-site agency variation without introducing a separate plan/features model.

5. Prepare the release artifact

Add the package as a WooCommerce downloadable-file entry on the same product. Each entry has a download ID.

A software version must bind to that exact ID:

product_id + version + artifact_download_id

Do not rely on file order or assume WooNooW will use the first downloadable file. This binding prevents a release from silently serving the wrong package when a product has multiple downloads.

6. Publish a version

The release operation must provide:

• version number;
• changelog;
• whether the version is current;
• exact WooCommerce artifact_download_id.

WooNooW then resolves the file and records its name, size, and SHA-256 automatically. The release is rejected if the selected download does not belong to the product, the file cannot be resolved, or hashing fails.

The authenticated admin endpoint is:

POST /wp-json/woonoow/v1/software/products/{product_id}/versions
Content-Type: application/json
X-WP-Nonce: <rest-nonce>

{
  "version": "1.3.0",
  "set_current": true,
  "artifact_download_id": "woocommerce-download-id",
  "changelog": {
    "narrative": "Compatibility and maintenance release.",
    "points": [
      { "type": "ADD", "text": "Added feature X." },
      { "type": "FIX", "text": "Fixed issue Y." }
    ]
  }
}

The endpoint requires a logged-in administrator with the manage_woocommerce capability and valid WordPress REST authentication.

For endpoint details and response metadata, read Software Updates API.

7. Integrate the product client

The plugin, theme, or application you distribute is responsible for:

1. creating one persistent canonical installation UUID;
2. sending that UUID and the current site URL during activation, validation, deactivation by identity, OAuth, and update checks;
3. using the product's exact software slug;
4. obtaining a fresh download URL immediately before download;
5. hashing the downloaded package and comparing it with file_sha256 before installation.

WooNooW identifies a website with this pair:

persistent installation UUID + normalized domain

Neither field can replace the other. See Website Identity and Licensing API.

8. Understand the download lifecycle

When a licensed installation checks for an update, WooNooW verifies:

1. license lifecycle, including revoke, expiry, and linked subscription state;
2. active UUID + domain identity;
3. license entitlement to the product resolved by the software slug;
4. release version and exact artifact metadata.

If an update is available, WooNooW returns file_sha256 and a download URL whose token is valid for five minutes and can be used once.

Immediately before download, WooNooW revalidates entitlement and recalculates the actual file SHA-256. A missing or changed package is rejected. A successful package response includes X-Package-Sha256.

The product client must still verify the completed download before unzip or installation. The reference WooNooW updater provides identity and WordPress update metadata patterns, but integrators must add the final post-download checksum verification and fresh-token handling.

9. Manage licenses and activations

WooNooW generates licenses for eligible purchased products. Use the license screens to:

• inspect product ownership and effective lifecycle;
• review active installations and slot usage;
• deactivate old installations during migrations;
• revoke a license when required.

Activation retries for the same UUID + domain pair are idempotent and do not consume another slot. A new UUID on the same domain, or the same UUID on a new domain, is a different identity.

When customer deactivation is enabled, customers can manage their installations from My Account → Licenses.

10. Optional advanced signing

Asymmetric signing is not required for standard WooNooW software delivery. The baseline already uses HTTPS, entitlement checks, exact artifact binding, short-lived tokens, and SHA-256 verification.

Advanced signing may be appropriate for publishers that require an additional trust layer independent of the delivery server, but the current release endpoints do not accept package signatures. If signing is implemented later as a separate end-to-end capability:

• the software publisher owns and protects the private key outside WooNooW's runtime;
• the client must ship or otherwise trust the corresponding public key;
• the build/release pipeline produces the signature;
• key distribution, rotation, revocation, and client failure policy become publisher responsibilities.

A future implementation could integrate with Gitea, another CI system, or an offline release workstation. It should be adopted only as a complete publisher-and-client workflow, not by merely requiring a non-null signature field.

Release checklist

Before announcing a release:

• Licensing and Software Distribution are enabled.
• The product has the intended software slug.
• Activation limit and expiry inheritance are correct.
• The package is attached to the same WooCommerce product.
• The version is bound to the exact artifact_download_id.
• WooNooW accepted and hashed the artifact.
• The client sends persistent installation identity on update checks.
• The client refreshes expired/consumed download tokens.
• The client rejects missing or mismatched SHA-256 before installation.