Skip to content

Plans

Purpose

Plans define the feature values offered by a product. Billing cycles provide their billing cadence, and subscriptions select a plan through a billing cycle. Plans can also nominate a billing cycle to use after expiration.

Access and initialization

Access

const plans = subscrio.plans;

using Subscrio.Core.Application.DTOs;

var plans = subscrio.Plans;

Method catalog

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

Method Purpose
createPlan Creates an active plan.
updatePlan Updates plan details or its transition target.
getPlan Gets a plan or null.
listPlans Lists matching plans.
getPlansByProduct Lists all plans for a product.
setFeatureValue Sets a plan feature value.
removeFeatureValue Removes a plan feature value.
getFeatureValue Reads a stored plan value.
getPlanFeatures Lists stored plan feature values.
archivePlan Archives a plan.
unarchivePlan Restores a plan.
deletePlan Permanently deletes an unused plan.
Method Purpose
CreatePlanAsync Creates an active plan.
UpdatePlanAsync Updates plan details or its transition target.
GetPlanAsync Gets a plan or null.
ListPlansAsync Lists matching plans.
GetPlansByProductAsync Lists all plans for a product.
SetFeatureValueAsync Sets a plan feature value.
RemoveFeatureValueAsync Removes a plan feature value.
GetFeatureValueAsync Reads a stored plan value.
GetPlanFeaturesAsync Lists stored plan feature values.
ArchivePlanAsync Archives a plan.
UnarchivePlanAsync Restores a plan.
DeletePlanAsync Permanently deletes an unused plan.

Method details

createPlan

Create an active plan under an existing product. The plan key is globally unique and cannot be changed. Assign feature values after creation.

createPlan(dto: CreatePlanDto): Promise<PlanDto>

Parameters

Returns PlanDto: Saved plan details and its product's add-on catalog.

Example

// pro-suite exists.
await subscrio.plans.createPlan({
  productKey: 'pro-suite', key: 'pro', displayName: 'Pro'
});
Errors (4)
  • ValidationError: The plan properties are invalid.
  • ConflictError: The plan key already exists.
  • NotFoundError: The product is missing.
  • Error: The specified expiration billing cycle does not exist.
Task<PlanDto> CreatePlanAsync(CreatePlanDto dto)

Parameters

Returns PlanDto: Saved plan details and its product's add-on catalog.

Example

// pro-suite exists.
await subscrio.Plans.CreatePlanAsync(new CreatePlanDto(
    ProductKey: "pro-suite", Key: "pro", DisplayName: "Pro"));
Errors (3)
  • ValidationException: The plan properties are invalid.
  • ConflictException: The plan key already exists.
  • NotFoundException: The product or specified expiration billing cycle is missing.

updatePlan

Update mutable plan details without changing its key or product. Use the explicit clear flag to remove an expiration-transition target; the clear flag takes precedence over a supplied target. Changing the target does not itself transition subscriptions.

updatePlan(planKey: string, dto: UpdatePlanDto): Promise<PlanDto>

Parameters

Returns PlanDto: Saved plan details and its product's add-on catalog.

Example

await subscrio.plans.updatePlan('pro', {
  clearOnExpireTransitionToBillingCycleKey: true
});
Errors (3)
  • ValidationError: A supplied property is invalid.
  • NotFoundError: The plan does not exist.
  • Error: The specified expiration billing cycle does not exist.
Task<PlanDto> UpdatePlanAsync(string planKey, UpdatePlanDto dto)

Parameters

Returns PlanDto: Saved plan details and its product's add-on catalog.

Example

await subscrio.Plans.UpdatePlanAsync("pro", new UpdatePlanDto(
    ClearOnExpireTransitionToBillingCycleKey: true));
Errors (2)
  • ValidationException: A supplied property is invalid.
  • NotFoundException: The plan or specified expiration billing cycle does not exist.

getPlan

Retrieve a plan definition, including archived plans.

getPlan(planKey: string): Promise<PlanDto | null>

Parameters

  • planKey: Plan key.

Returns PlanDto | null: Plan and add-on catalog, or null when missing.

Example

const plan = await subscrio.plans.getPlan('pro');
console.log(plan?.addons);

Task<PlanDto?> GetPlanAsync(string planKey)

Parameters

  • planKey: Plan key.

Returns PlanDto?: Plan and add-on catalog, or null when missing.

Example

var plan = await subscrio.Plans.GetPlanAsync("pro");
Console.WriteLine(plan?.Addons.Count);

listPlans

List plans with filtering, sorting, and pagination. TypeScript defaults to creation time ascending; .NET defaults to display name ascending.

listPlans(filters?: PlanFilterDto): Promise<PlanDto[]>

Parameters

  • filters: Optional PlanFilterDto. Defaults to 50 records at offset zero.

Returns PlanDto[]: Matching plans and add-on catalogs, or an empty collection.

Example

const plans = await subscrio.plans.listPlans({
  productKey: 'pro-suite', status: 'active', limit: 20, offset: 0
});
console.log(plans);
Errors (1)
  • ValidationError: A filter or pagination value is invalid.
Task<List<PlanDto>> ListPlansAsync(PlanFilterDto? filters)

Parameters

  • filters: Optional PlanFilterDto. Defaults to 50 records at offset zero.

Returns List<PlanDto>: Matching plans and add-on catalogs, or an empty collection.

Example

var plans = await subscrio.Plans.ListPlansAsync(
    new PlanFilterDto(ProductKey: "pro-suite", Status: "active", Limit: 20));
Console.WriteLine(plans.Count);
Errors (1)
  • ValidationException: A filter or pagination value is invalid.

getPlansByProduct

List every plan belonging to a product, including archived plans. This method does not paginate.

getPlansByProduct(productKey: string): Promise<PlanDto[]>

Parameters

  • productKey: Product key.

Returns PlanDto[]: Product plans, or an empty collection when none exist.

Example

const plans = await subscrio.plans.getPlansByProduct('pro-suite');
console.log(plans);
Errors (1)
  • NotFoundError: The product does not exist.
Task<List<PlanDto>> GetPlansByProductAsync(string productKey)

Parameters

  • productKey: Product key.

Returns List<PlanDto>: Product plans, or an empty collection when none exist.

Example

var plans = await subscrio.Plans.GetPlansByProductAsync("pro-suite");
Console.WriteLine(plans.Count);
Errors (1)
  • NotFoundException: The product does not exist.

setFeatureValue

Set or replace a plan's value for a feature associated with its product. This value participates in feature resolution; it does not change the global feature default.

setFeatureValue(planKey: string, featureKey: string, value: string): Promise<void>

Parameters

  • planKey: Plan key.
  • featureKey: Global feature key.
  • value: Value stored as a string; must be valid for the feature type.

Returns No returned value.

Example

// pro exists; seats is associated with its product.
await subscrio.plans.setFeatureValue('pro', 'seats', '20');
Errors (2)
  • NotFoundError: The plan or feature does not exist.
  • ValidationError: The feature is not associated with the plan's product, or the value is invalid.
Task SetFeatureValueAsync(string planKey, string featureKey, string value)

Parameters

  • planKey: Plan key.
  • featureKey: Global feature key.
  • value: Value stored as a string; must be valid for the feature type.

Returns No returned value.

Example

// pro exists; seats is associated with its product.
await subscrio.Plans.SetFeatureValueAsync("pro", "seats", "20");
Errors (2)
  • NotFoundException: The plan or feature does not exist.
  • ValidationException: The feature is not associated with the plan's product, or the value is invalid.

removeFeatureValue

Remove the stored plan value. Feature resolution can then fall back to the feature default unless another applicable source supplies a value. Removing an absent value makes no changes.

removeFeatureValue(planKey: string, featureKey: string): Promise<void>

Parameters

  • planKey: Plan key.
  • featureKey: Global feature key.

Returns No returned value.

Example

// pro exists; seats is associated with its product.
await subscrio.plans.removeFeatureValue('pro', 'seats');
Errors (1)
  • NotFoundError: The plan or feature does not exist.
Task RemoveFeatureValueAsync(string planKey, string featureKey)

Parameters

  • planKey: Plan key.
  • featureKey: Global feature key.

Returns No returned value.

Example

// pro exists; seats is associated with its product.
await subscrio.Plans.RemoveFeatureValueAsync("pro", "seats");
Errors (1)
  • NotFoundException: The plan or feature does not exist.

getFeatureValue

Read the stored plan value directly. This does not resolve subscription overrides or add-ons.

getFeatureValue(planKey: string, featureKey: string): Promise<string | null>

Parameters

  • planKey: Plan key.
  • featureKey: Global feature key.

Returns string | null: Stored value, or null if the feature or value is missing.

Example

// pro exists; seats is associated with its product.
const value = await subscrio.plans.getFeatureValue('pro', 'seats');
console.log(value);
Errors (1)
  • NotFoundError: The plan does not exist.
Task<string?> GetFeatureValueAsync(string planKey, string featureKey)

Parameters

  • planKey: Plan key.
  • featureKey: Global feature key.

Returns string?: Stored value, or null if the feature or value is missing.

Example

// pro exists; seats is associated with its product.
var value = await subscrio.Plans.GetFeatureValueAsync("pro", "seats");
Console.WriteLine(value);
Errors (1)
  • NotFoundException: The plan does not exist.

getPlanFeatures

List the feature values explicitly stored on a plan. Features using only their global defaults are not included.

getPlanFeatures(planKey: string): Promise<{ featureKey: string; value: string; }[]>

Parameters

  • planKey: Plan key.

Returns Array<{ featureKey: string; value: string }>: Stored feature-value entries; empty when none are set.

Example

const values = await subscrio.plans.getPlanFeatures('pro');
console.log(values);
Errors (1)
  • NotFoundError: The plan does not exist.
Task<List<PlanFeatureDto>> GetPlanFeaturesAsync(string planKey)

Parameters

  • planKey: Plan key.

Returns List<PlanFeatureDto>: Stored feature values; empty when none are set.

Example

var values = await subscrio.Plans.GetPlanFeaturesAsync("pro");
Console.WriteLine(values.Count);
Errors (1)
  • NotFoundException: The plan does not exist.

archivePlan

Mark the plan as archived while retaining its feature values and billing cycles. Existing subscriptions are not cancelled by this operation.

archivePlan(planKey: string): Promise<void>

Parameters

  • planKey: Plan key.

Returns No returned value.

Example

// pro exists.
await subscrio.plans.archivePlan('pro');
Errors (1)
  • NotFoundError: The plan does not exist.
Task ArchivePlanAsync(string planKey)

Parameters

  • planKey: Plan key.

Returns No returned value.

Example

// pro exists.
await subscrio.Plans.ArchivePlanAsync("pro");
Errors (1)
  • NotFoundException: The plan does not exist.

unarchivePlan

Restore the plan to active status, retaining its saved values and billing cycles.

unarchivePlan(planKey: string): Promise<void>

Parameters

  • planKey: Plan key.

Returns No returned value.

Example

// pro exists.
await subscrio.plans.unarchivePlan('pro');
Errors (1)
  • NotFoundError: The plan does not exist.
Task UnarchivePlanAsync(string planKey)

Parameters

  • planKey: Plan key.

Returns No returned value.

Example

// pro exists.
await subscrio.Plans.UnarchivePlanAsync("pro");
Errors (1)
  • NotFoundException: The plan does not exist.

deletePlan

Permanently delete an archived plan. All subscriptions and billing cycles referencing it must be removed first, regardless of their status. Cancelling subscriptions or archiving billing cycles alone does not permit deletion.

deletePlan(planKey: string): Promise<void>

Parameters

  • planKey: Plan key.

Returns No returned value.

Example

// pro is archived and has no references.
await subscrio.plans.deletePlan('pro');
Errors (2)
  • NotFoundError: The plan does not exist.
  • DomainError: The plan is active or has references that block deletion.
Task DeletePlanAsync(string planKey)

Parameters

  • planKey: Plan key.

Returns No returned value.

Example

// pro is archived and has no references.
await subscrio.Plans.DeletePlanAsync("pro");
Errors (2)
  • NotFoundException: The plan does not exist.
  • DomainException: The plan is active or has references that block deletion.

Data types

Required refers to supplied input fields or guaranteed returned properties. Type documents nullability.

CreatePlanDto

Properties for a new plan.

Field Type Required Default Meaning
productKey string Yes None Owning product key.
key string Yes None Stable identifier.
displayName string Yes None Human-readable label, 1 to 255 characters.
description string | undefined No None Optional description, up to 1,000 characters.
onExpireTransitionToBillingCycleKey string | undefined No None Existing billing cycle to use for expiration transitions. The subscription transition processor applies this target.
metadata Record<string, unknown> | undefined No None Application-defined metadata. Supplying it on update replaces the saved object; an empty object clears entries.
Property Type Required Default Meaning
ProductKey string Yes None Owning product key.
Key string Yes None Stable identifier.
DisplayName string Yes None Human-readable label, 1 to 255 characters.
Description string? No null Optional description, up to 1,000 characters.
OnExpireTransitionToBillingCycleKey string? No null Existing billing cycle to use for expiration transitions. The subscription transition processor applies this target.
Metadata Dictionary<string, object?>? No null Application-defined metadata. Supplying it on update replaces the saved object; an empty object clears entries.

PlanDto

Plan details and the owning product's add-on catalog.

Field Type Required Default Meaning
addons AddonDto[] Yes Not applicable Related add-on definitions.
productKey string Yes Not applicable Owning product key.
key string Yes Not applicable Stable identifier.
displayName string Yes Not applicable Human-readable label, 1 to 255 characters.
description string | null | undefined No Not applicable Optional description, up to 1,000 characters.
status string Yes Not applicable Current record status.
onExpireTransitionToBillingCycleKey string | null | undefined No Not applicable Existing billing cycle to use for expiration transitions. The subscription transition processor applies this target.
metadata Record<string, unknown> | null | undefined No Not applicable Application-defined metadata. Supplying it on update replaces the saved object; an empty object clears entries.
createdAt string Yes Not applicable Creation time in UTC.
updatedAt string Yes Not applicable Last update time in UTC.
Property Type Required Default Meaning
ProductKey string Yes Not applicable Owning product key.
Key string Yes Not applicable Stable identifier.
DisplayName string Yes Not applicable Human-readable label, 1 to 255 characters.
Description string? Yes Not applicable Optional description, up to 1,000 characters.
Status string Yes Not applicable Current record status.
OnExpireTransitionToBillingCycleKey string? Yes Not applicable Existing billing cycle to use for expiration transitions. The subscription transition processor applies this target.
Metadata Dictionary<string, object?>? Yes Not applicable Application-defined metadata. Supplying it on update replaces the saved object; an empty object clears entries.
CreatedAt string Yes Not applicable Creation time in UTC.
UpdatedAt string Yes Not applicable Last update time in UTC.
Addons List<AddonDto> Yes Not applicable Related add-on definitions.

UpdatePlanDto

Editable plan properties. Uses partial updates.

Field Type Required Default Meaning
displayName string | undefined No None Human-readable label, 1 to 255 characters.
description string | undefined No None Optional description, up to 1,000 characters.
onExpireTransitionToBillingCycleKey string | undefined No None Existing billing cycle to use for expiration transitions. The subscription transition processor applies this target.
clearOnExpireTransitionToBillingCycleKey boolean | undefined No None True removes the expiration target, even when a replacement target is also supplied.
metadata Record<string, unknown> | undefined No None Application-defined metadata. Supplying it on update replaces the saved object; an empty object clears entries.
Property Type Required Default Meaning
DisplayName string? No null Human-readable label, 1 to 255 characters.
Description string? No null Optional description, up to 1,000 characters.
OnExpireTransitionToBillingCycleKey string? No null Existing billing cycle to use for expiration transitions. The subscription transition processor applies this target.
ClearOnExpireTransitionToBillingCycleKey bool No false True removes the expiration target, even when a replacement target is also supplied.
Metadata Dictionary<string, object?>? No null Application-defined metadata. Supplying it on update replaces the saved object; an empty object clears entries.

PlanFilterDto

Filters for the plan catalog. TypeScript requires limit and offset when supplying a filter object.

Field Type Required Default Meaning
limit number Yes 50 Maximum page size, 1 to 100.
offset number Yes 0 Nonnegative number of rows to skip.
productKey string | undefined No None Restrict results to one product.
status "active" | "archived" | undefined No None Filter by active or archived status.
search string | undefined No None Match plan key or display name.
sortBy "displayName" | "createdAt" | undefined No None displayName or createdAt. Defaults to createdAt.
sortOrder "asc" | "desc" | undefined No None asc or desc; defaults to asc when omitted.
Property Type Required Default Meaning
ProductKey string? No null Restrict results to one product.
Status string? No null Filter by active or archived status.
Search string? No null Match plan key or display name.
SortBy string? No null displayName or createdAt. Defaults to displayName.
SortOrder string? No null asc or desc; defaults to asc when omitted.
Limit int No 50 Maximum page size, 1 to 100.
Offset int No 0 Nonnegative number of rows to skip.

PlanFeatureDto

A stored plan feature value. TypeScript returns anonymous objects with these fields; .NET uses PlanFeatureDto.

Field Type Required Default Meaning
featureKey string Yes Not applicable Feature key.
value string Yes Not applicable Stored value, not a resolved subscription allowance.
Property Type Required Default Meaning
FeatureKey string Yes Not applicable Feature key.
Value string Yes Not applicable Stored value, not a resolved subscription allowance.