Add payments to a Chrome extension

By the end of this guide, your Chrome extension sells a plan on your own Stripe account. Your paid action asks Toolaby first and answers a refusal with the paywall. A test purchase has unlocked the extension, and the Live build is on the Chrome Web Store.

Before you begin

• A Chrome extension with its manifest.json at the top of its folder, or a WXT, CRXJS or Plasmo project. For another bundler, see Frameworks.
• Node.js 20 or later, for the command line.
• Nothing from Stripe on Test. Toolaby makes a Stripe test account for your workspace.
• To ship: a Chrome Web Store developer account, and your business's details for Stripe's onboarding.

1. Create a workspace

Open the dashboard at toolaby.app/test/dev and sign in with the one-time link sent to your email. If sign-up asks for an invitation, request one at toolaby.app/access.

The first sign-in asks for your workspace's name. The workspace is the seller a buyer sees: its name, its support address and, later, its domain.

This is Test, where buyers pay with Stripe's test cards. There is nothing to connect: Configure → Payments shows the workspace's Stripe test account Ready a minute or two later. You connect your own Stripe account on Live, in step 8.

2. Register a tool

On the Tools page, select Register a tool (New once you have tools) and enter a name. The tool id is made from it. Edit the id changes it before you create the tool; after that it is permanent.

The commands below take the full id, shown as Tool id on the tool's page, such as <workspace>--word-count.

3. Add a plan

On the tool's Pricing page, select New plan. Choose the billing: once, for a lifetime licence, or a subscription, monthly or yearly. Enter the amount and currency. Each plan is a Price on your Stripe account.

Or from the terminal:

npx -y toolaby@latest plan add <tool-id> --billing one_time --amount 5 --currency usd

A subscription takes --billing subscription --interval month (or year), and --trial-days for a free trial. See Pricing for every field.

4. Wire the extension

Open the tool. Until someone uses it, its page is Set up, and its first step is wiring. Select Choose your extension's folder to wire it in Chrome, copy the prompt into a coding agent, or run the command in your extension's folder:

npx -y toolaby@latest wire <tool-id>

The first run shows a code to approve in your browser. In a plain extension, the wiring then:

• writes the client (toolaby.js, toolaby.config.js with your tool key, toolaby.d.ts) and the Toolaby popup beside your code;
• adds to manifest.json the key that gives every copy the same id, the storage permission, and your workspace's address under externally_connectable. It adds no host permission, so Chrome shows no warning for Toolaby;
• puts the Toolaby background, toolaby.background.js, in front of yours, which runs as it did;
• sets the Toolaby popup as the action popup, unless your code calls chrome.action.setPopup() or getPopup(). It opens your popup when the device may continue, and the paywall when it may not.

A WXT project gets a module that WXT loads by itself. CRXJS and Plasmo projects get printed lines for the framework's config.

Load the extension at chrome://extensions (Developer mode, then Load unpacked), from its output folder if it has a build. When it worked, step 2 of Set up says Checked in.

5. Choose what is free

A new tool is Everything free: the Toolaby popup opens straight onto your popup. The Access card, at the top of Pricing, sets what a person gets before paying:

Choose Free uses or Nothing free, and select Save. The Require an account switch on the same card makes everyone sign in first. Preview shows the paywall in each of its states.

Open the extension's popup. With Nothing free it shows your plans. With Free uses it opens your popup until the device has spent its uses. A later change under Access shows at the next open, with no new build.

6. Gate the paid action

Where your extension does the work it charges for, ask first, and answer a refusal with the paywall. In your popup, inside the handler of that action:

import { toolaby } from './toolaby.js';

document.getElementById('export').addEventListener('click', async () => {
  const permit = await toolaby.gate();
  if (!permit.allowed) return toolaby.showPaywall(permit);
  runExport(); // the work you charge for
});

The popup loads this script as a module: <script type="module" src="popup.js"></script>. Keep the check inside the handler: a return outside a function does not run.

• gate() answers a paid device from its token, with no request. With Free uses, it spends a use only when it allows.
• showPaywall() shows the paywall for the permit's reason, with a Back button, and returns to your popup once the device may continue.
• gate() runs anywhere. showPaywall() runs in your popup or side panel: from the background, return the refused permit to the page that asked.

To sell a feature rather than the whole tool, add it on the Features card under Pricing. Then pass its key: toolaby.gate({ feature: 'export' }).

Run npx -y toolaby@latest upgrade <tool-id>, then rebuild and reload. upgrade writes countOpens: false in toolaby.config.js once your code calls toolaby.gate(), so opening the popup spends no free use.

7. Make a test purchase

Open the popup and select the plan's button, such as Buy once or Subscribe. With Free uses, spend them first. The checkout page opens with that plan chosen: select its button there. A subscription asks you to sign in first.

Pay on Stripe's page with the card 4242 4242 4242 4242, any future date and any CVC. The after-purchase page signs the extension in to the account the purchase is on, and the popup opens your popup. Bought signed out, the page's button is Sign in to unlock.

When it worked, you appear on the tool's Customers page.

8. Connect Stripe and copy the tool to Live

Open the dashboard on Live, at toolaby.app/dev. Your first visit asks for a workspace name: give the same name as on Test.

Under Configure → Payments, select Connect. Toolaby makes a Stripe account for the workspace, with its own Stripe Dashboard, and opens Stripe's onboarding. It does not attach a Stripe account you already have. When it worked, Configure → Payments shows Connected.

Buyers pay on that account and see your name on their statement. Toolaby costs 0.5% of a sale, or $25 a month per workspace. On the Hobby plan the 0.5% is a Stripe application fee on each sale; Pro takes none. See Money.

Then, on Test, open the tool's Set up page and select Copy to Live, at its foot. Toolaby creates the tool on Live with the same tool id, its Free plan, features and plans. When it worked, the page says On Live.

9. Ship the Live build

In the extension's folder, put the Live tool key in:

npx -y toolaby@latest wire <tool-id> --live --force

It writes the Live tool key (tk_live_…) into toolaby.config.js, and your workspace's Live address under externally_connectable in place of the Test one.

Build as you always do, then make the zip:

npx -y toolaby@latest pack

pack writes <name>-<version>.zip, without the manifest's key. It stops with the reason when the build carries a tk_test_ key or localhost in its manifest.

In the Chrome Web Store Developer Dashboard, select New item and upload the zip. On the Privacy tab, declare what your extension collects. Toolaby's part is a signed-in buyer's email address (Personally identifiable information) and the sign-in credential kept on the device (Authentication information). Review takes from a few hours to several days.

After the first upload, open the tool's Settings on Live and paste the listing's address under Store → Chrome Web Store listing. Toolaby then accepts your tool key from the store copy and your unpacked copy, and refuses any other extension.

Next steps

• Gate your extension — features, metered uses, content scripts, and your popup first.
• Pricing — trials, device counts, seats and coupons.
• Subscriptions — renewals, failed payments and cancellation.
• Ship to the Chrome Web Store — every check pack makes, and updates.
• Webhooks — tell your server about purchases and refunds.