How to Validate Lemon Squeezy License Keys from Your App

October 30, 2026

You validate a Lemon Squeezy license key by calling two endpoints with the key and an instance ID: one activates the key for a device, the other re-checks it. Both hit api.lemonsqueezy.com/v1/licenses/, need no API key, and return a boolean plus your product metadata.

The trap is that the activate call has a hard instance limit — usually one per seat — and most implementations call it on every app launch. Users then hit “activation limit reached” on their own laptop.

How does the license API actually work?

Two endpoints, both form-encoded POST:

Endpoint Purpose When to call
/v1/licenses/activate Binds a key to an instance ID First run per device
/v1/licenses/validate Re-checks an existing binding Every 7-30 days
/v1/licenses/deactivate Frees the instance slot On uninstall or logout

activate returns a license_key object and an instance object containing instance_id. Store both. Every later check uses validate with that instance ID — it does not consume a new slot.

Products are configured in the dashboard under Products → your product → License keys, where you set the activation limit (default 1) and whether keys expire.

Why does the 3-device lockout happen?

Because the instance ID is generated locally and lost on reinstall. A user who wipes their app data gets a fresh UUID, which burns a second slot, then a third.

Fix it by deriving the instance ID from something stable — the machine ID on desktop, a hashed email on web. instance_name is free text, so put the actual device name there; your support team will thank you when someone asks for a slot reset.

If a key is already at its limit and the user insists it is their own machine, the correct path is the API deactivate call from your admin tool rather than guessing in the dashboard.

How do you keep it working offline?

Validation needs the network, and your paid desktop app probably needs to run on a plane.

Cache the last successful validation with an expiry — a signed local file with the timestamp and a 14-day grace period. Shorten it to 7 days for higher-value licenses. If the grace expires without a successful check, lock the paid features but keep the app usable in read-only mode.

Do not check on every request. A license check on each API call adds 80-200 ms and turns a Lemon Squeezy outage into your outage.

What does a minimal check look like?

POST https://api.lemonsqueezy.com/v1/licenses/validate
Content-Type: application/x-www-form-urlencoded

license_key=XXXX-XXXX&instance_id=abc-123

Response includes valid: true|false and license_key.status. Statuses are inactive, active, expired and disabled. Treat only active as pass. An expired subscription key should downgrade, not crash.

Rate limits: the unauthenticated license endpoints allow roughly 60 requests per minute per IP. Local caching keeps you far below that.

Where this design breaks down

  • Team seats. One key, five developers, one instance each. You need a seat count and a UI that lets an admin free a slot — the API does not do that automatically.
  • Trials. Trial keys behave like normal keys with an expiry date. Use license_key.expires_at rather than a separate trial flag.
  • Cracked binaries. Any client-side license check can be patched. If piracy matters, verify server-side on every sensitive operation, which for a desktop tool means at least a signed API call for sync.

The whole feature is about 150 lines of code. The bug report you will actually get is not about security — it is about the lockout.

Key Takeaways

  • Use /v1/licenses/activate once per device, then /v1/licenses/validate for re-checks — validate does not use a new slot.
  • Derive instance_id from a stable machine fingerprint, not a random UUID per install.
  • Cache successful validation for 7-14 days offline; never check on every API request.
  • Default activation limit is 1 per key; set seats in the product’s license key settings.
  • Only active status passes; expired and disabled should downgrade gracefully.