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:

  1. Go to the Freemius Developer Dashboard.
  2. Open the Settings page of the relevant product.
  3. Click on the API Token tab.
  4. 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

Terms of Service

Languages
Servers
Production API

https://api.freemius.com/v1/

Local development API

http://api.freemius-local.com:8080/v1/

Mock server

https://docs.freemius.com/_mock/api/

Products

All operations which can be done on a product.

Operations

Developers

All operations which can be done from on a developer.

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

Change ownership

Request

Change ownership of 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
user_idinteger(int64)>= 1required

The ID of the User.

Example: 1234
Bodyapplication/jsonrequired
token_saltanyrequired

The transfer token salt. This is generated by Freemius and sent over email with expiration.

emailanyrequired

Candidate or owner email.

transfer_typeany

Defaults to 'transfer' for backward compatibility.

owner_tokenany

Token generated by Freemius. Get this from the Developer Dashboard.

candidate_tokenany

Token generated by Freemius. Get this from the Developer Dashboard.

after_confirm_urlany

The URL to redirect after the user confirms the ownership change.

install_idsany

Comma-separated list of IDs of installs that should be transferred to the new owner. This can include add-ons' install IDs.

curl -i -X PUT \
  https://api.freemius.com/v1/products/1234/installs/1234/users/1234/ownership-change.json \
  -H 'Authorization: Bearer <YOUR_AccessToken_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "token_salt": null,
    "email": null
  }'

Responses

Install ownership changed successfully. No response will be sent, but it will be redirected to the after_confirm_url if it was used when initiating the ownership transfer.

Response
No content

Send a verification email

Request

Sends an email to the user associated with the install, containing a link to verify the email address.

With the after_email_confirm_url parameter, you can specify a URL address that the user will be auto forwarded to after email confirmation is clicked.

Path
product_idinteger(int64)>= 1required

The ID of the product.

Example: 1234
install_idinteger(int64)>= 1required

The ID of the install.

Example: 1234
user_idinteger(int64)>= 1required

The ID of the User.

Example: 1234
Bodyapplication/jsonrequired
after_email_confirm_urlstring

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

Example: "https://example.com/email-confirmation/"
curl -i -X PUT \
  https://api.freemius.com/v1/products/1234/installs/1234/users/1234/verify.json \
  -H 'Authorization: Bearer <YOUR_AccessToken_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{}'

Responses

Successful operation.

Response
No content

Uninstall from anonymous site

Request

Uninstall a product from anonymous site

Path
product_idinteger(int64)>= 1required

The ID of the product.

Example: 1234
Bodyapplication/jsonrequired
uidstring(uid)= 32 characters

Unique identifier of the caller. The UID must be same when pinging and when activating or deactivating a license. The generation of the UID is a responsibility of the client.

Example: "7W131pej6bJYV8WYM9KgGoBNB9bCiSrY"
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
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/uninstall.json \
  -H 'Authorization: Bearer <YOUR_AccessToken_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{}'

Responses

The product is uninstalled.

Bodyapplication/json
string
Response
application/json
"200 OK"

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

Events

Operations related to events of a store or product.

Operations

Reviews

Operations related to reviews of a product.

Operations

Deployments

Operations related to version deployments and retrieval.

Operations