Freemius

https://freemius.com/help
Admin
Freemius is a monetization platform for selling digital products including WordPress plugins,...
Tokens:829,076
Snippets:9,130
Trust Score:10
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install IDs query parameter example

Source: https://freemius.com/help/api/users/list-installs.md

Example of a comma-separated list of install IDs for filtering.

```text
1234,2478,2345
```

--------------------------------

### Count Response Example

Source: https://freemius.com/help/llms-full.txt

Example response value for the install count.

```text
123
```

--------------------------------

### POST /v1/products/{product_id}/installs/{install_id}/plans/{plan_id}/trials.json

Source: https://freemius.com/help/llms-full.txt

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

```APIDOC
## POST /v1/products/{product_id}/installs/{install_id}/plans/{plan_id}/trials.json

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

### Method
POST

### Endpoint
https://api.freemius.com/v1/products/{product_id}/installs/{install_id}/plans/{plan_id}/trials.json

### Parameters
#### Path Parameters
- **product_id** (integer) - Required - The ID of the product.
- **install_id** (integer) - Required - The ID of the install.
- **plan_id** (integer) - Required - The ID of the plan.

#### Query Parameters
- **fields** (string) - Optional - Comma separated list of fields to return in the response.

#### Request Body
- **trial_ends** (string) - Optional - The expiry date of the trial.
- **phone** (string) - Optional - The phone number used in the billing.
- **is_migration** (boolean) - Optional - Whether emails will be sent to users or log events.
- **trial_token** (string) - Optional - Security token for sandbox mode trial.
- **trial_timestamp** (string) - Optional - Security timestamp for sandbox mode trial.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the entity.
- **created** (string) - The date and time the entity was created, under UTC timezone.
- **updated** (string) - The date and time the entity was updated, under UTC timezone.
```

--------------------------------

### POST /products/{product_id}/installs/{install_id}/plans/{plan_id}/trials.json

Source: https://freemius.com/help/api/installations/start-trial.md

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

```APIDOC
## POST /products/{product_id}/installs/{install_id}/plans/{plan_id}/trials.json

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

### Method
POST

### Endpoint
https://api.freemius.com/v1/products/{product_id}/installs/{install_id}/plans/{plan_id}/trials.json

### Parameters
#### Path Parameters
- **product_id** (integer) - Required - The ID of the product.
- **install_id** (integer) - Required - The ID of the install.
- **plan_id** (integer) - Required - The ID of the plan.

#### Query Parameters
- **fields** (string) - Optional - Comma separated list of fields to return in the response.

#### Request Body
- **trial_ends** (string) - Optional - The expiry date of the trial.
- **phone** (string) - Optional - The phone number used in the billing.
- **is_migration** (boolean) - Optional - Whether emails will be sent to users or log events.
- **trial_token** (string) - Optional - Security token for sandbox mode trial.
- **trial_timestamp** (string) - Optional - Security timestamp for sandbox mode trial.
```

--------------------------------

### Example from query parameter

Source: https://freemius.com/help/api/trials/list.md

An example date-time string for the start of the date range.

```text
2025-08-01 00:00:00
```

--------------------------------

### GET /installs

Source: https://freemius.com/help/api/installations/list-installs.md

Retrieves a collection of installation entities.

```APIDOC
## GET /installs

### Description
Retrieves a collection of installation entities.

### Method
GET

### Endpoint
/installs

### Response
#### Success Response (200)
- **installs** (array) - A collection of installation objects.
  - **secret_key** (string) - The secret key associated with the entity for authorization.
  - **public_key** (string) - The public key associated with the entity for authorization.
  - **id** (string) - The unique identifier of the entity.
  - **created** (string) - The date and time the entity was created (UTC).
  - **updated** (string) - The date and time the entity was updated (UTC), or null.
  - **site_id** (string) - The ID of the site.
  - **plugin_id** (string) - The ID of the product the entity belongs to.
  - **user_id** (string) - The ID of the user the entity belongs to.
  - **url** (string) - The site URL, or null.
  - **title** (string) - The site title, or null.
  - **version** (string) - The Product version.
  - **plan_id** (string) - The ID of the plan associated with the product.
  - **license_id** (string) - The ID of the license associated with the entity, or null.
  - **trial_plan_id** (string) - The ID of the trial license, or null.
  - **trial_ends** (string) - The product trial license expiry date, or null.
  - **subscription_id** (string) - The ID of the subscription associated with the entity, or null.
  - **gross** (number) - The gross amount the install has spent on the product.
  - **country_code** (string) - The ISO 3166-1 alpha 2 country code, or null.
```

--------------------------------

### GET /products/{product_id}/installs.json

Source: https://freemius.com/help/api.md

List all installations for a specific product.

```APIDOC
## GET /products/{product_id}/installs.json

### Description
List all installations for a specific product.

### Method
GET

### Endpoint
/products/{product_id}/installs.json
```

--------------------------------

### GET /products/{product_id}/users/{user_id}/installs.json

Source: https://freemius.com/help/api/users.md

List all installs for a user.

```APIDOC
## GET /products/{product_id}/users/{user_id}/installs.json

### Description
List all software installs associated with the user.

### Method
GET

### Endpoint
/products/{product_id}/users/{user_id}/installs.json
```

--------------------------------

### GET /installations/list-plans

Source: https://freemius.com/help/api/installations/list-plans.md

Retrieves a list of plans for an installation.

```APIDOC
## GET /installations/list-plans

### Description
Retrieves a list of plans associated with the installation.

### Method
GET

### Endpoint
/installations/list-plans

### Response
#### Success Response (200)
- **plans** (array) - A list of plan objects.
  - **id** (string) - The unique identifier of the entity.
  - **created** (string) - The date and time the entity was created (UTC).
  - **updated** (string) - The date and time the entity was updated (UTC), or null.
  - **plugin_id** (string) - The ID of the product the entity belongs to.
  - **name** (string) - The name of the plan.
  - **title** (string) - The human readable name of the plan.
  - **description** (string) - The description of the plan.
  - **is_free_localhost** (boolean) - Whether the plan offers unlimited local or staging activations.
  - **is_block_features** (boolean) - Whether to block features on expiration of annual licenses.
  - **is_block_features_monthly** (boolean) - Whether to block features on expiration of monthly licenses.
  - **license_type** (integer) - The type of the license (0 for per domain, 1 for per subdomain).
  - **trial_period** (integer) - The number of days a trial period will last, or null.
  - **is_require_subscription** (boolean) - Whether to require a subscription payment for the trial period.
  - **support_kb** (string) - The Knowledge Base URL.
  - **support_forum** (string) - The support Forum URL.
  - **support_email** (string) - The support email address.
  - **support_phone** (string) - The support phone contact.
  - **is_success_manager** (boolean) - Is a personal success manager allocated with the plan.

#### Response Example
[
  {
    "id": "123456",
    "created": "2025-01-01 00:00:00",
    "updated": "2025-01-01 00:00:00",
    "plugin_id": "123456",
    "name": "professional",
    "title": "Professional",
    "description": "For small to medium businesses.",
    "is_free_localhost": true,
    "is_block_features": true,
    "is_block_features_monthly": true,
    "license_type": 0,
    "trial_period": 14,
    "is_require_subscription": false,
    "support_kb": "https://example.com/help/documentation",
    "support_forum": "https://example.com/support",
    "support_email": "support@example.com",
    "support_phone": "555-555-5555",
    "is_success_manager": false
  }
]
```

--------------------------------

### GET /products/{product_id}/installs/{install_id}.json

Source: https://freemius.com/help/api.md

Retrieve details for a specific installation of a product.

```APIDOC
## GET /products/{product_id}/installs/{install_id}.json

### Description
Retrieve details for a specific installation of a product.

### Method
GET

### Endpoint
/products/{product_id}/installs/{install_id}.json
```

--------------------------------

### GET /products/{product_id}/installs/{install_id}/plans.json

Source: https://freemius.com/help/api/installations/list-plans.md

Retrieve all the available product plans to which an install can subscribe.

```APIDOC
## GET https://api.freemius.com/v1/products/{product_id}/installs/{install_id}/plans.json

### Description
Retrieve all the available product plans to which an install can subscribe.

### Method
GET

### Endpoint
https://api.freemius.com/v1/products/{product_id}/installs/{install_id}/plans.json

### Parameters
#### Path Parameters
- **product_id** (integer<int64>) - Required - The ID of the product.
- **install_id** (integer<int64>) - Required - The ID of the install.

#### Query Parameters
- **show_pending** (boolean) - Optional - Show all plans whether released to customers or hidden. Default: false.
- **fields** (string) - Optional - Comma separated list of fields to return in the response.
```

--------------------------------

### GET /v1/products/{product_id}/installs/{install_id}/plans.json

Source: https://freemius.com/help/llms-full.txt

Retrieve all the available product plans to which an install can subscribe.

```APIDOC
## GET https://api.freemius.com/v1/products/{product_id}/installs/{install_id}/plans.json

### Description
Retrieve all the available product plans to which an install can subscribe.

### Method
GET

### Endpoint
https://api.freemius.com/v1/products/{product_id}/installs/{install_id}/plans.json

### Parameters
#### Path Parameters
- **product_id** (integer<int64>) - Required - The ID of the product.
- **install_id** (integer<int64>) - Required - The ID of the install.

#### Query Parameters
- **show_pending** (boolean) - Optional - Show all plans whether released to customers or hidden. Default: false.
- **fields** (string) - Optional - Comma separated list of fields to return in the response.

### Response
#### Success Response (200)
- **plans** (object[]) - List of available plans.
  - **id** (string<int64>) - The unique identifier of the entity.
  - **created** (string<date-time>) - The date and time the entity was created.
  - **updated** (string<date-time>) - The date and time the entity was updated.
  - **plugin_id** (string<int64>) - The ID of the product the entity belongs to.
  - **name** (string<slug>) - The name of the plan.
  - **title** (string) - The human readable name of the plan.
  - **description** (string) - The description of the plan.
  - **is_free_localhost** (boolean) - Whether the plan offers unlimited local or staging activations.
  - **is_block_features** (boolean) - Whether features are blocked.
```

--------------------------------

### Configure bundle_public_key

Source: https://freemius.com/help/llms-full.txt

Example value for the unique bundle public key.

```text
'pk_hrjss36joj632vgyy345ggv555'
```

--------------------------------

### Get licenses

Source: https://freemius.com/help/llms-full.txt

Retrieve all licenses for a specific user and product.

```http
GET https://api.freemius.com/v1/products/{product_id}/users/{user_id}/licenses.json
```

--------------------------------

### Initial Plugin Settings Markup

Source: https://freemius.com/help/llms-full.txt

Start by wrapping your plugin settings in a div.wrap element and adding the nav-tab-wrapper header.

```html
<div class="wrap">

  <h2 class="nav-tab-wrapper">

    <!-- Replace the # placeholder link with a full link to your plugin settings page. -->

    <a href="#" class="nav-tab nav-tab-active">Settings</a>

  </h2>

  <!-- Plugin settings go here -->

</div>
```

--------------------------------

### Implement Webhook Listener in JavaScript

Source: https://freemius.com/help/llms-full.txt

This example uses the JS SDK to create a listener that processes license events and updates entitlements in the database.

```javascript
import { freemius } from './lib/freemius'; // our freemius instance

import { processPurchaseInfo } from './lib/user-entitlement'; // Our shared entitlement logic

import { db } from './lib/db'; // our database instance



async function syncEntitlementFromWebhook(licenseId) {

  const purchase = await freemius.purchase.retrievePurchase(licenseId);



  await processPurchaseInfo(purchase);

}



export async function deleteEntitlement(fsLicenseId) {

  await db.userFsEntitlement.delete({

    where: { fsLicenseId },

  });

}



export default {

  async fetch(request) {

    if (request.method !== 'POST') {

      return new Response('Method Not Allowed', { status: 405 });

    }



    const listener = freemius.webhook.createListener();

    const licenseEvents = [

      'license.created',

      'license.extended',

      'license.shortened',

      'license.updated',

      'license.cancelled',

      'license.expired',

      'license.plan.changed',

    ];



    listener.on(licenseEvents, async ({ objects: { license } }) => {

      if (license?.id) {

        await syncEntitlementFromWebhook(license.id);

      }

    });



    // Specific listener for the license deletion event, which is fired when a license is deleted from the Freemius system.

    listener.on('license.deleted', async ({ data} }) => {

      await deleteEntitlement(data.license_id);

    });



    return freemius.webhook.processFetch(listener, request);

  },

};
```

--------------------------------

### Get subscriptions

Source: https://freemius.com/help/llms-full.txt

Retrieve all subscriptions for a specific user and product.

```http
GET https://api.freemius.com/v1/products/{product_id}/users/{user_id}/subscriptions.json
```

--------------------------------

### Filter show_admin_notice

Source: https://freemius.com/help/llms-full.txt

Use this filter to control the visibility of admin notices. The example demonstrates how to hide a specific trial promotion notice by returning false.

```php
<?php

  /**

   * @param bool  $show

   * @param array $msg {

   *     @var string $message The actual message.

   *     @var string $title An optional message title.

   *     @var string $type The type of the message ('success', 'update', 'warning', 'promotion').

   *     @var string $id The unique identifier of the message.

   *     @var string $manager_id The unique identifier of the notices manager. For plugins it would be the plugin's slug, for themes - `<slug>-theme`.

   *     @var string $plugin The product's title.

   *     @var string $wp_user_id An optional WP user ID that this admin notice is for.

   * }

   * @return bool

   */

  function my_custom_show_admin_notice( $show, $msg ) {

      if ('trial_promotion' == $msg['id']) {

          // Don't show the trial promotional admin notice.

          return false;

      }



      return $show;

  }



  my_fs()->add_filter( 'show_admin_notice', 'my_custom_show_admin_notice', 10, 2 );
```

--------------------------------

### Set reshow_trial_after_every_n_sec filter

Source: https://freemius.com/help/llms-full.txt

Adjusts the frequency at which the trial promotional offer is re-shown. This example changes the interval to 60 days.

```php
function my_reshow_trial_after_every_60_days( $thirty_days_in_sec ) {

    // 60 days in sec.

    return 60 * 24 * 60 * 60;

}



my_fs()->add_filter( 'reshow_trial_after_every_n_sec', 'my_reshow_trial_after_every_60_days' );
```

--------------------------------

### Path Parameter Examples

Source: https://freemius.com/help/api/users/list-events.md

Examples for the required product_id and user_id path parameters.

```text
1234
```

```text
1234
```

--------------------------------

### GET request for installation payments

Source: https://freemius.com/help/api/installations/list-payments.md

The endpoint to retrieve payments for a specific product installation.

```http
GET 
https://api.freemius.com/v1/products/{product_id}/installs/{install_id}/payments.json
```

--------------------------------

### Retrieve Installs Count Endpoint

Source: https://freemius.com/help/api/installations/retrieve-installs-count.md

The base GET request URL for retrieving the installation count of a product.

```http
GET 
https://api.freemius.com/v1/products/{product_id}/installs/count.json
```

--------------------------------

### GET list all installs endpoint

Source: https://freemius.com/help/llms-full.txt

The endpoint URL used to retrieve the install collection for a specific product and user.

```http
GET 
https://api.freemius.com/v1/products/{product_id}/users/{user_id}/installs.json
```

--------------------------------

### Query Parameter Examples

Source: https://freemius.com/help/llms-full.txt

Example values for fields and license_key query parameters.

```text
id,name,slug
```

```text
sk_123FGqM456Pa786WtOp%^+67Y+;sXXz
```

--------------------------------

### Product ID Example

Source: https://freemius.com/help/api/coupons/delete.md

Example value for the product_id path parameter.

```text
1234
```

--------------------------------

### GET /installations/updates

Source: https://freemius.com/help/api/installations/list-updates.md

Retrieves a collection of update entities for installations.

```APIDOC
## GET /installations/updates

### Description
Retrieves a collection of update entities.

### Method
GET

### Endpoint
/installations/updates

### Response
#### Success Response (200)
- **id** (string<int64>) - The unique identifier of the entity.
- **created** (string<date-time>) - The date and time the entity was created, under UTC timezone.
- **updated** (string<date-time>) - The date and time the entity was updated, under UTC timezone. If null then the entity was never updated since its creation.
- **plugin_id** (string<int64>) - The ID of the product the entity belongs to.
- **developer_id** (string<int64>) - The ID of a developer.
- **slug** (string) - The slug of the product.
- **premium_slug** (string) - The slug of the premium product.
- **version** (string<semver>) - The version of the product.
- **sdk_version** (string) - The Freemius SDK version.
- **requires_platform_version** (string) - The platform version required.
- **requires_programming_language_version** (string) - The programming language version.
- **tested_up_to_version** (string) - The tested platform version that the product is compatible.
- **downloaded** (integer) - The number of times the product has been downloaded.
- **has_free** (boolean) - If the product has a free version.
- **has_premium** (boolean) - If the product has a premium version.
- **release_mode** (string) - The release mode of the product (released, pending, beta).
- **limit** (integer) - The maximum number of downloads allowed for this version.
- **uniques** (integer) - The number of unique users that have downloaded the product.

#### Response Example
[
  {
    "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
  }
]
```

--------------------------------

### GET /v1/products/{product_id}/installs/{install_id}/license.json

Source: https://freemius.com/help/api/installations/retrieve-active-license-by-uid.md

Retrieve the full information about the active license for the specified install when the UID of the install is known.

```APIDOC
## GET https://api.freemius.com/v1/products/{product_id}/installs/{install_id}/license.json

### Description
Retrieve the full information about the active license for the specified install when the UID of the install is known.

### Method
GET

### Endpoint
https://api.freemius.com/v1/products/{product_id}/installs/{install_id}/license.json

### Parameters
#### Path Parameters
- **install_id** (integer) - Required - The ID of the install.
- **product_id** (integer) - Required - The ID of the product.

#### Query Parameters
- **license_key** (string) - Required - The license key used for the activation of the install.
- **uid** (string) - Required - The Unique identifier (32 characters long).
- **fields** (string) - Optional - Comma separated list of fields to return in the response.
```

--------------------------------

### Product ID Parameter Example

Source: https://freemius.com/help/llms-full.txt

Example value for the product_id path parameter.

```integer
1234
```
Tokens:
Raw