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

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

Retrieve cart events

Request

Get the list of events associated with a cart.

Path
product_idinteger(int64)>= 1required

The ID of the product.

Example: 1234
cart_idinteger(int64)>= 1required

The ID of the Cart.

Example: 1234
Query
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
curl -i -X GET \
  'https://api.freemius.com/v1/products/1234/carts/1234/events.json?count=10&offset=10' \
  -H 'Authorization: Bearer <YOUR_AccessToken_HERE>'

Responses

The cart's events collection.

Bodyapplication/json
eventsArray of objects(EventLog)
Response
application/json
{
  "events": [
    { … }
  ]
}

Retrieve a cart

Request

Retrieve cart details associated with the product.

You can use enriched=true to get more details about the cart, for example the gross, coupon_code and licenses fields will only be returned if enriched is enabled. Please see individual parameters in the response data below to learn more.

Path
product_idinteger(int64)>= 1required

The ID of the product.

Example: 1234
cart_idinteger(int64)>= 1required

The ID of the Cart.

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
enrichedboolean

Defaults to false, if true returns enriched cart details.

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

Responses

Cart details associated with the product.

Bodyapplication/json
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"
statusstring

The status of the cart.

Default "visit"
Enum"pricing_visit""visit""abandoned""completed""email_1_sent""email_2_sent""email_3_sent""recovered"
modestring

The mode the checkout app was opened in, when the cart was created. For example

  • dashboard: The checkout was opened through our WordPress SDK.
  • dialog: The checkout was opened through our JavaScript SDK.
  • page: The checkout was opened directly.
Default "dialog"
Enum"dashboard""dialog""page"
payment_methodstring

The payment method selected for the purchase.

Default "cc"
Enum"cc""paypal"
plugin_idstring(int64)>= 1

The ID of the product the entity belongs to.

Example: "123456"
plan_idstring or null(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"
is_trialboolean

Whether the plan is a trial.

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

The ID of the coupon associated with the entity.

Example: "123456"
country_codestring or null

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

Example: "us"
zip_postal_codestring

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

The ID of the user the entity belongs to. If NULL then still not associated to any user.

Example: "123456"
emailstring

The prospect's email address.

Example: "doe@example.com"
firststring

The prospect's first name.

Example: "John"
laststring

The prospect's last name.

Example: "Doe"
ipstring(ipv4|ipv6)

The IP address associated with the entity.

Example: "0.0.0.0"
urlstring

The page URL containing the checkout.

Example: "https://example.com/pricing"
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
is_disabledboolean

Cart supports recovery campaign. If disabled, the recovery campaign will be stopped.

Default "false"
is_unsubscribedboolean

If set to true, the cart recovery campaign will be non-functional and cannot be re-enabled. This happens if the prospect has clicked the "unsubscribe" link from any of the cart recovery emails.

Default "false"
visitedstring or null(date-time)

The first time the prospect visited the checkout when the cart was being created.

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

The cart completion date.

Example: "2025-01-01 00:00:00"
pricenumber(float)

The cart's original price.

Example: "19.99"
grossnumber or null(float)

Gross amount associated with the cart. (Only available when enriched is set to true.)

Example: "359.64"
coupon_codestring or null

Coupon code associated with the cart. (Only available when enriched is set to true.)

Example: "BLACKFRIDAY2024"
licensesnumber or null

Number of licenses associated with the cart. (Only available when enriched is set to true.)

Example: "10"
Response
application/json
{
  "id": "123456",
  "created": "2025-01-01 00:00:00",
  "updated": "2025-01-01 00:00:00",
  "status": "pricing_visit",
  "mode": "dashboard",
  "payment_method": "cc",
  "plugin_id": "123456",
  "plan_id": "123456",
  "pricing_id": "123456",
  "is_trial": true,
  "billing_cycle": 1,
  "install_id": "123456",
  "coupon_id": "123456",
  "country_code": "us",
  "zip_postal_code": "92710",
  "vat_id": "GB12345678",
  "user_id": "123456",
  "email": "doe@example.com",
  "first": "John",
  "last": "Doe",
  "ip": "0.0.0.0",
  "url": "https://example.com/pricing",
  "environment": 0,
  "is_disabled": "false",
  "is_unsubscribed": "false",
  "visited": "2025-01-01 00:00:00",
  "completed": "2025-01-01 00:00:00",
  "price": "19.99",
  "gross": "359.64",
  "coupon_code": "BLACKFRIDAY2024",
  "licenses": "10"
}

List all carts

Request

Retrieve the cart collection associated with your product.

If enriched=true you will get more details about the cart for example the gross, coupon_code and licenses fields.

You can use the filter or email or count parameters to get more refined results from your query. Please learn more about the individual parameters below.

Path
product_idinteger(int64)>= 1required

The ID of the product.

Example: 1234
Query
filterstring

You can use the filter parameter to filter by status. If you don't provide a status, the endpoint will return all carts.

Default "all"
Enum"all""abandoned""completed""recovered""recovery""active"
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
enrichedboolean

Defaults to false, if true returns enriched cart details.

Default "false"
emailstring

Filter the cart collections by the email address.

Example: email=doe@example.com
countinteger

Number of carts to retrieve.

Default "50"
curl -i -X GET \
  'https://api.freemius.com/v1/products/1234/carts.json?count=50&email=doe%40example.com&enriched=false&fields=id%2Cname%2Cslug&filter=all&offset=10' \
  -H 'Authorization: Bearer <YOUR_AccessToken_HERE>'

Responses

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

Bodyapplication/json
cartsArray of objects
Response
application/json
{
  "carts": [
    { … }
  ]
}

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