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

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

List all currencies

Request

Retrieve all the currencies available for all the plans.

Path

product_idinteger(int64)>= 1required

The ID of the product.

Example: 1234

curl -i -X GET \
  https://api.freemius.com/v1/products/1234/plans/currencies.json \
  -H 'Authorization: Bearer <YOUR_AccessToken_HERE>'

Responses

The list of all currencies for all the plans.

Bodyapplication/json

currenciesArray of strings

Items Enum"usd""eur""gbp"

Response

application/json

{
  "currencies": [
    "usd"
  ]
}

List all features

Request

Retrieve the features collection of a plan.

Path

product_idinteger(int64)>= 1required

The ID of the product.

Example: 1234

plan_idinteger(int64)>= 1required

The ID of the plan.

Example: 1234

Query

countinteger[ 1 .. 50 ]

The number of records to return.

Default 25

Example: count=10

offsetinteger>= 0

The number of records to skip before starting to return records. Default is 0.

Default 0

Example: offset=10

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/plans/1234/features.json?count=10&fields=id%2Cname%2Cslug&offset=10' \
  -H 'Authorization: Bearer <YOUR_AccessToken_HERE>'

Responses

Feature listing of a plan.

Bodyapplication/json

featuresArray of objects

Response

application/json

{
  "features": [
    { … }
  ]
}

Retrieve a plan

Request

Retrieve a specific plan by ID.

Path

product_idinteger(int64)>= 1required

The ID of the product.

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

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

Responses

Plan listing.

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"

namestring(slug)

The name of the plan. Only lowercase characters allowed.

Example: "professional"

titlestring

The title of the plan. This is the human readable name of the plan. Please do not add the suffix Plan to the title, as Freemius does that for you at various places.

Example: "Professional"

descriptionstring or null

The description of the plan.

Example: "For small to medium businesses."

is_free_localhostboolean

Whether the plan offers unlimited local or staging activations with the same license.

Default true

is_block_featuresboolean

Whether to block features on expiration of annual licenses. If false, does not block features but only block updates and support.

Default true

is_block_features_monthlyboolean

Whether to block particular features on expiration of monthly licenses. If false, does not block features but only block updates and support.

Default true

license_typeinteger

The type of the license. 0 for per domain license. 1 for per subdomain license.

Default 0

Enum01

trial_periodinteger or null>= 1

The number of days a trial period will last. If null the plan does not support trials.

Example: "14"

is_require_subscriptionboolean

Whether to require a subscription payment for the trial period.

support_kbstring or null

The Knowledge Base URL.

Example: "https://example.com/help/documentation"

support_forumstring or null

The support Forum URL.

Example: "https://example.com/support"

support_emailstring or null

The support email address.

Example: "support@example.com"

support_phonestring or null

The support phone contact.

Example: "555-555-5555"

support_skypestring or null

The support Skype username.

Example: "skype_username"

is_success_managerboolean

Is a personal success manager allocated with the plan.

is_featuredboolean

Whether this is a featured plan.

is_hiddenboolean

Whether to hide the plan from the auto-generated pricing page. Mostly relevant for WordPress products and our WordPress SDK. Please see our pricing-page library to implement your own.

Response

application/json

{
  "id": "123456",
  "created": "2025-01-01 00:00:00",
  "updated": "2025-01-01 00:00:00",
  "plugin_id": "123456",
  "name": "professional",
  "title": "Professional",
  "description": "For small to medium businesses.",
  "is_free_localhost": true,
  "is_block_features": true,
  "is_block_features_monthly": true,
  "license_type": 0,
  "trial_period": "14",
  "is_require_subscription": true,
  "support_kb": "https://example.com/help/documentation",
  "support_forum": "https://example.com/support",
  "support_email": "support@example.com",
  "support_phone": "555-555-5555",
  "support_skype": "skype_username",
  "is_success_manager": true,
  "is_featured": true,
  "is_hidden": true
}

List all plans

Request

Retrieve the plans collection.

Path

product_idinteger(int64)>= 1required

The ID of the product.

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

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

Responses

List of all the plans.

Bodyapplication/json

plansArray of objects(Plan)

Response

application/json

{
  "plans": [
    { … }
  ]
}

Clone pricing to other currency

Request

Create new pricing in a specified currency from an existing one.

Path

product_idinteger(int64)>= 1required

The ID of the product.

Example: 1234

plan_idinteger(int64)>= 1required

The ID of the plan.

Example: 1234

Bodyapplication/jsonrequired

to_currencystring

The currency of the pricing to be created.

Enum"eur""usd""gbp"

Example: "eur"

from_currencystring

The currency of the pricing to clone.

Default "usd"

Enum"eur""usd""gbp"

curl -i -X POST \
  https://api.freemius.com/v1/products/1234/plans/1234/pricing/clone.json \
  -H 'Authorization: Bearer <YOUR_AccessToken_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{}'

Responses

New pricing for the currency created.

Bodyapplication/json

pricingArray of objects(Pricing)

Response

application/json

{
  "pricing": [
    { … }
  ]
}

Retrieve a pricing

Request

Retrieve a specific plan pricing by ID.

Path

product_idinteger(int64)>= 1required

The ID of the product.

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

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

Responses

The plan pricing.

Bodyapplication/json

pricingobject(Pricing)

The pricing represents the cost of a quota and billing cycles of a plan.

Response

application/json

{
  "pricing": {
    "id": "123456",
    "created": "2025-01-01 00:00:00",
    "updated": "2025-01-01 00:00:00",
    "currency": "usd",
    "plan_id": "1234",
    "licenses": "10",
    "monthly_price": "59.99",
    "annual_price": "159.99",
    "lifetime_price": "359.99",
    "is_whitelabeled": true,
    "is_hidden": true
  }
}

List all plan's pricing

Request

Retrieve the collection of all the plan's pricings.

Path

product_idinteger(int64)>= 1required

The ID of the product.

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

currencystring= 3 characters

3-char currency code.

Enum"usd""eur""gbp"

countinteger[ 1 .. 50 ]

The number of records to return.

Default 25

Example: count=10

offsetinteger>= 0

The number of records to skip before starting to return records. Default is 0.

Default 0

Example: offset=10

curl -i -X GET \
  'https://api.freemius.com/v1/products/1234/plans/1234/pricing.json?count=10&currency=usd&fields=id%2Cname%2Cslug&offset=10' \
  -H 'Authorization: Bearer <YOUR_AccessToken_HERE>'

Responses

The collection of the plan's pricing.

Bodyapplication/json

pricingArray of objects(Pricing)

Response

application/json

{
  "pricing": [
    { … }
  ]
}

Create a license

Request

Create a new license for the plan and pricing. Please note that:

Either period or expires_at or is_block_features must be set.
If you create a license with is_block_features set to false and do not specify period and expires_at, the license will never expire or block features and will continue to work for lifetime.
If you specify an email address, the user must have already activated a license or installed your product before. If your user has not activated a license, then please don't use the field and when they activate the license we will collect their email and register the user with Freemius.
Use the source parameter only when creating migrated licenses from a legacy system.

More information about every other parameters can be found below.

Path

product_idinteger(int64)>= 1required

The ID of the product.

Example: 1234

plan_idinteger(int64)>= 1required

The ID of the plan.

Example: 1234

pricing_idinteger(int64)>= 1required

The ID of the Pricing.

Example: 1234

Bodyapplication/jsonrequired

is_whitelabeledboolean

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

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

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

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"

emailstring

(optional) License owner email.

existing_install_idstring

(optional) If the module type is bundle and existing_install_id is a valid ID of an install that is using a product of the bundle, a child license will automatically be created and activated for the install.

send_emailboolean

(optional) Whether to email the license key and download link to the user.

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

license_keystring

(optional) Predefined license key - this can be used when duplicating a license of another product into another product.

curl -i -X POST \
  https://api.freemius.com/v1/products/1234/plans/1234/pricing/1234/licenses.json \
  -H 'Authorization: Bearer <YOUR_AccessToken_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{}'

Responses

The license created successfully.

Bodyapplication/json

licenseobject(License)

A license represents authorization to use available features of the product.

Response

application/json

{
  "license": {
    "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
  }
}

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

Trials

Addons

Plans

List all currencies

Request

Responses

Was this helpful?

List all features

Request

Responses

Was this helpful?

Retrieve a plan

Request

Responses

Was this helpful?

List all plans

Request

Responses

Was this helpful?

Clone pricing to other currency

Request

Responses

Was this helpful?

Retrieve a pricing

Request

Responses

Was this helpful?

List all plan's pricing

Request

Responses

Was this helpful?

Create a license

Request

Responses

Was this helpful?

Deployments