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.

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

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

Retrieve a subscription

Request

Retrieve a subscription associated with your product.

Path
product_idinteger(int64)>= 1required

The ID of the product.

Example: 1234
subscription_idinteger(int64)>= 1required

The ID of the Subscription.

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/subscriptions/1234.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"
}

Update a subscription

Request

Update a subscription's auto-renewal status and activate a cancellation coupon.

To cancel a subscription please use the Developer Dashboard.

Path
product_idinteger(int64)>= 1required

The ID of the product.

Example: 1234
subscription_idinteger(int64)>= 1required

The ID of the Subscription.

Example: 1234
Bodyapplication/jsonrequired
auto_renewboolean

Logs an event that confirms the user requested that the subscription will continue to auto-renew.

coupon_idinteger

An optional subscription cancellation coupon ID. The coupon must be set as a special "Cancellation Coupon" in the Freemius Developer Dashboard. If provided the discount will be applied to the next renewals.

curl -i -X PUT \
  https://api.freemius.com/v1/products/1234/subscriptions/1234.json \
  -H 'Authorization: Bearer <YOUR_AccessToken_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{}'

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

List all subscriptions

Request

Retrieve the subscription collecttion associated with your product.

Subscriptions are created when someone purchases your product using the Freemius Checkout.

Searching and filtering

There are various parameters to help you search and/or filter subscription.

  • You can search by subscription ID, external subscription ID, or user email.
  • You can also filter by billing cycle, gateway, plan ID, and subscription status. Please see the parameters for more information.
Path
product_idinteger(int64)>= 1required

The ID of the product.

Example: 1234
Query
searchstring

Optional search: subscription id, external subscription id or user email

billing_cyclenumber

Filter by billing cycle.

Enum1120
gatewaystring

Filter by gateway.

Enum"paypal""stripe"
Example: gateway=stripe
filterstring

Optional filtering based on the status of the subscription. Defaults to all.

Default "all"
Enum"all""active""cancelled"
extendedboolean

When set to true enrich the subscriptions with the plan name, install URL & title, and user email.

Example: extended=false
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
sortstring

The sort order of the subscriptions. Example: -id. Default: -id.

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

Responses

Provides a collection of subscriptions associated with the product. All subscriptions are listed under the subscriptions key.

Bodyapplication/json
subscriptionsArray of objects
discountsArray of objects(Discount)
Response
application/json
{
  "subscriptions": [
    { … }
  ],
  "discounts": [
    { … }
  ]
}

List all payments

Request

Retrieve the payment collection associated with the subscription.

Path
product_idinteger(int64)>= 1required

The ID of the product.

Example: 1234
subscription_idinteger(int64)>= 1required

The ID of the Subscription.

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

Responses

Provides a collection of payments associated with the subscription. All payments are listed under the payments key.

Bodyapplication/json
paymentsArray of objects(Payment)
Response
application/json
{
  "payments": [
    { … }
  ]
}

Create a new migrated payment

Request

In case you want to synchronize migrated subscription from the legacy platform use this endpoint to have our system log a migrated payment. Depending on your use case you can also choose to extend the license. Please read our migration documentation to learn more.

Path
product_idinteger(int64)>= 1required

The ID of the product.

Example: 1234
subscription_idinteger(int64)>= 1required

The ID of the Subscription.

Example: 1234
Bodyapplication/jsonrequired
grossnumber(float)

The payment amount (not including taxes).

Example: 2075.45
payment_external_idstring

The external ID of the gateway entity.

Example: "abcde12345"
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"
vatnumber

The actual tax amount. It could be any kind of tax, not necessarily VAT. For example we support US Sales Tax.

Default 0
Example: 1.24
gateway_feenumber(float)

The fee that the gateway took for processing this payment.

Default 0
Example: 2.99
processed_atstring or null(date-time)

The cart completion date.

Example: "2025-01-01 00:00:00"
is_extend_licenseboolean

Whether the license should be extended. The default value is false.

next_paymentstring or null(date-time)

Datetime of the next payment, or null if cancelled.

Example: "2025-01-01 00:00:00"
curl -i -X POST \
  https://api.freemius.com/v1/products/1234/subscriptions/1234/payments.json \
  -H 'Authorization: Bearer <YOUR_AccessToken_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{}'

Responses

The payment was successfully created.

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"
subscription_idstring or null(int64)>= 1

The ID of the subscription associated with the entity.

Example: "123456"
grossnumber(float)

The payment amount (not including taxes).

Example: 2075.45
bound_payment_idstring(int64)>= 1

The ID of the payment that this payment is bound to, in case of a refund or chargeback/dispute.

Example: "123456"
gateway_feenumber(float)

The fee that the gateway took for processing this payment.

Default 0
Example: 2.99
vatnumber

The actual tax amount. It could be any kind of tax, not necessarily VAT. For example we support US Sales Tax.

Default 0
Example: 1.24
is_renewalboolean

If the payment is a renewal.

Default false
typestring

The type of the payment.

Default "payment"
Enum"payment""refund""disputed""won_dispute""lost_dispute""chargeback"
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",
  "subscription_id": "123456",
  "gross": 2075.45,
  "bound_payment_id": "123456",
  "gateway_fee": 2.99,
  "vat": 1.24,
  "is_renewal": false,
  "type": "payment"
}

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

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