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 '@subscrio/core';

const subscrio = new Subscrio({ database: { connectionString: process.env.DATABASE_URL! } });
const 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.

Signature

createSubscription(dto: CreateSubscriptionDto): Promise<SubscriptionDto>

Inputs

Input Properties

Returns

Promise<SubscriptionDto> – persisted subscription snapshot with derived customer/product/plan keys.

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

Example

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

updateSubscription

Description

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

Signature

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

Inputs

Input Properties

Returns

Promise<SubscriptionDto> – updated subscription snapshot.

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

Example

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

getSubscription

Description

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

Signature

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

Inputs

Returns

Promise<SubscriptionDto | null>

Return Properties

• SubscriptionDto when found.
• null when missing.

Expected Results

• Loads subscription via repository and maps to DTO.

Potential Errors

Example

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

listSubscriptions

Description

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

Signature

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

Inputs

Returns

Promise<SubscriptionDto[]>

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

Example

const activeSubs = await subscriptions.listSubscriptions({
  productKey: 'pro-suite',
  status: 'active',
  isArchived: false
});

// Each subscription includes the full customer object
activeSubs.forEach(sub => {
  console.log(sub.customer?.displayName);
});

findSubscriptions

Description

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

Signature

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

Inputs

Returns

Promise<SubscriptionDto[]>

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.

Signature

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

Inputs

Returns

Promise<SubscriptionDto[]>

Expected Results

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

Potential Errors

Example

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

archiveSubscription

Description

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

Signature

archiveSubscription(key: string): Promise<void>

Inputs

Returns

Promise<void>

Expected Results

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

Potential Errors

Example

await subscriptions.archiveSubscription('sub_legacy');

unarchiveSubscription

Description

Clears the archived flag, allowing updates again.

Signature

unarchiveSubscription(key: string): Promise<void>

Inputs

Returns

Promise<void>

Expected Results

• Loads subscription, calls unarchive(), persists.

Potential Errors

Example

await subscriptions.unarchiveSubscription('sub_legacy');

deleteSubscription

Description

Deletes a subscription record irrespective of status.

Signature

deleteSubscription(key: string): Promise<void>

Inputs

Returns

Promise<void>

Expected Results

• Loads subscription, ensures it exists, deletes record.

Potential Errors

Example

await subscriptions.deleteSubscription('sub_deprecated');

addFeatureOverride

Description

Adds or updates a subscription-level feature override with optional override type.

Signature

addFeatureOverride(
  subscriptionKey: string,
  featureKey: string,
  value: string,
  overrideType?: 'permanent' | 'temporary'
): Promise<void>

Inputs

Returns

Promise<void>

Expected Results

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

Potential Errors

Example

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

removeFeatureOverride

Description

Removes a specific feature override from a subscription.

Signature

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

Inputs

Returns

Promise<void>

Expected Results

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

Potential Errors

Example

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

clearTemporaryOverrides

Description

Deletes only temporary overrides for a subscription.

Signature

clearTemporaryOverrides(subscriptionKey: string): Promise<void>

Inputs

Returns

Promise<void>

Expected Results

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

Potential Errors

Example

await subscriptions.clearTemporaryOverrides('sub_1001');

transitionExpiredSubscriptions

Description

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

Signature

transitionExpiredSubscriptions(): Promise<TransitionExpiredSubscriptionsReport>

Inputs

None – automatically finds expired subscriptions with transition plans.

Returns

Promise<TransitionExpiredSubscriptionsReport> with counts and errors.

Return Properties

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

Example

// Run transition process (typically called from a cron job or scheduled task)
const report = await subscriptions.transitionExpiredSubscriptions();

console.log(`Processed: ${report.processed}`);
console.log(`Transitioned: ${report.transitioned}`);
console.log(`Errors: ${report.errors.length}`);

if (report.errors.length > 0) {
  report.errors.forEach(err => {
    console.error(`Subscription ${err.subscriptionKey}: ${err.error}`);
  });
}

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

Fields optional: billingCycleKey, expirationDate, cancellationDate, trialEndDate, currentPeriodStart, currentPeriodEnd, stripeSubscriptionId, metadata. Activation date and customer key are immutable.

SubscriptionDto

SubscriptionFilterDto

DetailedSubscriptionFilterDto

Adds: - billingCycleKey - isArchived - Filters by is_archived flag. true for archived, false for non-archived, undefined for all. - Date ranges: activationDateFrom/To, expirationDateFrom/To, trialEndDateFrom/To, currentPeriodStartFrom/To, currentPeriodEndFrom/To - Booleans: hasStripeId, hasTrial, hasFeatureOverrides - featureKey, metadataKey, metadataValue - Pagination/sorting same as above.

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.