Skip to content

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.

  1. Eligibility. If the subscription isn’t eligible, the result is granted: false, source: none, with the reason. Nothing below applies.
  2. An active override for this feature: source: override.
  3. The pinned plan version’s value: source: plan.
  4. The feature’s default_value: source: default.
  5. Nothing: granted: false, source: none, reason: not_included.
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.

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
  • A known Customer with nothing granted gets 200 with granted: false.
  • An unknown Customer is 404 customer_not_found. An unknown feature key on single evaluation is 404 feature_not_found.
  • evaluate-all returns every feature in the environment; only an unknown Customer is a 404.

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.