Trial licenses

A trial is a license that expires after a few days, so people can try your app before they buy it. LicenseManager has no special trial feature: a trial is a regular license following a trial policy. That’s what makes it simple: your app validates trial keys exactly like paid ones, and the trial stops by itself when the license expires.

This guide sets up a 14-day trial of Acme Photo, on one computer, that visitors request from Acme’s website. You’ll:

Create a trial policy.
Issue a trial key when a visitor asks for one.
Handle the end of the trial in your app.
Turn the trial into a paid license.

Create the trial policy

Open the policies

Open your product, then Policies, and New policy.

Set the trial’s terms

Name: 14-day trial. Give it a slug like trial, to find it from your code.
Duration: 14 days.
Max machines: 1, so one trial can’t be shared across a team.
Max offline duration: leave the default. A license token never outlives its license, so the app stops at the end of the trial even offline, whatever this duration.
Updates: Free updates: a trial should run your latest version.

Keep your paid policy as the default

Don’t make the trial the default policy: licenses created without a policy, like by a teammate in a hurry, would be trials.

The trial’s clock starts when the license is created, not when the app is first opened: see duration. Create the trial key when the visitor asks for it, not in advance.

Issue trial keys

From your website

A Start your free trial form asks for an email. Your backend, with an API key, creates the license and emails the key:


curl -X POST https://api.licensemanager.dev/v1/products/x7Kp2QaZ/licenses \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com",
    "policyId": "p4Rt8LmQ",
    "sendKey": true
  }'

Find the policy’s id once with GET /v1/products/x7Kp2QaZ/policies?slug=trial, and keep it in your configuration.

Leave the price empty: a trial isn’t a sale, and stays out of your revenue stats. A price of 0 would count it as a free sale. See price.

By hand

For a prospect who asked by email, open Licenses, then New license, choose the trial policy, and check Email the key to the customer.

One trial per person

LicenseManager doesn’t stop an email from getting several trials: each request creates a new license. To give one trial per email, check before creating one:

Find the customer

GET /v1/products/x7Kp2QaZ/customers?email=jane@example.com. No customer means no trial yet.

List their trials

GET /v1/products/x7Kp2QaZ/licenses?customerId=c9Wd3RtE&policyId=p4Rt8LmQ. When there’s one, email its key again with POST /v1/licenses/send-keys, rather than creating a new trial.

Someone can still use another email. A trial limited to 1 machine still works on a new device with a new license: LicenseManager counts machines per license, not across licenses. If you need one trial per device, store a flag on the device when the trial starts, in your app.

In your app

Your app validates the trial key like any other key:

When the trial ends, validation fails with license_expired: show a Buy button rather than an error. See handling validation errors.
Offline, the stored token expires with the trial, at the latest: the app locks itself on time without reaching LicenseManager. See offline validation.

The license token doesn’t say which policy the license follows. To show Trial: 9 days left in your app, create trial keys with your own key, like TRIAL- followed by at least 20 random letters and digits from a secure generator, and check the token’s sub, which is the key. The days left are the token’s exp when the max offline duration is longer than the trial: otherwise, keep the end date in your app when the trial starts.

Turn a trial into a paid license

A license can’t change policy, so buying doesn’t turn the trial license into a paid one: the customer gets a new license, with a new key, following the paid policy.

The customer buys, through Stripe or your store, with the same email.
A paid license is created for the same customer, and its key emailed.
They enter the new key in your app, which replaces the trial key.
The trial license expires by itself. Its machine stays active on it, and doesn’t count on the paid license, which counts its own machines.

Since both licenses belong to the same customer, the customer portal shows both, and you see who converted: customers with a trial and a paid license.

To avoid asking for a new key, your app can let customers enter a new key anytime, from its License menu, and offer it on the trial ended screen.

Extending a trial

A prospect needs a few more days? Edit the license and push back its expiration. The key stays the same: the app picks up the new date at its next validation.

Edge cases

Trials and your plan. Validated trials count toward your plan’s active licenses until they expire. Expired trials don’t count.

A trial that’s never opened never counts as active, and expires on its own.

Shortening a running trial applies at the app’s next validation: the token already issued stays valid until its own expiration.

Stripe and trials. Stripe’s subscription trials aren’t supported by the Stripe integration: issue trials from your website, and sell the paid license with a one-time price.