Gate Features with Entitlements

What you’ll build

This tutorial gates product features by plan without hard-coding plan names into your app. You’ll grant boolean and limit entitlements to a plan, check them on the hot path with a single endpoint, and wire a usage limit so your dashboard can show remaining headroom. The pattern replaces if (plan === 'pro') scattered through your codebase with if (entitled(customer, 'sso')). Change what a plan includes in Recurso and every subscriber picks it up immediately — no deploy.

Recurso resolves whether a customer is entitled and how much. Counting actual consumption against a limit is your application’s job. For metered billing on that consumption, see usage-based billing.

Step 1: Define plan entitlements

Entitlements come in two kinds: boolean (on/off, uses bool_value) and limit (a numeric quota, uses limit_value). Setting a plan’s entitlements is a full replacement — always send the complete set the plan should grant.

curl -X PUT http://localhost:8080/v1/plans/plan_pro/entitlements \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    { "feature_key": "sso", "kind": "boolean", "bool_value": true },
    { "feature_key": "api_access", "kind": "boolean", "bool_value": true },
    { "feature_key": "seats", "kind": "limit", "limit_value": 25 },
    { "feature_key": "api_calls", "kind": "limit", "limit_value": 100000 }
  ]'

await recurso.entitlements.setForPlan('plan_pro', [
  { feature_key: 'sso', kind: 'boolean', bool_value: true },
  { feature_key: 'api_access', kind: 'boolean', bool_value: true },
  { feature_key: 'seats', kind: 'limit', limit_value: 25 },
  { feature_key: 'api_calls', kind: 'limit', limit_value: 100000 },
]);

Because this replaces the whole set, sending only the feature you changed deletes the rest. Send the full list every time. Feature keys must match ^[A-Za-z0-9][A-Za-z0-9._:-]*$; duplicate keys in one request are rejected with validation_failed.

A customer holding several subscriptions gets the union: booleans resolve any-true wins, limits resolve maximum wins, and only active and trialing subscriptions count. See Entitlements for the full resolution rules.

Step 2: Check a feature at request time

GET /v1/entitlements/check is the hot path — one indexed query for a customer_id + feature pair. A feature the customer doesn’t have answers granted: false with a null limit; it is never a 404.

curl "http://localhost:8080/v1/entitlements/check?customer_id=cust_abc&feature=sso" \
  -H "Authorization: Bearer $API_KEY"

const check = await recurso.entitlements.check('cust_abc', 'sso');
if (check.granted) {
  // feature enabled
}

import requests

resp = requests.get(
    "http://localhost:8080/v1/entitlements/check",
    headers={"Authorization": f"Bearer {API_KEY}"},
    params={"customer_id": "cust_abc", "feature": "sso"},
).json()
# { "feature_key": "sso", "granted": true, "limit_value": null }

Gate a route with middleware

Node

function requireFeature(feature: string) {
  return async (req, res, next) => {
    const check = await recurso.entitlements.check(req.user.recursoCustomerId, feature);
    if (!check.granted) {
      return res.status(403).json({
        error: { code: 'feature_not_entitled', message: `Upgrade to use ${feature}` },
      });
    }
    next();
  };
}

app.post('/api/sso/configure', requireFeature('sso'), configureSSO);

For latency-sensitive paths, cache check results for a short TTL (30–60s) keyed by customer_id:feature. Entitlements only change when a plan or subscription changes, so a short cache is safe and removes the round-trip.

Step 3: Enforce a limit

For limit entitlements, compare the entitled ceiling to your own counter:

Node

async function canAddSeat(customerId: string, currentSeats: number) {
  const check = await recurso.entitlements.check(customerId, 'seats');
  return check.granted && currentSeats < (check.limit_value ?? 0);
}

Step 4: Wire usage headroom

When a limit’s feature_key matches a usage dimension of the same name, GET /v1/subscriptions/{id}/usage joins the limit and remaining headroom into each row automatically — the “4,231 of 10,000” view, without you doing the math.

Node

// Limit and dimension share the name "api_calls"
await recurso.entitlements.setForPlan('plan_pro', [
  { feature_key: 'api_calls', kind: 'limit', limit_value: 100000 },
]);

await recurso.usage.record({
  subscription_id: 'sub_xyz',
  customer_id: 'cust_abc',
  dimension: 'api_calls',
  quantity: 150,
});

const usage = await recurso.subscriptions.usage('sub_xyz');
const api = usage.dimensions.find((d) => d.dimension === 'api_calls');
// api.limit_value = 100000, api.remaining = limit_value - period_quantity
// remaining goes negative when over the limit — a natural upgrade trigger.

See the usage tutorial for the full metering flow.

Step 5: See why a customer has a feature

To display why a feature is granted (which plans contributed), fetch the effective set for the customer — each entry lists the contributing plan_ids:

curl http://localhost:8080/v1/customers/cust_abc/entitlements \
  -H "Authorization: Bearer $API_KEY"

Next Steps

Entitlements

Full resolution semantics and validation rules

Check Feature API

The hot-path check endpoint reference

Usage-Based Billing

Meter and bill on consumption

Set Plan Entitlements API

Replace a plan’s grants

Start Here

Tutorials

Billing & Monetization

Payments & Recovery

Growth & Retention

Compliance

Finance

Platform

Gate Features with Entitlements

What you’ll build

Step 1: Define plan entitlements

Step 2: Check a feature at request time

Gate a route with middleware

Step 3: Enforce a limit

Step 4: Wire usage headroom

Step 5: See why a customer has a feature

Next Steps

Entitlements

Check Feature API

Usage-Based Billing

Set Plan Entitlements API

​What you’ll build

​Step 1: Define plan entitlements

​Step 2: Check a feature at request time

​Gate a route with middleware

​Step 3: Enforce a limit

​Step 4: Wire usage headroom

​Step 5: See why a customer has a feature

​Next Steps

Entitlements

Check Feature API

Usage-Based Billing

Set Plan Entitlements API

What you’ll build

Step 1: Define plan entitlements

Step 2: Check a feature at request time

Gate a route with middleware

Step 3: Enforce a limit

Step 4: Wire usage headroom

Step 5: See why a customer has a feature

Next Steps