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

Freemius API supports Bearer Token authentication for product-specific operations.

To retrieve your API token:

Go to the Freemius Developer Dashboard.
Open the Settings page of the relevant product.
Click on the API Token tab.
Copy the API Bearer Authorization Token from the UI.

Use this token by including it in the Authorization header of your API requests:

Authorization: Bearer {api_token}

Bearer tokens are scoped to a specific product. This means they can only be used with endpoints under the /products/{product_id}/ namespace. For example:

GET /products/12345/users.json
Authorization Bearer {api_token}

Requests to endpoints outside the product scope will result in an authorization error.

Other Scopes and Authentication

The Freemius API is organized around different scopes, based on the top-level entity of the operation:

For example, let's say you want to list all payments of a product. This operation can be done in several scopes:

Product Scope: /products/{product_id}/payments.json.
Developer Scope: /developers/{developer_id}/products/{product_id}/payments.json.

On the other hand, if a user would want to list their payment, then endpoint will be scoped to the user:

User Scope: /users/{user_id}/payments.json.

Some operations can be done from a particular scope only. For example only a developer can update a plan of a product or create a new plan. So the following operations will work:

Update Plan: POST /developers/{developer_id}/products/{product_id}/plans/{plan_id}.json
Create Plan: POST /developers/{developer_id}/products/{product_id}/plans.json

If you try to perform the same operation on a product scope, it will return an error. The scopes provides a way to control access and permissions for different entities in the Freemius ecosystem.

Currently, Bearer Token authentication is supported for product scope only. If you need access to endpoints in others scopes, use the secret-key based authentication with the following SDKs:

For most use cases, managing your products, licenses, and customers through the Developer Dashboard or Customer Portal provides all the necessary capabilities.

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 events

Request

Retrieve a log of the events for the user associated with the product. Freemius tracks events such as opt-in, license activation, purchase etc. You can use this data for marketing and other automation purposes. More information can be found here.

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

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

Responses

The user's events log.

Bodyapplication/json

eventsArray of objects(EventLog)

Response

application/json

{
  "events": [
    { … }
  ]
}

Retrieve a user

Request

Retrieve a user associated with your product.

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

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

Responses

The product user data.

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. We do not recommend using this option anymore since it will opt-in the user to all sites/activations. Currently, sites or activations can be managed individually.

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

Update a user

Request

Update a user associated with your product.

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

Bodyapplication/jsonrequired

namestring

The name of the user (Optional).

firststring

First name of the person.

Example: "Jane"

laststring

Last name of the person.

Example: "Doe"

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

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

Responses

The product user updated data.

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

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

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

Create a checkout token

Request

Create a 1 min long token that represents the details of the user for setting the user context in a checkout session. Please read our documentation to learn how to use it.

Path

product_idinteger(int64)>= 1required

The ID of the product.

Example: 1234

user_idinteger(int64)>= 1required

The ID of the User.

Example: 1234

curl -i -X POST \
  https://api.freemius.com/v1/products/1234/users/1234/tokens/checkout.json \
  -H 'Authorization: Bearer <YOUR_AccessToken_HERE>'

Responses

The created checkout token.

Bodyapplication/json

tokenany

Example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoxLCJwcm9kdWN0X2lkIjozLCJ0b2tlbl9leHBpcmF0aW9uIjoxNTY3ODk4NzYwfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"

Response

application/json

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoxLCJwcm9kdWN0X2lkIjozLCJ0b2tlbl9leHBpcmF0aW9uIjoxNTY3ODk4NzYwfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

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

Deployments

Operations related to version deployments and retrieval.

Operations

Freemius API (1.0)

Bearer Token Auth

Other Scopes and Authentication

Products

Subscriptions

Users

List all events

Request

Responses

Was this helpful?

Retrieve a user

Request

Responses

Was this helpful?

Update a user

Request

Responses

Was this helpful?

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?

Create a checkout token

Request

Responses

Was this helpful?

Licenses

Coupons

Carts

Payments

Installations

Trials

Addons

Plans

Deployments