Skip to content

Manage licenses

Import the keys your customers hold from another platform, find a software product's licenses, read a key, give uses back, disable a leaked key and rotate it.

Updated

Every customer who holds a software product holds one license for it, issued with their first access or imported from another platform. A license’s status follows their access: it’s active while they hold the product, expired once a subscription lapses and revoked after a refund or a revoke, with no license call of yours. This guide finds, reads and changes licenses. It uses the sherpo helper from your first call and a token with customer:read and customer:write.

Find licenses

GET /products/{product}/licenses lists a product’s licenses, newest first:

curl -g 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/products/3e9d1f6b-72a4-4c58-b0e3-9a6f2d84c1b7/licenses?filter[status]=active&search=3JVGS' \
  -H "Authorization: Bearer $SHERPO_TOKEN"
const answer = await sherpo('GET', '/v1/stores/STORE_ID/products/3e9d1f6b-72a4-4c58-b0e3-9a6f2d84c1b7/licenses', {
  query: [
    ['filter[status]', 'active'],
    ['search', '3JVGS'],
  ],
});

Answers 200, abridged:

{
  "items": [
    {
      "id": "8c7b6a59-4837-4261-9f0e-1d2c3b4a5968",
      "product_id": "3e9d1f6b-72a4-4c58-b0e3-9a6f2d84c1b7",
      "customer_id": "7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918",
      "key_ending": "3JVGS",
      "status": "active",
      "expires_at": "2026-12-02T09:14:00.000Z",
      "has_access": true,
      "uses": 14,
      "activation_limit": null,
      "tier": {
        "id": "e1d2c3b4-a596-4877-8695-a4b3c2d1e0f9",
        "name": "Pro",
        "rank": 2
      },
      "customer": {
        "id": "7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918",
        "name": "Ada Lovelace",
        "email": "ada@example.com",
        "phone": null,
        "erased": false
      }
    }
  ],
  "cursor": null
}
  • Keys are shortened in the list to their last characters, key_ending, so a support reply can name one without the list carrying every key.
  • search matches part of a key, typed with or without its hyphens, in any case, or the holder’s name, email or phone.
  • Filters take customer_id, status, source (issued, or imported from another platform) and tier_id, the tier the customer’s access opens, else the one it last opened.
  • Sorts are created (the default), last_verified and uses, and facets=status counts the licenses in each status.

Read a license

GET /products/{product}/licenses/{license} answers one license with its whole key:

curl 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/products/3e9d1f6b-72a4-4c58-b0e3-9a6f2d84c1b7/licenses/8c7b6a59-4837-4261-9f0e-1d2c3b4a5968' \
  -H "Authorization: Bearer $SHERPO_TOKEN"
const answer = await sherpo('GET', '/v1/stores/STORE_ID/products/3e9d1f6b-72a4-4c58-b0e3-9a6f2d84c1b7/licenses/8c7b6a59-4837-4261-9f0e-1d2c3b4a5968');

Answers 200, abridged:

{
  "id": "8c7b6a59-4837-4261-9f0e-1d2c3b4a5968",
  "key": "APP-7Q2KD-M4XHT-9BNWC-R6PZF-3JVGS",
  "status": "active",
  "reason": null,
  "expires_at": "2026-12-02T09:14:00.000Z",
  "has_access": true,
  "uses": 14,
  "disabled_at": null,
  "replaced_by": null
}

status is one of active, expired, revoked, disabled (you turned it off) or replaced (its key was rotated). reason says why a license isn’t active: replaced, disabled, or how the customer’s access ended, lapse, refund or revoke, as a license check answers it. tier is the tier their access opens, else the one it last opened. expires_at is when access ends or ended, null while it never does, and null too for a customer who never held access. has_access says whether the customer holds the product right now (false before their access begins), which a disabled or replaced status leaves open: a key you disabled may belong to a customer who still has access, or to one who never had any. activations are the devices the license counts now (count) and the most it may hold (limit): its own activation_limit, else its tier’s, else its product’s, null when nothing limits it. With subscription:read too, subscription names the subscription behind that access, with its status and current_period_end, or null for a one-time purchase or a grant.

Change uses, limits and metadata

PATCH /products/{product}/licenses/{license} sets uses as a whole number, so lowering it gives uses back; activation_limit, where null holds its tier’s, else the product’s; and metadata, which it replaces whole:

curl -X PATCH 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/products/3e9d1f6b-72a4-4c58-b0e3-9a6f2d84c1b7/licenses/8c7b6a59-4837-4261-9f0e-1d2c3b4a5968' \
  -H "Authorization: Bearer $SHERPO_TOKEN" \
  -H 'Idempotency-Key: reset-uses-8c7b6a59-4837-4261-9f0e-1d2c3b4a5968' \
  -H 'Content-Type: application/json' \
  -d '{
  "uses": 0,
  "activation_limit": 5
}'
const answer = await sherpo('PATCH', '/v1/stores/STORE_ID/products/3e9d1f6b-72a4-4c58-b0e3-9a6f2d84c1b7/licenses/8c7b6a59-4837-4261-9f0e-1d2c3b4a5968', {
  body: {
    "uses": 0,
    "activation_limit": 5
  },
  key: 'reset-uses-8c7b6a59-4837-4261-9f0e-1d2c3b4a5968',
});

Answers 200, abridged:

{
  "id": "8c7b6a59-4837-4261-9f0e-1d2c3b4a5968",
  "uses": 0,
  "activation_limit": 5
}

Disable and enable

POST /products/{product}/licenses/{license}/disable stops a license from checking as valid, whatever the customer’s access, with an optional reason. POST /products/{product}/licenses/{license}/enable lets it check as their access says again:

curl -X POST 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/products/3e9d1f6b-72a4-4c58-b0e3-9a6f2d84c1b7/licenses/8c7b6a59-4837-4261-9f0e-1d2c3b4a5968/enable' \
  -H "Authorization: Bearer $SHERPO_TOKEN" \
  -H 'Idempotency-Key: enable-8c7b6a59-4837-4261-9f0e-1d2c3b4a5968'
const answer = await sherpo('POST', '/v1/stores/STORE_ID/products/3e9d1f6b-72a4-4c58-b0e3-9a6f2d84c1b7/licenses/8c7b6a59-4837-4261-9f0e-1d2c3b4a5968/enable', {
  key: 'enable-8c7b6a59-4837-4261-9f0e-1d2c3b4a5968',
});

Answers 200, abridged:

{
  "id": "8c7b6a59-4837-4261-9f0e-1d2c3b4a5968",
  "status": "active",
  "disabled_at": null
}

Disabling one already disabled answers 409 conflict on status, and so does enabling one that isn’t disabled, naming the status it reads as. Both run in bulk, many licenses in one call, each item refused alone:

curl -X POST 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/bulk' \
  -H "Authorization: Bearer $SHERPO_TOKEN" \
  -H 'Idempotency-Key: disable-leaked-keys' \
  -H 'Content-Type: application/json' \
  -d '{
  "accessor": "disableLicense",
  "items": [
    {
      "product": {
        "id": "3e9d1f6b-72a4-4c58-b0e3-9a6f2d84c1b7"
      },
      "license": {
        "id": "8c7b6a59-4837-4261-9f0e-1d2c3b4a5968"
      },
      "reason": "Key posted publicly"
    },
    {
      "product": {
        "id": "3e9d1f6b-72a4-4c58-b0e3-9a6f2d84c1b7"
      },
      "license": {
        "id": "f6e5d4c3-b2a1-4098-8e7f-6a5b4c3d2e1f"
      },
      "reason": "Key posted publicly"
    }
  ]
}'
const answer = await sherpo('POST', '/v1/stores/STORE_ID/bulk', {
  body: {
    "accessor": "disableLicense",
    "items": [
      {
        "product": {
          "id": "3e9d1f6b-72a4-4c58-b0e3-9a6f2d84c1b7"
        },
        "license": {
          "id": "8c7b6a59-4837-4261-9f0e-1d2c3b4a5968"
        },
        "reason": "Key posted publicly"
      },
      {
        "product": {
          "id": "3e9d1f6b-72a4-4c58-b0e3-9a6f2d84c1b7"
        },
        "license": {
          "id": "f6e5d4c3-b2a1-4098-8e7f-6a5b4c3d2e1f"
        },
        "reason": "Key posted publicly"
      }
    ]
  },
  key: 'disable-leaked-keys',
});

Answers 200, abridged:

{
  "results": [
    {
      "outcome": "done"
    },
    {
      "outcome": "refused",
      "error": {
        "code": "conflict",
        "detail": {
          "field": "status",
          "current": "disabled"
        }
      }
    }
  ]
}

Rotate a key

POST /products/{product}/licenses/{license}/rotate gives the customer a fresh key. A new license takes the old one’s place, with its limit, uses, metadata and disabled state, and the old key stops checking at once:

curl -X POST 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/products/3e9d1f6b-72a4-4c58-b0e3-9a6f2d84c1b7/licenses/8c7b6a59-4837-4261-9f0e-1d2c3b4a5968/rotate' \
  -H "Authorization: Bearer $SHERPO_TOKEN" \
  -H 'Idempotency-Key: rotate-8c7b6a59-4837-4261-9f0e-1d2c3b4a5968'
const answer = await sherpo('POST', '/v1/stores/STORE_ID/products/3e9d1f6b-72a4-4c58-b0e3-9a6f2d84c1b7/licenses/8c7b6a59-4837-4261-9f0e-1d2c3b4a5968/rotate', {
  key: 'rotate-8c7b6a59-4837-4261-9f0e-1d2c3b4a5968',
});

Answers 200, abridged:

{
  "id": "f6e5d4c3-b2a1-4098-8e7f-6a5b4c3d2e1f",
  "key": "APP-4TB8R-M2KQX-9WHC7-VJ3PN-D6Y5S",
  "status": "active",
  "replaced_by": null
}

Sherpo emails the new key to the customer a couple of minutes after your rotation, at an address they proved, telling them the store replaced their key. A burst of rotations sends one email with the last key, and a license gets at most 5 key emails in any 24 hours, the customer’s own rotations included: past that, rotations still work and send nothing. A disabled license is emailed its new key once you enable it, and an invite once they sign in. The customer also sees the new key in their library, on the product’s page and on the order that sold them the product, and their own front end can read it through the customer API’s license reads. The old key’s devices are freed with it (deactivated_by reads merchant), so the new key starts with none and each device activates again. The old license stays readable as replaced, its replaced_by naming the new one, and every change to it answers 409 conflict on status.

Devices

A license counts the devices your software activates on it (Limit devices). GET /products/{product}/licenses/{license}/activations pages them, latest activated first, freed and inactive ones too, filtered on status (active, inactive or deactivated). POST /products/{product}/licenses/{license}/activations/{activation}/deactivate frees one, whatever the license’s status, so a customer who lost a computer can activate a new one; a device already freed answers 404 not_found with the kind activation. A device’s own id is never answered.

Import existing keys

Moving from Gumroad or another platform, record the keys your customers already hold, so the software they run keeps checking. Migrate from Gumroad walks the whole move, products, members and the app’s check included. POST /products/{product}/licenses stores a key as you send it, with source: imported:

curl -X POST 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/products/3e9d1f6b-72a4-4c58-b0e3-9a6f2d84c1b7/licenses' \
  -H "Authorization: Bearer $SHERPO_TOKEN" \
  -H 'Idempotency-Key: gumroad-import-B4C5D6E7' \
  -H 'Content-Type: application/json' \
  -d '{
  "customer": {
    "email": "ada@example.com"
  },
  "key": "B4C5D6E7-12345678-9ABCDEF0-0F0F0F0F",
  "uses": 14,
  "metadata": {
    "gumroad_sale_id": "A1b2C3d4=="
  }
}'
const answer = await sherpo('POST', '/v1/stores/STORE_ID/products/3e9d1f6b-72a4-4c58-b0e3-9a6f2d84c1b7/licenses', {
  body: {
    "customer": {
      "email": "ada@example.com"
    },
    "key": "B4C5D6E7-12345678-9ABCDEF0-0F0F0F0F",
    "uses": 14,
    "metadata": {
      "gumroad_sale_id": "A1b2C3d4=="
    }
  },
  key: 'gumroad-import-B4C5D6E7',
});

Answers 201, abridged:

{
  "id": "8c7b6a59-4837-4261-9f0e-1d2c3b4a5968",
  "source": "imported",
  "key_ending": "F0F0F",
  "status": "expired",
  "has_access": false,
  "uses": 14
}
  • customer is { "id" }, or { "email" }: an address no customer holds yet gets a customer who claims it when they first sign in with it, as a grant does.
  • key is 6 to 128 letters, digits, hyphens, underscores and dots, with at least one letter or digit. A hex key, like Gumroad’s, then checks in any case and spacing; any other key checks exactly as you recorded it.
  • uses carries over the count from the old platform, and metadata anything you want to keep with the key, like the old sale’s id.
  • disabled: true, with an optional disabled_reason, records a key refunded or turned off at the old platform: it never checks as valid, and support can still find it. Enabling it later works as for any license.

A license follows the customer’s access like any other, so record the key, then give access with POST /grants. Until then it reads expired, or revoked when their earlier access was refunded or revoked. In that order the grant keeps the key you recorded instead of issuing one.

A key that any license of the store already holds, in any spelling a check would read as it, answers 409 conflict on key, naming that license in current, so a script that runs again can count it as imported. A customer who holds a license for the product already answers 409 on customer, naming theirs: that’s the case when you granted access before importing, which issued them a key. Send replace: true to have the imported key take that license’s place, as a rotation does: the old key stops checking and its devices are freed (deactivated_by reads merchant), so each activates again under the imported key; the imported license keeps its activation limit, and its uses, metadata and disabled state unless you send your own; and license.replaced tells the change.

When a customer you recorded a key for by email signs in to an account that already holds a license for the product, they keep one live license: the one recorded for their address, when theirs was issued here and never checked, activated on a device, used or disabled and the recorded one isn’t disabled, and otherwise theirs. The other reads as replaced, so support can still find it, its devices are freed (deactivated_by reads customer), and license.replaced tells the change.

Import a catalog in bulk, up to 50 keys a call, each item refused alone:

curl -X POST 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/bulk' \
  -H "Authorization: Bearer $SHERPO_TOKEN" \
  -H 'Idempotency-Key: gumroad-import-page-1' \
  -H 'Content-Type: application/json' \
  -d '{
  "accessor": "recordLicense",
  "items": [
    {
      "customer": {
        "email": "ada@example.com"
      },
      "product": {
        "id": "3e9d1f6b-72a4-4c58-b0e3-9a6f2d84c1b7"
      },
      "key": "B4C5D6E7-12345678-9ABCDEF0-0F0F0F0F"
    },
    {
      "customer": {
        "email": "grace@example.com"
      },
      "product": {
        "id": "3e9d1f6b-72a4-4c58-b0e3-9a6f2d84c1b7"
      },
      "key": "1A2B3C4D-56789ABC-DEF01234-56789ABC",
      "disabled": true,
      "disabled_reason": "Refunded at Gumroad"
    }
  ]
}'
const answer = await sherpo('POST', '/v1/stores/STORE_ID/bulk', {
  body: {
    "accessor": "recordLicense",
    "items": [
      {
        "customer": {
          "email": "ada@example.com"
        },
        "product": {
          "id": "3e9d1f6b-72a4-4c58-b0e3-9a6f2d84c1b7"
        },
        "key": "B4C5D6E7-12345678-9ABCDEF0-0F0F0F0F"
      },
      {
        "customer": {
          "email": "grace@example.com"
        },
        "product": {
          "id": "3e9d1f6b-72a4-4c58-b0e3-9a6f2d84c1b7"
        },
        "key": "1A2B3C4D-56789ABC-DEF01234-56789ABC",
        "disabled": true,
        "disabled_reason": "Refunded at Gumroad"
      }
    ]
  },
  key: 'gumroad-import-page-1',
});

Answers 200, abridged:

{
  "results": [
    {
      "outcome": "done"
    },
    {
      "outcome": "done"
    }
  ]
}

Bulk answers each item’s outcome without its id: list the product’s licenses with filter[source]=imported or filter[customer_id] to find them afterwards.

Usage stats

GET /products/{product}/licenses/stats answers how a software product’s licenses are used over a period, by default the 30 days ending today in the store’s time zone, and the span of the same length before it. It takes customer:read, like every license read, and a product of another category answers 400 invalid on product.

curl 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/products/3e9d1f6b-72a4-4c58-b0e3-9a6f2d84c1b7/licenses/stats?from=2026-11-01&to=2026-11-03' \
  -H "Authorization: Bearer $SHERPO_TOKEN"
const answer = await sherpo('GET', '/v1/stores/STORE_ID/products/3e9d1f6b-72a4-4c58-b0e3-9a6f2d84c1b7/licenses/stats', {
  query: [
    ['from', '2026-11-01'],
    ['to', '2026-11-03'],
  ],
});

Answers 200, abridged:

{
  "time_zone": "Europe/Rome",
  "from": "2026-11-01",
  "to": "2026-11-03",
  "previous_range": {
    "from": "2026-10-29",
    "to": "2026-10-31"
  },
  "issued": {
    "current": 12,
    "previous": 9
  },
  "imported": {
    "current": 0,
    "previous": 140
  },
  "verifies": {
    "current": 2210,
    "previous": 1985
  },
  "uses": {
    "current": 640,
    "previous": 571
  },
  "active_license_days": {
    "current": 411,
    "previous": 388
  },
  "activations": {
    "current": 19,
    "previous": 152
  },
  "deactivations": {
    "current": 4,
    "previous": 6
  },
  "refusals": {
    "current": 2,
    "previous": 0
  },
  "series": [
    {
      "start": "2026-11-01",
      "end": "2026-11-01",
      "issued": 3,
      "imported": 0,
      "verifies": 702,
      "uses": 205,
      "active_license_days": 134,
      "activations": 6,
      "deactivations": 1,
      "refusals": 0,
      "previous_verifies": 640,
      "previous_active_license_days": 126,
      "previous_activations": 48
    },
    {
      "start": "2026-11-02",
      "end": "2026-11-02",
      "issued": 4,
      "imported": 0,
      "verifies": 731,
      "uses": 211,
      "active_license_days": 136,
      "activations": 7,
      "deactivations": 2,
      "refusals": 1,
      "previous_verifies": 655,
      "previous_active_license_days": 129,
      "previous_activations": 51
    },
    {
      "start": "2026-11-03",
      "end": "2026-11-03",
      "issued": 5,
      "imported": 0,
      "verifies": 777,
      "uses": 224,
      "active_license_days": 141,
      "activations": 6,
      "deactivations": 1,
      "refusals": 1,
      "previous_verifies": 690,
      "previous_active_license_days": 133,
      "previous_activations": 53
    }
  ]
}
  • issued counts the licenses the store gave customers with their access, and imported the keys you recorded from another platform. A rotation’s new key, or a key you record with replace: true, is the same license, so it counts in neither, and when an invited customer signs in to an account that holds the product too, the license that goes or reads replaced takes its count back, so they count once.
  • verifies counts your server’s checks, whatever they found, and uses the checks that counted a use. A key no license holds counts nothing.
  • active_license_days counts each license that checked in while active (a verify that found it active, a device activated, or activated again while counted, or its token refreshed) once a day. Each daily point of series is that day’s active licenses; a weekly or monthly point, and the whole period, adds its days up, so a license checking every day of a week counts 7.
  • activations counts devices that began counting, new or back after being freed or inactive; refusals the activations refused at the limit; deactivations the devices freed by the customer, by you, by your software, by a new key, or when an invited customer’s duplicate license goes as they sign in.

series cuts the period into days, or into weeks or months when you ask for them, each point beside the same point of the span before. The figures are counted as each check lands, so a day keeps the time zone it was counted in when the store changes its own.

Events

Webhooks tell each change: license.issued when a customer first gets their license or you import their key, license.disabled and license.enabled, and license.replaced with the new license and the one it replaced, whoever rotated the key, and license.activated, license.deactivated and license.limit_reached for its devices. Events name the license and never carry its key: read it with GET /products/{product}/licenses/{license} when you need it.

Type to search…

↑↓ navigate↵ selectEsc close