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:

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

Terms of Service

Languages
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

Deployments

Operations related to version deployments and retrieval.

Operations

Update a deployment

Request

Update a specific deployed version of the product. This applies to WordPress products only. Use this endpoint to update the release_mode of a deployment to make it available to your customers.

Release Modes

Defined by the release_mode property, with the following possible values:

  • pending – The deployment is pending and not visible to customers. This is the default value.
  • beta – The deployment is in beta mode. Only customers with beta access will see this version.
  • released – The deployment is released and visible to all customers.

Additionally, WordPress plugins and themes support incremental releases and staged rollouts:

  • Incremental Release: Controlled via the is_incremental flag, incremental releases enforce sequential updates, requiring users to install designated intermediate versions before proceeding to newer ones.
  • Staged Rollout: Managed through the limit and percentage_limit flags, staged rollouts enable gradual deployment of updates to a subset of users, allowing for monitoring and issue resolution before full release.

Note: Incremental Release and Staged Rollout are not supported for templates and widgets.

Path
product_idinteger(int64)>= 1required

The ID of the product.

Example: 1234
tag_idinteger(int64)>= 1required

The ID of the product version.

Example: 1234
Bodyapplication/json
release_modestring

The release mode of the product.

Enum"released""pending""beta"
limitinteger>= 1

The maximum number of downloads allowed for this version. This is used for staged rollout of WordPress products. Unlimited number is set as null.

Example: 50
percentage_limitinteger[ 0 .. 100 ]

Instead of limit, you can use this property to limit the percentage of license owners that will receive an update. The value must be between 0 and 100. Behind the scenes the system will count the current active license owners and convert it into an absolute value.

is_incrementalboolean

Determines whether the version is incremental or not.

Example: true
curl -i -X PUT \
  https://api.freemius.com/v1/products/1234/tags/1234.json \
  -H 'Authorization: Bearer <YOUR_AccessToken_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{}'

Responses

The updated deployment.

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"
developer_idstring(int64)>= 1

The ID of a developer.

Example: "1234"
slugstring or null

The slug of the product. This is auto-generated from your product settings.

Example: "my-freemius-plugin"
premium_slugstring or null

The slug of the premium product. This is auto-generated from your product's settings.

Example: "my-freemius-plugin-pro"
versionstring(semver)

The version of the product. For WordPress.org products (plugins and themes), we recommend using semver semantics to support composer integration.

Example: "1.0.0"
sdk_versionstring

The Freemius SDK version. Only relevant for WordPress products using the Freemius WP SDK.

Example: "1.2.2"
requires_platform_versionstring or null

The platform version required (e.g WordPress version).

Example: "1.0.0"
requires_programming_language_versionstring or null

The programming language version (e.g PHP version).

Example: "5.6"
tested_up_to_versionstring or null

The tested platform version that the product is compatible (e.g WordPress version).

Example: "1.0.0"
downloadedinteger>= 0

The number of times the product has been downloaded.

Example: "1234"
has_freeboolean

If the product has a free version.

has_premiumboolean

If the product has a premium version.

release_modestring

The release mode of the product.

Enum"released""pending""beta"
limitinteger>= 1

The maximum number of downloads allowed for this version. This is used for staged rollout of WordPress products. Unlimited number is set as null.

Example: 50
uniquesinteger>= 1

The number of unique users that have downloaded the product.

Example: "1234"
is_incrementalboolean

Determines whether the version is incremental or not.

Example: true
Response
application/json
{
  "id": "123456",
  "created": "2025-01-01 00:00:00",
  "updated": "2025-01-01 00:00:00",
  "plugin_id": "123456",
  "developer_id": "1234",
  "slug": "my-freemius-plugin",
  "premium_slug": "my-freemius-plugin-pro",
  "version": "1.0.0",
  "sdk_version": "1.2.2",
  "requires_platform_version": "1.0.0",
  "requires_programming_language_version": "5.6",
  "tested_up_to_version": "1.0.0",
  "downloaded": "1234",
  "has_free": true,
  "has_premium": true,
  "release_mode": "released",
  "limit": 50,
  "uniques": "1234",
  "is_incremental": true
}

Download a deployment

Request

Download a specific deployed version of the product. This is for WordPress products only (including plugins, themes, templates and widgets). It outputs the zip file of the deployed version.

You can download both the premium and the free version of the deployment using the is_premium flag. This will help you setup automation to deploy Freemius generated free version to WordPress.org repository.

Path
product_idinteger(int64)>= 1required

The ID of the product.

Example: 1234
tag_idinteger(int64)>= 1required

The ID of the product version.

Example: 1234
Query
is_premiumboolean

(Optional) Whether to retrieve a premium version of the product or not. For WordPress products (plugins and themes) only.

Default "true"
curl -i -X GET \
  'https://api.freemius.com/v1/products/1234/tags/1234.zip?is_premium=true' \
  -H 'Authorization: Bearer <YOUR_AccessToken_HERE>'

Responses

The zip file of the deployed version.

Bodyapplication/zip
Response
No content

List all deployments

Request

Get the product version collection. This is for WordPress products only.

Path
product_idinteger(int64)>= 1required

The ID of the product.

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

Responses

The product version collection.

Bodyapplication/json
tagsArray of objects(ProductTag)
Response
application/json
{
  "tags": [
    { … }
  ]
}

Create a deployment

Request

Upload a new version of the product (for WordPress products only). The endpoint supports only the multipart/form-data content type and expects two payloads: file and data.

  • file - The zip file containing the product. For WordPress plugins or themes this must contain the root directory.
  • data - Please omit this when deploying WordPress plugins and themes. In case of deploying templates and widgets, this needs to be a stringified JSON and must have the version and requires_platform_version properties.

An example of the data property:

{"version": "2.0.0", "requires_platform_version": "1.0.0"}

After you have created a deployment, please send another PUT request to the newly created version to update the release_status to either released or beta. The default value is pending which means none of the customers will be able to see the new version.

You can learn more about the deployment process here.

Path
product_idinteger(int64)>= 1required

The ID of the product.

Example: 1234
Bodymultipart/form-data
filestring(binary)required

The zip file containing the product. For WordPress plugins or themes this must contain the root directory.

datastring(json)

The metadata details associated with this specific product version.

Example: "{\"version\": \"1.0.0\", \"requires_platform_version\": \"1.0.0\"}"
curl -i -X POST \
  https://api.freemius.com/v1/products/1234/tags.json \
  -H 'Authorization: Bearer <YOUR_AccessToken_HERE>' \
  -H 'Content-Type: multipart/form-data' \
  -F file=string \
  -F 'data={"version": "1.0.0", "requires_platform_version": "1.0.0"}'

Responses

OK

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"
developer_idstring(int64)>= 1

The ID of a developer.

Example: "1234"
slugstring or null

The slug of the product. This is auto-generated from your product settings.

Example: "my-freemius-plugin"
premium_slugstring or null

The slug of the premium product. This is auto-generated from your product's settings.

Example: "my-freemius-plugin-pro"
versionstring(semver)

The version of the product. For WordPress.org products (plugins and themes), we recommend using semver semantics to support composer integration.

Example: "1.0.0"
sdk_versionstring

The Freemius SDK version. Only relevant for WordPress products using the Freemius WP SDK.

Example: "1.2.2"
requires_platform_versionstring or null

The platform version required (e.g WordPress version).

Example: "1.0.0"
requires_programming_language_versionstring or null

The programming language version (e.g PHP version).

Example: "5.6"
tested_up_to_versionstring or null

The tested platform version that the product is compatible (e.g WordPress version).

Example: "1.0.0"
downloadedinteger>= 0

The number of times the product has been downloaded.

Example: "1234"
has_freeboolean

If the product has a free version.

has_premiumboolean

If the product has a premium version.

release_modestring

The release mode of the product.

Enum"released""pending""beta"
limitinteger>= 1

The maximum number of downloads allowed for this version. This is used for staged rollout of WordPress products. Unlimited number is set as null.

Example: 50
uniquesinteger>= 1

The number of unique users that have downloaded the product.

Example: "1234"
is_incrementalboolean

Determines whether the version is incremental or not.

Example: true
Response
application/json
{
  "id": "123456",
  "created": "2025-01-01 00:00:00",
  "updated": "2025-01-01 00:00:00",
  "plugin_id": "123456",
  "developer_id": "1234",
  "slug": "my-freemius-plugin",
  "premium_slug": "my-freemius-plugin-pro",
  "version": "1.0.0",
  "sdk_version": "1.2.2",
  "requires_platform_version": "1.0.0",
  "requires_programming_language_version": "5.6",
  "tested_up_to_version": "1.0.0",
  "downloaded": "1234",
  "has_free": true,
  "has_premium": true,
  "release_mode": "released",
  "limit": 50,
  "uniques": "1234",
  "is_incremental": true
}

Get latest deployment

Request

Get the information about the latest deployment the product has, including a secure download link. The download link will work without any authentication header and will expire in 24 hours.

Path
product_idinteger(int64)>= 1required

The ID of the product.

Example: 1234
Query
is_premiumboolean

(Optional) Whether to retrieve a premium version of the product or not. For WordPress products (plugins and themes) only.

Default "true"
typestring

Type of the latest deployment to load. If the type provided is all, the latest released, beta, or pending version will be returned, whichever has the higher version.

Default "released"
Enum"released""beta""pending""all"
curl -i -X GET \
  'https://api.freemius.com/v1/products/1234/tags/latest.json?is_premium=true&type=released' \
  -H 'Authorization: Bearer <YOUR_AccessToken_HERE>'

Responses

The latest deployment information.

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"
developer_idstring(int64)>= 1

The ID of a developer.

Example: "1234"
slugstring or null

The slug of the product. This is auto-generated from your product settings.

Example: "my-freemius-plugin"
premium_slugstring or null

The slug of the premium product. This is auto-generated from your product's settings.

Example: "my-freemius-plugin-pro"
versionstring(semver)

The version of the product. For WordPress.org products (plugins and themes), we recommend using semver semantics to support composer integration.

Example: "1.0.0"
sdk_versionstring

The Freemius SDK version. Only relevant for WordPress products using the Freemius WP SDK.

Example: "1.2.2"
requires_platform_versionstring or null

The platform version required (e.g WordPress version).

Example: "1.0.0"
requires_programming_language_versionstring or null

The programming language version (e.g PHP version).

Example: "5.6"
tested_up_to_versionstring or null

The tested platform version that the product is compatible (e.g WordPress version).

Example: "1.0.0"
downloadedinteger>= 0

The number of times the product has been downloaded.

Example: "1234"
has_freeboolean

If the product has a free version.

has_premiumboolean

If the product has a premium version.

release_modestring

The release mode of the product.

Enum"released""pending""beta"
limitinteger>= 1

The maximum number of downloads allowed for this version. This is used for staged rollout of WordPress products. Unlimited number is set as null.

Example: 50
uniquesinteger>= 1

The number of unique users that have downloaded the product.

Example: "1234"
is_incrementalboolean

Determines whether the version is incremental or not.

Example: true
urlstring

URL to download the deployed ZIP file. This is a secure URL and does not need any additional authentication header. Will expire after 24 hours from the time of generation.

Response
application/json
{
  "id": "123456",
  "created": "2025-01-01 00:00:00",
  "updated": "2025-01-01 00:00:00",
  "plugin_id": "123456",
  "developer_id": "1234",
  "slug": "my-freemius-plugin",
  "premium_slug": "my-freemius-plugin-pro",
  "version": "1.0.0",
  "sdk_version": "1.2.2",
  "requires_platform_version": "1.0.0",
  "requires_programming_language_version": "5.6",
  "tested_up_to_version": "1.0.0",
  "downloaded": "1234",
  "has_free": true,
  "has_premium": true,
  "release_mode": "released",
  "limit": 50,
  "uniques": "1234",
  "is_incremental": true,
  "url": "string"
}

Download latest deployment

Request

Download the latest deployment the product has. This is for WordPress products only (including plugins, themes, templates and widgets). It outputs the zip file of the deployed version.

Path
product_idinteger(int64)>= 1required

The ID of the product.

Example: 1234
Query
is_premiumboolean

(Optional) Whether to retrieve a premium version of the product or not. For WordPress products (plugins and themes) only.

Default "true"
typestring

Type of the latest deployment to load. If the type provided is all, the latest released, beta, or pending version will be returned, whichever has the higher version.

Default "released"
Enum"released""beta""pending""all"
curl -i -X GET \
  'https://api.freemius.com/v1/products/1234/tags/latest.zip?is_premium=true&type=released' \
  -H 'Authorization: Bearer <YOUR_AccessToken_HERE>'

Responses

The zip file of the deployed version.

Bodyapplication/zip
Response
No content