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
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:
A successful response will look like this:
In the response you can see details about the
instance and the order, product and customer in
activated value shows whether the license key has been successfully activated (
true) or not (
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
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
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
An example response will look like this:
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
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:
The response will include an
instance object and the
valid value will reflect the validity of the instance rather than the license key itself.
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.
The response will look like this:
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
Note: If your product is a subscription, license keys will be automatically disabled when a subscription becomes
expired. Read about subscription statuses.