Start a trial

POST 
https://api.freemius.com/v1/products/{product_id}/installs/{install_id}/plans/{plan_id}/trials.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.

---

Start the trial of a plan for which an install is subscribed. The install must not have utilized the trial before.

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
plan_id integer<int64>required
The ID of the plan.
Possible values: >= 1
Example: 1234

Query Parameters

fields string
Comma separated list of fields to return in the response. If not specified, all fields are returned.
Example: id,name,slug

application/json

Bodyrequired

trial_endsstring<date-time>
The expiry date of the trial. If set, will set the trial expiration based on that parameter. Note: Trial expiration date cannot exceed the maximum trial period days based on the plan configuration.
Example: 2025-01-01 00:00:00
phonestring
The phone number used in the billing.
Example: 555-555-5555
is_migrationboolean

Whether emails will be sent to users or log events. If true, no emails will be sent nor events logged.

trial_tokenstring

Security token for sandbox mode trial.

trial_timestampstring
Security timestamp for sandbox mode trial.
Example: 1730160000

Responses

200

Started Trial

application/json

Schema

trial object

A trial represents a user's trial period for a product. Please read our documentation to learn more about trials.

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

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

payment_idstring<int64>nullable

The ID of the payment associated to the entity.

Possible values: >= 1

Example: 123456

subscription_idstring<int64>nullable

The ID of the subscription associated with the entity.

Possible values: >= 1

Example: 123456

license_idstring<int64>nullable

The ID of the license associated with the entity.

Possible values: >= 1

Example: 123456

trial_ends_atstring<date-time>

The date and time the trial ends, under UTC timezone.

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

with_payment_methodboolean

Whether the trial was created with a payment method. Freemius supports both free and paid trials.

canceled_atstring<date-time>nullable

The date and time the trial was cancelled, under UTC timezone. If null the trial has not been cancelled.

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

converted_atstring<date-time>nullable

The date and time the trial was converted to a paid subscription or one-time purchase, under UTC timezone. If null the trial has not been converted.

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

environmentnumber

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

Possible values: [1, 0]

Example: 0

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