Benefits catalogue

A benefit is a per-app catalogue entry that answers "what does buying a product grant the customer?" — Stripe's entitlements.feature. Each benefit has a stable lookupKey that your gating code keys on; attaching it to a product is what turns a paid subscription or one-time purchase into a live entitlement.

This page covers the admin console surface (/api/v1/admin/benefits, session-authenticated, RBAC-guarded). It drives the same engine as the app-API-key benefits guide — there is no parallel benefit type, only a second audience.

All responses use the standard envelope:

{
  "data": { "...": "payload or null" },
  "meta": { "success": true, "message": null, "errorCode": null, "timestamp": "2026-06-30T12:00:00Z" },
  "pagination": null
}

Below we show only the data payload unless the envelope itself is the point.

The lookupKey gating model

The lookupKey is the app's own stable gating identifier. Your client code keys on it — never on the numeric id or the display name — so gating survives repricing, renaming, or replacing the benefit.

Every benefit also carries an app_id and a mode (TEST/LIVE). A benefit from another app or another mode is never returned — see app isolation and modes.

Permissions

Both authorities are seeded to Super Admin only by default (migration V23). Every other role is opt-in — grant the authority through role management to delegate catalogue work. The coarse gate is checked on the controller; a finer per-app scope check (RBAC-4) runs inside each use case, and every write is audited.

Create, search, read, edit

All examples use the base URL http://localhost:8080/api/v1 and an admin session token.

Create a benefit

POST /admin/benefits?applicationId={appId}&mode={TEST|LIVE} — both query params are required. The benefit starts active.

curl -X POST "http://localhost:8080/api/v1/admin/benefits?applicationId=42&mode=TEST" \
  -H "Authorization: Bearer SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "lookupKey": "pro_seats",
        "name": "Pro seats",
        "metadata": "{\"seats\": 10}"
      }'

{
  "lookupKey": "pro_seats",
  "name": "Pro seats",
  "metadata": "{\"seats\": 10}"
}

Returns 201 Created with the new benefit:

{
  "data": {
    "id": 4012,
    "lookupKey": "pro_seats",
    "name": "Pro seats",
    "metadata": "{\"seats\": 10}",
    "active": true,
    "mode": "TEST",
    "createdAt": "2026-06-30T12:00:00",
    "updatedAt": "2026-06-30T12:00:00"
  },
  "meta": { "success": true, "message": null, "errorCode": null, "timestamp": "2026-06-30T12:00:00Z" },
  "pagination": null
}

BenefitDto

The read model returned by create, detail, search rows, edit, and the activate/deactivate toggles.

Search benefits

GET /admin/benefits — paginated, cross-app, narrowed to the apps your benefit:read grants cover (out-of-scope rows are simply not returned).

curl "http://localhost:8080/api/v1/admin/benefits?applicationId=42&mode=TEST&active=true&search=seats" \
  -H "Authorization: Bearer SESSION_TOKEN"

{
  "data": [
    {
      "id": 4012,
      "lookupKey": "pro_seats",
      "name": "Pro seats",
      "metadata": "{\"seats\": 10}",
      "active": true,
      "mode": "TEST",
      "createdAt": "2026-06-30T12:00:00",
      "updatedAt": "2026-06-30T12:00:00"
    }
  ],
  "meta": { "success": true, "message": null, "errorCode": null, "timestamp": "2026-06-30T12:00:00Z" },
  "pagination": { "page": 0, "size": 20, "totalElements": 1, "totalPages": 1 }
}

Read one benefit

GET /admin/benefits/{id}. A benefit outside your app scope reads as 404 — identical to a missing id, so the console never leaks the existence of another app's benefit.

curl "http://localhost:8080/api/v1/admin/benefits/4012" \
  -H "Authorization: Bearer SESSION_TOKEN"

Edit a benefit

PATCH /admin/benefits/{id} — PATCH semantics. The lookupKey is immutable and is therefore not editable here.

metadata clearing rules (it is a string field, so JSON null and an omitted field are indistinguishable):

• Omit metadata (or send null) → the stored value is left unchanged.
• Send "" (blank/whitespace) → the stored value is cleared to null.
• Send valid JSON → replaces the stored value.
• Send malformed JSON → rejected with 400.

curl -X PATCH "http://localhost:8080/api/v1/admin/benefits/4012" \
  -H "Authorization: Bearer SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Pro seats (10)", "metadata": "{\"seats\": 12}" }'

Activate & deactivate

A benefit toggles between active and inactive. Deactivating it stops it granting entitlements without deleting it or breaking the lookupKey your gating code relies on.

• POST /admin/benefits/{id}/activate — set active = true.
• POST /admin/benefits/{id}/deactivate — set active = false.

Both require benefit:write plus the per-app scope check, are audited, and resolve the benefit's owning app + mode from the stored record (no mode param).

curl -X POST "http://localhost:8080/api/v1/admin/benefits/4012/deactivate" \
  -H "Authorization: Bearer SESSION_TOKEN"

metadata as raw JSON

metadata is an optional, free-form JSON value stored as-is in a jsonb column — it carries structured limits such as {"seats": 10} or {"tier": "gold", "apiCallsPerMonth": 100000}. The service does not interpret it; your app reads it back and decides what it means.

On both create and edit, a supplied value is parsed for well-formedness before it reaches the column. A malformed value is rejected up front:

{
  "data": null,
  "meta": {
    "success": false,
    "message": "metadata must be a valid JSON object",
    "errorCode": "VALIDATION_ERROR",
    "timestamp": "2026-06-30T12:00:00Z"
  },
  "pagination": null
}

A blank value normalises to null (clears it). Because the DTO field is a string, the value is echoed back on reads as a JSON-encoded string — JSON.parse it.

How benefits power entitlements

A benefit only matters once it is attached to a product. When a customer holds an active entitling subscription or a paid one-time purchase of that product, the product's attached benefits become the customer's live entitlements, deduplicated by lookupKey.

Attach a benefit to a product

Product↔benefit attachment lives on the products controller, but is gated by benefit:write (not product:write):

• POST /admin/products/{id}/benefits — attach. Body: { "benefitId": 4012 } (benefitId is required). Both the product and the benefit must belong to the same app + mode (resolved from the product); attaching the same pair twice is a no-op (idempotent). Returns the product with its prices and attached benefits.
• DELETE /admin/products/{id}/benefits/{benefitId} — detach a single attachment.

curl -X POST "http://localhost:8080/api/v1/admin/products/900/benefits" \
  -H "Authorization: Bearer SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "benefitId": 4012 }'

Reading the result

Entitlement derivation is an app-facing read. Your integration calls GET /api/v1/entitlements?customerReference=... to list a customer's active entitlements, or GET /api/v1/entitlements/check to test a single lookupKey.

Dashboard metrics

GET /admin/benefits/metrics powers the App-Selector dashboard metrics row.

curl "http://localhost:8080/api/v1/admin/benefits/metrics?applicationId=42&mode=TEST&from=2026-06-01&to=2026-06-30" \
  -H "Authorization: Bearer SESSION_TOKEN"

Returns BenefitMetricsDto:

{
  "data": { "totalCount": 7, "activeCount": 6 },
  "meta": { "success": true, "message": null, "errorCode": null, "timestamp": "2026-06-30T12:00:00Z" },
  "pagination": null
}

If the acting admin is not scoped to applicationId, the metrics come back zeroed ({ "totalCount": 0, "activeCount": 0 }) rather than 403, mirroring how an out-of-scope search returns no rows. This mode-as-query-parameter shape matches the wider dashboard analytics endpoints — the one place mode is a request input rather than a credential property.

Related