Skip to main content
Start selling

Freemius RESTful APIv1

Welcome to the Freemius API Documentation. The Freemius API follows RESTful principles and provides a powerful way to interact with your Freemius products programmatically. Whether you're looking to automate tasks, integrate with third-party services, or build custom applications, the Freemius API has you covered.

A few examples of what you can do with the Freemius API include:

and more.

WordPress Makers

If you are using Freemius for a WordPress product, check out our official WordPress integration guide.

Bearer Token Authentication​

The Freemius API supports Bearer Token authentication for product-specific operations.

To retrieve your API token:

  1. Go to the Freemius Developer Dashboard.
  2. Open the Settings page of the relevant product.
  3. Click on the API & Keys tab.
  4. Copy the API Bearer Authorization Token from the UI.

Use this token by including it in the Authorization header of your API requests:

Authorization: Bearer <token>

You will also need the product ID which you can find in the same API & Keys section of the product settings.

Security Warning

Never expose the API token in client-side code or public repositories. Treat it as a secret and store it securely.

Making API Requests​

When making requests, you need to add the Bearer token to the Authorization header as shown below. For example, to retrieve the users of a product:

Example:

GET /products/12345/users.json  HTTP/1.1
Host: api.freemius.com
Accept: application/json
Authorization: Bearer <token>

Regenerating API Keys​

To regenerate the API key, you need to regenerate the product's secret key.

  1. Navigate to the product's Settings page.
  2. Select the API & Keys tab.
  3. Click on the Regenerate button beside the secret key.

This regenerates both the secret key and the API token and invalidates the previous keys. Make sure to update your applications with the new keys to avoid any disruption in service.

JavaScript SDK​

The Freemius JavaScript SDK (also supports TypeScript) has built-in support for the API and can be used to make authenticated requests. Check out the JS SDK documentation for more details. It works for any JavaScript-based backend environment, such as Node.js, Bun, Deno, etc. Here's some example code to get you started:

freemius-api.ts
import { Freemius } from '@freemius/sdk';

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

// Retrieve a license by ID
const license = await freemius.api.license.retrieve(licenseId);

// Retrieve subscription of a license
const subscription = await freemius.api.license.retrieveSubscription(licenseId);

More use cases and examples can be found in the documentation.

Other Scopes and Authentication​

The Freemius API is organized around different scopes based on the top-level entity of the operation.

For example, let's say you want to list all payments of a product. This operation can be done in several scopes:

  • Product Scope: 
    GET /products/{product_id}/payments.json
  • Developer Scope: 
    GET /developers/{developer_id}/products/{product_id}/payments.json

On the other hand, if a user wants to list their payments, the endpoint is scoped to the user:

  • User Scope: 
    GET /users/{user_id}/payments.json

Some operations can be performed only from a specific scope. For example, only a developer can update a product plan or create a new plan. Therefore, the following operations work:

  • Update Plan: 
    POST /developers/{developer_id}/products/{product_id}/plans/{plan_id}.json
  • Create Plan: 
    POST /developers/{developer_id}/products/{product_id}/plans.json

If you try to perform the same operation in the product scope, it returns an error. Scopes provide a way to control access and permissions for different entities in the Freemius ecosystem.

Currently, Bearer Token authentication is supported for product scope only. If you need access to endpoints in other scopes, use secret-key-based authentication with the following libraries:

For most use cases, managing your products, licenses, and customers through the Developer Dashboard or Customer Portal provides all the necessary capabilities.

note

The rest of the documentation covers product-scoped endpoints only, which are the most commonly used by App and SaaS makers. If you need to use endpoints in other scopes, please contact our support team through the Developer Dashboard and explain your use case. We will be happy to assist you and provide guidance on how to achieve your goals with the API.

API Endpoints​

Find the full list of API endpoints in the sections below. Each section corresponds to a specific category of endpoints, such as products, subscriptions, users, etc. You can also try out the endpoints directly from the API Explorer, which provides an interactive interface for testing API requests and viewing responses.

Products ​

Products

Subscriptions ​

Subscriptions

Users ​

Users

Licenses ​

Licenses

Coupons ​

Coupons

Carts ​

Carts

Payments ​

Payments

Installations ​

Installations

Trials ​

Trials

Addons ​

Addons

Plans ​

Plans

Events ​

Events

Reviews ​

Reviews

Deployments ​

Deployments

On this page: