Update an install

PUT 
https://api.freemius.com/v1/products/{product_id}/installs/{install_id}.json

Auth:Bearer TokenSCOPE: PRODUCT

Product-scoped API tokens allow you to operate on the product itself. This token usually allows read-only access to the product configuration and write access to several operations on subscriptions, customers, payments, and more. For most SaaS or app integrations, this is the token you will need.

1. Go to the Freemius Developer Dashboard.
2. Open the Settings page of the relevant product.
3. Click the API & Keys tab.
4. Copy the API Bearer Authorization Token from the UI.

---

Update the details related to the product install.

Request

Path Parameters

product_id integer<int64>required
The ID of the product.
Possible values: >= 1
Example: 1234
install_id integer<int64>required
The ID of the install.
Possible values: >= 1
Example: 1234

application/json

Bodyrequired

uidstring<uid>
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.
Possible values: >= 32 characters and <= 32 characters
Example: 7W131pej6bJYV8WYM9KgGoBNB9bCiSrY
license_keystring
The license key. This is used for activating the license on the user's site.
Example: sk_123FGqM456Pa786WtOp%^+67Y+;sXXz
urlstringnullable
The site URL.
Example: https://example.com
titlestringnullable
The site title.
Example: Catwalk Designs
versionstring
The Product version.
Example: 1.0.0
sdk_versionstringnullable
The Freemius SDK version. Only relevant for WordPress products using the Freemius WP SDK.
Example: 1.2.2
platform_versionstringnullable
The platform version (e.g WordPress version).
Example: 1.0.0
programming_language_versionstringnullable
The programming language version (e.g PHP version).
Example: 5.6
plan_idstring<int64>
The unique identifier of the entity.
Possible values: >= 1
Example: 123456
trial_plan_idstring<int64>
The ID of the trial license associated to the product. If this is not a trial, this will be null.
Possible values: >= 1
Example: 1234
trials_endsstring<date-time>
The datetime that the trial expires.
Example: 2025-01-01 00:00:00
subscription_idstring<int64>
The unique identifier of the entity.
Possible values: >= 1
Example: 123456
is_lockedboolean

If the product is locked on the site.

is_activeboolean

If the product is actively installed on the site.

is_disconnectedboolean

If the product is disconnected on the site.

is_premiumboolean

If the install using the premium code. Relevant only for WP Products.

is_sdk_requiredboolean

A flag that controls whether the SDK should be required or not during deployment of a version. It defaults to true.

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
Possible values: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15]
Example: 1
reason_infostring

Additional information gathered from the user for the uninstallation. This is populated when the product user chooses “Other” in contrast to pre-set options.

pluginsstring

The site plugins installed.

themesstring

The site themes installed.

is_betaboolean

Whether the product user is participating in the beta program.

recoverboolean

Recover the install.

is_uninstalledboolean

If the product is uninstalled on the site.

user_idstring<int64>
The ID of the user. This is used for ownership change of the install.
Possible values: >= 1
Example: 1234
user_emailstring
The email of the user. This is used for ownership change of the install.
Example: [email protected]
install_idsstring[]
A comma seperated string of Install IDs. This is used for ownership change of the install.
Example: 1234,2478,2345

Responses

200

Install updated

application/json

Schema

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>

The unique identifier of the entity.

Possible values: >= 1

Example: 123456

createdstring<date-time>

The date and time the entity was created, under UTC timezone.

Example: 2025-01-01 00:00:00

updatedstring<date-time>nullable

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

site_idstring<int64>

The ID of the site.

Example: 1234

plugin_idstring<int64>

The ID of the product the entity belongs to.

Possible values: >= 1

Example: 123456

user_idstring<int64>

The ID of the user the entity belongs to.

Possible values: >= 1

Example: 123456

urlstringnullable

The site URL.

Example: https://example.com

titlestringnullable

The site title.

Example: Catwalk Designs

versionstring

The Product version.

Example: 1.0.0

plan_idstring<int64>

The ID of the plan associated with the product that the install has a license activation. If null it means the install is using the free plan.

Possible values: >= 1

Example: 1234

license_idstring<int64>nullable

The ID of the license associated with the entity.

Possible values: >= 1

Example: 123456

trial_plan_idstring<int64>

The ID of the trial license associated to the product. If this is not a trial, this will be null.

Possible values: >= 1

Example: 1234

trial_endsstring<date-time>nullable

The product trial license expiry date. If this is not a trial, this will be null.

Example: 2025-01-01 00:00:00

subscription_idstring<int64>nullable

The ID of the subscription associated with the entity.

Possible values: >= 1

Example: 123456

grossnumber<float>

The gross amount the install has spent on the product. This includes one time purchase, or subscriptions and renewals.

Example: 100

country_codestringnullable

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

Example: us

languagestringnullable

The language specified for the product install.

Example: en-GB

platform_versionstringnullable

The platform version (e.g WordPress version).

Example: 1.0.0

sdk_versionstringnullable

The Freemius SDK version. Only relevant for WordPress products using the Freemius WP SDK.

Example: 1.2.2

programming_language_versionstringnullable

The programming language version (e.g PHP version).

Example: 5.6

is_activeboolean

If the product is actively installed on the site.

is_disconnectedboolean

If the product is disconnected on the site.

is_premiumboolean

If the install using the premium code. Relevant only for WP Products.

is_uninstalledboolean

If the product is uninstalled on the site.

is_lockedboolean

If the product is locked on the site.

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

Possible values: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]

upgradedstring<date-time>nullable

Time when the product was upgraded to the current version. If never upgraded since the initial installation, this will be null.

Example: 2025-01-01 00:00:00

last_seen_atstring<date-time>nullable

The last time the product was used on the site.

Example: 2025-01-01 00:00:00

last_served_update_versionstringnullable

The last product version update used on the site. If not updated, this will be null.

Example: 1.2.2

400

Bad request. The request could not be understood by the server due to malformed syntax or arguments.

application/json

Schema

pathstring

The API request path.

Example: :/products/product_id/users.json

error object

This object contains the error details.

typestring

The type of the error encountered by the server.

Example: UnauthorizedAccess

messagestring

The descriptive error message.

Example: Some error has occured.

codestring

The error code.

Example: unauthorized_access

httpinteger

The HTTP status code returned by the server.

Example: 401

timestampstring

Current timestamp.

Example: Thu, 11 May 2023 11:45:30 +0000

request object

This object sends back the request payload as received by the server (both from path and from body or query).

property name*any

This object sends back the request payload as received by the server (both from path and from body or query).

Example: {"beautify":true,"format":"json"}

401

Unauthorized access error. The request requires authentication but was not provided or the provided authentication does not satisfy the required permissions.

application/json

Schema

pathstring

The API request path.

Example: :/products/product_id/users.json

error object

This object contains the error details.

typestring

The type of the error encountered by the server.

Example: UnauthorizedAccess

messagestring

The descriptive error message.

Example: Some error has occured.

codestring

The error code.

Example: unauthorized_access

httpinteger

The HTTP status code returned by the server.

Example: 401

timestampstring

Current timestamp.

Example: Thu, 11 May 2023 11:45:30 +0000

request object

This object sends back the request payload as received by the server (both from path and from body or query).

property name*any

This object sends back the request payload as received by the server (both from path and from body or query).

Example: {"beautify":true,"format":"json"}

402

The request is missing the specified argument.

application/json

Schema

pathstring

The API request path.

Example: :/products/product_id/users.json

error object

This object contains the error details.

typestring

The type of the error encountered by the server.

Example: UnauthorizedAccess

messagestring

The descriptive error message.

Example: Some error has occured.

codestring

The error code.

Example: unauthorized_access

httpinteger

The HTTP status code returned by the server.

Example: 401

timestampstring

Current timestamp.

Example: Thu, 11 May 2023 11:45:30 +0000

request object

This object sends back the request payload as received by the server (both from path and from body or query).

property name*any

This object sends back the request payload as received by the server (both from path and from body or query).

Example: {"beautify":true,"format":"json"}

404

The requested resource was not found.

application/json

Schema

pathstring

The API request path.

Example: :/products/product_id/users.json

error object

This object contains the error details.

typestring

The type of the error encountered by the server.

Example: UnauthorizedAccess

messagestring

The descriptive error message.

Example: Some error has occured.

codestring

The error code.

Example: unauthorized_access

httpinteger

The HTTP status code returned by the server.

Example: 401

timestampstring

Current timestamp.

Example: Thu, 11 May 2023 11:45:30 +0000

request object

This object sends back the request payload as received by the server (both from path and from body or query).

property name*any

This object sends back the request payload as received by the server (both from path and from body or query).

Example: {"beautify":true,"format":"json"}