How to activate and validate license keys with Lemon Squeezy: Lemon Squeezy

Dan Rowden · April 19, 2023

In this tutorial, we'll go through the full process of creating, verifying and removing license keys for your customers using Lemon Squeezy's API.

About license keys

License keys are a feature in Lemon Squeezy, which let you control access to your external application via orders and subscriptions.

Enabling license keys

You can turn on license keys at a product and variant level in Lemon Squeezy.

You have options for length of license and how many activations are allowed for each license.

If your product is a subscription, the "License length" field is not shown in the product form because the length of the license is instead tied to the subscription's lifecycle. When a subscription becomes expired, the related license key's status will automatically become expired.

Each time a customer purchases a product with license keys enabled, a license key will be generated and emailed to the customer in their receipt. The customer will also find the license key via the My Orders page.

Each license key can have one or many license key instances, which are created every time you activate the license key. You can deactivate each instance individually as well as disable the license key altogether.

Managing license keys

Once you have customers with license keys, you can easily manage them from Store > Licenses.

Here you can view all license keys and edit their activation limits and expiration dates. You can also disable and regenerate keys.

License key statuses

When accessing license keys with the API, you'll see a status value which you can use to determine if a customer should have access to your application.

status will be 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.

Activating a license key

After a customer has purchased your product, you will need to prompt the user to input their license key into your app so they can gain access.

You can create a simple form like this:

Once submitted, you will need to verify the active user somehow. We recommend checking against their email address. To do this you could add an email input into your form, asking the customer to input the email address they used at checkout, then check that when activating the key (see below).

When the user provdes their license key you should activate it using the Lemon Squeezy API:

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"

A successful response will look like this:

{ "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, "product_name": "Example Product", "variant_id": 5, "variant_name": "Default", "customer_id": 6, "customer_name": "Luke Skywalker", "customer_email": "[email protected]" } }

In the response you can see details about the license_key, instance and the order, product and customer in meta.

The activated value shows whether the license key has been successfully activated (true) or not (false).

A new license key instance is created for each successful activation request, each with a unique ID (an instance is a recorded "use" of a license key). Make sure you save the instance.id value into your app as you will need this to validate and deactivate license key instances.

Important: You should verify that the store_id, product_id and/or variant_id from this response match the IDs of your Lemon Squeezy product. If you don't do this, someone using a license key from another Lemon Squeezy product could use it to get access to your product. We recommend hard-coding the store_id, product_id and/or variant_id into your client and using them to validate that the key belongs to your product.

You can also verify that the customer inputting the license key in your app is the same customer who purchased it by checking against meta.customer_email in the response. If the email address matches, you can give access to the user.

If you limited activations when creating the product, you are able to check how many activations have occured from license_key.activation_usage. Lemon Squeezy will not allow new activations once the activation limit has been reached.

Checking the validity of a license key

Now that you have active license keys working in your app, you should periodically check if a license key is still valid.

You can do this with an API request to /v1/licenses/validate:

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

An example response will look like this:

{ "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": 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]" } }

The valid value will show if the license key is valid or not.

Similarly to above, you can verify that the key is being used for the right user by checking against meta.customer_email.

Validating a license key instance

You can also use the same endpoint to validate a specific license key instance. Just add an instance_id into the request like this:

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=47596ad9-a811-4ebf-ac8a-03fc7b6d2a17"

The response will include an instance object and the valid value will reflect the validity of the instance rather than the license key itself.

{ "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": "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, "product_name": "Example Product", "variant_id": 5, "variant_name": "Default", "customer_id": 6, "customer_name": "Luke Skywalker", "customer_email": "[email protected]" } }

Deactivating a license key instance

You can easily deactivate a specific license key instance using the following request. Deactivating a license will delete the instance and reduce the activation_usage for the license key.

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"

The response will look like this:

{ "deactivated": true, "error": null, "license_key": { "id": 1, "status": "active", "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, "product_name": "Example Product", "variant_id": 5, "variant_name": "Default", "customer_id": 6, "customer_name": "Luke Skywalker", "customer_email": "[email protected]" } }

Note that there is no instance object in the response because it has been deleted.

Also worth noting is that the underlying license key may still be active, as this endpoint deactivates license key instances rather than the key itself (read on to find out how to disable license keys).

Disabling a license key

If you want to disable a license key (i.e. fully stop a customer from having access to your product), you can do this from your Lemon Squeezy dashboard. It's not currently possible to disable license keys using the API.

Go to Store > Licenses and click on the ... menu icon on the license you want to disable. Click on the Disable key option and confirm.

When your app next validates the license key or a related license key instance, the license key status will be disabled.

Note: If your product is a subscription, license keys will be automatically disabled when a subscription becomes expired. Read about subscription statuses.

Access license keys with the API

If you want to access individual or lists of license key and license key instance data, you can use the License key and License key instance endpoints.