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.

Open the Settings page of the relevant product.
Click on the API Token tab.
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

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

List all users

Request

Gets the user collection associated with a product.

Filtering

There are a few filters that can be applied to the request.

Search by email

You can specify the parameter email to filter the users by email. Optionally you can also put a valid email in the search parameter.

Other filtering options

The search parameter also accepts the following values:

User ID (number).
Full or partial name (string).
Full or partial email (string).

You can use the combination of count and offset parameters to paginate the results.

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

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

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

Responses

Bodyapplication/json

usersArray of objects(User)

Response

application/json

{
  "users": [
    { … }
  ]
}

Create a user

Request

Create a new user associated with the product.

The user will be linked to the product if they already exist in Freemius.

User can only be created for products with elevated permissions or during data migration.

Migrating users from other platforms

Freemius allows to migrate your users from other platforms. To do so, you need to set the is_migration parameter to true. This will prevent any emails from being sent to the users and will not log any events. Once migrated the user can use their existing licenses to activate your product.

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

emailstring

Valid email address.

passwordstring

Valid password. Must have at least 8 characters.

ipstring

(optional) IPv4 or IPv6 Address

namestring

(optional) Full name property. If not specified, first and last must be provided instead.

firststring

(optional) First name. Required if no valid name was provided.

laststring

(optional) Last name. Required if no valid name was provided.

picturestring

(optional) Profile picture URL.

is_verifiedboolean

(optional) Tells if person is already verified, defaults to FALSE.

after_email_confirm_urlstring

(optional) URL address that the user will be auto forwarded to after email confirmation is clicked.

send_verification_emailboolean

(optional) Defaults to TRUE. If false, email verification message will NOT be sent after registration.

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.

is_migrationstring

(optional) If true, no emails will be sent to users nor events will be logged.

sourcestring

The source of the migration data. To get support migrating from other platform please see our documentation.

Enum"freemius""edd""easydigitaldownloads""woo""wc""woocommerce""gumroad""cc""codecanyon""tf"

Example: "ls"

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

Responses

Bodyapplication/json

notestring

A note about the user. Only visible to the developer.

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.

is_betaboolean

Whether or not the user has opted-in to beta versions.

emailstring

Email address of the person.

Example: "jane@example.com"

firststring

First name of the person.

Example: "Jane"

laststring

Last name of the person.

Example: "Doe"

picturestring

Profile picture URL.

Example: "https://example.com/profile-pic.jpg"

ipstring or null(ipv4|ipv6)

The IP address (v4 or v6).

Example: "127.0.0.1"

is_verifiedboolean

Whether the person is trusted or not.

Example: "true"

authstring

The type of authentication. If app2fa is set, the person has signed for 2FA authentication.

Enum"app2fa""password"

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"

grossnumber(float)

The total amount of money the user has spent on the platform.

last_login_atstring or null(date-time)

Date and time of the last login.

Example: "2025-07-30 05:56:29"

email_statusstring

The status of the last email sent to the user.

Enum"delivered""bounce""dropped"

Response

application/json

{
  "note": "string",
  "is_marketing_allowed": true,
  "is_beta": true,
  "email": "jane@example.com",
  "first": "Jane",
  "last": "Doe",
  "picture": "https://example.com/profile-pic.jpg",
  "ip": "127.0.0.1",
  "is_verified": "true",
  "auth": "app2fa",
  "secret_key": "sk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "public_key": "pk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "id": "123456",
  "created": "2025-01-01 00:00:00",
  "updated": "2025-01-01 00:00:00",
  "gross": 0.1,
  "last_login_at": "2025-07-30 05:56:29",
  "email_status": "delivered"
}

List all installs

Request

Retrieve the install collection associated with the user.

Various filtering and search parameters are available to narrow down the results.

Path

product_idinteger(int64)>= 1required

The ID of the product.

Example: 1234

user_idinteger(int64)>= 1required

The ID of the User.

Example: 1234

Query

install_idsstring(comma-separated)

Comma-separated install IDs list to filter.

Example: install_ids=1234,2478,2345

license_idinteger

License ID filter. If set, return installs that are linked to the specified license.

plan_idinteger

Plan ID filter. If set, return installs associated with the given plan.

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/users/1234/installs.json?count=10&fields=id%2Cname%2Cslug&install_ids=1234%2C2478%2C2345&license_id=0&offset=10&plan_id=0' \
  -H 'Authorization: Bearer <YOUR_AccessToken_HERE>'

Responses

Installs collection

Bodyapplication/json

installsArray of objects(Install)

Response

application/json

{
  "installs": [
    { … }
  ]
}

List all licenses

Request

Retrieve the license collection associated with a user.

Path

product_idinteger(int64)>= 1required

The ID of the product.

Example: 1234

user_idinteger(int64)>= 1required

The ID of the User.

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

offsetinteger>= 0

The number of records to skip before starting to return records. Default is 0.

Default 0

Example: offset=10

countinteger[ 1 .. 50 ]

The number of records to return.

Default 25

Example: count=10

license_keystring

Retrieve specific license by its key.

idsstring

Comma-separated license IDs.

license_keysstring

Retrieve specific multiple license with a comma-separated string of their license keys.

typestring

The type of license.

Default "all"

Enum"all""active""expired"

is_enrichedboolean

Returns the license's product type.

Default false

curl -i -X GET \
  'https://api.freemius.com/v1/products/1234/users/1234/licenses.json?count=10&fields=id%2Cname%2Cslug&ids=string&is_enriched=false&license_key=string&license_keys=string&offset=10&type=all' \
  -H 'Authorization: Bearer <YOUR_AccessToken_HERE>'

Responses

License collection.

Bodyapplication/json

licensesArray of objects

Response

application/json

{
  "licenses": [
    { … }
  ]
}

List all payments

Request

Retrieve the payment collection associated with a user.

Path

product_idinteger(int64)>= 1required

The ID of the product.

Example: 1234

user_idinteger(int64)>= 1required

The ID of the User.

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

offsetinteger>= 0

The number of records to skip before starting to return records. Default is 0.

Default 0

Example: offset=10

countinteger[ 1 .. 50 ]

The number of records to return.

Default 25

Example: count=10

extendedboolean

If true, loads linked user, plan and subscription.

Default "false"

include_addonsboolean

Returns the plugin add-ons' payments as well.

Default "false"

include_bundlesboolean

Returns the plugin bundles' payments as well.

Default "false"

filterstring

Filter the payments by the status.

Default "all"

Enum"all""refunds""not_refunded""not_refunded_renewals"

billing_cyclenumber

Filter by billing cycle.

Enum1120

curl -i -X GET \
  'https://api.freemius.com/v1/products/1234/users/1234/payments.json?billing_cycle=1&count=10&extended=false&fields=id%2Cname%2Cslug&filter=all&include_addons=false&include_bundles=false&offset=10' \
  -H 'Authorization: Bearer <YOUR_AccessToken_HERE>'

Responses

Payment collection.

Bodyapplication/json

paymentsArray of objects

discountsArray of objects(Discount)

Response

application/json

{
  "payments": [
    { … }
  ],
  "discounts": [
    { … }
  ]
}

List all subscriptions

Request

Retrieve the subscription collection associated with a user.

Path

product_idinteger(int64)>= 1required

The ID of the product.

Example: 1234

user_idinteger(int64)>= 1required

The ID of the User.

Example: 1234

Query

extendedboolean

Enrich the subscriptions with the plan name, install URL & title, and user email.

Default "false"

filterstring

Filter the subscriptions by the status.

Default "all"

Enum"all""active""cancelled"

billing_cyclestring

Filter by billing cycle.

Enum112

gatewaystring

Filter by gateway.

Enum"paypal""stripe"

Example: gateway=stripe

fieldsstring

Comma separated list of fields to return in the response. If not specified, all fields are returned.

Example: fields=id,name,slug

offsetinteger>= 0

The number of records to skip before starting to return records. Default is 0.

Default 0

Example: offset=10

countinteger[ 1 .. 50 ]

The number of records to return.

Default 25

Example: count=10

plan_idstring

Filter the subscriptions by the plan ID.

sortstring

Sort the subscriptions by the ID or the next payment date.

Default "id"

Enum"id""next_payment"

searchstring

Search by subscription ID, external subscription ID or user email.

curl -i -X GET \
  'https://api.freemius.com/v1/products/1234/users/1234/subscriptions.json?billing_cycle=1&count=10&extended=false&fields=id%2Cname%2Cslug&filter=all&gateway=stripe&offset=10&plan_id=string&search=string&sort=id' \
  -H 'Authorization: Bearer <YOUR_AccessToken_HERE>'

Responses

Subscription collection.

Bodyapplication/json

subscriptionsArray of objects

discountsArray of objects(Discount)

Response

application/json

{
  "subscriptions": [
    { … }
  ],
  "discounts": [
    { … }
  ]
}

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

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

Freemius API (1.0)

Bearer Token Auth

Products

Subscriptions

Users

List all users

Request

Filtering

Search by email

Other filtering options

Pagination

Responses

Was this helpful?

Create a user

Request

Migrating users from other platforms

Responses

Was this helpful?

List all installs

Request

Responses

Was this helpful?

List all licenses

Request

Responses

Was this helpful?

List all payments

Request

Responses

Was this helpful?

List all subscriptions

Request

Responses

Was this helpful?

Licenses

Coupons

Carts

Payments

Installations

Trials

Addons

Plans