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

List all subscriptions

Request

Retrieve the subscription collection associated with a license.

A license can have one active and multiple inactive subscriptions. Subscriptions are inactivated when a license is downgraded or upgraded or when the payment method is updated.

Path
product_idinteger(int64)>= 1required

The ID of the product.

Example: 1234
install_idinteger(int64)>= 1required

The ID of the install.

Example: 1234
license_idinteger(int64)>= 1required

The ID of the License.

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

Responses

Subscriptions collection.

Bodyapplication/json
subscriptionsArray of objects(Subscription)
Response
application/json
{
  "subscriptions": [
    { … }
  ]
}

Activate a license

Request

Activate a license and if needed, create an install with the given properties.

No Authorization header is required. If the provided license doesn't have an associated user, the endpoint will require the first_name, last_name, and user_email parameters to create a new user and associate it with the license.

Path
product_idinteger(int64)>= 1required

The ID of the product.

Example: 1234
Bodyapplication/jsonrequired
uidstring(uid)= 32 charactersrequired

Unique identifier of the caller. The UID must be same when pinging and when activating or deactivating a license. The generation of the UID is a responsibility of the client.

Example: "7W131pej6bJYV8WYM9KgGoBNB9bCiSrY"
license_keystringrequired

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

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

Site's homepage URL.

titlestring

Site's title.

versionstring

Product's version.

is_marketing_allowedboolean or null

Whether or not the user has given their consent for marketing materials. A null value indicates that the user has not made a decision yet.

install_idinteger

Install ID when activating on an already existing install. If provided must belong to the same user as the license owner and must have the same UID. The new license will be activated for the install and existing one will be deactivated.

first_namestring

First name of the user (only needed when activating a ghost license).

last_namestring

Last name of the user (only needed when activating a ghost license).

user_emailstring

Email address of the user (only needed when activating a ghost license).

curl -i -X POST \
  https://api.freemius.com/v1/products/1234/licenses/activate.json \
  -H 'Content-Type: application/json' \
  -d '{
    "uid": "7W131pej6bJYV8WYM9KgGoBNB9bCiSrY",
    "license_key": "sk_123FGqM456Pa786WtOp%^+67Y+;sXXz"
  }'

Responses

License activated successfully.

Bodyapplication/json
user_idstring(int64)>= 1

The unique identifier of the entity.

Example: "123456"
user_secret_keystring

The secret key associated with the entity for authorization.

Example: "sk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
user_public_keystring

The public key associated with the entity for authorization.

Example: "pk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
plugin_idstring(int64)>= 1

The unique identifier of the entity.

Example: "123456"
license_plan_namestring(slug)

The name of the plan. Only lowercase characters allowed.

Example: "professional"
is_marketing_allowedboolean or null

Whether or not the user has given their consent for marketing materials. A null value indicates that the user has not made a decision yet.

install_idstring(int64)>= 1

The unique identifier of the entity.

Example: "123456"
install_secret_keystring

The secret key associated with the entity for authorization.

Example: "sk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
install_public_keystring

The public key associated with the entity for authorization.

Example: "pk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
install_api_tokenstring

The API access token with which authenticated requests can be made for this install entity. You need to set this token as the Bearer token in the Authorization header. For example: 

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

Example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9"
Response
application/json
{
  "user_id": "123456",
  "user_secret_key": "sk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "user_public_key": "pk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "plugin_id": "123456",
  "license_plan_name": "professional",
  "is_marketing_allowed": true,
  "install_id": "123456",
  "install_secret_key": "sk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "install_public_key": "pk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "install_api_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9"
}

Generate upgrade link

Request

Generate an upgrade link for a license. The API accepts a variety of parameters with which you can specify new plans or quota or billing cycles. If you skip all those, then a manual renewal link will be generated instead. The link will be valid for 24 hours.

Path
product_idinteger(int64)>= 1required

The ID of the product.

Example: 1234
license_idinteger(int64)>= 1required

The ID of the License.

Example: 1234
Bodyapplication/jsonrequired
plan_idstring(int64)>= 0

The plan ID to upgrade to.

billing_cyclestring

The billing cycle or period of a plan.

Enum"monthly""annual""lifetime"
quotainteger or string

The quota to use. Can be a number or the string 'unlimited'.

One of:

The quota to use. Can be a number or the string 'unlimited'.

>= 1
integer>= 1

The quota to use. Can be a number or the string 'unlimited'.

is_payment_method_updateboolean

Whether to update the payment method. If true, the link will be generated for the current plan and billing cycle of the license and other parameters will be ignored. If the license is not associated with a subscription, or is lifetime, an exception will be thrown.

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

Responses

Upgrade link generated successfully.

Bodyapplication/json
urlstring(uri)

The URL to the checkout page.

settingsobject

The settings used to generate the link. This can be fed as-is to the Freemius Checkout JS SDK if you're using modals in your website.

Example: {"plugin_id":1,"plan_id":2,"licenses":"unlimited"}
expiresstring(date-time)

The expiration date of the link.

Response
application/json
{
  "url": "http://example.com",
  "settings": {
    "plugin_id": 1,
    "plan_id": 2,
    "licenses": "unlimited"
  },
  "expires": "2019-08-24T14:15:22Z"
}

Deactivate a license

Request

Deactivate a license from an install (No Authorization header is required).

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
Bodyapplication/jsonrequired
uidstring(uid)= 32 charactersrequired

Unique identifier of the caller. The UID must be same when pinging and when activating or deactivating a license. The generation of the UID is a responsibility of the client.

Example: "7W131pej6bJYV8WYM9KgGoBNB9bCiSrY"
install_idintegerrequired

Install ID from which the license should be deactivated. The license must be active on the install.

license_keystringrequired

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

Example: "sk_123FGqM456Pa786WtOp%^+67Y+;sXXz"
curl -i -X POST \
  'https://api.freemius.com/v1/products/1234/licenses/deactivate.json?fields=id%2Cname%2Cslug' \
  -H 'Content-Type: application/json' \
  -d '{
    "uid": "7W131pej6bJYV8WYM9KgGoBNB9bCiSrY",
    "install_id": 0,
    "license_key": "sk_123FGqM456Pa786WtOp%^+67Y+;sXXz"
  }'

Responses

License deactivated.

Bodyapplication/json
secret_keystring

The secret key associated with the entity for authorization.

Example: "sk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
public_keystring

The public key associated with the entity for authorization.

Example: "pk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
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"
site_idstring(int64)

The ID of the site.

Example: 1234
plugin_idstring(int64)>= 1

The ID of the product the entity belongs to.

Example: "123456"
user_idstring(int64)>= 1

The ID of the user the entity belongs to.

Example: "123456"
urlstring or null

The site URL.

Example: "https://example.com"
titlestring or null

The site title.

Example: "Catwalk Designs"
versionstring

The Product version.

Example: "1.0.0"
plan_idstring(int64)>= 1

The ID of the plan associated with the product that the install has a license activation. If null it means the install is using the free plan.

Example: "1234"
license_idstring or null(int64)>= 1

The ID of the license associated with the entity.

Example: "123456"
trial_plan_idstring(int64)>= 1

The ID of the trial license associated to the product. If this is not a trial, this will be null.

Example: "1234"
trial_endsstring or null(date-time)

The product trial license expiry date. If this is not a trial, this will be null.

Example: "2025-01-01 00:00:00"
subscription_idstring or null(int64)>= 1

The ID of the subscription associated with the entity.

Example: "123456"
grossnumber(float)

The gross amount the install has spent on the product. This includes one time purchase, or subscriptions and renewals.

Example: 100
country_codestring or null

The ISO 3166-1 alpha 2 two-letter country code associated with the entity.

Example: "us"
languagestring or null

The language specified for the product install.

Example: "en-GB"
platform_versionstring or null

The platform version (e.g WordPress version).

Example: "1.0.0"
sdk_versionstring or null

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

Example: "1.2.2"
programming_language_versionstring or null

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

Example: "5.6"
is_activeboolean

If the product is actively installed on the site.

is_disconnectedboolean

If the product is disconnected on the site.

is_premiumboolean

If the install using the premium code. Relevant only for WP Products.

is_uninstalledboolean

If the product is uninstalled on the site.

is_lockedboolean

If the product is locked on the site.

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
upgradedstring or null(date-time)

Time when the product was upgraded to the current version. If never upgraded since the initial installation, this will be null.

Example: "2025-01-01 00:00:00"
last_seen_atstring or null(date-time)

The last time the product was used on the site.

Example: "2025-01-01 00:00:00"
last_served_update_versionstring or null

The last product version update used on the site. If not updated, this will be null.

Example: "1.2.2"
Response
application/json
{
  "secret_key": "sk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "public_key": "pk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "id": "123456",
  "created": "2025-01-01 00:00:00",
  "updated": "2025-01-01 00:00:00",
  "site_id": 1234,
  "plugin_id": "123456",
  "user_id": "123456",
  "url": "https://example.com",
  "title": "Catwalk Designs",
  "version": "1.0.0",
  "plan_id": "1234",
  "license_id": "123456",
  "trial_plan_id": "1234",
  "trial_ends": "2025-01-01 00:00:00",
  "subscription_id": "123456",
  "gross": 100,
  "country_code": "us",
  "language": "en-GB",
  "platform_version": "1.0.0",
  "sdk_version": "1.2.2",
  "programming_language_version": "5.6",
  "is_active": true,
  "is_disconnected": true,
  "is_premium": true,
  "is_uninstalled": true,
  "is_locked": true,
  "source": 0,
  "upgraded": "2025-01-01 00:00:00",
  "last_seen_at": "2025-01-01 00:00:00",
  "last_served_update_version": "1.2.2"
}

Retrieve a license

Request

Retrieve a specific license by its ID.

Path
product_idinteger(int64)>= 1required

The ID of the product.

Example: 1234
license_idinteger(int64)>= 1required

The ID of the License.

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/licenses/1234.json?fields=id%2Cname%2Cslug' \
  -H 'Authorization: Bearer <YOUR_AccessToken_HERE>'

Responses

The retrieved license.

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
}

Update a license

Request

Update a specific license by its ID. For ownership transfer please use the new_user_id. Ownership transfer is not supported for SaaS products.

Path
product_idinteger(int64)>= 1required

The ID of the product.

Example: 1234
license_idinteger(int64)>= 1required

The ID of the License.

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/json
quotainteger or null

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

Example: 10
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"
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_whitelabeledboolean

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

is_free_localhostboolean

Whether the license offers unlimited local or staging environment activations.

Default true
new_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"
cancel_subscriptionboolean

(optional) When set to true will cancel the subscription.

Example: true
extend_bundleboolean

(optional) When set to true to extend the bundle license.

Example: true
update_subscription_renewal_dateboolean

(optional) When set to true, it will update the relevant (subscription renewal or trial end) date to 24 hours before license expiration.

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

Responses

The updated license.

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
}

Cancel a license

Request

Cancel or delete a license. The Delete action is irreversible and will remove the license from the system.

Path
product_idinteger(int64)>= 1required

The ID of the product.

Example: 1234
license_idinteger(int64)>= 1required

The ID of the License.

Example: 1234
Query
deleteboolean

(optional) Whether to delete the license. If not true then the license is cancelled.

Example: delete=true
include_bundleboolean

(optional) Whether to include the bundle license in the deletion or delete the main license only.

Example: include_bundle=true
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 DELETE \
  'https://api.freemius.com/v1/products/1234/licenses/1234.json?delete=true&fields=id%2Cname%2Cslug&include_bundle=true' \
  -H 'Authorization: Bearer <YOUR_AccessToken_HERE>'

Responses

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

Response
No content

List all licenses

Request

Retrieve the license collection associated with a product.

Path
product_idinteger(int64)>= 1required

The ID of the product.

Example: 1234
Query
filterstring

Filter licenses by status.

Enum"active""cancelled""expired""abandoned""migrated"
Example: filter=active
plan_idnumber

Filter licenses by plan ID.

Example: plan_id=123
searchstring

Search license id or key.

Example: search=123
enrichedboolean

If true, returns the associated user information.

Default false
Example: enriched=true
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
sourcenumber

If set, returns only licenses that are associated with the given source ID.

Example: source=123
curl -i -X GET \
  'https://api.freemius.com/v1/products/1234/licenses.json?count=10&enriched=true&fields=id%2Cname%2Cslug&filter=active&offset=10&plan_id=123&search=123&source=123' \
  -H 'Authorization: Bearer <YOUR_AccessToken_HERE>'

Responses

The licenses collection is retrieved.

Bodyapplication/json
licensesArray of objects(LicenseEnriched)
Response
application/json
{
  "licenses": [
    { … }
  ]
}

Assign a license

Request

Associate an orphan license with a user and send a welcome email. If the user does not exist yet, one will be created.

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
Bodyapplication/jsonrequired
emailstringrequired

User's email address.

Example: "foo@example.com"
license_keystringrequired

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

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

User's full name.

Example: "John Doe"
is_marketing_allowedboolean or null

Whether or not the user has given their consent for marketing materials. A null value indicates that the user has not made a decision yet.

curl -i -X PUT \
  'https://api.freemius.com/v1/products/1234/licenses.json?fields=id%2Cname%2Cslug' \
  -H 'Authorization: Bearer <YOUR_AccessToken_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "foo@example.com",
    "license_key": "sk_123FGqM456Pa786WtOp%^+67Y+;sXXz"
  }'

Responses

The license is assigned.

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
}

Deactivate installs

Request

Deactivate license from all installs.

Path
product_idinteger(int64)>= 1required

The ID of the product.

Example: 1234
license_idinteger(int64)>= 1required

The ID of the License.

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 DELETE \
  'https://api.freemius.com/v1/products/1234/licenses/1234/installs.json?fields=id%2Cname%2Cslug' \
  -H 'Authorization: Bearer <YOUR_AccessToken_HERE>'

Responses

Licenses deactivated from all installs.

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
}

Send the renewal email

Request

Send the manual license renewal email. The system will send emails only for licenses with cancelled or inactive subscriptions.

Path
product_idinteger(int64)>= 1required

The ID of the product.

Example: 1234
license_idinteger(int64)>= 1required

The ID of the License.

Example: 1234
curl -i -X POST \
  https://api.freemius.com/v1/products/1234/licenses/1234/renewals.json \
  -H 'Authorization: Bearer <YOUR_AccessToken_HERE>'

Responses

The license renewal email is sent.

Bodyapplication/json
sentboolean

Whether the email is sent.

Response
application/json
{
  "sent": true
}

Resend license keys

Request

Send an email from Freemius with all the license keys associated with the given email address. The email is sent to the email address.

Path
product_idinteger(int64)>= 1required

The ID of the product.

Example: 1234
Bodyapplication/jsonrequired
emailstringrequired

The user's email address associated with the license.

Example: "johndoe@example.com"
curl -i -X POST \
  https://api.freemius.com/v1/products/1234/licenses/resend.json \
  -H 'Authorization: Bearer <YOUR_AccessToken_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "johndoe@example.com"
  }'

Responses

The license key has been resent.

Response
No content

Resend the upgrade email

Request

Resend the license upgrade email.

Path
product_idinteger(int64)>= 1required

The ID of the product.

Example: 1234
license_idinteger(int64)>= 1required

The ID of the License.

Example: 1234
curl -i -X POST \
  https://api.freemius.com/v1/products/1234/licenses/1234/resend.json \
  -H 'Authorization: Bearer <YOUR_AccessToken_HERE>'

Responses

License email resent.

Response
No content

Get review URL

Request

Retrieve the review URL associated with a license.

Path
product_idinteger(int64)>= 1required

The ID of the product.

Example: 1234
user_idinteger(int64)>= 1required

The ID of the User.

Example: 1234
license_idinteger(int64)>= 1required

The ID of the License.

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

Responses

The retrieved review URL.

Bodyapplication/json
any
Response
application/json
null

Create a review

Request

Creat a review associated with a license. If you want to create/import reviews which are not associated with a license or from a different system, please use the Review endpoint under products/{product_id}/reviews.json.

Path
product_idinteger(int64)>= 1required

The ID of the product.

Example: 1234
user_idinteger(int64)>= 1required

The ID of the User.

Example: 1234
license_idinteger(int64)>= 1required

The ID of the License.

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
Body
required

Data needed to create a review with an optional picture. When sending multipart/form-data the data property must be a JSON object with same structure as the JSON payload.

picturestring(binary)

Reviewer's profile picture. A maximum of 200KB in size and 300px width and 300px height is allowed.

datastring(json)

The JSON data of the endpoint, matching the same schema as the json request body. Must be a valid JSON object.

Example: "{\"name\":\"My Product\"}"
curl -i -X POST \
  'https://api.freemius.com/v1/products/1234/users/1234/licenses/1234/reviews.json?fields=id%2Cname%2Cslug' \
  -H 'Authorization: Bearer <YOUR_AccessToken_HERE>' \
  -H 'Content-Type: multipart/form-data' \
  -F picture=string \
  -F 'data={"name":"My Product"}'

Responses

The created review.

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"
external_idstring

The external ID of the review (in case migrating from another system).

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"
rateinteger[ 0 .. 100 ]

The score of the review.

Example: 80
titlestring

The title of the review.

Example: "Great plugin! It works perfectly."
textstring

The content of the review.

Example: "I love this plugin! It has all the features I need and more. The support team is also very responsive and helpful. Highly recommend!"
namestring

The full name of the reviewer.

Example: "John Doe"
job_titlestring

The job title of the reviewer.

Example: "Software Engineer"
companystring

The company name of the reviewer.

Example: "Example Software Inc."
company_urlstring

The URL of the entity.

Example: "https://www.example.com"
picturestring(binary)

The icon of the entity, must be a valid JPG, PNG or GIF image, with dimension not exceeding 300px by 300px. Max allowed size is 200KB

profile_urlstring

The URL of the reviewer's profile.

Example: "https://example.com/profile"
license_idstring(int64)>= 1

The ID of the license associated with the entity.

Example: "123456"
is_verifiedboolean

Whether this is a genuine review generated by a real user.

Default true
is_featuredboolean

Whether the review should be included in marketing material (e.g. pricing page).

Default false
Response
application/json
{
  "id": "123456",
  "created": "2025-01-01 00:00:00",
  "updated": "2025-01-01 00:00:00",
  "plugin_id": "123456",
  "external_id": "string",
  "user_id": "123456",
  "rate": 80,
  "title": "Great plugin! It works perfectly.",
  "text": "I love this plugin! It has all the features I need and more. The support team is also very responsive and helpful. Highly recommend!",
  "name": "John Doe",
  "job_title": "Software Engineer",
  "company": "Example Software Inc.",
  "company_url": "https://www.example.com",
  "picture": "string",
  "profile_url": "https://example.com/profile",
  "license_id": "123456",
  "is_verified": true,
  "is_featured": false
}

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