Customer Management Service Reference

Service Overview

Customers represent your end users or tenant accounts. This service manages creation, updates, lifecycle transitions (active/archived), uniqueness of customer keys, and optional externalBillingId (e.g., Stripe customer ID). Customers must be archived before deletion to ensure downstream data (subscriptions, invoices) can be reviewed.

• Customer keys are provided by your system and immutable once stored.
• externalBillingId is optional but must remain unique when present.
• Delete operations require the customer to be archived and pass entity canDelete() checks.

Accessing the Service

import { Subscrio } from 'core.typescript';

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

using Subscrio.Core;

var subscrio = new Subscrio(config);
var customers = subscrio.Customers;

Method Catalog

Method Reference

createCustomer

Description

Validates a new customer payload, ensures the key and externalBillingId (if provided) are unique, and persists the customer with active status.

Signature

createCustomer(dto: CreateCustomerDto): Promise<CustomerDto>

Task<CustomerDto> CreateCustomerAsync(CreateCustomerDto dto)

Inputs

Input Properties

Returns

Return Properties

Expected Results

• Validates DTO via schema.
• Ensures customer key and externalBillingId (if provided) are unique.
• Persists customer with status = 'active'.

Potential Errors

Example

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

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

updateCustomer

Description

Applies partial updates to display name, email, externalBillingId, or metadata.

Signature

updateCustomer(key: string, dto: UpdateCustomerDto): Promise<CustomerDto>

Task<CustomerDto> UpdateCustomerAsync(string key, UpdateCustomerDto dto)

Inputs

Input Properties

Returns

Expected Results

• Validates DTO.
• Loads customer by key.
• Ensures new externalBillingId is unique before saving.
• Applies updates and refreshes updatedAt.

Potential Errors

Example

await customers.updateCustomer('cust_123', {
  displayName: 'Acme Corp (2025)',
  metadata: { segment: 'enterprise' }
});

await subscrio.Customers.UpdateCustomerAsync("cust_123", new UpdateCustomerDto(
    DisplayName: "Acme Corp (2025)",
    Metadata: new Dictionary<string, object?> { ["segment"] = "enterprise" }
));

getCustomer

Description

Fetches a customer by key; returns null when missing.

Signature

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

Task<CustomerDto?> GetCustomerAsync(string key)

Inputs

Returns

Return Properties

Expected Results

• Reads from repository and returns DTO; null when key missing.

Potential Errors

Example

const customer = await customers.getCustomer('cust_123');
if (!customer) throw new Error('Missing customer');

var customer = await subscrio.Customers.GetCustomerAsync("cust_123");
if (customer == null) throw new InvalidOperationException("Missing customer");

listCustomers

Description

Lists customers with optional status/search filters and pagination.

Signature

listCustomers(filters?: CustomerFilterDto): Promise<CustomerDto[]>

Task<List<CustomerDto>> ListCustomersAsync(CustomerFilterDto? filters = null)

Inputs

Input Properties

Returns

Return Properties

Expected Results

• Validates filters and returns DTO array.

Potential Errors

Example

const customersPage = await customers.listCustomers({
  status: 'active',
  search: 'acme',
  limit: 25
});

var customersPage = await subscrio.Customers.ListCustomersAsync(new CustomerFilterDto(
    Status: "active",
    Search: "acme",
    Limit: 25
));

archiveCustomer

Description

Marks a customer as archived (no new subscriptions should be issued).

Signature

archiveCustomer(key: string): Promise<void>

Task ArchiveCustomerAsync(string key)

Inputs

Returns

Expected Results

• Loads customer, calls entity archive(), saves.

Potential Errors

Example

await customers.archiveCustomer('cust_legacy');

await subscrio.Customers.ArchiveCustomerAsync("cust_legacy");

unarchiveCustomer

Description

Restores an archived customer to active.

Signature

unarchiveCustomer(key: string): Promise<void>

Task UnarchiveCustomerAsync(string key)

Inputs

Returns

Expected Results

• Loads customer, calls unarchive(), saves.

Potential Errors

Example

await customers.unarchiveCustomer('cust_legacy');

await subscrio.Customers.UnarchiveCustomerAsync("cust_legacy");

deleteCustomer

Description

Permanently deletes a customer that has already been archived and passes domain checks.

Signature

deleteCustomer(key: string): Promise<void>

Task DeleteCustomerAsync(string key)

Inputs

Returns

Expected Results

• Loads customer, ensures customer.canDelete() (must be archived and free of blocking relationships).
• Deletes record via repository.

Potential Errors

Example

await customers.deleteCustomer('cust_retired');

await subscrio.Customers.DeleteCustomerAsync("cust_retired");

Related Workflows

• Subscriptions reference customers by ID; deleting a customer does not cascade—clean related subscriptions manually if needed.
• Stripe integration (StripeIntegrationService) expects externalBillingId to store the Stripe customer ID.
• Feature checker APIs use customer keys to resolve entitlements; keep keys stable for the life of the user/account.