Check one entitlement
The entitlements.check operation: GET /api/v1/entitlements/check in the REST API and the entitlements_check tool in the MCP server.
/api/v1/entitlements/checkReturns one customer's value of one feature, from the customer's stored entitlements: a single read for the
checks your product makes on every request. enabled is true for true or a limit above 0; compare value
for limits and enum features.
The value is the same as in customers.entitlements.get (resolved from the sources while a recompute is
pending). Ownrecord doesn't enforce it: your product decides what to allow.
At a glance
- REST:
GET /api/v1/entitlements/check - MCP tool:
entitlements_check - Operation ID:
entitlements.check - Scope: Brand
- Permission:
customers:read - Risk tier:
read - Dry run: Not supported
- Idempotency: Not needed (read only)
- Modes: Test and live
- Authentication: API key with the
customers:readscope - Since: M5
Request
Query parameters
| Field | Type | Required | Description |
|---|---|---|---|
customer | cus_… ID | Yes | The customer (cus_…). |
feature | string | Yes | The feature key, e.g. seats.max. |
Response
200 OK with a JSON object:
| Field | Type | Description |
|---|---|---|
object | "entitlement_check" | |
customerId | cus_… ID | |
featureKey | string | |
value | boolean or number or string | The customer's value of the feature. |
enabled | boolean | true when the value is true or a limit above 0 (an enum value is never 'enabled': compare value). |
computedAt | date-time |
Examples
A seat limit
GET /api/v1/entitlements/check?customer=cus_01m4ty3c2b5qx7mhd9k8w6s0aa&feature=seats.max
Authorization: Bearer or_test_…
Response (200):
{
"object": "entitlement_check",
"customerId": "cus_01m4ty3c2b5qx7mhd9k8w6s0aa",
"featureKey": "seats.max",
"value": 20,
"enabled": true,
"computedAt": "2026-10-14T10:00:05.000Z"
}
A boolean feature
GET /api/v1/entitlements/check?customer=cus_01m4ty3c2b5qx7mhd9k8w6s0aa&feature=feature.export
Authorization: Bearer or_test_…
Response (200):
{
"object": "entitlement_check",
"customerId": "cus_01m4ty3c2b5qx7mhd9k8w6s0aa",
"featureKey": "feature.export",
"value": true,
"enabled": true,
"computedAt": "2026-10-14T10:00:05.000Z"
}
Errors
| Code | HTTP status | When | What to do |
|---|---|---|---|
validation_failed | 400 | customer isn't a customer ID, or feature isn't a feature key (e.g. seats.max). | Fix the fields listed in details.issues and send the request again. |
resource_not_found | 404 | This brand has no such customer in this mode (customers belong to one brand and one mode). | Check the ID and that your credentials are scoped to the right organization, entity, brand and mode. |
entitlement_feature_not_found | 400 | The brand has no feature with this key in this mode. | Check the feature key against features.list (test and live mode have separate features), or create the feature first with features.create. |
scope_required | 400 | The request names no brand (an org or entity key without Ownrecord-Brand). | Call the operation with credentials or a target at its level: an organization, a legal entity, a brand or the platform (details.required_scope). |
livemode_not_allowed | 403 | You have no live-mode access, so you can't act on live customers. | Use test mode, or credentials for the target's mode. Developers need live access granted by an organization owner or admin. |
permission_denied | 403 | You can't read this brand's customers (customers:read). | Ask an organization owner or admin for a role or scope that allows this action. |
It can also return these common errors: api_version_unsupported, authentication_required, api_key_invalid, dry_run_not_supported, rate_limited, internal_error.