Evaluation
Evaluation answers: for this Customer, at this instant, what does this feature resolve to? Call POST /v1/entitlements/evaluate for one feature, or POST /v1/entitlements/evaluate-all for every feature in the environment. Both are read-only and safe to retry. Seal0 chooses the evaluation instant.
The order
Section titled “The order”- Eligibility. If the subscription isn’t eligible, the result is
granted: false,source: none, with the reason. Nothing below applies. - An active override for this feature:
source: override. - The pinned plan version’s value:
source: plan. - The feature’s
default_value:source: default. - Nothing:
granted: false,source: none,reason: not_included.
The result
Section titled “The result”| Field | Meaning |
|---|---|
granted |
Whether the feature applies. For numbers it’s true whenever a value resolved; the value is the limit. |
value |
The resolved value (true, 10, "unlimited", "csv"), or null. |
source |
override, plan, default or none. |
reason |
Why, as a code. Clients must tolerate new codes. |
override_id |
Set when an override decided the value. |
valid_until |
The earliest future instant when this answer can change without a write, or null. See Caching. |
usage |
For metered features that resolved a value; null otherwise. See Metered usage. |
The response also carries the Customer’s current subscription (ID, status, plan key and version), or null.
Reasons
Section titled “Reasons”source |
reason |
Meaning |
|---|---|---|
override |
customer_override |
an active override applied |
plan |
included_in_plan |
the pinned plan version’s value |
default |
feature_default |
the feature’s default (the version omits the feature) |
none |
not_included |
eligible, but no override, plan value or default |
none |
no_subscription, subscription_not_started, subscription_paused, subscription_expired, trial_ended, period_ended, grace_ended, subscription_canceled |
not eligible; see Subscriptions |
any but none |
usage_within_limit, usage_within_grace, usage_limit_exceeded |
metered features; see Metered usage |
Missing is not an error
Section titled “Missing is not an error”- A known Customer with nothing granted gets
200withgranted: false. - An unknown Customer is
404 customer_not_found. An unknown feature key on single evaluation is404 feature_not_found. evaluate-allreturns every feature in the environment; only an unknown Customer is a404.
Enforcing the answer
Section titled “Enforcing the answer”Seal0 says what applies; your code enforces it. For a limit, compare your own count with the value: currentProjects < 10. If the call fails (network, 5xx, a revoked key), fail closed: treat it as not granted, or use a cached answer that’s still within its valid_until.