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/

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

Resend the upgrade email

Request

Resend the license upgrade email.

Path
product_idinteger(int64)>= 1required

The ID of the product.

Example: 1234
license_idinteger(int64)>= 1required

The ID of the License.

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

Responses

License email resent.

Response
No content

Retrieve latest subscription

Request

A license can have only one active subscription at any given time. However, users may upgrade, downgrade, or change their payment method, which may result in a new subscription being created and associated with the same license.

Use this endpoint to retrieve the latest or currently active subscription linked to a specific license.

This is useful when you're building tools for license management or need to inspect the billing state of a customer. If you're integrating Freemius with your SaaS please refer to our guide here.

Path
product_idinteger(int64)>= 1required

The ID of the product.

Example: 1234
license_idinteger(int64)>= 1required

The ID of the License.

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

Responses

Subscription retrieved.

Bodyapplication/json
user_idstring(int64)>= 1

The ID of the user the entity belongs to.

Example: "123456"
install_idstring or null(int64)>= 1

The ID of the installation or site the entity is associated with, a null value means it has not been associated with an installation yet.

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

The ID of the plan associated with the entity.

Example: "123456"
pricing_idstring or null(int64)>= 1

The ID of the pricing associated with the entity.

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

The ID of the license associated with the entity.

Example: "123456"
ipstring or null(ipv4|ipv6)

The IP address associated with the entity.

Example: "0.0.0.0"
country_codestring

The ISO 3166-1 alpha 2 two-letter country code associated with the entity.

Example: "us"
zip_postal_codestring or null

The postal/zip code of the location.

Example: "92710"
vat_idstring or null

The business VAT number (EU or UK territories) or other tax ID (for example Sales Tax ID for the US).

Example: "GB12345678"
coupon_idstring or null(int64)>= 1

The ID of the coupon associated with the entity.

Example: "123456"
user_card_idstring(int64)

The ID of the user card that was used for this payment.

Example: "12345"
sourcenumber

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

  • 0 - Freemius
  • 1 - Other
  • 2 - Easy Digital Downloads (EDD)
  • 3 - WooCommerce (WC)
  • 4 - Rating Widget
  • 5 - Gumroad
  • 6 - CodeCanyon
  • 7 - ThemeForest
  • 8 - AppSumo
  • 9 - SendOwl
  • 10 - WHMCS
  • 11 - Lemon Squeezy
Enum0123456789
plugin_idstring(int64)>= 1

The ID of the product the entity belongs to.

Example: "123456"
external_idstring

The external ID of the gateway entity.

Example: "abcde12345"
gatewaystring or null

The gateway used for the purchase. The gateway will be set to null when purchasing a product with a 100% discount.

environmentnumber

The environment the entity belongs to. 0 means it belongs to the production environment, 1 means it belongs to the sandbox environment.

Enum10
Example: 0
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"
currencystring= 3 characters

3-char currency code.

Enum"usd""eur""gbp"
tax_ratenumber(float)>= 0

The tax rate as a fraction. It will either be US sales tax or VAT.

Example: "1.00"
total_grossnumber(float)>= 0

The total gross amount of the subscription, including taxes.

Example: "1.21"
amount_per_cyclenumber(float)>= 0

The plan's original amount per cycle (not including taxes).

Example: "1.00"
initial_amountnumber(float)>= 0

The initial payment amount (not including taxes).

Example: "1.00"
renewal_amountnumber(float)>= 0

The renewals amount (not including taxes).

Example: "1.00"
renewals_discountinteger>= 0

The renewals discount that will be applied to the chosen plan.

Example: "1"
renewals_discount_typestring

The type of renewals discount, percentage or dollar.

Enum"percentage""dollar"
billing_cyclenumber

The billing cycle of the subscription in number of months. 1 means monthly, 12 means annually, 0 means lifetime usually when subscriptions are created for lifetime trials.

Enum1120
outstanding_balancenumber(float)>= 0

Any outstanding balance that the user has for this subscription.

Example: "1.00"
failed_paymentsinteger>= 0

Number of failed payments associated with the subscription.

Example: "1"
trial_endsstring or null(date-time)

The date time when the trial period ends. If null the subscription is not associated with a trial.

Example: "2025-01-01 00:00:00"
next_paymentstring or null(date-time)

Datetime of the next payment, or null if cancelled.

Example: "2025-01-01 00:00:00"
canceled_atstring or null(date-time)

Datetime of the cancellation.

Example: "2025-01-01 00:00:00"
Response
application/json
{
  "user_id": "123456",
  "install_id": "123456",
  "plan_id": "123456",
  "pricing_id": "123456",
  "license_id": "123456",
  "ip": "0.0.0.0",
  "country_code": "us",
  "zip_postal_code": "92710",
  "vat_id": "GB12345678",
  "coupon_id": "123456",
  "user_card_id": "12345",
  "source": 0,
  "plugin_id": "123456",
  "external_id": "abcde12345",
  "gateway": "string",
  "environment": 0,
  "id": "123456",
  "created": "2025-01-01 00:00:00",
  "updated": "2025-01-01 00:00:00",
  "currency": "usd",
  "tax_rate": "1.00",
  "total_gross": "1.21",
  "amount_per_cycle": "1.00",
  "initial_amount": "1.00",
  "renewal_amount": "1.00",
  "renewals_discount": "1",
  "renewals_discount_type": "percentage",
  "billing_cycle": 1,
  "outstanding_balance": "1.00",
  "failed_payments": "1",
  "trial_ends": "2025-01-01 00:00:00",
  "next_payment": "2025-01-01 00:00:00",
  "canceled_at": "2025-01-01 00:00:00"
}

Cancel current subscription

Request

Use this endpoint to cancel the active subscription associated with a license. If the license is currently in a trialing state, this will also cancel the trial.

This is useful when you want to programmatically offer a cancellation feature from within your SaaS or custom dashboards. If you're integrating Freemius with your SaaS, please see our guide here.

⚠️ This action is irreversible and will immediately cancel the subscription or trial.

Cancelling an already cancelled subscription will not have any effect and the endpoint will return the same subscription details as before.

Path
product_idinteger(int64)>= 1required

The ID of the product.

Example: 1234
license_idinteger(int64)>= 1required

The ID of the License.

Example: 1234
Query
reason_idsArray of integers

Optional cancellation reason IDs.

Items Enum12345678910
Example: reason_ids=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 DELETE \
  'https://api.freemius.com/v1/products/1234/licenses/1234/subscription.json?reason=string&reason_ids=1' \
  -H 'Authorization: Bearer <YOUR_AccessToken_HERE>'

Responses

Subscription retrieved.

Bodyapplication/json
user_idstring(int64)>= 1

The ID of the user the entity belongs to.

Example: "123456"
install_idstring or null(int64)>= 1

The ID of the installation or site the entity is associated with, a null value means it has not been associated with an installation yet.

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

The ID of the plan associated with the entity.

Example: "123456"
pricing_idstring or null(int64)>= 1

The ID of the pricing associated with the entity.

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

The ID of the license associated with the entity.

Example: "123456"
ipstring or null(ipv4|ipv6)

The IP address associated with the entity.

Example: "0.0.0.0"
country_codestring

The ISO 3166-1 alpha 2 two-letter country code associated with the entity.

Example: "us"
zip_postal_codestring or null

The postal/zip code of the location.

Example: "92710"
vat_idstring or null

The business VAT number (EU or UK territories) or other tax ID (for example Sales Tax ID for the US).

Example: "GB12345678"
coupon_idstring or null(int64)>= 1

The ID of the coupon associated with the entity.

Example: "123456"
user_card_idstring(int64)

The ID of the user card that was used for this payment.

Example: "12345"
sourcenumber

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

  • 0 - Freemius
  • 1 - Other
  • 2 - Easy Digital Downloads (EDD)
  • 3 - WooCommerce (WC)
  • 4 - Rating Widget
  • 5 - Gumroad
  • 6 - CodeCanyon
  • 7 - ThemeForest
  • 8 - AppSumo
  • 9 - SendOwl
  • 10 - WHMCS
  • 11 - Lemon Squeezy
Enum0123456789
plugin_idstring(int64)>= 1

The ID of the product the entity belongs to.

Example: "123456"
external_idstring

The external ID of the gateway entity.

Example: "abcde12345"
gatewaystring or null

The gateway used for the purchase. The gateway will be set to null when purchasing a product with a 100% discount.

environmentnumber

The environment the entity belongs to. 0 means it belongs to the production environment, 1 means it belongs to the sandbox environment.

Enum10
Example: 0
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"
currencystring= 3 characters

3-char currency code.

Enum"usd""eur""gbp"
tax_ratenumber(float)>= 0

The tax rate as a fraction. It will either be US sales tax or VAT.

Example: "1.00"
total_grossnumber(float)>= 0

The total gross amount of the subscription, including taxes.

Example: "1.21"
amount_per_cyclenumber(float)>= 0

The plan's original amount per cycle (not including taxes).

Example: "1.00"
initial_amountnumber(float)>= 0

The initial payment amount (not including taxes).

Example: "1.00"
renewal_amountnumber(float)>= 0

The renewals amount (not including taxes).

Example: "1.00"
renewals_discountinteger>= 0

The renewals discount that will be applied to the chosen plan.

Example: "1"
renewals_discount_typestring

The type of renewals discount, percentage or dollar.

Enum"percentage""dollar"
billing_cyclenumber

The billing cycle of the subscription in number of months. 1 means monthly, 12 means annually, 0 means lifetime usually when subscriptions are created for lifetime trials.

Enum1120
outstanding_balancenumber(float)>= 0

Any outstanding balance that the user has for this subscription.

Example: "1.00"
failed_paymentsinteger>= 0

Number of failed payments associated with the subscription.

Example: "1"
trial_endsstring or null(date-time)

The date time when the trial period ends. If null the subscription is not associated with a trial.

Example: "2025-01-01 00:00:00"
next_paymentstring or null(date-time)

Datetime of the next payment, or null if cancelled.

Example: "2025-01-01 00:00:00"
canceled_atstring or null(date-time)

Datetime of the cancellation.

Example: "2025-01-01 00:00:00"
Response
application/json
{
  "user_id": "123456",
  "install_id": "123456",
  "plan_id": "123456",
  "pricing_id": "123456",
  "license_id": "123456",
  "ip": "0.0.0.0",
  "country_code": "us",
  "zip_postal_code": "92710",
  "vat_id": "GB12345678",
  "coupon_id": "123456",
  "user_card_id": "12345",
  "source": 0,
  "plugin_id": "123456",
  "external_id": "abcde12345",
  "gateway": "string",
  "environment": 0,
  "id": "123456",
  "created": "2025-01-01 00:00:00",
  "updated": "2025-01-01 00:00:00",
  "currency": "usd",
  "tax_rate": "1.00",
  "total_gross": "1.21",
  "amount_per_cycle": "1.00",
  "initial_amount": "1.00",
  "renewal_amount": "1.00",
  "renewals_discount": "1",
  "renewals_discount_type": "percentage",
  "billing_cycle": 1,
  "outstanding_balance": "1.00",
  "failed_payments": "1",
  "trial_ends": "2025-01-01 00:00:00",
  "next_payment": "2025-01-01 00:00:00",
  "canceled_at": "2025-01-01 00:00:00"
}

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