Activate a key
Activate a license key on a device and get back an instance id for later checks.
/api/v1/licenses/activateUses 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.
instance.id and call validate with it afterwards, instead of activating on every launch.Request
license_keystringrequiredThe key the buyer entered. Case and surrounding spaces don't matter.
instance_namestringrequiredA name for this device, up to 200 characters, like the computer's name. Buyers see it in their purchases.
product_idstringoptionalYour 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"const response = await fetch("https://shop.example.com/api/v1/licenses/activate", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
license_key: "7KQ2M-XW9PA-4TB8N-R2HDE",
instance_name: "Ada's MacBook Pro",
product_id: "pastepal",
}),
});
const result = await response.json();var request = URLRequest(url: URL(string: "https://shop.example.com/api/v1/licenses/activate")!)
request.httpMethod = "POST"
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.httpBody = try JSONEncoder().encode([
"license_key": "7KQ2M-XW9PA-4TB8N-R2HDE",
"instance_name": "Ada's MacBook Pro",
"product_id": "pastepal",
])
let (data, _) = try await URLSession.shared.data(for: request)import requests
result = requests.post("https://shop.example.com/api/v1/licenses/activate", json={
"license_key": "7KQ2M-XW9PA-4TB8N-R2HDE",
"instance_name": "Ada's MacBook Pro",
"product_id": "pastepal",
}, timeout=10).json()Response
200 when activated. Save instance.id: validate and deactivate need it.
{
"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.idstringrequiredThe key's id in your store.
license_key.statusstringrequiredinactive (never activated), active, expired or disabled.
license_key.keystringrequiredThe key itself, in its stored form.
license_key.activation_limitnumber | nullrequiredHow many devices it may be active on. null means unlimited.
license_key.activation_usagenumberrequiredHow many devices it's active on now.
license_key.created_atstringrequiredWhen the key was made, ISO 8601 in UTC.
license_key.expires_atstring | nullrequiredWhen it stops working, or null for never.
instanceobject | nullrequiredThe device: id, name, created_at. null when the call wasn't about one device.
metaobjectrequiredWhere 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.
{
"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.