Plumtier Docs Deploy free

Activate a key

Activate a license key on a device and get back an instance id for later checks.

POST/api/v1/licenses/activate

Uses one of the key's activations. Call it the first time a device uses a key. If the key is at its limit, the call is refused and nothing changes.

Important
Each successful call creates a new instance and uses another activation, even for a device that activated before. Save instance.id and call validate with it afterwards, instead of activating on every launch.

Request

license_keystringrequired

The key the buyer entered. Case and surrounding spaces don't matter.

instance_namestringrequired

A name for this device, up to 200 characters, like the computer's name. Buyers see it in their purchases.

product_idstringoptional

Your product's link or id. When sent, a key for a different product is refused.

curl https://shop.example.com/api/v1/licenses/activate \
  -d license_key="7KQ2M-XW9PA-4TB8N-R2HDE" \
  -d instance_name="Ada's MacBook Pro" \
  -d product_id="pastepal"

Response

200 when activated. Save instance.id: validate and deactivate need it.

200 OK
{
  "activated": true,
  "error": null,
  "license_key": {
    "id": "lic_3k9x…",
    "status": "active",
    "key": "7KQ2M-XW9PA-4TB8N-R2HDE",
    "activation_limit": 3,
    "activation_usage": 1,
    "created_at": "2026-11-17T09:51:52.000Z",
    "expires_at": null
  },
  "instance": {
    "id": "inst_8fq2…",
    "name": "Ada's MacBook Pro",
    "created_at": "2026-11-17T09:55:01.000Z"
  },
  "meta": {
    "store_id": "4b1c…",
    "order_id": "ord_q3fq…",
    "order_number": 1042,
    "product_id": "prod_s64g…",
    "product_name": "PastePal",
    "variant_id": "var_82vd…",
    "variant_name": "Family",
    "customer_id": "cus_ea3j…",
    "customer_name": "Ada Lovelace",
    "customer_email": "ada@example.com"
  }
}
license_key.idstringrequired

The key's id in your store.

license_key.statusstringrequired

inactive (never activated), active, expired or disabled.

license_key.keystringrequired

The key itself, in its stored form.

license_key.activation_limitnumber | nullrequired

How many devices it may be active on. null means unlimited.

license_key.activation_usagenumberrequired

How many devices it's active on now.

license_key.created_atstringrequired

When the key was made, ISO 8601 in UTC.

license_key.expires_atstring | nullrequired

When it stops working, or null for never.

instanceobject | nullrequired

The device: id, name, created_at. null when the call wasn't about one device.

metaobjectrequired

Where the key came from: store_id, order_id, order_number, product_id, product_name, variant_id, variant_name, customer_id, customer_name, customer_email. Ids are null for keys made in bulk or imported.

When it's refused

400 with activated: false and an error that says why. license_key and meta are still filled in, so your app can show the limit or the expiry date.

400 Bad Request
{
  "activated": false,
  "error": "This license key has reached its activation limit of 3.",
  "instance": null,
  "license_key": {
    "id": "lic_3k9x…",
    "status": "active",
    "key": "7KQ2M-XW9PA-4TB8N-R2HDE",
    "activation_limit": 3,
    "activation_usage": 3,
    "created_at": "2026-11-17T09:51:52.000Z",
    "expires_at": null
  },
  "meta": { "product_name": "PastePal", "variant_name": "Family", "…": "…" }
}

Other reasons: the key is disabled, it has expired, or it's for a different product. An unknown key is 404; a missing field is 400. See Errors.