Create a deployment

POST 
https://api.freemius.com/v1/products/{product_id}/tags.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.

---

Upload a new version of the product (for WordPress products only). The endpoint supports only the multipart/form-data content type and expects two payloads: file and data.

• file - The zip file containing the product. For WordPress plugins or themes this must contain the root directory.
• data - Please omit this when deploying WordPress plugins and themes. In case of deploying templates and widgets, this needs to be a stringified JSON and must have the version and requires_platform_version properties.

An example of the data property:

{"version": "2.0.0", "requires_platform_version": "1.0.0"}

After you have created a deployment, please send another PUT request to the newly created version to update the release_status to either released or beta. The default value is pending which means none of the customers will be able to see the new version.

You can learn more about the deployment process here.

Request

Path Parameters

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

multipart/form-data

Body

filestring<binary>required

The zip file containing the product. For WordPress plugins or themes this must contain the root directory.

datastring<json>
The metadata details associated with this specific product version.
Example: {"version": "1.0.0", "requires_platform_version": "1.0.0"}

Responses

200

OK

application/json

Schema

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

developer_idstring<int64>

The ID of a developer.

Possible values: >= 1

Example: 1234

slugstringnullable

The slug of the product. This is auto-generated from your product settings.

Example: my-freemius-plugin

premium_slugstringnullable

The slug of the premium product. This is auto-generated from your product's settings.

Example: my-freemius-plugin-pro

versionstring<semver>

The version of the product. For WordPress.org products (plugins and themes), we recommend using semver semantics to support composer integration.

Example: 1.0.0

sdk_versionstring

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

Example: 1.2.2

requires_platform_versionstringnullable

The platform version required (e.g WordPress version).

Example: 1.0.0

requires_programming_language_versionstringnullable

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

Example: 5.6

tested_up_to_versionstringnullable

The tested platform version that the product is compatible (e.g WordPress version).

Example: 1.0.0

downloadedinteger

The number of times the product has been downloaded.

Possible values: >= 0

Example: 1234

has_freeboolean

If the product has a free version.

has_premiumboolean

If the product has a premium version.

release_modestring

The release mode of the product.

Possible values: [released, pending, beta]

limitinteger

The maximum number of downloads allowed for this version. This is used for staged rollout of WordPress products. Unlimited number is set as null.

Possible values: >= 1

Example: 50

uniquesinteger

The number of unique users that have downloaded the product.

Possible values: >= 1

Example: 1234

is_incrementalboolean

Determines whether the version is incremental or not.

Example: true

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