Add a free trial to a Chrome extension

By the end of this guide, people can try your extension before they pay. Toolaby counts free uses, Stripe runs a plan's free trial on your account, and your website can start a trial with no card. Your code reads each one with gate() and getUser().

Before you begin

• An extension wired to a tool: toolaby.js and toolaby.config.js beside your code. See the Quickstart.
• For a trial counted in days, a subscription plan under the tool's Pricing. See Pricing.
• For a trial from your website, toolaby-web.js on your site. See Your website.

1. Choose a kind of trial

Toolaby gives one trial per inbox per tool. An inbox is the address without a +tag, and for Gmail without dots. A second subscription to the tool, on any plan and from any account on the same inbox, pays from the first day. So does a buyer whose address is unverified or disposable.

2. Set free uses

Under the tool's Pricing, in the Access card, set Before paying to Free uses. Enter the number of uses, choose how often they start again (in total, a day, a week or a month), and save. A day holds up to 200 uses; a week, a month or the total, up to 1,000.

From the command line:

npx -y toolaby@latest access <tool-id> --access free_uses --free-uses 5

Add --free-uses-per day, week or month for uses that start again. When it worked, the card writes back the sentence your buyers meet: Anyone can use Tab Tidy. It is free for 5 uses per device, then a plan. Preview, at the top of the Pricing page, shows the popup in each of its states.

Toolaby counts the uses per device, or per account where Require an account is on. It counts in UTC: a day from midnight, a week from Monday, a month from the 1st. Removing the extension and adding it again makes a new device, with a count of its own. To keep a reinstall from giving the uses again, require an account.

Addresses from a throwaway mail service, and unverified ones, have no count of their own. They spend one count together, and gate() says so with sharedUses: true.

The Toolaby popup's meter says 2 free uses left today, and when more come, in the buyer's own time: More at 03:00. Once the uses are spent, the paywall shows the free-use meter, then the plan to buy.

On Test, installed copies see a change within seconds. On Live, a change shows within an hour, and within 6 minutes where the Toolaby popup opens.

3. Count a use at the action

Pass gate() the number of uses the action spends. It spends them only when it allows.

const permit = await toolaby.gate(invoices.length);
if (!permit.allowed) return { permit }; // reason 'limit', remaining, limit

While uses remain, gate() answers { allowed: true, isPremium: false, remaining, limit, used }. Once they are spent, it answers { allowed: false, reason: 'limit', remaining: 0, limit }. Where uses start again, both answers carry per and resetsAt: the period, and a Date when more come. An answer given offline has neither.

In your popup, pass a refused permit to toolaby.showPaywall(): it shows the meter, then the plans. Show what is left from the device's record, with no request:

const { usage } = await toolaby.getUser();
if (!usage.unlimited) meter.textContent = `${usage.remaining} of ${usage.limit} free`;

Where your code calls no gate(), each open of the Toolaby popup spends one use instead.

4. Give a subscription plan a free trial

Under the tool's Pricing, select Edit on a subscription plan, or New plan for a new one. Set Free trial to a number of days, from 0 to 365. Free trials are on subscription plans only.

When it worked, the plan's card carries a tag such as 7-day trial. Edit changes the trial for the next checkouts, and changes nothing for existing subscribers. To name the trial in a popup of your own, getPlans() lists each plan with its trialDays.

The checkout page shows the trial in the plan's line: 7 days free, then renews every month. Cancel any time. The paywall in the extension shows the same line. The buyer signs in, then pays on Stripe's page, which takes the card and charges nothing until the trial ends.

During the trial, the subscription is trialing:

When the trial ends, Stripe charges the card. Paid, the subscription is active. Refused, it is past_due, which unlocks nothing: gate() answers as the Free plan does. Neither sends a webhook event.

The buyer can cancel before the trial ends, from their account page. A subscription set to end unlocks until its period ends, and in a trial that period is the trial.

5. Start a trial from your website

Your website can start a trial with no card. Add a button with the tool's id:

<button data-toolaby-trial="word-count">Try it free</button>

From code, call Toolaby.startTrial({ tool: 'word-count' }). Refused, it rejects with the reason: no trial, an unverified or a disposable address.

• The trial lasts as long as the longest trial your plans offer (step 4). It unlocks what that plan does, with the Free plan's features.
• When several plans offer that longest trial, it unlocks what the one with the fewest features does.
• It needs a signed-in buyer. Clicked signed out, the button opens the sign-in page, and the trial continues when the buyer returns.
• Once started, it opens the after-purchase page, which signs the extension in to the buyer's account.
• When the page cannot see the buyer's session (Toolaby.state.mode is link), startTrial() opens the checkout page instead. On Live, the page sees the session on your own domain or through the proxy, which are Pro features: see Your website.

Wrap any HTML your visitors write, such as comments, in an element with data-toolaby-ignore. Otherwise a visitor can post a trial button, and one click by a buyer starts that buyer's only trial.

During the trial, gate() allows as it does for a paid plan. user.via is 'trial', and user.trial is { endsAt, active }. With no popup of yours behind it, the Toolaby popup shows Trial until 29 Sep. Under Customers, Extend gives the trial a later end date, and End ends it at the next check.

When the trial ends without a purchase, user.paid is false, and gate() answers as the Free plan does. user.trial still describes the trial that ran.

6. Test each trial

Try each kind you set up on Test:

• Free uses: set them, then spend them. The paywall shows the limit refusal.
• A plan's free trial: subscribe with the card 4242 4242 4242 4242. user.subscription.status is 'trialing'.
• A trial from your website: select the button while signed in, then read user.via in the extension.

Each trial needs an inbox that has not had one: a +tag address shares its inbox's trial. Copy to Live, at the foot of the tool's Set up page, creates the same plans on Live, with their trial.

Next steps

• Access and features
• Pricing
• Subscriptions
• Website components
• Gate your extension