License 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.

ParameterRequiredDescription
license_keyYesThe license key.
instance_nameYesA 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"
    },
    "meta": {
        "store_id": 1,
        "order_id": 2,
        "order_item_id": 3,
        "product_id": 4
    }
}

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
    },
    "meta": {
        "store_id": 1,
        "order_id": 2,
        "order_item_id": 3,
        "product_id": 4
    }
}

POST /v1/licenses/validate

Validate a license key instance.

ParameterRequiredDescription
license_keyYesThe license key.
instance_idNoThe 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"
    },
    "meta": {
        "store_id": 1,
        "order_id": 2,
        "order_item_id": 3,
        "product_id": 4
    }
}

POST /v1/licenses/deactivate

Deactivate a license key instance.

ParameterRequiredDescription
license_keyYesThe license key.
instance_idYesThe 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
    },
    "meta": {
        "store_id": 1,
        "order_id": 2,
        "order_item_id": 3,
        "product_id": 4
    }
}

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.

Meta

All license_key objects include an id attribute which can be used to fetch the full license key information from the Lemon Squeezy API. ID fields in the meta object can be used to fetch data related to the license key, such as relevant order/product information, from the API.

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 CodeDescription
400An error occurred. See the error field for details.
404An item could not be found.
422A required field was invalid or missing.

Changelog

  • 13 Dec 2021 – Added “meta” object in responses
  • 21 Sep 2021 – Made the “instance_id” optional on the /validate endpoint
  • 23 Aug 2021 – Added “id” field to license key object