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

Start a trial

Request

Start the trial of a plan for which an install is subscribed. The install must not have utilized the trial before.

Path
product_idinteger(int64)>= 1required

The ID of the product.

Example: 1234
install_idinteger(int64)>= 1required

The ID of the install.

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
Bodyapplication/jsonrequired
trial_endsstring(date-time)

The expiry date of the trial. If set, will set the trial expiration based on that parameter. Note: Trial expiration date cannot exceed the maximum trial period days based on the plan configuration.

Example: "2025-01-01 00:00:00"
phonestring

The phone number used in the billing.

Example: "555-555-5555"
is_migrationboolean

Whether emails will be sent to users or log events. If true, no emails will be sent nor events logged.

trial_tokenstring

Security token for sandbox mode trial.

trial_timestampstring

Security timestamp for sandbox mode trial.

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

Responses

Started Trial

Bodyapplication/json
trialobject(Trial)

A trial represents a user's trial period for a product. Please read our documentation to learn more about trials.

Response
application/json
{
  "trial": {
    "id": "123456",
    "created": "2025-01-01 00:00:00",
    "updated": "2025-01-01 00:00:00",
    "plugin_id": "123456",
    "user_id": "123456",
    "payment_id": "123456",
    "subscription_id": "123456",
    "license_id": "123456",
    "trial_ends_at": "2025-01-01 00:00:00",
    "with_payment_method": true,
    "canceled_at": "2025-01-01 00:00:00",
    "converted_at": "2025-01-01 00:00:00",
    "environment": 0
  }
}

Retrieve uninstall details

Request

Retrieve the details of an install where the product has been uninstalled.

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

Responses

The uninstall details.

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

The ID of the installation or site the entity is associated with.

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

The ID of the site.

Example: "1234"
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.

reasonstring

The reason for the uninstall which translates to the string value of the uninstall reason_id.

Response
application/json
{
  "id": "123456",
  "created": "2025-01-01 00:00:00",
  "updated": "2025-01-01 00:00:00",
  "plugin_id": "123456",
  "install_id": "123456",
  "site_id": "1234",
  "reason_id": 1,
  "reason_info": "string",
  "reason": "string"
}

List all updates

Request

Retrieve the product update collection available for an 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
versionstringrequired

The product's version of the current install. The endpoint will return newer versions when set. This is a required param unless older_than is provided.

Example: version=1.0.0
older_thanstring

If provided, only versions that are older than this will be returned.

Example: older_than=1.0.0
typestring

The product type. If the type provide is all, the latest released or pending version will be returned, whichever has the higher version.

Default "released"
Enum"released""pending""beta""all"
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/updates.json?count=10&fields=id%2Cname%2Cslug&offset=10&older_than=1.0.0&type=released&version=1.0.0' \
  -H 'Authorization: Bearer <YOUR_AccessToken_HERE>'

Responses

Updates collection.

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

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