License Lifecycle
Use this page to manage license state transitions such as suspend, reinstate, revoke, renew, and transfer.
Who This Is For
- operators managing renewals, non-payment holds, fraud actions, or transfers
- developers wiring lifecycle actions into a back office or dashboard
- teams that need predictable state transition rules
When To Use This
Use lifecycle actions whenever the license state itself must change, not just when runtime entitlements are being checked.
How It Works
Core lifecycle routes:
POST /api/v1/licenses/{id}/suspendPOST /api/v1/licenses/{id}/reinstatePOST /api/v1/licenses/{id}/revokePOST /api/v1/licenses/{id}/renewPOST /api/v1/licenses/{id}/transfer
Key behavior:
- renewals are only for
subscription,time_limited, andtrial - renewals are idempotent per license and
Idempotency-Key - revocation is permanent
- renewals keep suspended licenses suspended
- transfers move assignee linkage without rewriting the rest of the license history
Example
Renew a license by 365 days:
bash
curl -X POST https://api.licensekit.dev/api/v1/licenses/lic_123/renew \
-H "Authorization: Bearer $LICENSEKIT_TOKEN" \
-H "Idempotency-Key: renew-lic-123-2026-annual" \
-H "Content-Type: application/json" \
-d '{
"extend_by_days": 365
}'Suspend a license:
bash
curl -X POST https://api.licensekit.dev/api/v1/licenses/lic_123/suspend \
-H "Authorization: Bearer $LICENSEKIT_TOKEN"Transfer a license:
bash
curl -X POST https://api.licensekit.dev/api/v1/licenses/lic_123/transfer \
-H "Authorization: Bearer $LICENSEKIT_TOKEN" \
-H "Idempotency-Key: transfer-lic-123-cust-456" \
-H "Content-Type: application/json" \
-d '{
"customer_id": "cust_456"
}'Common Mistakes
- using revoke for a temporary hold that should be suspend/reinstate
- attempting to renew perpetual or consumption licenses
- assuming renewal automatically reinstates a suspended license
- treating renewal-time order or subscription references as rewriting stored origin linkage