Sign inGet started →
Help DocsAPI Guides

Licensing

License API

Lemon Squeezy offers a REST API to allow sellers to manage licenses generated by Lemon Squeezy. There are two possible flows for using license keys.

1. License keys without an activation limit

If your license keys don't have an activation limit, then you can simply pass the license key to the /validate endpoint to check that it is a valid key.

2. License keys with an activation limit

If your license keys do have an activation limit, the flow normally looks 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 alongside the license key in your application to validate or deactivate the license at a later date.
  2. Whenever your application needs to validate a license (e.g. to periodically check the license is still valid), 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 and needs to free up a space) 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-01-24T14:15:07.000000Z", "expires_at": null }, "instance": { "id": "47596ad9-a811-4ebf-ac8a-03fc7b6d2a17", "name": "Test", "created_at": "2021-04-06T14:15:07.000000Z" }, "meta": { "store_id": 1, "order_id": 2, "order_item_id": 3, "product_id": 4, "product_name": "Example Product", "variant_id": 5, "variant_name": "Default", "customer_id": 6, "customer_name": "Luke Skywalker", "customer_email": "[email protected]" } }

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-01-24T14:15:07.000000Z", "expires_at": null }, "meta": { "store_id": 1, "order_id": 2, "order_item_id": 3, "product_id": 4, "product_name": "Example Product", "variant_id": 5, "variant_name": "Default", "customer_id": 6, "customer_name": "Luke Skywalker", "customer_email": "[email protected]" } }

POST /v1/licenses/validate

Validate a license key or license key instance.

ParameterRequiredDescription
license_keyYesThe license key.
instance_idNoIf included, validate a license key instance, otherwise a license key. If no instance_id is provided, 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-01-24T14:15:07.000000Z", "expires_at": "2022-01-24T14:15:07.000000Z" }, "instance": { "id": "f90ec370-fd83-46a5-8bbd-44a241e78665", "name": "Test", "created_at": "2021-02-24T14:15:07.000000Z" }, "meta": { "store_id": 1, "order_id": 2, "order_item_id": 3, "product_id": 4, "product_name": "Example Product", "variant_id": 5, "variant_name": "Default", "customer_id": 6, "customer_name": "Luke Skywalker", "customer_email": "[email protected]" } }

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-01-24T14:15:07.000000Z", "expires_at": null }, "meta": { "store_id": 1, "order_id": 2, "order_item_id": 3, "product_id": 4, "product_name": "Example Product", "variant_id": 5, "variant_name": "Default", "customer_id": 6, "customer_name": "Luke Skywalker", "customer_email": "[email protected]" } }

License Key Statuses

A license key status can be one of:

  • inactive - The license key is valid but has no activations.
  • active - The license key has one or more activations.
  • expired - The license key's expiry date has passed, either because the related product had a defined license length or because the license's subscription has expired.
  • disabled - The license key has been manually disabled from the Lemon Squeezy dashboard.

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. Responses also include a meta object containing information related to the license key.

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. The meta object also contains convenience information from the license key order, including product and variant names, and the customer's name and email address.

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

  • 11 Jan 2024 - Changed the formatting for created_at, expires_at attributes to properly match LicenseKey and LicenseKeyInstance objects.
  • 2 Feb 2023 - Added product_name, variant_name, customer_id, customer_name, and customer_email to the meta object in responses
  • 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
Previous
Multiple stores
Next
Generating license keys