Licenses API

Lemon Squeezy offers a REST API to allow sellers to manage licenses generated by Lemon Squeezy. The flow for using license keys normally looks something like this:

  1. Your application sends a request to the /activate endpoint to activate a license. You'll receive an "instance" ID in the response. Save this in your application to validate or deactivate the license at a later date.
  2. Whenever your application needs to validate a license, send the license key and instance ID to the /validate endpoint. The response will contain a "valid" flag that you can use, along with the license key status, to display the status of the license to your users.
  3. If your application needs to deactivate a license (e.g. when a customer has reached their license activation limit) your application can send a request to the /deactivate endpoint to deactivate a license. Deactivating a license will remove the instance and reduce the "activation_usage" for the license.

Requests

  • Use the Base URL https://api.lemonsqueezy.com
  • All requests should be sent with the Accept: application/json header
  • POST requests should be sent with the Content-Type: application/x-www-form-urlencoded header
  • Responses are always in JSON format
  • API calls are rate limited to 60/minute

Endpoints

POST /v1/licenses/activate

Activate a license key and receive an instance ID in return.

Parameter Required Description
license_key Yes The license key.
instance_name Yes A label for the new instance to identify it in Lemon Squeezy.

Example request:

curl -X POST https://api.lemonsqueezy.com/v1/licenses/activate \
  -H "Accept: application/json" \
  -d "license_key=38b1460a-5104-4067-a91d-77b872934d51" \
  -d "instance_name=Test"

Example response:

{
    "activated": true,
    "error": null,
    "license_key": {
        "id": 1,
        "status": "active",
        "key": "38b1460a-5104-4067-a91d-77b872934d51",
        "activation_limit": 1,
        "activation_usage": 5,
        "created_at": "2021-03-25 11:10:18",
        "expires_at": null
    },
    "instance": {
        "id": "47596ad9-a811-4ebf-ac8a-03fc7b6d2a17",
        "name": "Test",
        "created_at": "2021-04-06 14:08:46"
    }
}

Example error response:

{
    "activated": false,
    "error": "This license key has reached the activation limit.",
    "license_key": {
        "id": 1,
        "status": "active",
        "key": "38b1460a-5104-4067-a91d-77b872934d51",
        "activation_limit": 5,
        "activation_usage": 5,
        "created_at": "2021-03-25 11:10:18",
        "expires_at": null
    }
}

POST /v1/licenses/validate

Validate a license key instance.

Parameter Required Description
license_key Yes The license key.
instance_id No The instance ID returned when activating a license key. If this is not included, the response will contain "instance": null.

Example request:

curl -X POST https://api.lemonsqueezy.com/v1/licenses/validate \
  -H "Accept: application/json" \
  -d "license_key=38b1460a-5104-4067-a91d-77b872934d51" \
  -d "instance_id=f90ec370-fd83-46a5-8bbd-44a241e78665"

Example response:

{
    "valid": true,
    "error": null,
    "license_key": {
        "id": 1,
        "status": "active",
        "key": "38b1460a-5104-4067-a91d-77b872934d51",
        "activation_limit": 1,
        "activation_usage": 5,
        "created_at": "2021-03-25 11:10:18",
        "expires_at": "2022-03-25 11:10:18"
    },
    "instance": {
        "id": "f90ec370-fd83-46a5-8bbd-44a241e78665",
        "name": "Test",
        "created_at": "2021-04-06 14:08:45"
    }
}

POST /v1/licenses/deactivate

Deactivate a license key instance.

Parameter Required Description
license_key Yes The license key.
instance_id Yes The instance ID returned when activating a license key.

Example request:

curl -X POST https://api.lemonsqueezy.com/v1/licenses/deactivate \
  -H "Accept: application/json" \
  -d "license_key=38b1460a-5104-4067-a91d-77b872934d51" \
  -d "instance_id=f90ec370-fd83-46a5-8bbd-44a241e78665"

Example response:

{
    "deactivated": true,
    "error": null,
    "license_key": {
        "id": 1,
        "status": "inactive",
        "key": "38b1460a-5104-4067-a91d-77b872934d51",
        "activation_limit": 5,
        "activation_usage": 0,
        "created_at": "2021-03-25 11:10:18",
        "expires_at": null
    }
}

License Key Statuses

A license key status can be one of:

  • inactive - The license key has no activations.
  • active - The license key has one or more activations.
  • expired - The license key is expired.
  • disabled - The license key has been disabled.

Errors

The API will return a 4XX status code in the response if an error has occurred and an error field in the response body containing an explanation of the error.

Error Code Description
400 An error occurred. See the error field for details.
404 An item could not be found.
422 A required field was invalid or missing.

FAQ

How do I get the order/product information relating to a license key?

All  license_key objects include an id attribute. This can be used to fetch the full license key information, including relevant order/product information, from the Lemon Squeezy API.

Still need help? Contact Us Contact Us