Billing Cycle Management Service Reference

Service Overview

Billing cycles define how plans renew (duration, cadence, and external price IDs). Each cycle belongs to a plan, exposes derived planKey/productKey in DTOs, and enforces delete guards whenever subscriptions or plan transitions reference it.

• Duration units: days, weeks, months, years, or forever (when forever, durationValue must be omitted).
• Cycles can expose externalProductId (e.g., Stripe price) for payment processor mappings.
• Delete operations require the cycle to be archived and unused by subscriptions or plan transition settings.

Accessing the Service

import { Subscrio } from 'core.typescript';

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

using Subscrio.Core;

var subscrio = new Subscrio(config);
var billingCycles = subscrio.BillingCycles;

Method Catalog

Method Reference

createBillingCycle

Description

Validates a new billing cycle payload, ensures the plan exists, and persists the cycle with active status.

Signature

createBillingCycle(dto: CreateBillingCycleDto): Promise<BillingCycleDto>

Task<BillingCycleDto> CreateBillingCycleAsync(CreateBillingCycleDto dto)

Inputs

Input Properties

Returns

Return Properties

Expected Results

• Validates DTO (including duration rules).
• Loads plan by planKey and fails if missing.
• Rejects duplicate billing cycle keys.
• Persists cycle with status active.

Potential Errors

Example

await billingCycles.createBillingCycle({
  planKey: 'annual-pro',
  key: 'annual-pro-12m',
  displayName: 'Annual (12 months)',
  durationValue: 12,
  durationUnit: 'months',
  externalProductId: 'price_ABC123'
});

await subscrio.BillingCycles.CreateBillingCycleAsync(new CreateBillingCycleDto(
    PlanKey: "annual-pro",
    Key: "annual-pro-12m",
    DisplayName: "Annual (12 months)",
    DurationValue: 12,
    DurationUnit: "months",
    ExternalProductId: "price_ABC123"
));

updateBillingCycle

Description

Updates mutable fields (display name, description, duration config, pricing metadata) on an existing cycle.

Signature

updateBillingCycle(key: string, dto: UpdateBillingCycleDto): Promise<BillingCycleDto>

Task<BillingCycleDto> UpdateBillingCycleAsync(string key, UpdateBillingCycleDto dto)

Inputs

Input Properties

Returns

Return Properties

Expected Results

• Validates DTO.
• Loads cycle, applies permissible fields, saves.

Example

await billingCycles.updateBillingCycle('annual-pro-12m', {
  displayName: 'Annual Plan (12 months)',
  externalProductId: 'price_UPDATED'
});

await subscrio.BillingCycles.UpdateBillingCycleAsync("annual-pro-12m", new UpdateBillingCycleDto(
    DisplayName: "Annual Plan (12 months)",
    ExternalProductId: "price_UPDATED"
));

Potential Errors

getBillingCycle

Description

Retrieves a single billing cycle by key (returns null if not found).

Signature

getBillingCycle(key: string): Promise<BillingCycleDto | null>

Task<BillingCycleDto?> GetBillingCycleAsync(string key)

Inputs

Returns

Return Properties

Expected Results

• Loads cycle; if stored plan reference is missing (data corruption), throws NotFoundError.

Potential Errors

Example

const cycle = await billingCycles.getBillingCycle('annual-pro-12m');

var cycle = await subscrio.BillingCycles.GetBillingCycleAsync("annual-pro-12m");

getBillingCyclesByPlan

Description

Lists all billing cycles belonging to a plan.

Signature

getBillingCyclesByPlan(planKey: string): Promise<BillingCycleDto[]>

Task<List<BillingCycleDto>> GetBillingCyclesByPlanAsync(string planKey)

Inputs

Returns

Return Properties

Expected Results

• Ensures plan exists.
• Returns all cycles mapped to the plan (with derived product key).

Potential Errors

Example

const cycles = await billingCycles.getBillingCyclesByPlan('annual-pro');

var cycles = await subscrio.BillingCycles.GetBillingCyclesByPlanAsync("annual-pro");

listBillingCycles

Description

Paginates billing cycles with optional filters.

Signature

listBillingCycles(filters?: BillingCycleFilterDto): Promise<BillingCycleDto[]>

Task<List<BillingCycleDto>> ListBillingCyclesAsync(BillingCycleFilterDto? filters = null)

Inputs

Input Properties

Returns

Return Properties

Expected Results

• Validates filters.
• Executes query, returning DTO array (same schema as createBillingCycle result).

Potential Errors

Example

const paged = await billingCycles.listBillingCycles({
  status: 'active',
  durationUnit: 'months',
  limit: 20
});

var paged = await subscrio.BillingCycles.ListBillingCyclesAsync(new BillingCycleFilterDto(
    Status: "active",
    DurationUnit: "months",
    Limit: 20
));

archiveBillingCycle

Description

Marks a billing cycle as archived (cannot be used for new subscriptions).

Signature

archiveBillingCycle(key: string): Promise<void>

Task ArchiveBillingCycleAsync(string key)

Inputs

Returns

Return Properties

Expected Results

• Loads cycle, sets status archived, saves.

Potential Errors

Example

await billingCycles.archiveBillingCycle('annual-pro-12m');

await subscrio.BillingCycles.ArchiveBillingCycleAsync("annual-pro-12m");

unarchiveBillingCycle

Description

Restores an archived cycle to active.

Signature

unarchiveBillingCycle(key: string): Promise<void>

Task UnarchiveBillingCycleAsync(string key)

Inputs

Returns

Return Properties

Expected Results

• Loads cycle, sets status active, saves.

Potential Errors

Example

await billingCycles.unarchiveBillingCycle('annual-pro-12m');

await subscrio.BillingCycles.UnarchiveBillingCycleAsync("annual-pro-12m");

deleteBillingCycle

Description

Permanently deletes a billing cycle after ensuring it is archived and unused by subscriptions or plan transitions.

Signature

deleteBillingCycle(key: string): Promise<void>

Task DeleteBillingCycleAsync(string key)

Inputs

Returns

Return Properties

Expected Results

• Loads cycle, calls billingCycle.canDelete() (requires archived status).
• Verifies no subscriptions reference the cycle.
• Ensures no plan has onExpireTransitionToBillingCycleKey pointing to it.
• Deletes record.

Potential Errors

Example

await billingCycles.deleteBillingCycle('legacy-quarterly');

await subscrio.BillingCycles.DeleteBillingCycleAsync("legacy-quarterly");

calculateNextPeriodEnd

Description

Computes the next period end for a billing cycle, given the current period end.

Signature

calculateNextPeriodEnd(
  billingCycleKey: string,
  currentPeriodEnd: Date
): Promise<Date | null>

Task<DateTime?> CalculateNextPeriodEndAsync(string billingCycleKey, DateTime currentPeriodEnd)

Inputs

Returns

Return Properties

Expected Results

• Loads cycle, applies duration arithmetic (e.g., add N months) or returns null when unit is forever.

Potential Errors

Example

const nextEnd = await billingCycles.calculateNextPeriodEnd(
  'annual-pro-12m',
  new Date('2025-01-01T00:00:00Z')
);

var nextEnd = await subscrio.BillingCycles.CalculateNextPeriodEndAsync(
    "annual-pro-12m",
    new DateTime(2025, 1, 1, 0, 0, 0, DateTimeKind.Utc)
);

getBillingCyclesByDurationUnit

Description

Provides all cycles already stored with a specific duration unit.

Signature

getBillingCyclesByDurationUnit(durationUnit: DurationUnit): Promise<BillingCycleDto[]>

Task<List<BillingCycleDto>> GetBillingCyclesByDurationUnitAsync(DurationUnit durationUnit)

Inputs

Returns

Return Properties

Expected Results

• Filters existing cycles by unit (no errors thrown).

Example

const monthlyCycles = await billingCycles.getBillingCyclesByDurationUnit('months');

var monthlyCycles = await subscrio.BillingCycles.GetBillingCyclesByDurationUnitAsync(DurationUnit.Months);

getDefaultBillingCycles

Description

Retrieves pre-installed cycles (monthly/quarterly/yearly) when present.

Signature

getDefaultBillingCycles(): Promise<BillingCycleDto[]>

Task<List<BillingCycleDto>> GetDefaultBillingCyclesAsync()

Returns

Return Properties

Expected Results

• Attempts to load keys such as monthly, quarterly, yearly; returns whichever exist.

Potential Errors

• None (returns empty array when defaults not installed).

Example

const defaults = await billingCycles.getDefaultBillingCycles();

var defaults = await subscrio.BillingCycles.GetDefaultBillingCyclesAsync();

Related Workflows

• Plans must exist before creating billing cycles (PlanManagementService).
• Subscriptions reference billing cycles; deletion is blocked when subscriptions are present (SubscriptionManagementService).
• Stripe integration uses externalProductId to map cycles to Stripe prices (StripeIntegrationService).