@freemius/sdk

JavaScript SDK

Monetize your SaaS or app backend faster: one lightweight, fully typed SDK for Checkout creation, pricing + plans, licenses, subscriptions, purchases, entitlements, and secure webhooks. Built for real-world production flows.

Get Started » · Next.js Guide » · React Starter Kit »

Looking for a step‑by‑step walkthrough of backend checkout generation, secure purchase validation, local entitlement storage, webhook‑driven license lifecycle syncing, and feature gating logic? Check out the guides below.

• Next.js / React Starter Kit Integration.
• Framework Agnostic Integration.

We also have the React Starter Kit you can use on your front-end to quickly render Checkout overlays, pricing tables, and a customer portal.

Why @freemius/sdk?

• 🔐 Backend‑only & secure: built to keep your API / Secret keys off the client.
• 🧠 Fully typed: rich IntelliSense for API filters, webhook payloads, pricing, licenses, subscriptions, payments, and users.
• 🛒 Frictionless Checkout builder: generate overlay options & hosted links, sandbox mode, redirect verification, upgrade authorization.
• 💳 Subscriptions & one‑off purchases: normalize purchase + entitlement logic with helpers (e.g. purchase.retrievePurchaseData(), entitlement.getActive()).
• 🧱 Framework friendly: works great with Next.js (App Router), Express, Fastify, Hono, Nuxt server routes, Workers, etc.
• 🧾 Licenses, billing & invoices: retrieve, paginate, iterate, and show billing data to your customers.
• 🌐 Webhooks made simple: strongly typed listener + request processors for Fetch runtimes, Node HTTP, serverless, edge.
• ⚡ Runtime agnostic: Node.js, Bun, Deno—ship the same code.
• 🪶 Lightweight, modern ESM-first design (tree-shakeable patterns).
• 🚀 Production patterns included: entitlement storage, retrieval & paywalls.

Installation

npm install @freemius/sdk @freemius/checkout zod

Requires Node.js 18+ (or an Edge runtime supporting Web Crypto + standard fetch APIs). See the official documentation for full capability reference.

10 Seconds Initialization

Go to the Freemius Developer Dashboard) and obtain the following:

• productId – Numeric product identifier
• apiKey – API key (used as bearer credential)
• secretKey – Secret key used for signing (HMAC) and secure operations
• publicKey – RSA public key for license / signature related verification flows

Store these in your environment variables, e.g. in a .env file:

FREEMIUS_PRODUCT_ID=12345
FREEMIUS_API_KEY=...
FREEMIUS_SECRET_KEY=...
FREEMIUS_PUBLIC_KEY=...

Now initialize the SDK:

import { Freemius } from '@freemius/sdk';

export const freemius = new Freemius({
    productId: Number(process.env.FREEMIUS_PRODUCT_ID),
    apiKey: process.env.FREEMIUS_API_KEY!,
    secretKey: process.env.FREEMIUS_SECRET_KEY!,
    publicKey: process.env.FREEMIUS_PUBLIC_KEY!,
});

API Client

async function getUserByEmail(email: string) {
    const user = await freemius.api.user.retrieveByEmail(email);
    // user has typed shape matching Freemius API spec
    return user;
}

See also api.product, api.license, api.subscription, api.payment, api.user, etc.

Documentation »

Checkout & Pricing

Construct a hosted checkout URL or retrieve overlay options (pair with @freemius/checkout on the client):

const checkout = await freemius.checkout.create();
checkout.setCoupon({ code: 'SAVE10' });
checkout.setTrial('paid');

const hostedUrl = checkout.getLink(); // Redirect user or generate email link
const overlayOptions = checkout.getOptions(); // Serialize & send to frontend for modal embed

Retrieve pricing metadata (plans, currencies, etc.):

async function fetchPricing() {
    return await freemius.pricing.retrieve();
}

Use this to create your own pricing table on your site.

Documentation »

Webhooks

Listen for and securely process webhook events. Example using Node.js HTTP server:

import { createServer } from 'node:http';

const listener = freemius.webhook.createListener();

listener.on('license.created', async ({ objects: { license } }) => {
    // Persist or sync license state in your datastore
    console.log('license.created', license.id);
});

const server = createServer(async (req, res) => {
    if (req.url === '/webhook' && req.method === 'POST') {
        await freemius.webhook.processNodeHttp(listener, req, res);
    } else {
        res.statusCode = 404;
        res.end('Not Found');
    }
});

server.listen(3000, () => {
    console.log('Webhook listener active on :3000');
});

Documentation »

Purchase / License Retrieval

Resolve purchase data or validate entitlement status:

async function retrievePurchase(licenseId: number) {
    const purchase = await freemius.purchase.retrievePurchase(licenseId);
    if (!purchase) throw new Error('Purchase not found');
    return purchase;
}

const purchase = await retrievePurchase(123456);
if (purchase) {
    db.entitlement.insert(purchase.toEntitlementRecord());
}

async function getActiveEntitlement(userId: number) {
    const entitlements = await db.entitlement.query({ userId, type: 'subscription' });

    return freemius.entitlement.getActive(entitlements);
}

Documentation »

Security & Operational Notes

Backend Use Only

Never initialize the SDK in browser / untrusted contexts. The secretKey and apiKey are privileged credentials.

Happy shipping. ⚡

License

MIT © Freemius Inc

Payments, tax handling, subscription lifecycle management, and licensing are abstracted so you can focus on product functionality rather than billing infrastructure.

https://freemius.com