Everyone who holds a software product holds one license key for it, issued with their access and valid exactly as long as it is. Your software checks that key through your own server, which calls the API. This guide sets up the check, reads its answer, and limits how many devices a key runs on. It uses the sherpo helper from your first call and a token with customer:read, plus customer:write to activate devices.
Where the check runs
Your app never calls Sherpo itself. It sends the key the customer typed to your server, and your server calls POST /products/{product}/licenses/verify with its token and answers the app with what it needs:
- The customer pastes their key into your app.
- Your app sends it to your server, over your own API.
- Your server calls
verifyLicensewith its token and tells the app what to unlock.
An app that called Gumroad’s check itself moves that call to your server: see Switch the license check.
Never ship a token in your app or on a customer’s device: anyone who extracts it can read your customers and act on your store with every scope it holds. Keep it on your server, give it only the scopes the check needs, and let your server decide what the app may do.
Say what each tier unlocks
A software product’s tiers can list the features they unlock. POST /products/{product}/tiers and PATCH /products/{product}/tiers/{tier} take them in settings.software.features, each a flag your software reads (letters and digits, with single hyphens, underscores, dots or colons between them). Setting them takes a token with product:write, which your server’s checks don’t need:
curl -X POST 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/products/3e9d1f6b-72a4-4c58-b0e3-9a6f2d84c1b7/tiers' \
-H "Authorization: Bearer $SHERPO_TOKEN" \
-H 'Idempotency-Key: tier-app-pro' \
-H 'Content-Type: application/json' \
-d '{
"name": "Pro",
"settings": {
"software": {
"features": [
"export",
"sync"
],
"activation_limit": 3
}
}
}'const answer = await sherpo('POST', '/v1/stores/STORE_ID/products/3e9d1f6b-72a4-4c58-b0e3-9a6f2d84c1b7/tiers', {
body: {
"name": "Pro",
"settings": {
"software": {
"features": [
"export",
"sync"
],
"activation_limit": 3
}
}
},
key: 'tier-app-pro',
});Answers 201, abridged:
{
"id": "e1d2c3b4-a596-4877-8695-a4b3c2d1e0f9",
"product_id": "3e9d1f6b-72a4-4c58-b0e3-9a6f2d84c1b7",
"rank": 2,
"name": "Pro",
"settings": {
"software": {
"features": [
"export",
"sync"
],
"activation_limit": 3
}
}
}settings.software.activation_limit sets how many devices the tier’s licenses activate at once (see Limit devices).
A check answers the features of the tier the customer’s access opens together with every tier ranked below it, as a higher tier includes everything the lower ones unlock. Moving a customer to another tier, reordering tiers or changing a tier’s features changes what your software unlocks at the next check.
Check a key
curl -X POST 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/products/3e9d1f6b-72a4-4c58-b0e3-9a6f2d84c1b7/licenses/verify' \
-H "Authorization: Bearer $SHERPO_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"key": "APP-7Q2KD-M4XHT-9BNWC-R6PZF-3JVGS",
"count_use": true,
"instance": "b7e1c0d4-5a2f-4e98-9c3b-6d1f0a8e2c47"
}'const answer = await sherpo('POST', '/v1/stores/STORE_ID/products/3e9d1f6b-72a4-4c58-b0e3-9a6f2d84c1b7/licenses/verify', {
body: {
"key": "APP-7Q2KD-M4XHT-9BNWC-R6PZF-3JVGS",
"count_use": true,
"instance": "b7e1c0d4-5a2f-4e98-9c3b-6d1f0a8e2c47"
},
});Answers 200, abridged:
{
"id": "8c7b6a59-4837-4261-9f0e-1d2c3b4a5968",
"status": "active",
"reason": null,
"expires_at": "2026-12-02T09:14:00.000Z",
"tier": {
"id": "e1d2c3b4-a596-4877-8695-a4b3c2d1e0f9",
"name": "Pro",
"rank": 2
},
"features": [
"export",
"sync"
],
"uses": 14,
"activations": {
"count": 2,
"limit": 3
},
"activation": {
"id": "6b5a4938-2716-4f05-8e4d-3c2b1a0f9e8d",
"license_id": "8c7b6a59-4837-4261-9f0e-1d2c3b4a5968",
"name": "Studio Mac",
"status": "active",
"created_at": "2026-09-02T09:20:00.000Z",
"activated_at": "2026-09-02T09:20:00.000Z",
"last_seen_at": "2026-11-02T08:05:00.000Z",
"deactivated_at": null,
"deactivated_by": null
},
"customer": {
"id": "7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918"
},
"subscription": {
"id": "2a3b4c5d-6e7f-4809-9a1b-2c3d4e5f6071",
"status": "active",
"current_period_end": "2026-12-02T09:14:00.000Z",
"cancel_at_period_end": false,
"ended_at": null
},
"latest_release": {
"id": "0e9d8c7b-6a5f-4e3d-9c2b-1a0f9e8d7c6b",
"version": "2.4.0",
"occurred_at": "2026-10-28T16:30:00.000Z"
}
}keyis the key as the customer typed it: case, hyphens, spaces, and look-alike characters (Ofor0,IorLfor1) don’t matter. A key you imported from another platform matches the same way when it’s hex, like Gumroad’s, and exactly as you recorded it otherwise, past spaces around it.instanceis optional: the id your software activated the device with. The answer’sactivationis that device (nullwhen the license holds none for it), and a check of a device that counts stamps itslast_seen_at.count_usecounts the check as a use of your software, inuses, while the license is active. It defaults tofalse, so checking a key when the app starts, and again later, never inflates the count. Passtruewhere a check is a use you want counted, such as a first launch on a device.
A key that no license holds, or a key of another product, answers 404 not_found with the kind license, alike, so a check never tells a typo from another product’s key. The answer never repeats the key. A key with no letter from A to Z or digit answers 422 invalid instead.
Read the answer
status says whether to unlock your software:
status |
What it means | reason |
|---|---|---|
active |
The customer’s access holds: unlock it. | null |
expired |
Their access lapsed, as a subscription that ended, or hasn’t begun yet. | lapse, or null before any access began |
revoked |
Their access was taken back: refunded, lost to a dispute, or revoked. | refund or revoke |
disabled |
You disabled the license. | disabled |
replaced |
The key was replaced by a new one. | replaced |
expires_atis when all of the customer’s access ends, whatever its tier,nullwhile it never does. Past access, it’s when it ended.tieris the tier the customer’s access opens (past access, the one it opened last), with itsrank, andnullfor access with no tier. Holding one tier through a subscription and through another grant, it’s the subscription’s.featuresare that tier’s and every lower tier’s, each once, lowest tier first, while the license isactive, and empty otherwise, so unlocking by a feature never unlocks a key whose access ended.subscriptionis the subscription behind the access, withcurrent_period_end(when its latest paid period ends),cancel_at_period_endandended_at, ornullfor a one-time purchase or access you granted. Use it to warn a customer before their access ends.activationsare the devices the license counts now (count) and the most it may hold (limit,nullwhen nothing limits it).latest_releaseis the product’s newest release from its activity whose files have all finished uploading, with itsid,versionandoccurred_at, ornulluntil a release’s files are all in. A release with a file that failed to upload stays back, the release before it answered meanwhile, until that file is replaced or taken out of the release. It is the same whatever tier the customer holds, so a release limited to a higher tier still shows as out. Compareversionwith the one your software runs to tell the customer an update is out.customernames the holder, andidthe license, as thelicense.issuedwebhook names it. Events never carry the key.
A license follows the customer’s remaining access, with nothing to call when it changes: a revoke or a lapse ends the access it gave, and a full refund or a lost dispute does too while the store’s refund_revokes_access setting is on, unless another grant still opens the product. The next check answers what changed.
Limit devices
A license can run on a limited number of devices or seats at once. The limit is, first, the license’s own (activation_limit, which you set on the license), else the tier’s settings.software.activation_limit, else the product’s settings.software.activation_limit, else none. A tier can’t lift a product’s limit to unlimited: leave the product’s unset and set one on each tier that has one. A license nothing limits still holds at most 10,000 devices at once.
When your software starts on a device, it sends the key and a stable id of the device to your server, which calls POST /products/{product}/licenses/activate:
curl -X POST 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/products/3e9d1f6b-72a4-4c58-b0e3-9a6f2d84c1b7/licenses/activate' \
-H "Authorization: Bearer $SHERPO_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"key": "APP-7Q2KD-M4XHT-9BNWC-R6PZF-3JVGS",
"instance": "b7e1c0d4-5a2f-4e98-9c3b-6d1f0a8e2c47",
"name": "Studio Mac"
}'const answer = await sherpo('POST', '/v1/stores/STORE_ID/products/3e9d1f6b-72a4-4c58-b0e3-9a6f2d84c1b7/licenses/activate', {
body: {
"key": "APP-7Q2KD-M4XHT-9BNWC-R6PZF-3JVGS",
"instance": "b7e1c0d4-5a2f-4e98-9c3b-6d1f0a8e2c47",
"name": "Studio Mac"
},
});Answers 200, abridged:
{
"activation": {
"id": "6b5a4938-2716-4f05-8e4d-3c2b1a0f9e8d",
"license_id": "8c7b6a59-4837-4261-9f0e-1d2c3b4a5968",
"name": "Studio Mac",
"status": "active",
"created_at": "2026-09-02T09:20:00.000Z",
"activated_at": "2026-09-02T09:20:00.000Z",
"last_seen_at": "2026-09-02T09:20:00.000Z",
"deactivated_at": null,
"deactivated_by": null
},
"activations": {
"count": 2,
"limit": 3
},
"token": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCIsImtpZCI6IjBjMWIyYTM5LTQ4NTctNGY2ZS05ZDhjLTdiNmE1ZjRlM2QyYyJ9.eyJzdG9yZSI6IjVkNGMzYjJhLTE5MDgtNGY3ZS04ZDZjLTViNGEzOTI4MTcwNiIsInByb2R1Y3QiOiIzZTlkMWY2Yi03MmE0LTRjNTgtYjBlMy05YTZmMmQ4NGMxYjciLCJsaWNlbnNlIjoiOGM3YjZhNTktNDgzNy00MjYxLTlmMGUtMWQyYzNiNGE1OTY4IiwiYWN0aXZhdGlvbiI6IjZiNWE0OTM4LTI3MTYtNGYwNS04ZTRkLTNjMmIxYTBmOWU4ZCIsInRpZXJfcmFuayI6MiwiZmVhdHVyZXMiOlsic3luYyIsImV4cG9ydCJdLCJpYXQiOjE3ODgzNDA4MDAsImV4cCI6MTc5MDkzMjgwMH0.lTzRaa-n_zLU3KaU5wiBzNNOaBLXhoxTSrWrB5rlU3X-sE217UZYZiHAi5y9pQqo1syzW9FvTApZfNMlWvpHDA",
"token_expires_at": "2026-10-02T09:20:00.000Z"
}instanceis any stable id your software picks for the device or seat, up to 256 characters. Sherpo keeps only a digest of it, keyed by the license’s key, so the id itself is never stored and never answered.nameis optional: what the customer and you see the device as, such as its name. It’s cleaned to one line of up to 120 characters.
Activating a device the license already counts refreshes it (its last_seen_at, and its name when given) and doesn’t count it again, so your software can activate on every start. Every activation also answers a signed token your software can check with no network, until token_expires_at: see Verify licenses offline. Past the limit, a new device answers 409 conflict on items, its current the devices counted, and a license.limit_reached webhook tells you, at most once every 1 hour per license. A license that isn’t active answers 409 conflict on status, its current the license’s status. Lowering a limit keeps the devices already counted; new ones are refused until the count is under it.
When the software is uninstalled or signs out, your server frees the device with POST /products/{product}/licenses/deactivate, whatever the license’s status:
curl -X POST 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/products/3e9d1f6b-72a4-4c58-b0e3-9a6f2d84c1b7/licenses/deactivate' \
-H "Authorization: Bearer $SHERPO_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"key": "APP-7Q2KD-M4XHT-9BNWC-R6PZF-3JVGS",
"instance": "b7e1c0d4-5a2f-4e98-9c3b-6d1f0a8e2c47"
}'const answer = await sherpo('POST', '/v1/stores/STORE_ID/products/3e9d1f6b-72a4-4c58-b0e3-9a6f2d84c1b7/licenses/deactivate', {
body: {
"key": "APP-7Q2KD-M4XHT-9BNWC-R6PZF-3JVGS",
"instance": "b7e1c0d4-5a2f-4e98-9c3b-6d1f0a8e2c47"
},
});Answers 200, abridged:
{
"activation": {
"id": "6b5a4938-2716-4f05-8e4d-3c2b1a0f9e8d",
"license_id": "8c7b6a59-4837-4261-9f0e-1d2c3b4a5968",
"name": "Studio Mac",
"status": "deactivated",
"created_at": "2026-09-02T09:20:00.000Z",
"activated_at": "2026-09-02T09:20:00.000Z",
"last_seen_at": "2026-11-02T08:05:00.000Z",
"deactivated_at": "2026-11-03T17:41:00.000Z",
"deactivated_by": "software"
},
"activations": {
"count": 1,
"limit": 3
}
}A device the license never activated, or one already freed, answers 404 not_found with the kind activation; an inactive device can still be freed. A freed device that activates again comes back as the same activation. Customers can free a device from their account too, and you can list and free a license’s devices yourself.
A device’s status is active while it counts, deactivated once freed (deactivated_by says by whom: customer, merchant or software), and inactive when the product’s settings.software.inactive_days is set and the device went unseen longer than that. An inactive device stops counting without being freed, and counts again once it activates. A device is seen when it activates, or when a check names it in instance while the license is active and the device still counts, so with inactive_days set, have your software do one of those regularly.
When you limit devices, unlock your software only while the license is active and its device is too: check with instance, and when activation is null, inactive or deactivated, activate the device again before unlocking. Otherwise a freed device keeps working while another takes its place.
license.activated and license.deactivated webhooks tell you of each device counted and freed. Replacing a key frees the old key’s devices without license.deactivated events: license.replaced tells it. Like every license event, they never carry the key or the device’s id.
Limits
A check is a call like any other: it counts against your token’s rate and quota. Keep the answer on your server for a while (an hour, or until expires_at when it’s sooner) rather than checking on every request your app makes. A check still answers while your business is suspended, so your customers’ software keeps working.
A check, an activation, a token refresh and a deactivation take no idempotency key, and one sent is refused: each answers the license as it stands, never a recorded answer. Activating, refreshing a token and deactivating still answer while your business is suspended, as checks do.