# 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](https://dashboard.freemius.com/). 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[​](#request "Direct link to request") ### Path Parameters * **product\_id** integer\[](#param-property-installations-start-trial-param-path-product-id "Direct link to product_id")required The ID of the product. **Possible values:** `>= 1` **Example: **`1234` **install\_id** integer\[](#param-property-installations-start-trial-param-path-install-id "Direct link to install_id")required The ID of the install. **Possible values:** `>= 1` **Example: **`1234` **plan\_id** integer\[](#param-property-installations-start-trial-param-path-plan-id "Direct link to plan_id")required The ID of the plan. **Possible values:** `>= 1` **Example: **`1234` ### Query Parameters * **fields** string[](#param-property-installations-start-trial-param-query-fields "Direct link to fields") Comma separated list of fields to return in the response. If not specified, all fields are returned. **Example: **`id,name,slug` application/json ### Body**required** * **trial\_ends**string\[](#schema-property-installations-start-trial-request-body-trial-ends-string-date-time "Direct link to trial_ends") 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` **phone**string[](#schema-property-installations-start-trial-request-body-phone-string "Direct link to phone") The phone number used in the billing. **Example: **`555-555-5555` **is\_migration**boolean[](#schema-property-installations-start-trial-request-body-is-migration-boolean "Direct link to is_migration") Whether emails will be sent to users or log events. If `true`, no emails will be sent nor events logged. **trial\_token**string[](#schema-property-installations-start-trial-request-body-trial-token-string "Direct link to trial_token") Security token for sandbox mode trial. **trial\_timestamp**string[](#schema-property-installations-start-trial-request-body-trial-timestamp-string "Direct link to trial_timestamp") Security timestamp for sandbox mode trial. **Example: **`1730160000` ## Responses[​](#responses "Direct link to Responses") * 200 * 400 * 401 * 402 * 404 Started Trial application/json **Schema** **trial** object A trial represents a user's trial period for a product. Please read our [documentation](https://freemius.com/help/documentation/selling-with-freemius/free-trials/) to learn more about trials. **id**string\[](#schema-property-installations-start-trial-response-schema-id-string-int64 "Direct link to id") The unique identifier of the entity. **Possible values:** `>= 1` **Example: **`123456` **created**string\[](#schema-property-installations-start-trial-response-schema-created-string-date-time "Direct link to created") The date and time the entity was created, under UTC timezone. **Example: **`2025-01-01 00:00:00` **updated**string\[](#schema-property-installations-start-trial-response-schema-updated-string-date-time "Direct link to updated")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\_id**string\[](#schema-property-installations-start-trial-response-schema-plugin-id-string-int64 "Direct link to plugin_id") The ID of the product the entity belongs to. **Possible values:** `>= 1` **Example: **`123456` **user\_id**string\[](#schema-property-installations-start-trial-response-schema-user-id-string-int64 "Direct link to user_id") The ID of the user the entity belongs to. **Possible values:** `>= 1` **Example: **`123456` **payment\_id**string\[](#schema-property-installations-start-trial-response-schema-payment-id-string-int64 "Direct link to payment_id")nullable The ID of the payment associated to the entity. **Possible values:** `>= 1` **Example: **`123456` **subscription\_id**string\[](#schema-property-installations-start-trial-response-schema-subscription-id-string-int64 "Direct link to subscription_id")nullable The ID of the subscription associated with the entity. **Possible values:** `>= 1` **Example: **`123456` **license\_id**string\[](#schema-property-installations-start-trial-response-schema-license-id-string-int64 "Direct link to license_id")nullable The ID of the license associated with the entity. **Possible values:** `>= 1` **Example: **`123456` **trial\_ends\_at**string\[](#schema-property-installations-start-trial-response-schema-trial-ends-at-string-date-time "Direct link to trial_ends_at") The date and time the trial ends, under UTC timezone. **Example: **`2025-01-01 00:00:00` **with\_payment\_method**boolean[](#schema-property-installations-start-trial-response-schema-with-payment-method-boolean "Direct link to with_payment_method") Whether the trial was created with a payment method. Freemius supports both free and paid trials. **canceled\_at**string\[](#schema-property-installations-start-trial-response-schema-canceled-at-string-date-time "Direct link to canceled_at")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\_at**string\[](#schema-property-installations-start-trial-response-schema-converted-at-string-date-time "Direct link to converted_at")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` **environment**number[](#schema-property-installations-start-trial-response-schema-environment-number "Direct link to environment") 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` Bad request. The request could not be understood by the server due to malformed syntax or arguments. application/json **Schema** **path**string[](#schema-property-installations-start-trial-response-schema-path-string "Direct link to path") The API request path. **Example: **`:/products/product_id/users.json` **error** object This object contains the error details. **type**string[](#schema-property-installations-start-trial-response-schema-type-string "Direct link to type") The type of the error encountered by the server. **Example: **`UnauthorizedAccess` **message**string[](#schema-property-installations-start-trial-response-schema-message-string "Direct link to message") The descriptive error message. **Example: **`Some error has occured.` **code**string[](#schema-property-installations-start-trial-response-schema-code-string "Direct link to code") The error code. **Example: **`unauthorized_access` **http**integer[](#schema-property-installations-start-trial-response-schema-http-integer "Direct link to http") The HTTP status code returned by the server. **Example: **`401` **timestamp**string[](#schema-property-installations-start-trial-response-schema-timestamp-string "Direct link to timestamp") 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[](#schema-property-installations-start-trial-response-schema-property-name-any "Direct link to property name*") 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"}` Unauthorized access error. The request requires [authentication](https://freemius.com/help/api/#bearer-token-authentication) but was not provided or the provided authentication does not satisfy the required permissions. application/json **Schema** **path**string[](#schema-property-installations-start-trial-response-schema-path-string "Direct link to path") The API request path. **Example: **`:/products/product_id/users.json` **error** object This object contains the error details. **type**string[](#schema-property-installations-start-trial-response-schema-type-string "Direct link to type") The type of the error encountered by the server. **Example: **`UnauthorizedAccess` **message**string[](#schema-property-installations-start-trial-response-schema-message-string "Direct link to message") The descriptive error message. **Example: **`Some error has occured.` **code**string[](#schema-property-installations-start-trial-response-schema-code-string "Direct link to code") The error code. **Example: **`unauthorized_access` **http**integer[](#schema-property-installations-start-trial-response-schema-http-integer "Direct link to http") The HTTP status code returned by the server. **Example: **`401` **timestamp**string[](#schema-property-installations-start-trial-response-schema-timestamp-string "Direct link to timestamp") 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[](#schema-property-installations-start-trial-response-schema-property-name-any "Direct link to property name*") 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"}` The request is missing the specified argument. application/json **Schema** **path**string[](#schema-property-installations-start-trial-response-schema-path-string "Direct link to path") The API request path. **Example: **`:/products/product_id/users.json` **error** object This object contains the error details. **type**string[](#schema-property-installations-start-trial-response-schema-type-string "Direct link to type") The type of the error encountered by the server. **Example: **`UnauthorizedAccess` **message**string[](#schema-property-installations-start-trial-response-schema-message-string "Direct link to message") The descriptive error message. **Example: **`Some error has occured.` **code**string[](#schema-property-installations-start-trial-response-schema-code-string "Direct link to code") The error code. **Example: **`unauthorized_access` **http**integer[](#schema-property-installations-start-trial-response-schema-http-integer "Direct link to http") The HTTP status code returned by the server. **Example: **`401` **timestamp**string[](#schema-property-installations-start-trial-response-schema-timestamp-string "Direct link to timestamp") 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[](#schema-property-installations-start-trial-response-schema-property-name-any "Direct link to property name*") 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"}` The requested resource was not found. application/json **Schema** **path**string[](#schema-property-installations-start-trial-response-schema-path-string "Direct link to path") The API request path. **Example: **`:/products/product_id/users.json` **error** object This object contains the error details. **type**string[](#schema-property-installations-start-trial-response-schema-type-string "Direct link to type") The type of the error encountered by the server. **Example: **`UnauthorizedAccess` **message**string[](#schema-property-installations-start-trial-response-schema-message-string "Direct link to message") The descriptive error message. **Example: **`Some error has occured.` **code**string[](#schema-property-installations-start-trial-response-schema-code-string "Direct link to code") The error code. **Example: **`unauthorized_access` **http**integer[](#schema-property-installations-start-trial-response-schema-http-integer "Direct link to http") The HTTP status code returned by the server. **Example: **`401` **timestamp**string[](#schema-property-installations-start-trial-response-schema-timestamp-string "Direct link to timestamp") 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[](#schema-property-installations-start-trial-response-schema-property-name-any "Direct link to property name*") 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"}`