Subscrio

https://docs.subscrio.com
Admin
Subscrio is an entitlement engine that translates subscriptions into feature access, serving as the...
Tokens:68,909
Snippets:707
Trust Score:7.5
Update:2 months ago
Show doc for...
Tokens:
Raw
### Product Configuration Example

Source: https://docs.subscrio.com/reference/config-sync?q=

Example JSON object for a product configuration.

```json
{
  "key": "project-management",
  "displayName": "Project Management",
  "description": "Complete project management solution",
  "archived": false,
  "features": ["max-projects", "team-size", "gantt-charts"],
  "plans": [...]
}
```

--------------------------------

### Install Schema Usage Example

Source: https://docs.subscrio.com/reference/core-overview?q=

Example of invoking the schema installation method with an optional admin passphrase.

```typescript
await subscrio.installSchema('super-secret-passphrase');
```

```csharp
await subscrio.InstallSchemaAsync("super-secret-passphrase");
```

--------------------------------

### Plan Configuration Example

Source: https://docs.subscrio.com/reference/config-sync?q=

Example JSON object for a plan configuration.

```json
{
  "key": "basic",
  "displayName": "Basic Plan",
  "description": "For small teams",
  "archived": false,
  "featureValues": {
    "max-projects": "5",
    "gantt-charts": "false"
  },
  "billingCycles": [...]
}
```

--------------------------------

### Install and Use Extension

Source: https://docs.subscrio.com/reference/how-to-extend?q=

Commands and code to install and initialize the extension in a project.

```bash
npm install @acme/subscrio-my-extension
```

```typescript
import { Subscrio } from '@saas-experts/subscrio';
import { registerAuditLog } from '@acme/subscrio-my-extension';

const subscrio = new Subscrio({ database: { connectionString } });
registerAuditLog(subscrio, { sink: mySink });
```

```bash
dotnet add package Acme.Subscrio.MyExtension
```

```csharp
using Acme.Subscrio.MyExtension;

using var audit = subscrio.UseCustomAuditLog(new AuditLogOptions { Sink = mySink });
```

--------------------------------

### Create Customer Examples

Source: https://docs.subscrio.com/reference/customers?q=

Usage examples for creating a new customer record using the SDK.

```TypeScript
await customers.createCustomer({
  key: 'cust_123',
  displayName: 'Acme Corp',
  email: 'billing@acme.test'
});
```

```csharp
await subscrio.Customers.CreateCustomerAsync(new CreateCustomerDto(
    Key: "cust_123",
    DisplayName: "Acme Corp",
    Email: "billing@acme.test"
));
```

--------------------------------

### Feature Configuration Example

Source: https://docs.subscrio.com/reference/config-sync?q=

Example JSON object for a feature configuration.

```json
{
  "key": "max-projects",
  "displayName": "Maximum Projects",
  "description": "Maximum number of projects allowed",
  "valueType": "numeric",
  "defaultValue": "1",
  "groupName": "Limits",
  "archived": false
}
```

--------------------------------

### Billing Cycle Configuration Example

Source: https://docs.subscrio.com/reference/config-sync?q=

Example JSON object for a billing cycle configuration.

```json
{
  "key": "monthly",
  "displayName": "Monthly",
  "description": "Monthly billing cycle",
  "durationValue": 1,
  "durationUnit": "months",
  "externalProductId": "price_stripe_monthly",
  "archived": false
}
```

--------------------------------

### Create Subscription Example (TypeScript)

Source: https://docs.subscrio.com/reference/subscriptions

Demonstrates initializing a new subscription with a specific key, customer, billing cycle, and metadata.

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

--------------------------------

### Install Subscrio Dependencies

Source: https://docs.subscrio.com/reference/getting-started

Install the required packages for the TypeScript environment.

```bash
pnpm install
```

--------------------------------

### Initialize Product Management Service

Source: https://docs.subscrio.com/reference/products

Setup the Subscrio client to access product management functionality in TypeScript and .NET.

```typescript
import { Subscrio } from 'core.typescript';

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

```csharp
using Subscrio.Core;

var subscrio = new Subscrio(config);
var products = subscrio.Products;
```

--------------------------------

### Apply Initial Configuration at Construction

Source: https://docs.subscrio.com/reference/config-sync?q=

Configure initial sync settings during Subscrio instantiation and apply them after schema installation.

```typescript
import { Subscrio } from 'core.typescript';

const subscrio = new Subscrio({
  database: { connectionString: process.env.DATABASE_URL! },
  initialConfig: { type: 'file', filePath: './config.json' }
  // or: initialConfig: { type: 'json', config: myConfigSyncDto }
});
await subscrio.installSchema();
const report = await subscrio.runInitialConfigSync(); // applies initial config, or null if none
```

```csharp
using Subscrio.Core;
using Subscrio.Core.Config;

var subscrio = new Subscrio(new SubscrioConfig
{
    Database = new DatabaseConfig { ConnectionString = "..." },
    InitialConfig = new InitialConfigOptions { FilePath = "./config.json" }
    // or: InitialConfig = new InitialConfigOptions { Config = myConfigSyncDto }
});
await subscrio.InstallSchemaAsync();
var report = await subscrio.RunInitialConfigSyncAsync(); // applies initial config, or null if none
```

--------------------------------

### Install and Configure Audit Log Extension for .NET

Source: https://docs.subscrio.com/reference/how-to-extend?q=

Installation commands and initialization code for the Subscrio audit log extension in .NET environments.

```bash
dotnet add package Subscrio.AuditLog
```

```csharp
using Subscrio.AuditLog;
using Subscrio.AuditLog.DTOs;

await using var audit = subscrio.UseAuditLog(new AuditLogOptions
{
    ConnectionString = connectionString,
});
await audit.InstallSchemaAsync();

var page = await audit.ListAsync(new TransactionLogFilters { CustomerKey = "acme", Limit = 50 });
```

--------------------------------

### Install Schema Method Signature

Source: https://docs.subscrio.com/reference/core-overview?q=

Method signatures for initializing the database schema and seeding configuration.

```typescript
installSchema(adminPassphrase?: string): Promise<void>
```

```csharp
Task InstallSchemaAsync(string? adminPassphrase = null)
```

--------------------------------

### Initialize Subscrio Schema

Source: https://docs.subscrio.com/reference/getting-started

Bootstrap the Subscrio instance and ensure the database schema is installed or migrated to the latest version.

```typescript
import { Subscrio } from 'core.typescript';
import { loadConfig } from 'core.typescript/config';

async function main() {
  const config = loadConfig();
  const subscrio = new Subscrio(config);

  // Check if schema exists
  const schemaVersion = await subscrio.verifySchema();
  if (schemaVersion === null) {
    await subscrio.installSchema();
    console.log('Schema installed.');
  } else {
    console.log(`Schema version: ${schemaVersion}`);
    const migrationsApplied = await subscrio.migrate();
    if (migrationsApplied > 0) {
      console.log(`Applied ${migrationsApplied} migration(s).`);
    }
  }

  console.log('Ready to use Subscrio services.');
}

main().catch((error) => {
  console.error(error);
  process.exit(1);
});
```

```csharp
using Subscrio.Core;
using Subscrio.Core.Config;

var config = ConfigLoader.LoadConfig();
await using var subscrio = new Subscrio(config);

var schemaVersion = await subscrio.VerifySchemaAsync();
if (schemaVersion == null)
{
    await subscrio.InstallSchemaAsync();
    Console.WriteLine("Schema installed.");
}
else
{
    Console.WriteLine($"Schema version: {schemaVersion}");
    var migrationsApplied = await subscrio.MigrateAsync();
    if (migrationsApplied > 0)
    {
        Console.WriteLine($"Applied {migrationsApplied} migration(s).");
    }
}

Console.WriteLine("Ready to use Subscrio services.");
```

--------------------------------

### Sync Configuration from JSON

Source: https://docs.subscrio.com/reference/config-sync?q=

Examples of programmatically syncing configuration using the ConfigSyncDto object in TypeScript and C#.

```typescript
const config: ConfigSyncDto = {
  version: '1.0',
  features: [{ key: 'max-projects', displayName: 'Max Projects', valueType: 'numeric', defaultValue: '10' }],
  products: [{ key: 'my-product', displayName: 'My Product', features: ['max-projects'], plans: [] }]
};
const report = await subscrio.configSync.syncFromJson(config);
```

```csharp
var config = new ConfigSyncDto(
    Version: "1.0",
    Features: new List<FeatureConfig> { new("max-projects", "Max Projects", ValueType: "numeric", DefaultValue: "10") },
    Products: new List<ProductConfig> { new("my-product", "My Product", Features: new List<string> { "max-projects" }, Plans: new List<PlanConfig>()) }
);
var report = await subscrio.ConfigSync.SyncFromJsonAsync(config);
```

--------------------------------

### Verify Schema Installation

Source: https://docs.subscrio.com/reference/core-overview?q=

Checks if the schema is installed and retrieves the current version string.

```TypeScript
const version = await subscrio.verifySchema();
if (version === null) {
  console.warn('Subscrio schema missing – run installSchema() first.');
} else {
  console.log(`Schema version: ${version}`);
}
```

```C#
var version = await subscrio.VerifySchemaAsync();
if (version == null)
{
    Console.WriteLine("Subscrio schema missing – run InstallSchemaAsync() first.");
}
else
{
    Console.WriteLine($"Schema version: {version}");
}
```

--------------------------------

### Initialize and Use .NET Audit Log

Source: https://docs.subscrio.com/reference/how-to-extend

Configure the audit log extension, install the schema, and perform queries using the .NET SDK.

```csharp
using Subscrio.AuditLog;
using Subscrio.AuditLog.DTOs;

await using var audit = subscrio.UseAuditLog(new AuditLogOptions
{
    ConnectionString = connectionString,
});
await audit.InstallSchemaAsync();

var page = await audit.ListAsync(new TransactionLogFilters { CustomerKey = "acme", Limit = 50 });
```

--------------------------------

### Install and Configure Audit Log Extension

Source: https://docs.subscrio.com/reference/how-to-extend?q=

Installation commands and initialization code for the Subscrio audit log extension.

```bash
npm install @saas-experts/subscrio-audit-log
```

```typescript
import { Subscrio } from '@saas-experts/subscrio';
import { createAuditLog } from '@saas-experts/subscrio-audit-log';

const subscrio = new Subscrio({ database: { connectionString } });
await subscrio.installSchema();

const audit = createAuditLog(subscrio, { database: { connectionString } });
await audit.installSchema();

const { data, total } = await audit.list({ customerKey: 'acme', limit: 50 });
await audit.dispose();
```

--------------------------------

### Subscription State During Trial

Source: https://docs.subscrio.com/reference/subscription-lifecycle

Example of the subscription object state while the trial is active.

```json
{
  trialEndDate: "2025-02-03T00:00:00Z",      // 14 days from now
  expirationDate: "2025-02-03T00:00:00Z",    // Same as trialEndDate
  currentPeriodStart: "2025-02-03T00:00:00Z", // Would start billing here, but expires instead
  currentPeriodEnd: "2025-03-03T00:00:00Z",
  status: "trial"                             // trialEndDate > NOW()
}
```

```csharp
// SubscriptionDto: TrialEndDate, ExpirationDate (same), CurrentPeriodStart, CurrentPeriodEnd, Status: "trial"
```

--------------------------------

### Create Billing Cycle Usage Examples

Source: https://docs.subscrio.com/reference/billing-cycles?q=

Examples of invoking the createBillingCycle method to define a new billing cycle.

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

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

--------------------------------

### verifySchema() / VerifySchemaAsync()

Source: https://docs.subscrio.com/reference/core-overview?q=

Confirms whether the Subscrio schema is installed and returns the current version.

```APIDOC
## verifySchema() / VerifySchemaAsync()

### Description
Checks if the Subscrio schema is installed. Returns the version string if installed, or null if not.

### Returns
- **Promise<string | null> / Task<string?>** - The schema version string or null.

### Potential Errors
- **ConfigurationError** - Database connection is unavailable.
```

--------------------------------

### Install .NET Audit Log Package

Source: https://docs.subscrio.com/reference/how-to-extend

Add the required NuGet package for the Subscrio audit log extension.

```bash
dotnet add package Subscrio.AuditLog
```

--------------------------------

### verifySchema()

Source: https://docs.subscrio.com/reference/core-overview

Confirms whether the Subscrio schema is installed and returns the current version.

```APIDOC
## verifySchema()

### Description
Confirms whether the Subscrio schema is already installed. Returns the current schema version string or null if not installed.

### Returns
- **Promise<string | null> / Task<string?>** - The schema version string if installed, or null if not installed.

### Potential Errors
- **ConfigurationError** - Database connection is unavailable.
```

--------------------------------

### Initialize and Use TypeScript Audit Log

Source: https://docs.subscrio.com/reference/how-to-extend

Configure the audit log extension, install the schema, and perform queries.

```typescript
import { Subscrio } from '@saas-experts/subscrio';
import { createAuditLog } from '@saas-experts/subscrio-audit-log';

const subscrio = new Subscrio({ database: { connectionString } });
await subscrio.installSchema();

const audit = createAuditLog(subscrio, { database: { connectionString } });
await audit.installSchema();

const { data, total } = await audit.list({ customerKey: 'acme', limit: 50 });
await audit.dispose();
```

--------------------------------

### Subscrio SDK Methods

Source: https://docs.subscrio.com/reference/core-overview?q=

The Subscrio SDK provides methods for managing database lifecycle, including schema installation, migration, verification, and configuration synchronization.

```APIDOC
## SDK Methods

### installSchema / InstallSchemaAsync
Creates every Subscrio database table, seeds configuration rows, and optionally writes the admin passphrase hash.

### migrate / MigrateAsync
Runs pending database migrations to update the schema to the latest version.

### verifySchema / VerifySchemaAsync
Confirms whether the Subscrio schema is already installed and returns the current schema version.

### dropSchema / DropSchemaAsync
Removes every table created by Subscrio (for local development resets or automated tests).

### runInitialConfigSync / RunInitialConfigSyncAsync
If initial configuration was provided to the constructor, runs config sync (file or JSON) and returns the report.

### close / Dispose
Closes the database connection pool.
```

--------------------------------

### Initialize Subscrio Instance

Source: https://docs.subscrio.com/reference/core-overview?q=

Demonstrates how to instantiate the Subscrio client using database configuration strings in both TypeScript and .NET.

```typescript
import { Subscrio } from 'core.typescript';

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

```csharp
using Subscrio.Core;

var subscrio = new Subscrio(new SubscrioConfig
{
    Database = new DatabaseConfig
    {
        ConnectionString = Environment.GetEnvironmentVariable("DATABASE_URL") ?? ""
    }
});
```

--------------------------------

### new Subscrio(config: SubscrioConfig)

Source: https://docs.subscrio.com/reference/core-overview?q=

Instantiates the core library, initializes the database connection, and wires every repository and service for use.

```APIDOC
## Constructor

### Description
Instantiates the core library, initializes the database connection, and wires every repository and service so callers can use Subscrio synchronously after construction.

### Signature
`new Subscrio(config: SubscrioConfig)`

### Parameters
- **config** (SubscrioConfig) - Required - Database connection plus optional passphrase, Stripe, and logging overrides.

### Returns
- **Subscrio** - Instance with properties such as products, plans, featureChecker, etc.

### Potential Errors
- **ConfigurationError** - Thrown downstream if config is invalid or a database connection cannot be established.

### Example
```typescript
const subscrio = new Subscrio({
  database: { connectionString: process.env.DATABASE_URL! },
  adminPassphrase: process.env.ADMIN_PASSPHRASE
});
```
```

--------------------------------

### FindSubscriptionsAsync Usage Example

Source: https://docs.subscrio.com/reference/subscriptions?q=

Example of filtering subscriptions by expiration date range and feature overrides in C#.

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

--------------------------------

### installSchema

Source: https://docs.subscrio.com/reference/core-overview

Creates every Subscrio database table, seeds configuration rows, and optionally writes the admin passphrase hash when setting up a fresh environment.

```APIDOC
## installSchema

### Description
Creates every Subscrio database table, seeds configuration rows, and optionally writes the admin passphrase hash when setting up a fresh environment.

### Signature
- TypeScript: `installSchema(adminPassphrase?: string): Promise<void>`
- .NET: `Task InstallSchemaAsync(string? adminPassphrase = null)`

### Parameters
- **adminPassphrase** (string) - Optional - Plain text string that will be hashed before being stored in system_config. Supersedes config.adminPassphrase.

### Returns
- **void** (Promise<void> / Task) - Resolves/completes when the schema is fully installed.

### Potential Errors
- **ConfigurationError**: Database connection unavailable or migration prerequisites missing.
- **DomainError**: Passphrase validation fails the policy enforced by the installer.

### Example
```typescript
await subscrio.installSchema('super-secret-passphrase');
```
```csharp
await subscrio.InstallSchemaAsync("super-secret-passphrase");
```
```

--------------------------------

### findSubscriptions Usage Example

Source: https://docs.subscrio.com/reference/subscriptions?q=

Example of filtering subscriptions by expiration date range and feature overrides in TypeScript.

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

--------------------------------

### installSchema

Source: https://docs.subscrio.com/reference/core-overview?q=

Creates all necessary Subscrio database tables, seeds configuration rows, and optionally stores the admin passphrase hash for a fresh environment.

```APIDOC
## installSchema

### Description
Creates every Subscrio database table, seeds configuration rows, and optionally writes the admin passphrase hash when setting up a fresh environment.

### Signature
TypeScript: `installSchema(adminPassphrase?: string): Promise<void>`
.NET: `Task InstallSchemaAsync(string? adminPassphrase = null)`

### Parameters
- **adminPassphrase** (string) - Optional - Plain text string that will be hashed before being stored in system_config. Supersedes config.adminPassphrase.

### Returns
- **void** (Promise/Task) - Resolves/completes when the schema is fully installed.

### Potential Errors
- **ConfigurationError**: Database connection unavailable or migration prerequisites missing.
- **DomainError**: Passphrase validation fails the policy enforced by the installer.

### Example
TypeScript:
await subscrio.installSchema('super-secret-passphrase');

.NET:
await subscrio.InstallSchemaAsync("super-secret-passphrase");
```

--------------------------------

### Install TypeScript Audit Log Package

Source: https://docs.subscrio.com/reference/how-to-extend

Install the required npm package for the Subscrio audit log extension.

```bash
npm install @saas-experts/subscrio-audit-log
```

--------------------------------

### Create Products, Plans, and Billing Cycles

Source: https://docs.subscrio.com/reference/getting-started

Register a product, associate features, define a plan, and set up a billing cycle. Finally, configure specific feature values for the plan.

```typescript
const PRODUCT = 'projecthub';

const product = await subscrio.products.createProduct({
  key: PRODUCT,
  displayName: 'ProjectHub',
  description: 'Project management suite'
});

await subscrio.products.associateFeature(PRODUCT, FEATURE_KEYS.Analytics);
await subscrio.products.associateFeature(PRODUCT, FEATURE_KEYS.MaxProjects);

const PLAN = 'starter';

await subscrio.plans.createPlan({
  productKey: PRODUCT,
  key: PLAN,
  displayName: 'Starter Plan',
  description: 'Best for small teams'
});

const BILLING_CYCLE = 'starter-monthly';

await subscrio.billingCycles.createBillingCycle({
  planKey: PLAN,
  key: BILLING_CYCLE,
  displayName: 'Monthly',
  durationValue: 1,
  durationUnit: 'months'
});

await subscrio.plans.setFeatureValue(PLAN, FEATURE_KEYS.Analytics, 'true');
await subscrio.plans.setFeatureValue(PLAN, FEATURE_KEYS.MaxProjects, '10');
```

```csharp
const string PRODUCT = "projecthub";

var product = await subscrio.Products.CreateProductAsync(new CreateProductDto(
    Key: PRODUCT,
    DisplayName: "ProjectHub",
    Description: "Project management suite"
));

await subscrio.Products.AssociateFeatureAsync(PRODUCT, FEATURE_ANALYTICS);
await subscrio.Products.AssociateFeatureAsync(PRODUCT, FEATURE_MAX_PROJECTS);

const string PLAN = "starter";
const string BILLING_CYCLE = "starter-monthly";

await subscrio.Plans.CreatePlanAsync(new CreatePlanDto(
    ProductKey: PRODUCT,
    Key: PLAN,
    DisplayName: "Starter Plan",
    Description: "Best for small teams"
));

await subscrio.BillingCycles.CreateBillingCycleAsync(new CreateBillingCycleDto(
    PlanKey: PLAN,
    Key: BILLING_CYCLE,
    DisplayName: "Monthly",
    DurationValue: 1,
    DurationUnit: "months"
));

await subscrio.Plans.SetFeatureValueAsync(PLAN, FEATURE_ANALYTICS, "true");
await subscrio.Plans.SetFeatureValueAsync(PLAN, FEATURE_MAX_PROJECTS, "10");
```

--------------------------------

### Initialize Subscrio Instance

Source: https://docs.subscrio.com/reference/core-overview?q=

Instantiates the core library with database and administrative configuration. Throws a ConfigurationError if the provided config is invalid or the database connection fails.

```TypeScript
const subscrio = new Subscrio({
  database: { connectionString: process.env.DATABASE_URL! },
  adminPassphrase: process.env.ADMIN_PASSPHRASE
});
```

```.NET
var subscrio = new Subscrio(new SubscrioConfig
{
    Database = new DatabaseConfig { ConnectionString = Environment.GetEnvironmentVariable("DATABASE_URL")! },
    AdminPassphrase = Environment.GetEnvironmentVariable("ADMIN_PASSPHRASE")
});
```

--------------------------------

### runInitialConfigSync

Source: https://docs.subscrio.com/reference/config-sync

Applies the initial configuration defined during the Subscrio instance construction.

```APIDOC
## runInitialConfigSync()

### Description
Applies the configuration specified in the 'initialConfig' property of the Subscrio constructor. This is typically called after schema installation.

### Returns
- **report** (object|null) - The synchronization report if a configuration was applied, otherwise null.
```

--------------------------------

### Get Subscriptions by Customer

Source: https://docs.subscrio.com/reference/subscriptions

Retrieves all subscriptions associated with a specific customer key.

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

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

--------------------------------

### Get Feature Usage Summary

Source: https://docs.subscrio.com/reference/feature-checker?q=

Retrieves a rollup of feature resolutions and subscription counts for a customer and product.

```typescript
const summary = await featureChecker.getFeatureUsageSummary('acme-corp', 'projecthub');
console.log(summary.enabledFeatures);
```

```csharp
var summary = await subscrio.FeatureChecker.GetFeatureUsageSummaryAsync("acme-corp", "projecthub");
Console.WriteLine(string.Join(", ", summary.EnabledFeatures));
```

--------------------------------

### getPlansByProduct(productKey: string)

Source: https://docs.subscrio.com/reference/plans

Returns all plans associated with a specific product key.

```APIDOC
## getPlansByProduct(productKey: string)

### Description
Returns all plans owned by a product.

### Signature
- TypeScript: `getPlansByProduct(productKey: string): Promise<PlanDto[]>`
- C#: `Task<List<PlanDto>> GetPlansByProductAsync(string productKey)`

### Parameters
- **productKey** (string) - Required - Product key to inspect.

### Returns
- `Promise<PlanDto[]>` or `Task<List<PlanDto>>` - Array of plan entries scoped to the product.
```

--------------------------------

### Create a new subscription

Source: https://docs.subscrio.com/reference/subscriptions

Use this method to initialize a subscription with a specific customer, billing cycle, and metadata.

```csharp
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" }
));
```

--------------------------------

### syncFromFile

Source: https://docs.subscrio.com/reference/config-sync?q=

Loads configuration from a JSON file, validates it, and syncs products, features, plans, and billing cycles to the database.

```APIDOC
## syncFromFile

### Description
Loads configuration from a JSON file, validates it, and syncs products, features, plans, and billing cycles to the database. The `features` array must appear before the `products` array in the JSON file.

### Signature (TypeScript)
`syncFromFile(filePath: string): Promise<ConfigSyncReport>`

### Signature (.NET)
`Task<ConfigSyncReport> SyncFromFileAsync(string filePath)`

### Parameters
- **filePath** (string) - Required - Path to the JSON configuration file.

### Returns
- **ConfigSyncReport** (Object) - A report containing counts of created, updated, archived, unarchived, and ignored entities, along with any errors or warnings.

### Example (TypeScript)
```javascript
const report = await subscrio.configSync.syncFromFile('./config.json');
console.log(`Created: ${report.created.features} features, ${report.created.products} products`);
```

### Example (.NET)
```csharp
var report = await subscrio.ConfigSync.SyncFromFileAsync("./config.json");
Console.WriteLine($"Created: {report.Created.Features} features, {report.Created.Products} products");
```
```

--------------------------------

### Sync Configuration from JSON File

Source: https://docs.subscrio.com/reference/config-sync?q=

Synchronize features and products by loading a configuration from a local JSON file.

```typescript
import { Subscrio } from 'core.typescript';

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

// Sync from a JSON file
const report = await subscrio.configSync.syncFromFile('./config.json');

console.log(`Created: ${report.created.features} features, ${report.created.products} products`);
console.log(`Updated: ${report.updated.features} features, ${report.updated.products} products`);
```

```csharp
using Subscrio.Core;

var subscrio = new Subscrio(config);

var report = await subscrio.ConfigSync.SyncFromFileAsync("./config.json");

Console.WriteLine($"Created: {report.Created.Features} features, {report.Created.Products} products");
Console.WriteLine($"Updated: {report.Updated.Features} features, {report.Updated.Products} products");
```

--------------------------------

### Get Active Plans

Source: https://docs.subscrio.com/reference/feature-checker?q=

Retrieves a list of all plan keys associated with a customer's active or trial subscriptions.

```typescript
const plans = await featureChecker.getActivePlans('acme-corp');
```

```csharp
var plans = await subscrio.FeatureChecker.GetActivePlansAsync("acme-corp");
```

--------------------------------

### Create a product in C#

Source: https://docs.subscrio.com/reference/products

Uses the CreateProductAsync method to persist a new product with a dictionary for metadata.

```csharp
var product = await subscrio.Products.CreateProductAsync(new CreateProductDto(
    Key: "pro-suite",
    DisplayName: "Pro Suite",
    Description: "Advanced tier",
    Metadata: new Dictionary<string, object?> { ["tier"] = "pro" }
));
```

--------------------------------

### Initialize Configuration Sync Service

Source: https://docs.subscrio.com/reference/config-sync?q=

Instantiate the service using the core library to access the configuration synchronization features.

```typescript
import { Subscrio } from 'core.typescript';

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

```csharp
using Subscrio.Core;

var subscrio = new Subscrio(config);
var configSync = subscrio.ConfigSync;
```

--------------------------------

### Product Configuration Models

Source: https://docs.subscrio.com/reference/config-sync?q=

Definitions for product configuration in TypeScript and C#.

```typescript
interface ProductConfig {
  key: string;                    // Required, globally unique, immutable
  displayName: string;            // Required
  description?: string;           // Optional
  metadata?: Record<string, unknown>;  // Optional
  archived?: boolean;             // Optional, defaults to false
  features?: string[];            // Optional, array of feature keys
  plans?: PlanConfig[];          // Optional, nested plans
}
```

```csharp
public record ProductConfig(
    string Key,
    string DisplayName,
    string? Description = null,
    Dictionary<string, object?>? Metadata = null,
    bool? Archived = null,
    List<string>? Features = null,
    List<PlanConfig>? Plans = null
);
```

--------------------------------

### Initialize Plan Management Service

Source: https://docs.subscrio.com/reference/plans

Instantiate the service client to access plan management functionality.

```typescript
import { Subscrio } from 'core.typescript';

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

```csharp
using Subscrio.Core;

var subscrio = new Subscrio(config);
var plans = subscrio.Plans;
```

--------------------------------

### Retrieve plans by product

Source: https://docs.subscrio.com/reference/plans

Fetches all plans associated with a specific product key.

```typescript
const proPlans = await plans.getPlansByProduct('pro-suite');
```

```csharp
var proPlans = await subscrio.Plans.GetPlansByProductAsync("pro-suite");
```

--------------------------------

### Get Default Billing Cycles

Source: https://docs.subscrio.com/reference/billing-cycles?q=

Fetches pre-installed billing cycles like monthly, quarterly, or yearly. Returns an empty array if no defaults are configured.

```typescript
const defaults = await billingCycles.getDefaultBillingCycles();
```

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

--------------------------------

### syncFromFile / SyncFromFileAsync

Source: https://docs.subscrio.com/reference/config-sync?q=

Loads configuration from a JSON file and synchronizes it with the database.

```APIDOC
## syncFromFile / SyncFromFileAsync

### Description
Loads configuration from a JSON file and syncs the defined products, features, plans, and billing cycles to the database.

### Parameters
- **filePath** (string) - Required - The path to the JSON configuration file.

### Returns
- **ConfigSyncReport** - A report detailing the synchronization results.
```

--------------------------------

### Get Billing Cycles by Duration Unit

Source: https://docs.subscrio.com/reference/billing-cycles?q=

Retrieves a list of billing cycles filtered by a specific duration unit such as days, weeks, months, years, or forever.

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

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

--------------------------------

### getProduct(key: string)

Source: https://docs.subscrio.com/reference/products

Fetches a product snapshot by key, returning null when it does not exist.

```APIDOC
## getProduct(key: string)

### Description
Fetches a product snapshot by key, returning null when it does not exist.

### Parameters
- **key** (string) - Required - Product key to retrieve.

### Returns
- **Promise<ProductDto | null>** - The product snapshot or null if missing.
```

--------------------------------

### Create Subscription with Trial Period

Source: https://docs.subscrio.com/reference/subscription-lifecycle

Configures a subscription to automatically transition to a paid billing cycle after the trial period ends by omitting the expirationDate.

```typescript
// Calculate trial end date (7 days from now)
const trialEndDate = new Date();
trialEndDate.setDate(trialEndDate.getDate() + 7);

// Create subscription
const subscription = await subscrio.subscriptions.createSubscription({
  key: 'customer-123-pro-subscription',
  customerKey: 'customer-123',
  billingCycleKey: 'pro-monthly',
  trialEndDate: trialEndDate.toISOString(),
  // expirationDate is NOT set - billing will start after trial
});
```

```csharp
// Calculate trial end date (7 days from now)
var trialEndDate = DateTime.UtcNow.AddDays(7);

// Create subscription
var subscription = await subscrio.Subscriptions.CreateSubscriptionAsync(new CreateSubscriptionDto(
    Key: "customer-123-pro-subscription",
    CustomerKey: "customer-123",
    BillingCycleKey: "pro-monthly",
    TrialEndDate: trialEndDate
    // ExpirationDate is NOT set - billing will start after trial
));
```

--------------------------------

### Archive a product

Source: https://docs.subscrio.com/reference/products

Transitions a product to the archived state.

```typescript
const archived = await products.archiveProduct('starter');
console.log(archived.status); // 'archived'
```

```csharp
var archived = await subscrio.Products.ArchiveProductAsync("starter");
Console.WriteLine(archived.Status); // "archived"
```

--------------------------------

### SyncFromFileAsync

Source: https://docs.subscrio.com/reference/config-sync?q=

Synchronizes configuration data by loading it from a file.

```APIDOC
## SyncFromFileAsync

### Description
Synchronizes the system configuration by reading and parsing a configuration file. The file content must adhere to the defined JSON schema.

### Method
Async Method

### Parameters
- **filePath** (string) - Required - The path to the JSON configuration file.
```

--------------------------------

### syncFromFile

Source: https://docs.subscrio.com/reference/config-sync

Synchronizes configuration settings from a specified JSON file path.

```APIDOC
## syncFromFile(filePath: string)

### Description
Reads a configuration JSON file from the provided path and synchronizes the features and products defined within it.

### Parameters
- **filePath** (string) - Required - The local file path to the configuration JSON file.

### Returns
- **report** (object) - An object containing counts of created and updated features and products.
```

--------------------------------

### getCustomer(key: string)

Source: https://docs.subscrio.com/reference/customers?q=

Fetches a customer by key; returns null when missing.

```APIDOC
## getCustomer

### Description
Fetches a customer by key; returns null when missing.

### Signature
`getCustomer(key: string): Promise<CustomerDto | null>`

### Parameters
- **key** (string) - Required - Customer key.

### Returns
- **Promise<CustomerDto | null>** - The customer object or null if not found.
```

--------------------------------

### Initialize Stripe Integration Service

Source: https://docs.subscrio.com/reference/stripe-integration

Instantiate the service using the Subscrio core library in TypeScript and .NET environments.

```typescript
import { Subscrio } from 'core.typescript';

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

```csharp
using Subscrio.Core;

var subscrio = new Subscrio(config);
var stripeService = subscrio.Stripe;
```

--------------------------------

### Accessing Hooks

Source: https://docs.subscrio.com/reference/hooks?q=

How to initialize the Subscrio client and access the hooks interface in TypeScript and .NET.

```APIDOC
## Accessing Hooks

### TypeScript
```typescript
import { Subscrio, HookEvents } from 'core.typescript';

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

const hooks = subscrio.hooks;
```

### .NET
```csharp
using Subscrio.Core;
using Subscrio.Core.Application.Hooks;

var subscrio = new Subscrio(config);
var hooks = subscrio.Hooks;
```
```

--------------------------------

### createProduct

Source: https://docs.subscrio.com/reference/products

Creates a new product after validating key format, display name, and optional metadata. Rejects duplicate keys.

```APIDOC
## createProduct

### Description
Creates a new product after validating key format, display name, and optional metadata. Rejects duplicate keys.

### Signatures
- TypeScript: `createProduct(dto: CreateProductDto): Promise<ProductDto>`
- C#: `Task<ProductDto> CreateProductAsync(CreateProductDto dto)`

### Input Properties
- **key** (string) - Required - 1–255 chars, lowercase alphanumeric plus `-`.
- **displayName** (string) - Required - 1–255 char label.
- **description** (string) - Optional - ≤1000 chars.
- **metadata** (Record<string, unknown>) - Optional - JSON-safe metadata blob.

### Return Properties
- **key** (string) - Immutable product key.
- **displayName** (string) - Display name.
- **description** (string | null) - Optional description.
- **status** (string) - active, inactive, or archived.
- **metadata** (Record<string, unknown> | null) - Metadata blob.
- **createdAt** (string) - ISO timestamp.
- **updatedAt** (string) - ISO timestamp.

### Errors
- **ValidationError**: DTO fails schema checks (bad key format, display name length, etc.).
- **ConflictError**: A product with the same key already exists.
```

--------------------------------

### Create Trial Subscription

Source: https://docs.subscrio.com/reference/subscription-lifecycle

Initialize a subscription with a trial period by setting the trialEndDate and expirationDate to the same future timestamp.

```typescript
// Calculate trial end date (14 days from now)
const trialEndDate = new Date();
trialEndDate.setDate(trialEndDate.getDate() + 14);

const subscription = await subscrio.subscriptions.createSubscription({
  key: 'customer-123-pro-trial',
  customerKey: 'customer-123',
  billingCycleKey: 'pro-monthly',
  trialEndDate: trialEndDate.toISOString(),
  expirationDate: trialEndDate.toISOString(), // Same as trialEndDate - expires when trial ends
});
```

```csharp
// Calculate trial end date (14 days from now)
var trialEndDate = DateTime.UtcNow.AddDays(14);

var subscription = await subscrio.Subscriptions.CreateSubscriptionAsync(new CreateSubscriptionDto(
    Key: "customer-123-pro-trial",
    CustomerKey: "customer-123",
    BillingCycleKey: "pro-monthly",
    TrialEndDate: trialEndDate,
    ExpirationDate: trialEndDate  // Same as trialEndDate - expires when trial ends
));
```

--------------------------------

### Root Configuration JSON Structure

Source: https://docs.subscrio.com/reference/config-sync?q=

The features array must precede the products array in the configuration file.

```json
{
  "version": "1.0",
  "features": [...],
  "products": [...]
}
```

```json
{
  "version": "1.0",
  "features": [...],
  "products": [...]
}
```

--------------------------------

### Register Subscrio with Dependency Injection

Source: https://docs.subscrio.com/reference/getting-started

Configure Subscrio services within a .NET application using the dependency injection container.

```csharp
using Subscrio.Core.DependencyInjection;  // and Subscrio.Core.Config for ConfigLoader

var config = ConfigLoader.Load();
builder.Services.AddSubscrio(config, ServiceLifetime.Scoped);
```

--------------------------------

### Create a new plan

Source: https://docs.subscrio.com/reference/plans

Creates a new plan with an active status. Requires a valid product key and a unique plan key.

```TypeScript
await plans.createPlan({
  productKey: 'pro-suite',
  key: 'annual-pro',
  displayName: 'Annual Pro',
  metadata: { priceUsd: 499 }
});
```

```C#
await subscrio.Plans.CreatePlanAsync(new CreatePlanDto(
    ProductKey: "pro-suite",
    Key: "annual-pro",
    DisplayName: "Annual Pro",
    Metadata: new Dictionary<string, object?> { ["priceUsd"] = 499 }
));
```

--------------------------------

### Initialize Subscription Service

Source: https://docs.subscrio.com/reference/subscriptions

Initializes the Subscrio service instance for interacting with subscription data.

```typescript
import { Subscrio } from 'core.typescript';

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

```csharp
using Subscrio.Core;

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

--------------------------------

### Sync Configuration from File in .NET

Source: https://docs.subscrio.com/reference/config-sync

Synchronizes configuration from a JSON file using the asynchronous .NET method.

```csharp
Task<ConfigSyncReport> SyncFromFileAsync(string filePath)
```

```csharp
var report = await subscrio.ConfigSync.SyncFromFileAsync("./config.json");
Console.WriteLine($"Created: {report.Created.Features} features, {report.Created.Products} products");
```

--------------------------------

### createProduct / CreateProductAsync

Source: https://docs.subscrio.com/reference/products

Validates and persists a new product to the system.

```APIDOC
## createProduct / CreateProductAsync

### Description
Validates and persists a new product.

### Returns
- **ProductDto** (Object) - The created product object.
```

--------------------------------

### Create Checkout Session for New Subscription

Source: https://docs.subscrio.com/reference/how-to-integrate-with-stripe

Initializes a checkout session for a new subscription. Requires customer and billing cycle keys.

```typescript
// Create checkout for new subscription
const { url, sessionId } = await subscrio.stripe.createCheckoutSession({
  customerKey: 'customer_123',
  billingCycleKey: 'pro-monthly',
  successUrl: 'https://yourapp.com/success',
  cancelUrl: 'https://yourapp.com/cancel'
});

// Redirect user to checkout
window.location.href = url;
```

```csharp
var (url, sessionId) = await subscrio.Stripe.CreateCheckoutSessionAsync(
    customerKey: "customer_123",
    billingCycleKey: "pro-monthly",
    successUrl: "https://yourapp.com/success",
    cancelUrl: "https://yourapp.com/cancel"
);

return Redirect(url);
```

--------------------------------

### getPlan(planKey: string)

Source: https://docs.subscrio.com/reference/plans

Retrieves a specific plan by its unique key. Returns the PlanDto if found, or null if the plan does not exist.

```APIDOC
## getPlan(planKey: string)

### Description
Retrieves a plan by key, returning null when it is missing.

### Signature
- TypeScript: `getPlan(planKey: string): Promise<PlanDto | null>`
- C#: `Task<PlanDto?> GetPlanAsync(string planKey)`

### Parameters
- **planKey** (string) - Required - Plan identifier.

### Returns
- `Promise<PlanDto | null>` or `Task<PlanDto?>` - The plan object or null if not found.
```

--------------------------------

### Initialize Feature Management Service

Source: https://docs.subscrio.com/reference/features?q=

Instantiate the service client to begin interacting with feature management methods.

```typescript
import { Subscrio } from 'core.typescript';

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

```csharp
using Subscrio.Core;

var subscrio = new Subscrio(config);
var features = subscrio.Features;
```

--------------------------------

### Version Control Configuration Files

Source: https://docs.subscrio.com/reference/config-sync?q=

Organize environment-specific configuration files within a version control system.

```text
config/
├── production.json
├── staging.json
└── development.json
```

--------------------------------

### subscrio.plans.createPlan

Source: https://docs.subscrio.com/reference/subscription-lifecycle?q=

Configures a paid plan to automatically transition to a specified free billing cycle upon expiration.

```APIDOC
## subscrio.plans.createPlan

### Description
Creates a new plan with a defined transition target for when subscriptions expire.

### Parameters
- **productKey** (string) - Required - The product identifier.
- **key** (string) - Required - Unique identifier for the plan.
- **displayName** (string) - Required - Human-readable name of the plan.
- **onExpireTransitionToBillingCycleKey** (string) - Required - The billing cycle key to transition to when the subscription expires.
```

--------------------------------

### Sync Configuration from File in TypeScript

Source: https://docs.subscrio.com/reference/config-sync

Synchronizes configuration from a JSON file and logs the creation counts.

```typescript
syncFromFile(filePath: string): Promise<ConfigSyncReport>
```

```typescript
const report = await subscrio.configSync.syncFromFile('./config.json');
console.log(`Created: ${report.created.features} features, ${report.created.products} products`);
```

--------------------------------

### getActivePlans

Source: https://docs.subscrio.com/reference/feature-checker?q=

Lists plan keys for every active or trial subscription held by a customer across all products.

```APIDOC
## getActivePlans

### Description
Lists plan keys for every active/trial subscription held by a customer (across all products).

### Parameters
- **customerKey** (string) - Required - Customer identifier.

### Returns
- **Promise<string[]>** - Returns an array of plan keys; empty array when customer is missing or no active/trial subscriptions exist.

### Example
```typescript
const plans = await featureChecker.getActivePlans('acme-corp');
```
```

--------------------------------

### getProduct / GetProductAsync

Source: https://docs.subscrio.com/reference/products

Fetches a product by its unique key.

```APIDOC
## getProduct / GetProductAsync

### Description
Fetches a product by key.

### Returns
- **ProductDto | null** (Object) - The product object if found, otherwise null.
```

--------------------------------

### createPlan

Source: https://docs.subscrio.com/reference/plans

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

```APIDOC
## createPlan

### Description
Validates payload, ensures the product exists, and persists a new plan with active status.

### Signatures
- TypeScript: `createPlan(dto: CreatePlanDto): Promise<PlanDto>`
- .NET: `Task<PlanDto> CreatePlanAsync(CreatePlanDto dto)`

### Parameters
- **dto** (CreatePlanDto) - Required - Plan definition including product and metadata.

### Input Properties (CreatePlanDto)
- **productKey** (string) - Required - Product that owns the plan.
- **key** (string) - Required - Immutable plan key (1–255 chars).
- **displayName** (string) - Required - 1–255 char label.
- **description** (string) - Optional - ≤1000 characters.
- **onExpireTransitionToBillingCycleKey** (string) - Optional - Optional billing cycle key for automatic transitions.
- **metadata** (Record<string, unknown>) - Optional - JSON-safe metadata.

### Returns
- **PlanDto** - Persisted plan snapshot.

### Potential Errors
- **ValidationError**: DTO invalid.
- **NotFoundError**: Product key not found.
- **ConflictError**: Plan key already exists.
```
Tokens:
Raw