Subscriptions Manager - Trial Key Integration Guide

This guide is for developers who license their own Joomla extensions through a Subscription Manager (com_subsmgr) install. It explains what trial keys are and how to add trial support to an extension. If you are an end user of a Multizone extension, you do not need this — trials work out of the box.

{ToC}

What a trial key is

A trial key lets any site run your extension at its trial tier without you issuing a per-customer key. Each product has a single, shared key in the form:

TRIAL-{product_slug}-v{version}

for example TRIAL-com_acme-v1. Your extension ships with this key as its default, so a fresh install immediately runs at the trial tier (the limited feature set you define) until the customer enters a paid subscription key.

Trial keys are generic, not per-customer: every trial site for a product uses the same key. Per-site behaviour (expiry horizon, abuse control) is handled separately — see Day-to-day control below.

How trial validation works

1. The extension reads its configured subscription key. If none is set, it falls back to the product’s shared trial key (TRIAL-{product_slug}-v1).
2. It POSTs the key, the product slug, the requesting domain and an installation fingerprint to the Subscription Manager REST API (…/api/index.php/v1/subsmgr/validate).
3. The server resolves the tier (trial vs paid), signs the response, and returns the tier’s feature limits plus a trial expiry horizon.
4. The extension caches the signed response and gates features at render time against the returned limits.

The reference client is the shared SubscriptionValidationTrait used by the Multizone extensions — it implements the call, signature verification, fingerprint binding, signed caching, and a fail-open-to-trial fallback. Reuse its shape rather than rolling your own.

Adding trial support to your extension

1. Register the product and its trial features. Add the extension under Extensions, then define its trial-tier limits under Product Features. These values are exactly what a trial site receives. (Without trial features defined, the product will not appear in the New dropdown on the Trial Keys screen.)
2. Ship the client. Build your extension to validate against the Subscription Manager API using the SubscriptionValidationTrait pattern, defaulting to the shared trial key when no paid key is configured. Gate features at render/emission, never on save() — a live-validation result that resolves lower at save-time would otherwise drop user input.
3. Mint the key version. On the Trial Keys screen, use New → {product} to create the first trial-key version. The key string is generated for you.

Versioning and revocation

Each New creates the next version (v1, v2, …). Revoke marks a version inactive: every trial site still using that version is denied at validation and must update to a build carrying the new version. Because revocation hits every trial site on that version at once, treat it as a blunt, last-resort tool.

For targeted, day-to-day control, prefer the per-site tools rather than version revocation:

• Trial horizon — trials carry a computed expiry (first_seen + default_trial_days), so the extension can show a countdown and convert-or-degrade prompt.
• Per-(product, domain) revocation — cut off a single abusing site without affecting anyone else (see the Anomaliesreport).
• Anomalies report — surfaces over-domain use, gone-dark paid keys, and long-running unconverted trials, with one-click actions.

Security notes

• The integrity model is GPL-friendly: responses and cache rows are RSA-signed and bound to an installation fingerprint(a hash of the site’s Joomla secret), so a cached response cannot be copied between sites. It is anti-forgery + detection, not DRM.
• Validation fails open to the trial tier when the API is unreachable — the extension keeps working at trial limits rather than breaking the customer’s site.

See also:
Subscriptions Manager - How to integrate Joomla extensions to add tiered subscriptions

Subscriptions Manager Changelog

Subscriptions Manager