Features and usage limits

A license tells your app more than yes or no. Each plan can list the features it unlocks and the limits that apply, so a Pro plan can export PDFs, allow fifty projects and include ten thousand API calls a month, while the Basic plan does less. Change a plan in the dashboard and every license on it follows; no new app release needed.

Features on a plan#

Add features to a plan under Plans. Each one has a name your code checks, such as export_pdf, and a type:

Checking features from your app#

The verify answer already includes the plan's features, and so does the offline token. For a detailed view, including how much of each quota is left, ask for the entitlements:

curl -X POST https://licenses.example.com/api/v1/license/entitlements \
  -H "Content-Type: application/json" \
  -d '{"license_key":"KG-ABCD2345-EFGH6789-JKLM2345-NPQR6789"}'

{
  "success": true,
  "data": {
    "licensed": true,
    "status": "active",
    "plan_name": "Pro",
    "features": {
      "export_pdf": { "enabled": true, "value_type": "bool", "value": "true" },
      "api_calls": {
        "enabled": true, "value_type": "quota", "value": "10000",
        "used": 4512, "limit": 10000, "remaining": 5488,
        "period": "monthly", "resets_at": "2026-11-01T00:00:00Z"
      }
    }
  }
}

Add "feature": "api_calls" to the request to get a single feature back.

Usage quotas#

A quota feature counts something and stops at a limit. It resets on a schedule you choose: hourly, daily, monthly or yearly. Keygate does the counting in the database in one step, so even many requests at the same instant cannot push a license past its limit.

Recording usage#

Each time the metered thing happens, report it:

curl -X POST https://licenses.example.com/api/v1/license/usage \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0b8f6a4e-91c2-4d57-a3e1-6c2d9f7b4a10" \
  -d '{"license_key":"KG-ABCD2345-EFGH6789-JKLM2345-NPQR6789",
       "feature":"api_calls","quantity":1}'

{
  "success": true,
  "data": { "accepted": true, "used": 4513, "limit": 10000, "remaining": 5487,
            "period": "monthly", "period_key": "2026-10" }
}

• quantity defaults to 1. Send more to record a batch at once.
• metadata takes any JSON object and is stored with the event, which helps when you need to explain a bill later.
• Once the quota is spent, the answer is 429 QUOTA_EXCEEDED. Unlike other 429s, waiting does not help until the period resets, so do not retry it.
• Send an Idempotency-Key so a retried request is not counted twice.

To read the counter without changing it, call /api/v1/license/usage/status with the same license_key and feature.

Warnings before the limit#

When a license crosses 80 percent of a quota, Keygate sends the quota.warning webhook and emails the customer, and when the quota runs out it sends quota.exceeded. The 80 percent comes from QUOTA_WARNING_THRESHOLD. Use these to suggest an upgrade before the customer hits the wall.

Addons#

Addons sell extra capability on top of a plan, such as more API calls or an extra feature, without a separate plan for every combination. A license gets its plan's features plus those of its addons, and an addon wins when both name the same feature, for example a larger quota. This applies everywhere features are read: verify answers, offline tokens, usage limits and the entitlements answer. Manage them under Addons in the dashboard.

Want to react when usage gets high? Webhooks lists every event Keygate sends.