Skip to content

Feature Checker

Purpose

Feature Checker resolves plan values, add-ons, subscription overrides, and feature defaults. Use ordinary value and enabled checks for application decisions; explanation and summary methods help inspect configuration.

Access and initialization

Access

const featureChecker = subscrio.featureChecker;

var featureChecker = subscrio.FeatureChecker;

Method catalog

Database and connection failures may propagate from any operation. Method-specific errors are listed with each method.

Method Purpose
getValueForCustomer Resolves one customer feature value.
isEnabledForCustomer Checks a customer toggle value.
getAllFeaturesForCustomer Resolves every product feature.
getValueForSubscription Resolves one subscription feature value.
isEnabledForSubscription Checks a subscription toggle value.
getAllFeaturesForSubscription Resolves every feature for a subscription.
hasPlanAccess Checks active or trial plan membership.
getActivePlans Lists active or trial plan keys.
getFeatureUsageSummary Summarizes configured values for diagnostics.
explainForCustomer Explains a customer feature value.
explainForSubscription Explains a subscription feature value.
Method Purpose
GetValueForCustomerAsync Resolves one customer feature value.
IsEnabledForCustomerAsync Checks a customer toggle value.
GetAllFeaturesForCustomerAsync Resolves every product feature.
GetValueForSubscriptionAsync Resolves one subscription feature value.
IsEnabledForSubscriptionAsync Checks a subscription toggle value.
GetAllFeaturesForSubscriptionAsync Resolves every feature for a subscription.
HasPlanAccessAsync Checks active or trial plan membership.
GetActivePlansAsync Lists active or trial plan keys.
GetFeatureUsageSummaryAsync Summarizes configured values for diagnostics.
ExplainForCustomerAsync Explains a customer feature value.
ExplainForSubscriptionAsync Explains a subscription feature value.

Method details

getValueForCustomer

Resolve a feature across the customer's subscriptions using the product-feature resolution rules. With no eligible subscriptions, the feature default applies.

Supply a numeric or boolean fallback to request that runtime conversion; a generic type argument alone does not convert the stored string.

The generic type controls conversion. Invalid conversions return the fallback or the type's default value.

getValueForCustomer<T = string>(customerKey: string, productKey: string, featureKey: string, defaultValue?: T): Promise<T | null>

Parameters

  • customerKey: Customer key.
  • productKey: Product key.
  • featureKey: Feature key.
  • defaultValue: Optional fallback for missing records or failed conversion. Defaults to null.

Returns T | null: Resolved value or fallback.

Example

const seats = await subscrio.featureChecker.getValueForCustomer('acme', 'saas', 'max-seats', 0);
console.log(seats);
Errors (2)
  • NotFoundError: The feature exists but is not associated with the product, or required resolution context is missing.
  • ValidationError: Combining configured values overflows the supported numeric range.
Task<T?> GetValueForCustomerAsync<T>(string customerKey, string productKey, string featureKey, T? defaultValue)

Parameters

  • customerKey: Customer key.
  • productKey: Product key.
  • featureKey: Feature key.
  • defaultValue: Optional fallback for missing records or failed conversion. Defaults to default(T).

Returns T?: Resolved value or fallback; a non-nullable value type uses its default when no fallback is supplied.

Example

var seats = await subscrio.FeatureChecker.GetValueForCustomerAsync<int>("acme", "saas", "max-seats", 0);
Console.WriteLine(seats);
Errors (2)
  • NotFoundException: The feature exists but is not associated with the product, or required resolution context is missing.
  • ValidationException: Combining configured values overflows the supported numeric range.

isEnabledForCustomer

Return true only when the resolved string equals true, ignoring case. Missing records return false.

isEnabledForCustomer(customerKey: string, productKey: string, featureKey: string): Promise<boolean>

Parameters

  • customerKey: Customer key.
  • productKey: Product key.
  • featureKey: Toggle feature key.

Returns boolean: Whether the resolved value is true.

Example

const enabled = await subscrio.featureChecker.isEnabledForCustomer('acme', 'saas', 'export');
console.log(enabled);
Errors (1)
  • NotFoundError: The feature exists but is not associated with the product.
Task<bool> IsEnabledForCustomerAsync(string customerKey, string productKey, string featureKey)

Parameters

  • customerKey: Customer key.
  • productKey: Product key.
  • featureKey: Toggle feature key.

Returns bool: Whether the resolved value is true.

Example

var enabled = await subscrio.FeatureChecker.IsEnabledForCustomerAsync("acme", "saas", "export");
Console.WriteLine(enabled);
Errors (1)
  • NotFoundException: The feature exists but is not associated with the product.

getAllFeaturesForCustomer

Resolve all features associated with the product across the customer's subscriptions.

getAllFeaturesForCustomer(customerKey: string, productKey: string): Promise<Map<string, string>>

Parameters

  • customerKey: Customer key.
  • productKey: Product key.

Returns Map<string, string>: Feature keys mapped to resolved string values. Empty when customer or product is missing.

Example

const values = await subscrio.featureChecker.getAllFeaturesForCustomer('acme', 'saas');
console.log(values);
Errors (1)
  • ValidationError: Combining configured values overflows the supported numeric range.
Task<Dictionary<string, string>> GetAllFeaturesForCustomerAsync(string customerKey, string productKey)

Parameters

  • customerKey: Customer key.
  • productKey: Product key.

Returns Dictionary<string, string>: Feature keys mapped to resolved string values. Empty when customer or product is missing.

Example

var values = await subscrio.FeatureChecker.GetAllFeaturesForCustomerAsync("acme", "saas");
Console.WriteLine(values.Count);
Errors (1)
  • ValidationException: Combining configured values overflows the supported numeric range.

getValueForSubscription

Resolve a feature for one subscription, including its add-ons and unexpired override. This lookup does not reject inactive or archived subscriptions; it is not a subscription-status check.

Supply a numeric or boolean fallback to request that runtime conversion; a generic type argument alone does not convert the stored string.

The generic type controls conversion. Invalid conversions return the fallback or the type's default value.

getValueForSubscription<T = string>(subscriptionKey: string, featureKey: string, defaultValue?: T): Promise<T | null>

Parameters

  • subscriptionKey: Subscription key.
  • featureKey: Feature key.
  • defaultValue: Optional fallback for missing records or failed conversion. Defaults to null.

Returns T | null: Resolved value or fallback.

Example

const seats = await subscrio.featureChecker.getValueForSubscription('acme-pro', 'max-seats', 0);
console.log(seats);
Errors (2)
  • NotFoundError: The feature exists but is not associated with the product, or required resolution context is missing.
  • ValidationError: Combining configured values overflows the supported numeric range.
Task<T?> GetValueForSubscriptionAsync<T>(string subscriptionKey, string featureKey, T? defaultValue)

Parameters

  • subscriptionKey: Subscription key.
  • featureKey: Feature key.
  • defaultValue: Optional fallback for missing records or failed conversion. Defaults to default(T).

Returns T?: Resolved value or fallback; a non-nullable value type uses its default when no fallback is supplied.

Example

var seats = await subscrio.FeatureChecker.GetValueForSubscriptionAsync<int>("acme-pro", "max-seats", 0);
Console.WriteLine(seats);
Errors (2)
  • NotFoundException: The feature exists but is not associated with the product, or required resolution context is missing.
  • ValidationException: Combining configured values overflows the supported numeric range.

isEnabledForSubscription

Return true only when the resolved string equals true, ignoring case. Missing records return false. Subscription status is not checked by this lookup.

isEnabledForSubscription(subscriptionKey: string, featureKey: string): Promise<boolean>

Parameters

  • subscriptionKey: Subscription key.
  • featureKey: Toggle feature key.

Returns boolean: Whether the resolved value is true.

Example

const enabled = await subscrio.featureChecker.isEnabledForSubscription('acme-pro', 'export');
console.log(enabled);
Errors (1)
  • NotFoundError: The feature exists but is not associated with the product.
Task<bool> IsEnabledForSubscriptionAsync(string subscriptionKey, string featureKey)

Parameters

  • subscriptionKey: Subscription key.
  • featureKey: Toggle feature key.

Returns bool: Whether the resolved value is true.

Example

var enabled = await subscrio.FeatureChecker.IsEnabledForSubscriptionAsync("acme-pro", "export");
Console.WriteLine(enabled);
Errors (1)
  • NotFoundException: The feature exists but is not associated with the product.

getAllFeaturesForSubscription

Resolve all features associated with the subscription's product, without checking subscription status.

getAllFeaturesForSubscription(subscriptionKey: string): Promise<Map<string, string>>

Parameters

  • subscriptionKey: Subscription key.

Returns Map<string, string>: Feature keys mapped to resolved string values. Empty when the related plan is missing.

Example

const values = await subscrio.featureChecker.getAllFeaturesForSubscription('acme-pro');
console.log(values);
Errors (2)
  • NotFoundError: The subscription or related product is missing.
  • ValidationError: Combining configured values overflows the supported numeric range.
Task<Dictionary<string, string>> GetAllFeaturesForSubscriptionAsync(string subscriptionKey)

Parameters

  • subscriptionKey: Subscription key.

Returns Dictionary<string, string>: Feature keys mapped to resolved string values. Empty when the related plan is missing.

Example

var values = await subscrio.FeatureChecker.GetAllFeaturesForSubscriptionAsync("acme-pro");
Console.WriteLine(values.Count);
Errors (2)
  • NotFoundException: The subscription or related product is missing.
  • ValidationException: Combining configured values overflows the supported numeric range.

hasPlanAccess

Check for an active or trial subscription on the specified product and plan. This helper inspects up to the first 100 customer subscriptions and does not independently exclude archived records.

hasPlanAccess(customerKey: string, productKey: string, planKey: string): Promise<boolean>

Parameters

  • customerKey: Customer key.
  • productKey: Product key.
  • planKey: Plan key.

Returns boolean: False when any key is missing or the plan does not belong to the product.

Example

const result = await subscrio.featureChecker.hasPlanAccess('acme', 'saas', 'pro');
console.log(result);

Task<bool> HasPlanAccessAsync(string customerKey, string productKey, string planKey)

Parameters

  • customerKey: Customer key.
  • productKey: Product key.
  • planKey: Plan key.

Returns bool: False when any key is missing or the plan does not belong to the product.

Example

var result = await subscrio.FeatureChecker.HasPlanAccessAsync("acme", "saas", "pro");
Console.WriteLine(result);

getActivePlans

List distinct plan keys from active or trial subscriptions. This helper inspects up to the first 100 customer subscriptions and does not independently exclude archived records.

getActivePlans(customerKey: string): Promise<string[]>

Parameters

  • customerKey: Customer key.

Returns string[]: Plan keys, or an empty array when the customer is missing.

Example

const result = await subscrio.featureChecker.getActivePlans('acme');
console.log(result);

Task<List<string>> GetActivePlansAsync(string customerKey)

Parameters

  • customerKey: Customer key.

Returns List<string>: Plan keys, or an empty list when the customer is missing.

Example

var result = await subscrio.FeatureChecker.GetActivePlansAsync("acme");
Console.WriteLine(result);

getFeatureUsageSummary

Inspect resolved feature values grouped by type. Despite its name, this diagnostic does not report consumed usage; use Metered Usage for consumption. The subscription count considers up to 100 subscriptions and does not independently exclude archived records.

getFeatureUsageSummary(customerKey: string, productKey: string): Promise<{ activeSubscriptions: number; enabledFeatures: string[]; disabledFeatures: string[]; numericFeatures: Map<string, number>; meteredFeatures: Map<string, number>; textFeatures: Map<string, string> }>

Parameters

  • customerKey: Customer key.
  • productKey: Product key.

Returns Summary object: Resolved toggles, numeric values, metered limits, text, and subscription count.

Example

const summary = await subscrio.featureChecker.getFeatureUsageSummary('acme', 'saas');
console.log(summary.meteredFeatures);

Task<FeatureUsageSummaryDto> GetFeatureUsageSummaryAsync(string customerKey, string productKey)

Parameters

  • customerKey: Customer key.
  • productKey: Product key.

Returns FeatureUsageSummaryDto: Resolved values and subscription count.

Example

var summary = await subscrio.FeatureChecker.GetFeatureUsageSummaryAsync("acme", "saas");
Console.WriteLine(summary.MeteredFeatures.Count);

explainForCustomer

Explain why a feature resolves to its current value, including plan/default values, add-ons, and applied or expired overrides. Use this optional diagnostic for troubleshooting or support screens.

explainForCustomer(customerKey: string, productKey: string, featureKey: string): Promise<FeatureValueExplanationDto>

Parameters

  • customerKey: Customer key.
  • productKey: Product key.
  • featureKey: Feature key.

Returns FeatureValueExplanationDto: Effective value, rules, and contributing sources.

Example

const explanation = await subscrio.featureChecker.explainForCustomer('acme', 'saas', 'max-seats');
console.log(explanation.effectiveValue, explanation.subscriptions);
Errors (2)
  • NotFoundError: The customer, associated feature, or subscription context is missing.
  • ValidationError: The subscription context is inconsistent or value arithmetic overflows.
Task<FeatureValueExplanationDto> ExplainForCustomerAsync(string customerKey, string productKey, string featureKey)

Parameters

  • customerKey: Customer key.
  • productKey: Product key.
  • featureKey: Feature key.

Returns FeatureValueExplanationDto: Effective value, rules, and contributing sources.

Example

var explanation = await subscrio.FeatureChecker.ExplainForCustomerAsync("acme", "saas", "max-seats");
Console.WriteLine(explanation.EffectiveValue);
Errors (2)
  • NotFoundException: The customer, associated feature, or subscription context is missing.
  • ValidationException: The subscription context is inconsistent or value arithmetic overflows.

explainForSubscription

Explain why a feature resolves to its current value, including plan/default values, add-ons, and applied or expired overrides. Use this optional diagnostic for troubleshooting or support screens. It evaluates one subscription even if inactive or archived.

explainForSubscription(subscriptionKey: string, featureKey: string): Promise<FeatureValueExplanationDto>

Parameters

  • subscriptionKey: Subscription key.
  • featureKey: Feature key.

Returns FeatureValueExplanationDto: Effective value, rules, and contributing sources.

Example

const explanation = await subscrio.featureChecker.explainForSubscription('acme-pro', 'max-seats');
console.log(explanation.effectiveValue, explanation.subscriptions);
Errors (2)
  • NotFoundError: The customer, associated feature, or subscription context is missing.
  • ValidationError: The subscription context is inconsistent or value arithmetic overflows.
Task<FeatureValueExplanationDto> ExplainForSubscriptionAsync(string subscriptionKey, string featureKey)

Parameters

  • subscriptionKey: Subscription key.
  • featureKey: Feature key.

Returns FeatureValueExplanationDto: Effective value, rules, and contributing sources.

Example

var explanation = await subscrio.FeatureChecker.ExplainForSubscriptionAsync("acme-pro", "max-seats");
Console.WriteLine(explanation.EffectiveValue);
Errors (2)
  • NotFoundException: The customer, associated feature, or subscription context is missing.
  • ValidationException: The subscription context is inconsistent or value arithmetic overflows.

Data types

Required indicates whether a returned property is guaranteed present.

FeatureUsageSummaryDto

Resolved-value summary, an inline object in TypeScript and a named DTO in .NET.

Field Type Required Default Meaning
activeSubscriptions number Yes Not applicable Active or trial subscriptions counted for this product.
enabledFeatures string[] Yes Not applicable Toggle keys whose resolved value is true.
disabledFeatures string[] Yes Not applicable Other toggle keys.
numericFeatures Map<string, number> Yes Not applicable Feature keys mapped to resolved numeric values.
meteredFeatures Map<string, number> Yes Not applicable Metered feature keys mapped to resolved limits, not consumed usage.
textFeatures Map<string, string> Yes Not applicable Feature keys mapped to resolved text.
Property Type Required Default Meaning
ActiveSubscriptions int Yes Not applicable Active or trial subscriptions counted for this product.
EnabledFeatures List<string> Yes Not applicable Toggle keys whose resolved value is true.
DisabledFeatures List<string> Yes Not applicable Other toggle keys.
NumericFeatures Dictionary<string, double> Yes Not applicable Feature keys mapped to resolved numeric values.
TextFeatures Dictionary<string, string> Yes Not applicable Feature keys mapped to resolved text.
MeteredFeatures Dictionary<string, long> Yes Not applicable Metered feature keys mapped to resolved limits, not consumed usage.

FeatureValueExplanationDto

Explanation returned by the diagnostic methods.

Field Type Required Default Meaning
evaluatedAt string Yes Not applicable UTC evaluation timestamp.
effectiveValue string Yes Not applicable Final resolved value as a string.
resolution FeatureResolutionOptions Yes Not applicable Product-feature resolution options.
subscriptions Array<{ subscriptionKey: string; value: string; sources: FeatureValueSourceDto[] }> Yes Not applicable Per-subscription values and sources, documented below.
Property Type Required Default Meaning
EvaluatedAt string Yes Not applicable UTC evaluation timestamp.
EffectiveValue string Yes Not applicable Final resolved value as a string.
Resolution FeatureResolutionOptions Yes Not applicable Product-feature resolution options.
Subscriptions List<SubscriptionFeatureValueDto> Yes Not applicable Per-subscription values and sources, documented below.

SubscriptionFeatureValueDto

One subscription result; represented as an inline object in TypeScript.

Field Type Required Default Meaning
subscriptionKey string Yes Not applicable Subscription key.
value string Yes Not applicable Resolved value for this subscription.
sources FeatureValueSourceDto[] Yes Not applicable Candidate value sources.
Property Type Required Default Meaning
SubscriptionKey string Yes Not applicable Subscription key.
Value string Yes Not applicable Resolved value for this subscription.
Sources List<FeatureValueSourceDto> Yes Not applicable Candidate value sources.

FeatureValueSourceDto

A value considered during resolution.

Field Type Required Default Meaning
kind "override" | "plan" | "addon" | "default" Yes Not applicable override, plan, addon, or default.
key string Yes Not applicable Key of the source subscription, plan, add-on, or feature.
value string Yes Not applicable Unscaled source value as a string.
quantity number | undefined No Not applicable Attachment quantity for an add-on.
expiresAt string | null | undefined No Not applicable Timed override expiry, when applicable.
applied boolean Yes Not applicable Whether the source contributed within its subscription; not a guarantee that it won across subscriptions.
reason string | undefined No Not applicable Explanation when a source was replaced, lost priority, or expired.
Property Type Required Default Meaning
Kind string Yes Not applicable override, plan, addon, or default.
Key string Yes Not applicable Key of the source subscription, plan, add-on, or feature.
Value string Yes Not applicable Unscaled source value as a string.
Applied bool Yes Not applicable Whether the source contributed within its subscription; not a guarantee that it won across subscriptions.
Quantity int? Yes Not applicable Attachment quantity for an add-on.
ExpiresAt string? Yes Not applicable Timed override expiry, when applicable.
Reason string? Yes Not applicable Explanation when a source was replaced, lost priority, or expired.