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

Retrieve installs count

Request

Retrieve the number of installs associated with the product.

Filtering

You can filter the count by plan_id or is_active.

Path
product_idinteger(int64)>= 1required

The ID of the product.

Example: 1234
Query
plan_idnumber

(optional) Return the count of installs that are associated with a non-expired license for the given plan ID.

Example: plan_id=1
is_activeboolean

(optional) Return active installs only.

Example: is_active=false
curl -i -X GET \
  'https://api.freemius.com/v1/products/1234/installs/count.json?is_active=false&plan_id=1' \
  -H 'Authorization: Bearer <YOUR_AccessToken_HERE>'

Responses

The number of installs with the product.

Bodyapplication/json
countinteger>= 0
Example: 123
Response
application/json
{
  "count": 123
}

Downgrade to the default plan

Request

Downgrade install's plan to product’s default plan. This is usually the free plan.

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

Deactivate license.

reason_idsinteger

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
reasonstring

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

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

Responses

Product plan downgraded.

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

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": [
    { … }
  ]
}

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