Every customer who holds a software product holds one license for it: a key they enter in your app, which your software checks before it unlocks. The key is issued with their first purchase, subscription or grant, or imported from another platform, and it stays the same across renewals and plan changes. This page covers what a license holds and how its status follows the customer’s access. To build the check, see Verify licenses; to move keys from Gumroad, see Migrate from Gumroad.
Status
A license’s status follows the customer’s access to the product, unless you disabled it or its key was replaced. So a full refund, a lost dispute, a revoke or a subscription that lapses ends it with nothing for you to call, once no other grant of theirs still opens the product. A full refund or a lost dispute ends access while the store’s Remove access to what a refunded order unlocked setting is on (Settings).
| Status | What it means |
|---|---|
active |
The customer’s access holds. Unlock your software. |
expired |
Their access lapsed, as a subscription that ended or a grant that ran out, or hasn’t begun yet. |
revoked |
Their access was taken back: refunded, lost to a dispute, or revoked. |
disabled |
You turned the license off, whatever their access. |
replaced |
The key was replaced by a new one, and stopped working at once. |
When the customer holds the product again, through a new purchase, a subscription or a grant, an expired or revoked license is active again with the same key. A disabled one stays off until you enable it, and a replaced one never comes back: its new key does.
Expiry
A license expires when the customer’s access does. Access through a one-time purchase never ends, so its license has no expiry; a subscription’s lasts while it renews, and a grant’s until the end you gave it. A check answers expires_at, when all of the customer’s access ends, and the subscription behind it, so your software can warn a customer before a renewal fails.
Tiers and features
A software product’s tiers can list the features they unlock, each a flag your software reads. A check answers the features of the tier the customer’s access opens, while the license is active, so moving a customer to another tier changes what your software unlocks at its next check.
Activations
A license can be limited to a number of devices or seats at once. The limit is the license’s own, else its tier’s, else the product’s, else none. Your software activates each device it runs on, and frees it when it’s uninstalled; past the limit, a new device is refused until one is freed. A product can also stop counting devices that go unseen for a number of days, so a lost computer frees its place on its own.
Customers see the devices their license activates in their library and on the product’s page, and free one to make room for another. You can list and free them too.
Keys
A key is made of letters and digits in groups, starting with the product’s key prefix when it has one. Typed in any case, with or without its hyphens, and with look-alike characters such as O for 0, it still checks. A key imported from another platform keeps its own form: a hex key, like Gumroad’s, checks in any case and spacing, and any other exactly as you recorded it.
When a key leaks, the customer gets a new one from their library, or you rotate it. The old key stops working at once, its devices are freed, and the old license stays readable as replaced.
Who checks a key
Your software never checks a key with Sherpo directly. It sends the key to your own server, which checks it through the merchant API with an API token holding customer:read (and customer:write to activate devices), and tells the app what to unlock. A token in an app or on a customer’s device could be extracted and used on your store, so it stays on your server. Every plan includes the merchant API.
Customers see their keys and devices on your store, and your own front end shows them through the customer API. Webhooks tell your server when a license is issued, disabled, enabled or replaced, and when a device is activated or freed. They name the license and never carry its key.