Freemius API (1.0)

Welcome to the Freemius API Documentation!

You can use our API to access Freemius API endpoints, which can get information on various aspects of Freemius.

Manage products.
Manage license verifications.
Create custom integration with your SaaS.

If you're using Freemius for a WordPress product, please check out our official SDK.

Browse Tutorials and Guides.

Bearer Token Auth

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

To retrieve your API token:

Go to the Freemius Developer Dashboard.
Open the Settings page of the relevant product.
Click on the API Token tab.
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 {api_token}

Bearer tokens are scoped to a specific product. This means they can only be used with endpoints under the /products/{product_id}/ namespace. For example:

GET /products/12345/users.json
Authorization Bearer {api_token}

Requests to endpoints outside the product scope will result in an authorization error.

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: /products/{product_id}/payments.json.
Developer Scope: /developers/{developer_id}/products/{product_id}/payments.json.

On the other hand, if a user would want to list their payment, then endpoint will be scoped to the user:

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

Some operations can be done from a particular scope only. For example only a developer can update a plan of a product or create a new plan. So the following operations will 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 on a product scope, it will return an error. The scopes provides 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 others scopes, use the secret-key based authentication with the following SDKs:

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

Download OpenAPI description

openapi.yaml

Overview

URL

https://freemius.com

Freemius Support

support@freemius.com

License

Proprietary

Servers

Production API

https://api.freemius.com/v1/

Mock server

https://docs.freemius.com/_mock/api/

Products

All operations which can be done on a product.

Operations

Subscriptions

All operations associated to a subscription.

Operations

Users

All operations which can be done on a user belonging to a store or a product.

Operations

Licenses

All operations which can be done on a license belonging to a store or a product.

Operations

Coupons

All operations which can be done on a coupon belonging to a store or a product.

Operations

Carts

All operations which can be done on a cart belonging to a store or a product.

Operations

Payments

All operations associated to a payment.

Operations

Installations

Operations related to the installation of a product.

Operations

List all plans

Request

Retrieve all the available product plans to which an install can subscribe.

Path

product_idinteger(int64)>= 1required

The ID of the product.

Example: 1234

install_idinteger(int64)>= 1required

The ID of the install.

Example: 1234

Query

show_pendingboolean

Show all plans whether released to customers or hidden.

Default false

fieldsstring

Comma separated list of fields to return in the response. If not specified, all fields are returned.

Example: fields=id,name,slug

curl -i -X GET \
  'https://api.freemius.com/v1/products/1234/installs/1234/plans.json?fields=id%2Cname%2Cslug&show_pending=false' \
  -H 'Authorization: Bearer <YOUR_AccessToken_HERE>'

Responses

Install Plans

Bodyapplication/json

plansArray of objects(Plan)

Response

application/json

{
  "plans": [
    { … }
  ]
}

Create a new license

Request

Create a new license and assign it to the install.

Either period or expires_at must be set.

Path

product_idinteger(int64)>= 1required

The ID of the product.

Example: 1234

install_idinteger(int64)>= 1required

The ID of the install.

Example: 1234

plan_idinteger(int64)>= 1required

The ID of the plan.

Example: 1234

pricing_idinteger(int64)>= 1required

The ID of the Pricing.

Example: 1234

Query

fieldsstring

Comma separated list of fields to return in the response. If not specified, all fields are returned.

Example: fields=id,name,slug

Bodyapplication/jsonrequired

is_block_featuresboolean

Whether to block features after expiration of the license. If set to false, this would not block features, would only block updates.

Default true

periodnumber

The billing cycle of the subscription in number of months. 1 means monthly, 12 means annually, 0 means lifetime usually when subscriptions are created for lifetime trials.

Enum1120

expires_atstring or null(date-time)

The expiration date of the license. If null then it's a lifetime license.

Example: "2025-12-31 23:59:59"

send_emailboolean

Whether or not to email the license key and download link to the user.

curl -i -X POST \
  'https://api.freemius.com/v1/products/1234/installs/1234/plans/1234/pricing/1234/licenses.json?fields=id%2Cname%2Cslug' \
  -H 'Authorization: Bearer <YOUR_AccessToken_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{}'

Responses

License created successfully.

Bodyapplication/json

idstring(int64)>= 1

The unique identifier of the entity.

Example: "123456"

createdstring(date-time)

The date and time the entity was created, under UTC timezone.

Example: "2025-01-01 00:00:00"

updatedstring or null(date-time)

The date and time the entity was updated, under UTC timezone. If null then the entity was never updated since its creation.

Example: "2025-01-01 00:00:00"

plugin_idstring(int64)>= 1

The ID of the product the entity belongs to.

Example: "123456"

user_idstring or null(int64)>= 1

The ID of the user the entity belongs to. If NULL then still not associated to any user.

Example: "123456"

plan_idstring(int64)>= 1

The ID of the plan associated with the entity.

Example: "123456"

pricing_idstring or null(int64)>= 1

The ID of the pricing associated with the entity.

Example: "123456"

quotainteger or null

The maximum number of license activations. If null then the license will support unlimited activations.

Example: 10

activatedinteger

The total number of production activation the license has. This does not count local or staging environment activations.

Example: 1

activated_localinteger or null

The number of times the license is activated on local or staging environments.

Example: 1

expirationstring or null(date-time)

The expiration date of the license. If null then it's a lifetime license.

Example: "2025-12-31 23:59:59"

secret_keystring

The license key. This is used for activating the license on the user's site.

Example: "sk_123FGqM456Pa786WtOp%^+67Y+;sXXz"

is_free_localhostboolean

Whether the license offers unlimited local or staging environment activations.

Default true

is_block_featuresboolean

Whether to block features after expiration of the license. If set to false, this would not block features, would only block updates.

Default true

is_cancelledboolean

If the license is canceled from the Developer Dashboard.

is_whitelabeledboolean

Guide the Freemius WP SDK when the product should be running in a white-label mode.

environmentnumber

The environment the entity belongs to. 0 means it belongs to the production environment, 1 means it belongs to the sandbox environment.

Enum10

Example: 0

sourcenumber

The source of the migration data. To get support migrating from other platform please see our documentation.

0 - Freemius
1 - Other
2 - Easy Digital Downloads (EDD)
3 - WooCommerce (WC)
4 - Rating Widget
5 - Gumroad
6 - CodeCanyon
7 - ThemeForest
8 - AppSumo
9 - SendOwl
10 - WHMCS
11 - Lemon Squeezy

Enum0123456789

Response

application/json

{
  "id": "123456",
  "created": "2025-01-01 00:00:00",
  "updated": "2025-01-01 00:00:00",
  "plugin_id": "123456",
  "user_id": "123456",
  "plan_id": "123456",
  "pricing_id": "123456",
  "quota": 10,
  "activated": 1,
  "activated_local": 1,
  "expiration": "2025-12-31 23:59:59",
  "secret_key": "sk_123FGqM456Pa786WtOp%^+67Y+;sXXz",
  "is_free_localhost": true,
  "is_block_features": true,
  "is_cancelled": true,
  "is_whitelabeled": true,
  "environment": 0,
  "source": 0
}

Start a trial

Request

Start the trial of a plan for which an install is subscribed. The install must not have utilized the trial before.

Path

product_idinteger(int64)>= 1required

The ID of the product.

Example: 1234

install_idinteger(int64)>= 1required

The ID of the install.

Example: 1234

plan_idinteger(int64)>= 1required

The ID of the plan.

Example: 1234

Query

fieldsstring

Comma separated list of fields to return in the response. If not specified, all fields are returned.

Example: fields=id,name,slug

Bodyapplication/jsonrequired

trial_endsstring(date-time)

The expiry date of the trial. If set, will set the trial expiration based on that parameter. Note: Trial expiration date cannot exceed the maximum trial period days based on the plan configuration.

Example: "2025-01-01 00:00:00"

phonestring

The phone number used in the billing.

Example: "555-555-5555"

is_migrationboolean

Whether emails will be sent to users or log events. If true, no emails will be sent nor events logged.

trial_tokenstring

Security token for sandbox mode trial.

trial_timestampstring

Security timestamp for sandbox mode trial.

Example: "1730160000"

curl -i -X POST \
  'https://api.freemius.com/v1/products/1234/installs/1234/plans/1234/trials.json?fields=id%2Cname%2Cslug' \
  -H 'Authorization: Bearer <YOUR_AccessToken_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{}'

Responses

Started Trial

Bodyapplication/json

trialobject(Trial)

A trial represents a user's trial period for a product. Please read our documentation to learn more about trials.

Response

application/json

{
  "trial": {
    "id": "123456",
    "created": "2025-01-01 00:00:00",
    "updated": "2025-01-01 00:00:00",
    "plugin_id": "123456",
    "user_id": "123456",
    "payment_id": "123456",
    "subscription_id": "123456",
    "license_id": "123456",
    "trial_ends_at": "2025-01-01 00:00:00",
    "with_payment_method": true,
    "canceled_at": "2025-01-01 00:00:00",
    "converted_at": "2025-01-01 00:00:00",
    "environment": 0
  }
}

Trials

Operations related to a trial license of a product.

Operations

Addons

Operations related to an addon of a product.

Operations

Plans

Operations related to plans, pricings and features of a product.

Operations

Deployments

Operations related to version deployments and retrieval.

Operations

Freemius API (1.0)

Bearer Token Auth

Other Scopes and Authentication

Products

Subscriptions

Users

Licenses

Coupons

Carts

Payments

Installations

List all plans

Request

Responses

Was this helpful?

Create a new license

Request

Responses

Was this helpful?

Start a trial

Request

Responses

Was this helpful?

Trials

Addons

Plans

Deployments