---
title: "Verify licenses"
description: "Check a customer's license key from your own server, unlock your software by its status and features, and limit the devices it runs on."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.sherpo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Verify licenses

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](/merchant-api/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 <a href="/merchant-api/reference/verify-license/">`POST /products/{product}/licenses/verify`</a> with its token and answers the app with what it needs:

1. The customer pastes their key into your app.
2. Your app sends it to your server, over your own API.
3. Your server calls `verifyLicense` with 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](/merchant-api/guides/migrate-from-gumroad#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. <a href="/merchant-api/reference/create-tier/">`POST /products/{product}/tiers`</a> and <a href="/merchant-api/reference/update-tier/">`PATCH /products/{product}/tiers/{tier}`</a> 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:

```bash
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
    }
  }
}'
```

```js
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:

```json
{
  "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](#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

```bash
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"
}'
```

```js
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:

```json
{
  "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"
  }
}
```

- **`key`** is the key as the customer typed it: case, hyphens, spaces, and look-alike characters (`O` for `0`, `I` or `L` for `1`) don't matter. A key you [imported](/merchant-api/guides/manage-licenses#import-existing-keys) 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.
- **`instance`** is optional: the id your software activated the device with. The answer's `activation` is that device (`null` when the license holds none for it), and a check of a device that counts stamps its `last_seen_at`.
- **`count_use`** counts the check as a use of your software, in `uses`, while the license is active. It defaults to `false`, so checking a key when the app starts, and again later, never inflates the count. Pass `true` where 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`](/merchant-api/errors#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`](/merchant-api/errors#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_at`** is when all of the customer's access ends, whatever its tier, `null` while it never does. Past access, it's when it ended.
- **`tier`** is the tier the customer's access opens (past access, the one it opened last), with its `rank`, and `null` for access with no tier. Holding one tier through a subscription and through another grant, it's the subscription's. **`features`** are that tier's and every lower tier's, each once, lowest tier first, while the license is `active`, and empty otherwise, so unlocking by a feature never unlocks a key whose access ended.
- **`subscription`** is the subscription behind the access, with `current_period_end` (when its latest paid period ends), `cancel_at_period_end` and `ended_at`, or `null` for a one-time purchase or access you granted. Use it to warn a customer before their access ends.
- **`activations`** are the devices the license counts now (`count`) and the most it may hold (`limit`, `null` when nothing limits it).
- **`latest_release`** is the product's newest release from its [activity](/merchant-app/content#software-activity) whose files have all finished uploading, with its `id`, `version` and `occurred_at`, or `null` until 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. Compare `version` with the one your software runs to tell the customer an update is out.
- **`customer`** names the holder, and `id` the license, as the `license.issued` [webhook](/merchant-api/webhooks) 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 <a href="/merchant-api/reference/activate-license/">`POST /products/{product}/licenses/activate`</a>:

```bash
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"
}'
```

```js
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:

```json
{
  "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"
}
```

- **`instance`** is 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.
- **`name`** is 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](/merchant-api/guides/verify-licenses-offline). Past the limit, a new device answers `409` [`conflict`](/merchant-api/errors#conflict) on `items`, its `current` the devices counted, and a `license.limit_reached` [webhook](/merchant-api/webhooks) 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 <a href="/merchant-api/reference/deactivate-license/">`POST /products/{product}/licenses/deactivate`</a>, whatever the license's status:

```bash
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"
}'
```

```js
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:

```json
{
  "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`](/merchant-api/errors#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](/merchant-api/rate-limits). 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](/merchant-api/idempotency), 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.

Source: https://docs.sherpo.io/merchant-api/guides/verify-licenses/index.mdx
