Plugin Licenses

List plugin licenses

To list plugin licenses created for your plugins, create an authenticated GET request to /v1/plugin-licenses.

Licenses will be paginated.

Parameters

The following optional query string parameters are supported:

Parameter	Description
includeTrials	Set to 1 to include trial licenses in the response.
pluginHandle	Plugin handle
search	Case-insensitive search of plugin handle, key, email, and notes
before	Filter licenses created before the given datetime (UTC)
after	Filter licenses created after the given datetime (UTC)
orderBy	Defaults to dateCreated
ascending	Set to 0 for descending

Definition

GET https://api.craftcms.com/v1/plugin-licenses

Example Request

Example Response Body

{
  "total": 3,
  "totalPages": 1,
  "licenses": [
    {
      "id": 649,
      "pluginId": 1237,
      "editionId": 1415,
      "ownerId": 1,
      "cmsLicenseId": null,
      "plugin": "commerce",
      "edition": "standard",
      "trial": false,
      "expirable": false,
      "expired": false,
      "autoRenew": false,
      "email": "brandon@craftcms.com",
      "org": null,
      "key": "P8GQRVQO5MK9Q673U0IJZ2I3",
      "notes": null,
      "lastVersion": null,
      "lastAllowedVersion": null,
      "lastActivityOn": null,
      "lastRenewedOn": null,
      "expiresOn": null,
      "dateCreated": "2038-01-19T03:14:07",
      "dateUpdated": "2038-01-19T03:14:07",
      "uid": "2a71e0a6-e47e-4da5-9699-c6c296367619"
    },
    {
      // ...
    },
    {
      // ...
    }
  ]
}

Get a plugin license

To retrieve a single plugin license created for one of your plugins, make an authenticated GET request to /v1/plugin-licenses/<license-key>.

TIP

If a plugin is owned by an organization, email will be null, and org will contain the organization's slug.

Definition

GET https://api.craftcms.com/v1/plugin-licenses/<license-key>

Example Request

Example Response Body

{
  "license": {
    "id": 649,
    "pluginId": 1237,
    "editionId": 1415,
    "ownerId": 1,
    "cmsLicenseId": null,
    "plugin": "commerce",
    "edition": "standard",
    "expirable": false,
    "expired": false,
    "autoRenew": false,
    "email": null,
    "org": "pixelandtonic",
    "key": "P8GQRVQO5MK9Q673U0IJZ2I3",
    "notes": null,
    "lastVersion": null,
    "lastAllowedVersion": null,
    "lastActivityOn": null,
    "lastRenewedOn": null,
    "expiresOn": null,
    "dateCreated": "2038-01-19T03:14:07",
    "dateUpdated": "2038-01-19T03:14:07",
    "uid": "2a71e0a6-e47e-4da5-9699-c6c296367619"
  }
}

Create a plugin license

To create a new plugin license, create an authenticated POST request to /v1/plugin-licenses.

The request must have a JSON body with the following keys:

Key	Type	Description
plugin (required)	string	Plugin handle
edition (required)	string	Plugin edition
email (required unless org is provided)	string	Licensee’s email address
org (required unless email is provided)	string	Licensee’s organization slug
expirable	boolean	Whether the license should be expirable (false by default)
expiresOn	string, null	Expiration date, if expirable (a year from now by default)
notes	string, null	Customer notes
privateNotes	string, null	Private notes, never shared with the customer

The API generates a license key, and returns it in the response under the key property.

Definition

POST https://api.craftcms.com/v1/plugin-licenses

Example Request

Example Response Body

{
  "license": {
    "id": 649,
    "pluginId": 1237,
    "editionId": 1415,
    "ownerId": 1,
    "cmsLicenseId": null,
    "plugin": "commerce",
    "edition": "standard",
    "expirable": false,
    "expired": false,
    "autoRenew": false,
    "email": null,
    "org": "pixleandtonic",
    "key": "P8GQRVQO5MK9Q673U0IJZ2I3",
    "notes": null,
    "lastVersion": null,
    "lastAllowedVersion": null,
    "lastActivityOn": null,
    "lastRenewedOn": null,
    "expiresOn": null,
    "dateCreated": null,
    "dateUpdated": null,
    "uid": null
  }
}

Save a plugin license

To save a plugin license created for one of your plugins, create an authenticated POST request to /v1/plugin-licenses/<license-key>.

The request must have a JSON body with the following keys:

Key	Type	Description
edition	string	Plugin edition
expirable	boolean	Whether the license should be expirable
expiresOn	string, null	Expiration date, if expirable (a year from now by default)
notes	string, null	Customer notes
privateNotes	string, null	Private notes, never shared with the customer

WARNING

You cannot change the owner of a license after it is created. Only the licensee is allowed to release it.

Definition

POST https://api.craftcms.com/v1/plugin-licenses/<license-key>

Example Request

Example Response Body

{
  "license": {
    "id": 649,
    "pluginId": 1237,
    "editionId": 1415,
    "ownerId": 1,
    "cmsLicenseId": null,
    "plugin": "commerce",
    "edition": "pro",
    "expirable": true,
    "expired": false,
    "autoRenew": false,
    "email": null,
    "org": "pixelandtonic",
    "key": "P8GQRVQO5MK9Q673U0IJZ2I3",
    "notes": null,
    "lastVersion": null,
    "lastAllowedVersion": null,
    "lastActivityOn": null,
    "lastRenewedOn": null,
    "expiresOn": "2038-01-19T03:14:07",
    "dateCreated": "2038-01-19T03:14:07",
    "dateUpdated": "2038-01-19T03:14:07",
    "uid": "2a71e0a6-e47e-4da5-9699-c6c296367619"
  }
}