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

We support Bearer authentication. You can get the API Key from the Freemius Developer Dashboard for a product.

  1. Open the Settings page of the relevant product.
  2. Click on the API Token tab.
  3. Copy the API Bearer Authorization Token from the UI.

More information can be found under the Security section of every endpoint.

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

List all events

Request

Retrieve the event collection related to a product install.

Path
product_idinteger(int64)>= 1required

The ID of the product.

Example: 1234
install_idinteger(int64)>= 1required

The ID of the install.

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
typestring

Filter events by type string or event name.

Example: type=license.activated
curl -i -X GET \
  'https://api.freemius.com/v1/products/1234/installs/1234/events.json?count=10&fields=id%2Cname%2Cslug&offset=10&type=license.activated' \
  -H 'Authorization: Bearer <YOUR_AccessToken_HERE>'

Responses

Events triggered by the install.

Bodyapplication/json
eventsArray of objects(EventLog)
Response
application/json
{
  "events": [
    { … }
  ]
}

Retrieve an install

Request

Retrieve the details related to the product install.

Path
product_idinteger(int64)>= 1required

The ID of the product.

Example: 1234
install_idinteger(int64)>= 1required

The ID of the install.

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

Responses

The install details.

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

Whether the install is participating in the beta program.

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",
  "is_beta": true
}

Update an install

Request

Update the details related to the product install.

Path
product_idinteger(int64)>= 1required

The ID of the product.

Example: 1234
install_idinteger(int64)>= 1required

The ID of the install.

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

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_keystring

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

Example: "sk_123FGqM456Pa786WtOp%^+67Y+;sXXz"
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"
sdk_versionstring or null

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

Example: "1.2.2"
platform_versionstring or null

The platform version (e.g WordPress version).

Example: "1.0.0"
programming_language_versionstring or null

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

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

The unique identifier of 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"
trials_endsstring(date-time)

The datetime that the trial expires.

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

The unique identifier of the entity.

Example: "123456"
is_lockedboolean

If the product is locked on the site.

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_sdk_requiredboolean

A flag that controls whether the SDK should be required or not during deployment of a version. It defaults to true.

reason_idinteger

Uninstall reason. Possible values:

  • 1 - No longer needed
  • 2 - Found a better alternative
  • 3 - Only needed for short period
  • 4 - Broke the website
  • 5 - Suddenly stopped working
  • 6 - Cannot continue paying
  • 7 - Other
  • 8 - Didn't work after installation
  • 9 - User doesn't like to share data
  • 10 - Didn't understand how it works
  • 11 - Missing specific feature
  • 12 - Didn't work
  • 13 - Expected something else
  • 14 - Expected to work differently
  • 15 - Temporary deactivation
Enum12345678910
Example: 1
reason_infostring

Additional information gathered from the user for the uninstallation. This is populated when the product user chooses “Other” in contrast to pre-set options.

pluginsstring

The site plugins installed.

themesstring

The site themes installed.

is_betaboolean

Whether the product user is participating in the beta program.

recoverboolean

Recover the install.

is_uninstalledboolean

If the product is uninstalled on the site.

user_idstring(int64)>= 1

The ID of the user. This is used for ownership change of the install.

Example: "1234"
user_emailstring

The email of the user. This is used for ownership change of the install.

Example: "foo@example.com"
install_idsArray of strings

A comma seperated string of Install IDs. This is used for ownership change of the install.

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

Responses

Install updated

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

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