Freemius TypeScript SDK

Official, minimal TypeScript/JavaScript server SDK for integrating Freemius into SaaS & application backends. Provides typed API access, hosted checkout helpers, webhook verification, purchase / license / entitlement retrieval, and lightweight utilities – without imposing a framework.

Installation

npm install @freemius/sdk

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

Core Capabilities

Focused, framework‑agnostic primitives for securely interacting with the Freemius platform:

• Typed API Client: Fine-tuned OpenAPI-derived API classes to easily interact with the Freemius REST API.
• Checkout Utilities: Create Checkout URLs or Options for the Overlay mode, sandbox mode, redirect result parsing etc.
• Webhook Processing: HMAC‑SHA256 signature verification + event listener abstraction
• Purchases & Entitlements: License retrieval, entitlement state validation, minimal model helpers

See the full documentation for all exported capabilities.

Initialization

You must supply four credentials (obtainable via the Freemius Developer Dashboard):

• 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

Recommended environment variables (example):

FREEMIUS_PRODUCT_ID=12345
FREEMIUS_API_KEY=...
FREEMIUS_SECRET_KEY=...
FREEMIUS_PUBLIC_KEY=-----BEGIN PUBLIC KEY-----...-----END PUBLIC KEY-----

Hint: You can get the environment variables from the Freemius Developer Dashboard.

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!,
});

Edge runtimes: ensure the secret material is not bundled client‑side; pass via secure runtime environment injection.

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.

Checkout

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

Webhooks

Minimal Node HTTP example (raw body required for signature verification):

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');
});

Pricing

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.

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;
}

Security & Operational Notes

Backend Use Only

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

Next.js / React Starter Kit Integration

For an end‑to‑end reference (auth, UI components, portal flows, pricing tables), consult the Next.js Integration Guide and the accompanying Starter Kit repository section.