Entitlements

Entitlements answer one question your app asks all the time: does this customer currently have access to feature X? You define benefits in the catalogue, attach them to products, sell those products through subscriptions and one-time purchases, and then read back a flattened list of the benefits a customer holds — keyed by a stable lookupKey you gate on.

Entitlements are derived, not stored

There is no entitlement table. Every read derives the answer on the fly, per request, by walking the customer's entitling subscriptions and paid purchases down to their active benefits. Nothing is written when you read; nothing goes stale.

Each entitlement is benefit-shaped — it carries only the benefit's lookupKey, display name, and optional metadata. It never leaks the subscription, invoice, or price the derivation walked to produce it.

Where entitlements come from

The active set is the union of two sources, both scoped to the authenticating app and mode:

1. Entitling subscriptions — every subscription in status TRIALING or ACTIVE. Each grants the benefits of the product it bills.
2. Paid one-time purchases — every invoice that is PAID, carries a price_id, and has no subscription_id. The price_id resolves to its product, which grants its benefits.

Each distinct product's active benefits are gathered, then flattened and deduplicated.

Derivation rules

List a customer's entitlements

GET /api/v1/entitlements returns every active entitlement the customer holds.

This is an app-authenticated read. Send your API key and secret; the mode (TEST or LIVE) is derived from the API credential that authenticated the request — never from the request body. Every read is scoped to your app and mode, so one app never sees another's customers (app isolation).

Every endpoint returns the standard envelope — { data, meta, pagination } (see Responses & errors). The rest of this page shows just data.

Query parameters

EntitlementView (response item)

curl -X GET "http://localhost:8080/api/v1/entitlements?customerReference=cust_88f2a1" \
  -H "X-Api-Key: oi_test_4f3c2b1a09d8e7f6" \
  -H "X-Api-Secret: sk_test_a1b2c3d4e5f6g7h8"

A customer with a paid purchase and an active subscription:

{
  "data": [
    { "lookupKey": "priority_support", "name": "Priority support", "metadata": null },
    { "lookupKey": "pro_reports", "name": "Pro reports", "metadata": null },
    { "lookupKey": "team_seats", "name": "Team seats", "metadata": "{\"seats\": 10}" }
  ]
}

The list is not paginated — pagination is null and data is the full set.

Unknown customers return an empty list

A customerReference your app has never transacted against is not an error — it simply holds no entitlements:

{
  "data": []
}

Check a single entitlement

GET /api/v1/entitlements/check is the fast gate: pass a customerReference and a lookupKey and get a yes/no answer plus an echo of what you asked.

Query parameters

EntitlementCheckDto (response)

curl -X GET "http://localhost:8080/api/v1/entitlements/check?customerReference=cust_88f2a1&lookupKey=team_seats" \
  -H "X-Api-Key: oi_test_4f3c2b1a09d8e7f6" \
  -H "X-Api-Secret: sk_test_a1b2c3d4e5f6g7h8"

{
  "data": { "entitled": true, "lookupKey": "team_seats", "customerReference": "cust_88f2a1" }
}

An unknown customer, or a benefit the customer doesn't hold, reads entitled = false — never a 404:

{
  "data": { "entitled": false, "lookupKey": "enterprise_sso", "customerReference": "cust_88f2a1" }
}

List vs. check

Staying in sync

You usually want to cache the gate result in your app and refresh it when it changes, rather than calling on every request. The service emits a subscription.entitlements_updated webhook whenever a customer's derived active set changes, carrying the customer's current active lookup keys in its entitlements array.

The active set changes in exactly two situations:

A transition that does not cross the boundary fires no webhook — for example TRIALING → ACTIVE (both are entitling), so the derived set is unchanged. Listen for subscription.entitlements_updated, then re-read the list (or the relevant check) to refresh your cache.

Worked example: a purchase plus a subscription

{
  "data": [
    { "lookupKey": "priority_support", "name": "Priority support", "metadata": null },
    { "lookupKey": "pro_reports", "name": "Pro reports", "metadata": null },
    { "lookupKey": "team_seats", "name": "Team seats", "metadata": "{\"seats\": 10}" }
  ]
}

curl -X GET "http://localhost:8080/api/v1/entitlements/check?customerReference=cust_88f2a1&lookupKey=team_seats" \
  -H "X-Api-Key: oi_test_4f3c2b1a09d8e7f6" \
  -H "X-Api-Secret: sk_test_a1b2c3d4e5f6g7h8"

{
  "data": { "entitled": true, "lookupKey": "team_seats", "customerReference": "cust_88f2a1" }
}

Notes

• Auth and scope. Both endpoints require your X-Api-Key + X-Api-Secret. The mode (TEST or LIVE) is derived from the API credential that authenticated the request — never from the request body — and every read is scoped to your app and that mode. A test key never sees live entitlements, and vice versa.
• Reads, not mutations. These are GETs; there is nothing to make idempotent, so no Idempotency-Key applies.
• metadata is raw jsonb, echoed as a string. It is stored as-is and returned verbatim as a JSON string (e.g. "{\"seats\": 10}"); the service never interprets, merges, or expands it into a nested object. Parse it yourself if you need the structured value.
• Never a 404 for an unknown customer. Unknown customerReference ⇒ empty list (/entitlements) or entitled = false (/entitlements/check).