Skip to content

Subscriptions

Purpose

Subscriptions connect a customer to a plan through a billing cycle. Use this object to manage dates, attach add-ons, apply customer-specific feature overrides, and archive or transition subscriptions.

Access and initialization

Access

const subscriptions = subscrio.subscriptions;

var subscriptions = subscrio.Subscriptions;

Method catalog

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

Method Purpose
createSubscription Creates a customer subscription.
updateSubscription Updates dates and billing cycle.
getSubscription Gets a subscription or null.
listSubscriptions Lists matching subscriptions.
findSubscriptions Searches with additional date and presence filters.
getSubscriptionsByCustomer Lists all subscriptions for a customer.
attachAddon Attaches an add-on or replaces its quantity.
detachAddon Cancels an add-on attachment.
getAddons Lists attachment details.
addFeatureOverride Sets a subscription-specific feature value.
removeFeatureOverride Removes a feature override.
clearTemporaryOverrides Removes temporary overrides.
archiveSubscription Archives a subscription.
unarchiveSubscription Restores an archived subscription.
deleteSubscription Permanently deletes a subscription.
transitionExpiredSubscriptions Processes configured expiration transitions.
Method Purpose
CreateSubscriptionAsync Creates a customer subscription.
UpdateSubscriptionAsync Updates dates and billing cycle.
GetSubscriptionAsync Gets a subscription or null.
ListSubscriptionsAsync Lists matching subscriptions.
FindSubscriptionsAsync Searches with additional date and presence filters.
GetSubscriptionsByCustomerAsync Lists all subscriptions for a customer.
AttachAddonAsync Attaches an add-on or replaces its quantity.
DetachAddonAsync Cancels an add-on attachment.
GetAddonsAsync Lists attachment details.
AddFeatureOverrideAsync Sets a subscription-specific feature value.
RemoveFeatureOverrideAsync Removes a feature override.
ClearTemporaryOverridesAsync Removes temporary overrides.
ArchiveSubscriptionAsync Archives a subscription.
UnarchiveSubscriptionAsync Restores an archived subscription.
DeleteSubscriptionAsync Permanently deletes a subscription.
TransitionExpiredSubscriptionsAsync Processes configured expiration transitions.

Method details

createSubscription

Create a subscription using the selected billing cycle's plan and product. Activation and period start default to now; period end is calculated from the cycle unless supplied. A forever cycle has no period end. Mutations emit before and after hooks.

createSubscription(dto: CreateSubscriptionDto): Promise<SubscriptionDto>

Parameters

Returns SubscriptionDto: Saved subscription, overrides, and add-on attachments.

Example

// acme and pro-monthly exist.
await subscrio.subscriptions.createSubscription({
  key: 'acme-pro', customerKey: 'acme', billingCycleKey: 'pro-monthly'
});
Errors (3)
  • ValidationError: The input properties are invalid.
  • NotFoundError: The customer, cycle, plan, or product is missing.
  • ConflictError: The subscription key or Stripe subscription ID already exists.
Task<SubscriptionDto> CreateSubscriptionAsync(CreateSubscriptionDto dto)

Parameters

Returns SubscriptionDto: Saved subscription, overrides, and add-on attachments.

Example

// acme and pro-monthly exist.
await subscrio.Subscriptions.CreateSubscriptionAsync(new CreateSubscriptionDto(
    Key: "acme-pro", CustomerKey: "acme", BillingCycleKey: "pro-monthly"));
Errors (3)
  • ValidationException: The input properties are invalid.
  • NotFoundException: The customer, cycle, plan, or product is missing.
  • ConflictException: The subscription key or Stripe subscription ID already exists.

updateSubscription

Update a subscription that is not archived. The key, customer, and activation date cannot change. Selecting another billing cycle also changes the plan but does not recalculate the stored period dates. Supplied metadata replaces the entire object.

updateSubscription(subscriptionKey: string, dto: UpdateSubscriptionDto): Promise<SubscriptionDto>

Parameters

  • subscriptionKey: Subscription key.
  • dto: UpdateSubscriptionDto. Uses partial updates. Date nulls and empty date strings are treated as omission at runtime; use the trial-clear flag to remove a trial end.

Returns SubscriptionDto: Updated subscription details.

Example

await subscrio.subscriptions.updateSubscription('acme-pro', {
  clearTrialEndDate: true
});
Errors (3)
  • ValidationError: The updated properties are invalid.
  • NotFoundError: The subscription or selected billing cycle is missing.
  • DomainError: The subscription is archived.
Task<SubscriptionDto> UpdateSubscriptionAsync(string subscriptionKey, UpdateSubscriptionDto dto)

Parameters

Returns SubscriptionDto: Updated subscription details.

Example

await subscrio.Subscriptions.UpdateSubscriptionAsync("acme-pro",
    new UpdateSubscriptionDto(ClearTrialEndDate: true));
Errors (3)
  • ValidationException: The updated properties are invalid.
  • NotFoundException: The subscription or selected billing cycle is missing.
  • DomainException: The subscription is archived.

getSubscription

Retrieve subscription details, including archived subscriptions.

getSubscription(subscriptionKey: string): Promise<SubscriptionDto | null>

Parameters

  • subscriptionKey: Subscription key.

Returns SubscriptionDto | null: Subscription details, or null when missing.

Example

const subscription = await subscrio.subscriptions.getSubscription('acme-pro');
console.log(subscription?.addons);

Task<SubscriptionDto?> GetSubscriptionAsync(string subscriptionKey)

Parameters

  • subscriptionKey: Subscription key.

Returns SubscriptionDto?: Subscription details, or null when missing.

Example

var subscription = await subscrio.Subscriptions.GetSubscriptionAsync("acme-pro");
Console.WriteLine(subscription?.Addons.Count);

listSubscriptions

List subscriptions with pagination, including archived records unless filtered out. Missing customer, plan, or product filter keys return an empty collection.

listSubscriptions(filters?: SubscriptionFilterDto): Promise<SubscriptionDto[]>

Parameters

Returns SubscriptionDto[]: Matching subscriptions with customer details, overrides, and attachments.

Example

const matches = await subscrio.subscriptions.listSubscriptions({
  customerKey: 'acme', isArchived: false, limit: 20, offset: 0
});
console.log(matches);
Errors (1)
  • ValidationError: The filter values are invalid.
Task<List<SubscriptionDto>> ListSubscriptionsAsync(SubscriptionFilterDto? filters)

Parameters

Returns List<SubscriptionDto>: Matching subscriptions with customer details, overrides, and attachments.

Example

var matches = await subscrio.Subscriptions.ListSubscriptionsAsync(
    new SubscriptionFilterDto(CustomerKey: "acme", IsArchived: false, Limit: 20));
Console.WriteLine(matches.Count);
Errors (1)
  • ValidationException: The filter values are invalid.

findSubscriptions

Search subscriptions using additional date and presence filters. The override-presence check runs after pagination, so a page can contain fewer results than requested. Feature-key and metadata filters are currently ignored in both libraries.

findSubscriptions(filters: DetailedSubscriptionFilterDto): Promise<SubscriptionDto[]>

Parameters

Returns SubscriptionDto[]: Matching subscriptions with customer details, overrides, and attachments.

Example

const matches = await subscrio.subscriptions.findSubscriptions({
  customerKey: 'acme', isArchived: false, limit: 20, offset: 0
});
console.log(matches);
Errors (1)
  • ValidationError: The filter values are invalid.
Task<List<SubscriptionDto>> FindSubscriptionsAsync(DetailedSubscriptionFilterDto filters)

Parameters

Returns List<SubscriptionDto>: Matching subscriptions with customer details, overrides, and attachments.

Example

var matches = await subscrio.Subscriptions.FindSubscriptionsAsync(
    new DetailedSubscriptionFilterDto(CustomerKey: "acme", IsArchived: false, Limit: 20));
Console.WriteLine(matches.Count);
Errors (1)
  • ValidationException: The filter values are invalid.

getSubscriptionsByCustomer

Retrieve every subscription for the customer, including archived subscriptions. This lookup does not paginate.

getSubscriptionsByCustomer(customerKey: string): Promise<SubscriptionDto[]>

Parameters

  • customerKey: Customer key.

Returns SubscriptionDto[]: Customer subscriptions, or an empty collection.

Example

const subscriptions = await subscrio.subscriptions.getSubscriptionsByCustomer('acme');
console.log(subscriptions);
Errors (1)
  • NotFoundError: The customer does not exist.
Task<List<SubscriptionDto>> GetSubscriptionsByCustomerAsync(string customerKey)

Parameters

  • customerKey: Customer key.

Returns List<SubscriptionDto>: Customer subscriptions, or an empty collection.

Example

var subscriptions = await subscrio.Subscriptions.GetSubscriptionsByCustomerAsync("acme");
Console.WriteLine(subscriptions.Count);
Errors (1)
  • NotFoundException: The customer does not exist.

attachAddon

Attach an active add-on from the subscription's product. Reattaching replaces the quantity and reactivates a cancelled attachment. The subscription must not be archived; replacement add-ons require quantity one.

attachAddon(subscriptionKey: string, addonKey: string, quantity?: number): Promise<SubscriptionAddonDto>

Parameters

  • subscriptionKey: Subscription key.
  • addonKey: Add-on definition key.
  • quantity: Optional positive integer, at most 2,147,483,647; defaults to 1.

Returns SubscriptionAddonDto: Saved attachment with the add-on definition.

Example

// extra-seats is an additive add-on for this subscription's product.
await subscrio.subscriptions.attachAddon('acme-pro', 'extra-seats', 2);
Errors (2)
  • NotFoundError: The subscription, customer, or add-on is missing.
  • ValidationError: The quantity, product, add-on status, or subscription archive status is invalid.
Task<SubscriptionAddonDto> AttachAddonAsync(string subscriptionKey, string addonKey, int quantity)

Parameters

  • subscriptionKey: Subscription key.
  • addonKey: Add-on definition key.
  • quantity: Optional positive integer, at most 2,147,483,647; defaults to 1.

Returns SubscriptionAddonDto: Saved attachment with the add-on definition.

Example

// extra-seats is an additive add-on for this subscription's product.
await subscrio.Subscriptions.AttachAddonAsync("acme-pro", "extra-seats", 2);
Errors (2)
  • NotFoundException: The subscription, customer, or add-on is missing.
  • ValidationException: The quantity, product, add-on status, or subscription archive status is invalid.

detachAddon

Mark the attachment cancelled so it no longer contributes feature values. Its history remains available; calling again on an already-cancelled attachment succeeds.

detachAddon(subscriptionKey: string, addonKey: string): Promise<void>

Parameters

  • subscriptionKey: Subscription key.
  • addonKey: Attached add-on key.

Returns No returned value.

Example

await subscrio.subscriptions.detachAddon('acme-pro', 'extra-seats');
Errors (1)
  • NotFoundError: The subscription or attachment does not exist.
Task DetachAddonAsync(string subscriptionKey, string addonKey)

Parameters

  • subscriptionKey: Subscription key.
  • addonKey: Attached add-on key.

Returns No returned value.

Example

await subscrio.Subscriptions.DetachAddonAsync("acme-pro", "extra-seats");
Errors (1)
  • NotFoundException: The subscription or attachment does not exist.

getAddons

List active and cancelled attachments in add-on-key order. Each includes the current add-on definition.

getAddons(subscriptionKey: string, filter?: PageFilter): Promise<SubscriptionAddonDto[]>

Parameters

  • subscriptionKey: Subscription key.
  • filter: Optional PageFilter; defaults to 50 results at offset zero.

Returns SubscriptionAddonDto[]: Attachments, or an empty collection when none exist or the subscription is missing.

Example

const addons = await subscrio.subscriptions.getAddons('acme-pro');
console.log(addons);
Errors (1)
  • ValidationError: Pagination is invalid.
Task<List<SubscriptionAddonDto>> GetAddonsAsync(string subscriptionKey, int limit, int offset)

Parameters

  • subscriptionKey: Subscription key.
  • limit: Optional page size, 1 to 500; defaults to 50.
  • offset: Optional nonnegative rows to skip; defaults to 0.

Returns List<SubscriptionAddonDto>: Attachments, or an empty collection when none exist or the subscription is missing.

Example

var addons = await subscrio.Subscriptions.GetAddonsAsync("acme-pro");
Console.WriteLine(addons.Count);
Errors (1)
  • ValidationException: Pagination is invalid.

addFeatureOverride

Set a feature value specifically for this subscription, replacing any existing override for that feature. Timed overrides stop applying at their expiry but remain in returned history. The subscription must not be archived.

addFeatureOverride(subscriptionKey: string, featureKey: string, value: string, overrideType?: OverrideType, expiresAt?: Date | string | null): Promise<void>

Parameters

  • subscriptionKey: Subscription key.
  • featureKey: Feature key.
  • value: String value valid for the feature's type.
  • overrideType: Optional OverrideType, default Permanent.
  • expiresAt: Required future UTC timestamp for Timed; omitted or null for other types.

Returns No returned value.

Example

import { OverrideType } from 'subscrio';

// max-seats is a numeric feature.
await subscrio.subscriptions.addFeatureOverride(
  'acme-pro', 'max-seats', '50', OverrideType.Permanent
);
Errors (3)
  • NotFoundError: The subscription or feature is missing.
  • ValidationError: The value, override type, or expiry is invalid.
  • DomainError: The subscription is archived.
Task AddFeatureOverrideAsync(string subscriptionKey, string featureKey, string value, OverrideType overrideType, DateTime? expiresAt)

Parameters

  • subscriptionKey: Subscription key.
  • featureKey: Feature key.
  • value: String value valid for the feature's type.
  • overrideType: Optional OverrideType, default Permanent.
  • expiresAt: Required future UTC timestamp for Timed; omitted or null for other types.

Returns No returned value.

Example

// max-seats is a numeric feature.
await subscrio.Subscriptions.AddFeatureOverrideAsync(
    "acme-pro", "max-seats", "50",
    Subscrio.Core.Domain.ValueObjects.OverrideType.Permanent);
Errors (3)
  • NotFoundException: The subscription or feature is missing.
  • ValidationException: The value, override type, or expiry is invalid.
  • DomainException: The subscription is archived.

removeFeatureOverride

Remove the override for one feature. If no override is set, the operation succeeds without adding one. The subscription must not be archived.

removeFeatureOverride(subscriptionKey: string, featureKey: string): Promise<void>

Parameters

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

Returns No returned value.

Example

await subscrio.subscriptions.removeFeatureOverride('acme-pro', 'max-seats');
Errors (2)
  • NotFoundError: The subscription or feature is missing.
  • DomainError: The subscription is archived.
Task RemoveFeatureOverrideAsync(string subscriptionKey, string featureKey)

Parameters

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

Returns No returned value.

Example

await subscrio.Subscriptions.RemoveFeatureOverrideAsync("acme-pro", "max-seats");
Errors (2)
  • NotFoundException: The subscription or feature is missing.
  • DomainException: The subscription is archived.

clearTemporaryOverrides

Remove only Temporary overrides. Permanent and Timed overrides remain. The subscription must not be archived.

clearTemporaryOverrides(subscriptionKey: string): Promise<void>

Parameters

  • subscriptionKey: Subscription key.

Returns No returned value.

Example

await subscrio.subscriptions.clearTemporaryOverrides('acme-pro');
Errors (2)
  • NotFoundError: The subscription is missing.
  • DomainError: The subscription is archived.
Task ClearTemporaryOverridesAsync(string subscriptionKey)

Parameters

  • subscriptionKey: Subscription key.

Returns No returned value.

Example

await subscrio.Subscriptions.ClearTemporaryOverridesAsync("acme-pro");
Errors (2)
  • NotFoundException: The subscription is missing.
  • DomainException: The subscription is archived.

archiveSubscription

Archive the subscription without changing its dates or calculated status. It cannot be updated until restored. Customer feature checks exclude archived subscriptions when an explicit cross-subscription rule is configured; the default selection behavior does not.

archiveSubscription(subscriptionKey: string): Promise<void>

Parameters

  • subscriptionKey: Subscription key.

Returns No returned value.

Example

await subscrio.subscriptions.archiveSubscription('acme-pro');
Errors (1)
  • NotFoundError: The subscription is missing.
Task ArchiveSubscriptionAsync(string subscriptionKey)

Parameters

  • subscriptionKey: Subscription key.

Returns No returned value.

Example

await subscrio.Subscriptions.ArchiveSubscriptionAsync("acme-pro");
Errors (1)
  • NotFoundException: The subscription is missing.

unarchiveSubscription

Clear the archive flag. Existing dates still determine whether the subscription is active, expired, or cancelled.

unarchiveSubscription(subscriptionKey: string): Promise<void>

Parameters

  • subscriptionKey: Subscription key.

Returns No returned value.

Example

await subscrio.subscriptions.unarchiveSubscription('acme-pro');
Errors (1)
  • NotFoundError: The subscription is missing.
Task UnarchiveSubscriptionAsync(string subscriptionKey)

Parameters

  • subscriptionKey: Subscription key.

Returns No returned value.

Example

await subscrio.Subscriptions.UnarchiveSubscriptionAsync("acme-pro");
Errors (1)
  • NotFoundException: The subscription is missing.

deleteSubscription

Permanently delete the subscription and dependent overrides and add-on attachments, regardless of archive status. Retained accounting history can prevent deletion.

deleteSubscription(subscriptionKey: string): Promise<void>

Parameters

  • subscriptionKey: Subscription key.

Returns No returned value.

Example

await subscrio.subscriptions.deleteSubscription('acme-pro');
Errors (2)
  • NotFoundError: The subscription is missing.
  • ConflictError: Retained accounting or related history blocks deletion.
Task DeleteSubscriptionAsync(string subscriptionKey)

Parameters

  • subscriptionKey: Subscription key.

Returns No returned value.

Example

await subscrio.Subscriptions.DeleteSubscriptionAsync("acme-pro");
Errors (2)
  • NotFoundException: The subscription is missing.
  • ConflictException: Retained accounting or related history blocks deletion.

transitionExpiredSubscriptions

Process up to 1,000 unarchived expired subscriptions whose plans specify a transition billing cycle. Each replacement receives a versioned key and copied metadata, but no old overrides, add-ons, trial, or Stripe ID. The replacement is saved before the old subscription is archived. These writes are not one transaction; inspect the report for partial failures.

transitionExpiredSubscriptions(): Promise<TransitionExpiredSubscriptionsReport>

Returns TransitionExpiredSubscriptionsReport: Counts and per-subscription failures.

Example

const report = await subscrio.subscriptions.transitionExpiredSubscriptions();
console.log(report.transitioned, report.errors);

Task<TransitionExpiredSubscriptionsReport> TransitionExpiredSubscriptionsAsync()

Returns TransitionExpiredSubscriptionsReport: Counts and per-subscription failures.

Example

var report = await subscrio.Subscriptions.TransitionExpiredSubscriptionsAsync();
Console.WriteLine($"Transitioned: {report.Transitioned}, errors: {report.Errors.Count}");

Data types

Required means an input must be supplied, or an output property is guaranteed present.

CreateSubscriptionDto

Subscription creation properties.

Field Type Required Default Meaning
key string Yes None Globally unique key, 1 to 255 letters, digits, hyphens, or underscores.
customerKey string Yes None Customer key.
billingCycleKey string Yes None Lowercase billing-cycle key; determines the plan and product.
activationDate string | Date | undefined No None Activation time; defaults to now when creating. Immutable afterward.
expirationDate string | Date | undefined No None Explicit subscription expiration time, independent of period end.
cancellationDate string | Date | undefined No None Cancellation time; a future date schedules cancellation.
trialEndDate string | Date | undefined No None Trial end time.
currentPeriodStart string | Date | undefined No None Billing period start; defaults to now on creation.
currentPeriodEnd string | Date | undefined No None Billing period end; calculated from the cycle on creation when omitted.
stripeSubscriptionId string | undefined No None External Stripe subscription ID; unique when set.
metadata Record<string, unknown> | undefined No None Application metadata; supplied updates replace the saved object.
Property Type Required Default Meaning
Key string Yes None Globally unique key, 1 to 255 letters, digits, hyphens, or underscores.
CustomerKey string Yes None Customer key.
BillingCycleKey string Yes None Lowercase billing-cycle key; determines the plan and product.
ActivationDate DateTime? No null Activation time; defaults to now when creating. Immutable afterward.
ExpirationDate DateTime? No null Explicit subscription expiration time, independent of period end.
CancellationDate DateTime? No null Cancellation time; a future date schedules cancellation.
TrialEndDate DateTime? No null Trial end time.
CurrentPeriodStart DateTime? No null Billing period start; defaults to now on creation.
CurrentPeriodEnd DateTime? No null Billing period end; calculated from the cycle on creation when omitted.
StripeSubscriptionId string? No null External Stripe subscription ID; unique when set.
Metadata Dictionary<string, object?>? No null Application metadata; supplied updates replace the saved object.

SubscriptionDto

Returned subscription properties.

Field Type Required Default Meaning
addons SubscriptionAddonDto[] Yes Not applicable Active and cancelled attachments, including add-on definitions.
key string Yes Not applicable Globally unique key, 1 to 255 letters, digits, hyphens, or underscores.
customerKey string Yes Not applicable Customer key.
productKey string Yes Not applicable Owning product key.
planKey string Yes Not applicable Plan key.
billingCycleKey string Yes Not applicable Lowercase billing-cycle key; determines the plan and product.
status string Yes Not applicable Calculated lifecycle status; see Subscription Lifecycle.
isArchived boolean Yes Not applicable Archive flag, separate from calculated status.
activationDate string | null | undefined No Not applicable Activation time; defaults to now when creating. Immutable afterward.
expirationDate string | null | undefined No Not applicable Explicit subscription expiration time, independent of period end.
cancellationDate string | null | undefined No Not applicable Cancellation time; a future date schedules cancellation.
trialEndDate string | null | undefined No Not applicable Trial end time.
currentPeriodStart string | null | undefined No Not applicable Billing period start; defaults to now on creation.
currentPeriodEnd string | null | undefined No Not applicable Billing period end; calculated from the cycle on creation when omitted.
stripeSubscriptionId string | null | undefined No Not applicable External Stripe subscription ID; unique when set.
metadata Record<string, unknown> | null | undefined No Not applicable Application metadata; supplied updates replace the saved object.
customer CustomerDto | null | undefined No Not applicable Customer details included by list/find methods; may be null in other results.
featureOverrides FeatureOverrideDto[] | undefined No Not applicable All saved overrides, including expired timed overrides.
createdAt string Yes Not applicable Creation time in UTC.
updatedAt string Yes Not applicable Last update time in UTC.
Property Type Required Default Meaning
Addons List<SubscriptionAddonDto> Yes Not applicable Active and cancelled attachments, including add-on definitions.
FeatureOverrides List<FeatureOverrideDto> Yes Not applicable All saved overrides, including expired timed overrides.
Key string Yes Not applicable Globally unique key, 1 to 255 letters, digits, hyphens, or underscores.
CustomerKey string Yes Not applicable Customer key.
ProductKey string Yes Not applicable Owning product key.
PlanKey string Yes Not applicable Plan key.
BillingCycleKey string Yes Not applicable Lowercase billing-cycle key; determines the plan and product.
Status string Yes Not applicable Calculated lifecycle status; see Subscription Lifecycle.
IsArchived bool Yes Not applicable Archive flag, separate from calculated status.
ActivationDate string? Yes Not applicable Activation time; defaults to now when creating. Immutable afterward.
ExpirationDate string? Yes Not applicable Explicit subscription expiration time, independent of period end.
CancellationDate string? Yes Not applicable Cancellation time; a future date schedules cancellation.
TrialEndDate string? Yes Not applicable Trial end time.
CurrentPeriodStart string? Yes Not applicable Billing period start; defaults to now on creation.
CurrentPeriodEnd string? Yes Not applicable Billing period end; calculated from the cycle on creation when omitted.
StripeSubscriptionId string? Yes Not applicable External Stripe subscription ID; unique when set.
Metadata Dictionary<string, object?>? Yes Not applicable Application metadata; supplied updates replace the saved object.
Customer CustomerDto? Yes Not applicable Customer details included by list/find methods; may be null in other results.
CreatedAt string Yes Not applicable Creation time in UTC.
UpdatedAt string Yes Not applicable Last update time in UTC.

UpdateSubscriptionDto

Subscription update properties.

Field Type Required Default Meaning
billingCycleKey string | undefined No None Lowercase billing-cycle key; determines the plan and product.
expirationDate string | Date | undefined No None Explicit subscription expiration time, independent of period end.
cancellationDate string | Date | undefined No None Cancellation time; a future date schedules cancellation.
trialEndDate string | Date | undefined No None Trial end time.
clearTrialEndDate boolean | undefined No false Set true to clear the trial end, taking precedence over a supplied trial end.
currentPeriodStart string | Date | undefined No None Billing period start; defaults to now on creation.
currentPeriodEnd string | Date | undefined No None Billing period end; calculated from the cycle on creation when omitted.
stripeSubscriptionId string | undefined No None External Stripe subscription ID; unique when set.
metadata Record<string, unknown> | undefined No None Application metadata; supplied updates replace the saved object.
Property Type Required Default Meaning
BillingCycleKey string? No null Lowercase billing-cycle key; determines the plan and product.
ExpirationDate DateTime? No null Explicit subscription expiration time, independent of period end.
CancellationDate DateTime? No null Cancellation time; a future date schedules cancellation.
TrialEndDate DateTime? No null Trial end time.
ClearTrialEndDate bool No false Set true to clear the trial end, taking precedence over a supplied trial end.
CurrentPeriodStart DateTime? No null Billing period start; defaults to now on creation.
CurrentPeriodEnd DateTime? No null Billing period end; calculated from the cycle on creation when omitted.
StripeSubscriptionId string? No null External Stripe subscription ID; unique when set.
Metadata Dictionary<string, object?>? No null Application metadata; supplied updates replace the saved object.

SubscriptionFilterDto

Subscription filters. TypeScript requires limit and offset in a supplied 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.
customerKey string | undefined No None Customer key.
productKey string | undefined No None Owning product key.
planKey string | undefined No None Plan key.
status "active" | "cancelled" | "pending" | "trial" | "cancellation_pending" | "expired" | undefined No None pending, active, trial, cancelled, cancellation_pending, or expired.
isArchived boolean | undefined No None Select archived or unarchived records; omit to include both.
sortBy "createdAt" | "activationDate" | "expirationDate" | "currentPeriodStart" | "currentPeriodEnd" | "updatedAt" | undefined No None activationDate, expirationDate, createdAt, currentPeriodStart, or currentPeriodEnd. updatedAt currently falls back to createdAt.
sortOrder "asc" | "desc" | undefined No None asc or desc; defaults to desc.
Property Type Required Default Meaning
CustomerKey string? No null Customer key.
ProductKey string? No null Owning product key.
PlanKey string? No null Plan key.
Status string? No null pending, active, trial, cancelled, cancellation_pending, or expired.
IsArchived bool? No null Select archived or unarchived records; omit to include both.
SortBy string? No null Accepted but ignored; results use createdAt descending.
SortOrder string? No null Accepted but ignored; results use descending creation time.
Limit int? No 50 Maximum page size, 1 to 100.
Offset int? No 0 Nonnegative number of rows to skip.

DetailedSubscriptionFilterDto

Subscription filters. TypeScript requires limit and offset in a supplied 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.
customerKey string | undefined No None Customer key.
productKey string | undefined No None Owning product key.
planKey string | undefined No None Plan key.
billingCycleKey string | undefined No None Billing cycle key.
status "active" | "cancelled" | "pending" | "trial" | "cancellation_pending" | "expired" | undefined No None pending, active, trial, cancelled, cancellation_pending, or expired.
isArchived boolean | undefined No None Select archived or unarchived records; omit to include both.
activationDateFrom Date | undefined No None Inclusive earliest activation date.
activationDateTo Date | undefined No None Inclusive latest activation date.
expirationDateFrom Date | undefined No None Inclusive earliest expiration date.
expirationDateTo Date | undefined No None Inclusive latest expiration date.
trialEndDateFrom Date | undefined No None Inclusive earliest trial end date.
trialEndDateTo Date | undefined No None Inclusive latest trial end date.
currentPeriodStartFrom Date | undefined No None Inclusive earliest current period start.
currentPeriodStartTo Date | undefined No None Inclusive latest current period start.
currentPeriodEndFrom Date | undefined No None Inclusive earliest current period end.
currentPeriodEndTo Date | undefined No None Inclusive latest current period end.
hasStripeId boolean | undefined No None Match whether a Stripe subscription ID is present.
hasTrial boolean | undefined No None Match whether a trial end date is present, including past trials.
hasFeatureOverrides boolean | undefined No None Match saved override presence after pagination; expired timed overrides still count.
featureKey string | undefined No None Accepted but currently ignored.
metadataKey string | undefined No None Accepted but currently ignored.
metadataValue unknown No None Accepted but currently ignored.
sortBy "createdAt" | "activationDate" | "expirationDate" | "currentPeriodStart" | "currentPeriodEnd" | "updatedAt" | undefined No None activationDate, expirationDate, createdAt, currentPeriodStart, or currentPeriodEnd. updatedAt currently falls back to createdAt.
sortOrder "asc" | "desc" | undefined No None asc or desc; defaults to desc.
Property Type Required Default Meaning
CustomerKey string? No null Customer key.
ProductKey string? No null Owning product key.
PlanKey string? No null Plan key.
BillingCycleKey string? No null Billing cycle key.
Status string? No null pending, active, trial, cancelled, cancellation_pending, or expired.
IsArchived bool? No null Select archived or unarchived records; omit to include both.
ActivationDateFrom DateTime? No null Inclusive earliest activation date.
ActivationDateTo DateTime? No null Inclusive latest activation date.
ExpirationDateFrom DateTime? No null Inclusive earliest expiration date.
ExpirationDateTo DateTime? No null Inclusive latest expiration date.
TrialEndDateFrom DateTime? No null Inclusive earliest trial end date.
TrialEndDateTo DateTime? No null Inclusive latest trial end date.
CurrentPeriodStartFrom DateTime? No null Inclusive earliest current period start.
CurrentPeriodStartTo DateTime? No null Inclusive latest current period start.
CurrentPeriodEndFrom DateTime? No null Inclusive earliest current period end.
CurrentPeriodEndTo DateTime? No null Inclusive latest current period end.
HasStripeId bool? No null Match whether a Stripe subscription ID is present.
HasTrial bool? No null Match whether a trial end date is present, including past trials.
HasFeatureOverrides bool? No null Match saved override presence after pagination; expired timed overrides still count.
FeatureKey string? No null Accepted but currently ignored.
MetadataKey string? No null Accepted but currently ignored.
MetadataValue object? No null Accepted but currently ignored.
SortBy string? No null Accepted but ignored; results use createdAt descending.
SortOrder string? No null Accepted but ignored; results use descending creation time.
Limit int? No 50 Maximum page size, 1 to 100.
Offset int? No 0 Nonnegative number of rows to skip.

SubscriptionAddonDto

Attachment details returned with subscription snapshots and add-on queries.

Field Type Required Default Meaning
addon AddonDto Yes Not applicable Current add-on definition.
subscriptionKey string Yes Not applicable Subscription owning the attachment.
addonKey string Yes Not applicable Add-on key.
quantity number Yes Not applicable Number of units attached.
status "active" | "cancelled" Yes Not applicable active or cancelled.
createdAt string Yes Not applicable Creation time in UTC.
updatedAt string Yes Not applicable Last update time in UTC.
Property Type Required Default Meaning
SubscriptionKey string Yes Not applicable Subscription owning the attachment.
AddonKey string Yes Not applicable Add-on key.
Quantity int Yes Not applicable Number of units attached.
Status string Yes Not applicable active or cancelled.
CreatedAt string Yes Not applicable Creation time in UTC.
UpdatedAt string Yes Not applicable Last update time in UTC.
Addon AddonDto? Yes Not applicable Current add-on definition.

OverrideType

Override lifetime.

Value Meaning
OverrideType.Permanent Retained until replaced or removed.
OverrideType.Temporary Removed by the explicit temporary-override clearing method.
OverrideType.Timed Applies only before its required future expiry.
Value Meaning
OverrideType.Permanent Retained until replaced or removed.
OverrideType.Temporary Removed by the explicit temporary-override clearing method.
OverrideType.Timed Applies only before its required future expiry.

TransitionExpiredSubscriptionsReport

Outcome of one transition-processing call.

Field Type Required Default Meaning
processed number Yes Not applicable Subscriptions attempted.
transitioned number Yes Not applicable Replacements saved and their after-hooks completed.
archived number Yes Not applicable Old subscriptions archived and their after-hooks completed.
errors Array<{ subscriptionKey: string; error: string }> Yes Not applicable Per-subscription failures; other subscriptions continue processing.
Property Type Required Default Meaning
Processed int Yes Not applicable Subscriptions attempted.
Transitioned int Yes Not applicable Replacements saved and their after-hooks completed.
Archived int Yes Not applicable Old subscriptions archived and their after-hooks completed.
Errors List<TransitionError> Yes Not applicable Per-subscription failures; other subscriptions continue processing.

FeatureOverrideDto

Saved override details; expired timed overrides remain visible.

Field Type Required Default Meaning
expiresAt string | null | undefined No Not applicable Expiry timestamp for timed overrides; null otherwise.
isActive boolean | undefined No Not applicable False when a timed override has expired; true otherwise.
featureKey string Yes Not applicable Feature key.
value string Yes Not applicable Stored feature value.
type string Yes Not applicable permanent, temporary, or timed.
createdAt string Yes Not applicable Creation time in UTC.
Property Type Required Default Meaning
FeatureId long Yes Not applicable Internal feature identifier.
Value string Yes Not applicable Stored feature value.
Type string Yes Not applicable permanent, temporary, or timed.
CreatedAt string Yes Not applicable Creation time in UTC.
FeatureKey string? Yes Not applicable Feature key.
ExpiresAt string? Yes Not applicable Expiry timestamp for timed overrides; null otherwise.
IsActive bool Yes Not applicable False when a timed override has expired; true otherwise.

TransitionError

A failed transition, represented as an inline object in TypeScript.

Field Type Required Default Meaning
subscriptionKey string Yes Not applicable Subscription being processed.
error string Yes Not applicable Failure message.
Property Type Required Default Meaning
SubscriptionKey string Yes Not applicable Subscription being processed.
Error string Yes Not applicable Failure message.