After activation, call validate() to confirm the license is still good. It's cheap (cached locally) and safe to call on every startup.

Validate

const valid = await client.validate({
  licenseKey: 'LK-2025-XXXX-YYYY',
  fingerprint: storedFingerprint,
})
 
if (!valid.ok || !valid.data.active) {
  throw new Error('License invalid or expired')
}
 
const { plan, limits } = valid.data
console.log(`Plan: ${plan.name}, monthly cap: ${limits.apiRequestsPerMonth ?? 'unlimited'}`)

How often to validate

Strategy	Use when
On startup only	Long-running servers; lowest overhead
Every N minutes	Balance freshness vs. calls
Per request	Strict enforcement (rely on the local cache to stay fast)

Entitlements

To read limits and current usage without a full validation, call entitlements():

const ent = await client.entitlements({ licenseKey: 'LK-2025-XXXX-YYYY' })
 
if (ent.ok) {
  ent.data.limits.apiRequestsPerMonth // e.g. 10000 (or null = unlimited)
  ent.data.usage.used                 // e.g. 4230
  ent.data.usage.remaining            // e.g. 5770
  ent.data.usage.period               // e.g. '2025-06'
}

Offline / cache fallback

The SDK caches the last successful validation. If the portal is unreachable, it falls back to that cached response so a brief outage doesn't lock customers out.

const client = new LicenseClient({
  apiUrl: process.env.LICENSE_API_URL!,
  cache: {
    maxAgeSeconds: 86_400,      // trust cache for up to 24h offline
    store: 'filesystem',        // default is in-memory
    path: '/var/cache/my-plugin',
  },
})

Choose maxAgeSeconds deliberately. Longer windows are friendlier during outages but widen the gap before a revoked license stops working offline.

Handling each status

if (!valid.ok) {
  switch (valid.code) {
    case 'LICENSE_NOT_FOUND':  // wrong key
    case 'LICENSE_REVOKED':    // permanently invalid
    case 'LICENSE_EXPIRED':    // subscription lapsed / trial ended
    case 'LICENSE_SUSPENDED':  // temporarily blocked
      // Show the appropriate message and stop
      break
    default:
      // Network or server error — consider the cache fallback
  }
}

Metered Usage

Report usage and handle limits + credits.

Webhooks

React to license changes in real time.

Validation