Subscription Management Service Reference

Service Overview

Subscriptions tie customers to plans and billing cycles, track lifecycle dates, and store feature overrides. This service manages creation, updates, status synchronization, feature overrides, and batch maintenance tasks.

• Subscription keys are caller-supplied and immutable.
• Billing cycles derive plan/product context; updating a subscription’s billing cycle also changes its plan.
• Status is computed dynamically via the subscription_status_view database view, so status filters always reflect real time.

Accessing the Service

import { Subscrio } from 'core.typescript';

const subscrio = new Subscrio({ database: { connectionString: process.env.DATABASE_URL! } });
const subscriptions = subscrio.subscriptions;

using Subscrio.Core;

var subscrio = new Subscrio(config);
var subscriptions = subscrio.Subscriptions;

Method Catalog

Method Reference

createSubscription

Description

Creates a subscription linking a customer to a plan/billing cycle and initializes lifecycle dates and metadata.

createSubscription(dto: CreateSubscriptionDto): Promise<SubscriptionDto>

await subscriptions.createSubscription({
  key: 'sub_1001',
  customerKey: 'cust_123',
  billingCycleKey: 'annual-pro-12m',
  activationDate: new Date().toISOString(),
  metadata: { source: 'self-serve' }
});

Task<SubscriptionDto> CreateSubscriptionAsync(CreateSubscriptionDto dto)

await subscrio.Subscriptions.CreateSubscriptionAsync(new CreateSubscriptionDto(
    Key: "sub_1001",
    CustomerKey: "cust_123",
    BillingCycleKey: "annual-pro-12m",
    ActivationDate: DateTime.UtcNow,
    Metadata: new Dictionary<string, object?> { ["source"] = "self-serve" }
));

Expected Results

• Validates DTO and lifecycle dates.
• Ensures customer and billing cycle exist (deriving plan/product).
• Confirms subscription key and Stripe subscription ID are unique.
• Backfills currentPeriodEnd when omitted.
• Persists subscription; status is later read from the PostgreSQL view.

Potential Errors

updateSubscription

Description

Applies partial updates to lifecycle dates, billing cycle, Stripe linkage, or metadata.

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

await subscriptions.updateSubscription('sub_1001', {
  billingCycleKey: 'monthly-pro',
  currentPeriodEnd: new Date().toISOString()
});

Task<SubscriptionDto> UpdateSubscriptionAsync(string subscriptionKey, UpdateSubscriptionDto dto)

await subscrio.Subscriptions.UpdateSubscriptionAsync("sub_1001", new UpdateSubscriptionDto(
    BillingCycleKey: "monthly-pro",
    CurrentPeriodEnd: DateTime.UtcNow
));

Expected Results

• Validates DTO and detects explicitly cleared fields.
• Loads subscription; rejects if archived.
• Applies lifecycle and billing cycle changes (updating plan ID when billing cycle changes).
• Persists entity; status continues to be resolved by the database view.

Potential Errors

getSubscription

Description

Retrieves a subscription by key, returning null when it does not exist.

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

const subscription = await subscriptions.getSubscription('sub_1001');

Task<SubscriptionDto?> GetSubscriptionAsync(string subscriptionKey)

var subscription = await subscrio.Subscriptions.GetSubscriptionAsync("sub_1001");

Expected Results

• Loads subscription via repository and maps to DTO.

Potential Errors

listSubscriptions

Description

Lists subscriptions using simple filters (customer/product/plan/status) with pagination.

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

const activeSubs = await subscriptions.listSubscriptions({
  productKey: 'pro-suite',
  status: 'active',
  isArchived: false
});
activeSubs.forEach(sub => console.log(sub.customer?.displayName));

Task<List<SubscriptionDto>> ListSubscriptionsAsync(SubscriptionFilterDto? filters = null)

var activeSubs = await subscrio.Subscriptions.ListSubscriptionsAsync(new SubscriptionFilterDto(
    ProductKey: "pro-suite",
    Status: "active",
    IsArchived: false
));
foreach (var sub in activeSubs) Console.WriteLine(sub.Customer?.DisplayName);

Expected Results

• Validates filters.
• Resolves external keys to IDs; returns empty array if lookups fail.
• Queries the status view so status filters reflect real time.
• Each result includes the full customer object (CustomerDto) populated from the customers table join.

Potential Errors

findSubscriptions

Description

Performs advanced filtering with date ranges, metadata queries, and feature override criteria.

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

const subs = await subscriptions.findSubscriptions({
  expirationDateFrom: new Date('2025-01-01'),
  expirationDateTo: new Date('2025-12-31'),
  hasFeatureOverrides: true
});

Task<List<SubscriptionDto>> FindSubscriptionsAsync(DetailedSubscriptionFilterDto filters)

var subs = await subscrio.Subscriptions.FindSubscriptionsAsync(
    new DetailedSubscriptionFilterDto(
        ExpirationDateFrom: new DateTime(2025, 1, 1),
        ExpirationDateTo: new DateTime(2025, 12, 31),
        HasFeatureOverrides: true
    )
);

Expected Results

• Validates filters.
• Executes more complex SQL against the status view and supporting tables.
• Each result includes the full customer object (CustomerDto) populated from the customers table join.

Potential Errors

getSubscriptionsByCustomer

Description

Returns all subscriptions for a specific customer key.

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

const customerSubs = await subscriptions.getSubscriptionsByCustomer('cust_123');

Task<List<SubscriptionDto>> GetSubscriptionsByCustomerAsync(string customerKey)

var customerSubs = await subscrio.Subscriptions.GetSubscriptionsByCustomerAsync("cust_123");

Expected Results

• Ensures customer exists, then queries the status view for their subscriptions.

Potential Errors

archiveSubscription

Description

Marks a subscription as archived (preventing further updates until unarchived).

archiveSubscription(subscriptionKey: string): Promise<void>

await subscriptions.archiveSubscription('sub_legacy');

Task ArchiveSubscriptionAsync(string subscriptionKey)

await subscrio.Subscriptions.ArchiveSubscriptionAsync("sub_legacy");

Expected Results

• Loads subscription, calls entity archive(), persists. Status automatically reflects change via the view.

Potential Errors

unarchiveSubscription

Description

Clears the archived flag, allowing updates again.

unarchiveSubscription(subscriptionKey: string): Promise<void>

await subscriptions.unarchiveSubscription('sub_legacy');

Task UnarchiveSubscriptionAsync(string subscriptionKey)

await subscrio.Subscriptions.UnarchiveSubscriptionAsync("sub_legacy");

Expected Results

• Loads subscription, calls unarchive(), persists.

Potential Errors

deleteSubscription

Description

Deletes a subscription record irrespective of status.

deleteSubscription(subscriptionKey: string): Promise<void>

await subscriptions.deleteSubscription('sub_deprecated');

Task DeleteSubscriptionAsync(string subscriptionKey)

await subscrio.Subscriptions.DeleteSubscriptionAsync("sub_deprecated");

Expected Results

• Loads subscription, ensures it exists, deletes record.

Potential Errors

addFeatureOverride

Description

Adds or updates a subscription-level feature override with optional override type (permanent or temporary).

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

await subscriptions.addFeatureOverride('sub_1001', 'max-projects', '200', OverrideType.Temporary);

Task AddFeatureOverrideAsync(
    string subscriptionKey,
    string featureKey,
    string value,
    OverrideType overrideType = OverrideType.Permanent
)

await subscrio.Subscriptions.AddFeatureOverrideAsync(
    "sub_1001",
    "max-projects",
    "200",
    OverrideType.Temporary
);

Expected Results

• Loads subscription; rejects if archived.
• Loads feature and validates value via FeatureValueValidator.
• Adds override (replacing existing entry) and saves.

Potential Errors

removeFeatureOverride

Description

Removes a specific feature override from a subscription.

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

await subscriptions.removeFeatureOverride('sub_1001', 'max-projects');

Task RemoveFeatureOverrideAsync(string subscriptionKey, string featureKey)

await subscrio.Subscriptions.RemoveFeatureOverrideAsync("sub_1001", "max-projects");

Expected Results

• Ensures subscription exists and is not archived.
• Removes override if present and persists.

Potential Errors

clearTemporaryOverrides

Description

Deletes only temporary overrides for a subscription; permanent overrides are retained.

clearTemporaryOverrides(subscriptionKey: string): Promise<void>

await subscriptions.clearTemporaryOverrides('sub_1001');

Task ClearTemporaryOverridesAsync(string subscriptionKey)

await subscrio.Subscriptions.ClearTemporaryOverridesAsync("sub_1001");

Expected Results

• Ensures subscription exists and is active.
• Removes overrides flagged as temporary and saves.

Potential Errors

transitionExpiredSubscriptions

Description

Processes expired subscriptions and automatically transitions them to configured plans. Finds all expired subscriptions whose plans have an onExpireTransitionToBillingCycleKey configured, archives the old subscription, and creates a new subscription to the transition billing cycle.

transitionExpiredSubscriptions(): Promise<TransitionExpiredSubscriptionsReport>

const report = await subscriptions.transitionExpiredSubscriptions();
console.log(`Processed: ${report.processed}, Transitioned: ${report.transitioned}`);
report.errors.forEach(err => console.error(`${err.subscriptionKey}: ${err.error}`));

Task<TransitionExpiredSubscriptionsReport> TransitionExpiredSubscriptionsAsync()

var report = await subscrio.Subscriptions.TransitionExpiredSubscriptionsAsync();
Console.WriteLine($"Processed: {report.Processed}, Transitioned: {report.Transitioned}");
foreach (var err in report.Errors) Console.WriteLine($"{err.SubscriptionKey}: {err.Error}");

Expected Results

• Queries expired subscriptions (status='expired', not archived) with transition-enabled plans using an optimized database join.
• For each expired subscription:
• Marks old subscription as transitioned (sets isArchived = true and transitioned_at timestamp)
• Creates new subscription to the transition billing cycle
• Generates versioned subscription key: original-key → original-key-v1 (or increments if already versioned)
• Preserves metadata from old subscription
• Does not carry over feature overrides or Stripe subscription IDs
• Returns a report of processed, transitioned, and archived subscriptions.

Potential Errors

Errors are captured in the report's errors array rather than thrown. Common errors include: - Plan not found - Customer not found - Billing cycle not found - Generated subscription key already exists

Usage Notes

• When to call: Typically run as a scheduled job (cron, background worker) to process expired subscriptions periodically.
• Idempotent: Safe to run multiple times; only processes subscriptions that haven't been transitioned yet.
• Stripe integration: Original Stripe subscription ID remains on the archived subscription. The new subscription does not have a Stripe ID (you may need to create a new Stripe subscription if using Stripe).
• Query optimization: Uses an optimized database query with joins to only fetch expired subscriptions whose plans have transition requirements.

Need the full explanation of how each status works? See subscription-lifecycle.md for detailed rules, diagrams, and practical guidance.

DTO Reference

CreateSubscriptionDto

UpdateSubscriptionDto

SubscriptionDto

SubscriptionFilterDto

DetailedSubscriptionFilterDto

Related Workflows

• FeatureCheckerService relies on subscription data for resolving feature access; keep overrides up to date.
• StripeIntegrationService uses subscription CRUD for webhook synchronization.
• When deleting or transitioning plans/billing cycles, ensure subscriptions point to valid entities; run your own data migrations when changing plan relationships.
• Subscription Transitions: Use transitionExpiredSubscriptions() to automatically migrate expired subscriptions to new plans. Typically run as a scheduled job (cron, background worker) to process expired subscriptions periodically. See subscription-lifecycle.md for details on transition behavior.