Skip to content

Customers

Purpose

Customers identify the people or accounts that hold subscriptions. Their stable keys also identify usage and credit wallets; external billing IDs connect them to a payment provider.

Access and initialization

Access

const customers = subscrio.customers;

var customers = subscrio.Customers;

Method catalog

Database and connection failures may propagate from any operation. Method-specific errors are listed with each method.

Method Purpose
createCustomer Creates an active customer.
updateCustomer Updates contact and billing properties.
getCustomer Gets a customer or null.
listCustomers Lists matching customers.
archiveCustomer Archives a customer.
unarchiveCustomer Restores active status.
deleteCustomer Permanently deletes an archived customer.
Method Purpose
CreateCustomerAsync Creates an active customer.
UpdateCustomerAsync Updates contact and billing properties.
GetCustomerAsync Gets a customer or null.
ListCustomersAsync Lists matching customers.
ArchiveCustomerAsync Archives a customer.
UnarchiveCustomerAsync Restores active status.
DeleteCustomerAsync Permanently deletes an archived customer.

Method details

createCustomer

Create an active customer with a unique key and, when supplied, a unique external billing ID. Customer mutations emit before and after hooks.

createCustomer(dto: CreateCustomerDto): Promise<CustomerDto>

Parameters

Returns CustomerDto: Saved customer properties.

Example

await subscrio.customers.createCustomer({
  key: 'acme', displayName: 'Acme', email: 'billing@acme.test'
});
Errors (2)
  • ValidationError: The customer properties are invalid.
  • ConflictError: The key or external billing ID is already used.
Task<CustomerDto> CreateCustomerAsync(CreateCustomerDto dto)

Parameters

Returns CustomerDto: Saved customer properties.

Example

await subscrio.Customers.CreateCustomerAsync(new CreateCustomerDto(
    Key: "acme", DisplayName: "Acme", Email: "billing@acme.test"));
Errors (2)
  • ValidationException: The customer properties are invalid.
  • ConflictException: The key or external billing ID is already used.

updateCustomer

Update contact and billing details without changing the customer key. Supplied metadata replaces the saved object; an empty object removes all metadata entries.

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

Parameters

Returns CustomerDto: Saved customer properties.

Example

await subscrio.customers.updateCustomer('acme', {
  displayName: 'Acme Corporation', metadata: { segment: 'enterprise' }
});
Errors (3)
  • ValidationError: The updated properties are invalid.
  • NotFoundError: The customer does not exist.
  • ConflictError: Another customer uses the external billing ID.
Task<CustomerDto> UpdateCustomerAsync(string key, UpdateCustomerDto dto)

Parameters

Returns CustomerDto: Saved customer properties.

Example

await subscrio.Customers.UpdateCustomerAsync("acme", new UpdateCustomerDto(
    DisplayName: "Acme Corporation",
    Metadata: new Dictionary<string, object?> { ["segment"] = "enterprise" }));
Errors (3)
  • ValidationException: The updated properties are invalid.
  • NotFoundException: The customer does not exist.
  • ConflictException: Another customer uses the external billing ID.

getCustomer

Retrieve customer details, including archived customers.

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

Parameters

  • key: Customer key.

Returns CustomerDto | null: Customer details, or null when missing.

Example

const customer = await subscrio.customers.getCustomer('acme');
console.log(customer?.displayName);

Task<CustomerDto?> GetCustomerAsync(string key)

Parameters

  • key: Customer key.

Returns CustomerDto?: Customer details, or null when missing.

Example

var customer = await subscrio.Customers.GetCustomerAsync("acme");
Console.WriteLine(customer?.DisplayName);

listCustomers

List customers with filtering, sorting, and pagination. Results default to newest-created first.

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

Parameters

Returns CustomerDto[]: Matching customers, or an empty collection.

Example

const customers = await subscrio.customers.listCustomers({
  status: 'active', search: 'acme', limit: 25, offset: 0
});
console.log(customers);
Errors (1)
  • ValidationError: The filters or pagination values are invalid.
Task<List<CustomerDto>> ListCustomersAsync(CustomerFilterDto? filters)

Parameters

Returns List<CustomerDto>: Matching customers, or an empty collection.

Example

var customers = await subscrio.Customers.ListCustomersAsync(
    new CustomerFilterDto(Status: "active", Search: "acme", Limit: 25));
Console.WriteLine(customers.Count);
Errors (1)
  • ValidationException: The filters or pagination values are invalid.

archiveCustomer

Mark the customer as archived while retaining their subscriptions and history. Archiving does not cancel subscriptions.

archiveCustomer(key: string): Promise<void>

Parameters

  • key: Customer key.

Returns No returned value.

Example

await subscrio.customers.archiveCustomer('acme');
Errors (1)
  • NotFoundError: The customer does not exist.
Task ArchiveCustomerAsync(string key)

Parameters

  • key: Customer key.

Returns No returned value.

Example

await subscrio.Customers.ArchiveCustomerAsync("acme");
Errors (1)
  • NotFoundException: The customer does not exist.

unarchiveCustomer

Restore the customer to active status without changing their subscriptions.

unarchiveCustomer(key: string): Promise<void>

Parameters

  • key: Customer key.

Returns No returned value.

Example

await subscrio.customers.unarchiveCustomer('acme');
Errors (1)
  • NotFoundError: The customer does not exist.
Task UnarchiveCustomerAsync(string key)

Parameters

  • key: Customer key.

Returns No returned value.

Example

await subscrio.Customers.UnarchiveCustomerAsync("acme");
Errors (1)
  • NotFoundException: The customer does not exist.

deleteCustomer

Permanently delete an archived customer. Database cascades also delete dependent subscriptions and their overrides. Retained usage, credit, or related accounting history can block deletion; archive customers whose history must remain.

deleteCustomer(key: string): Promise<void>

Parameters

  • key: Customer key.

Returns No returned value.

Example

// acme is archived and has no retained accounting history.
await subscrio.customers.deleteCustomer('acme');
Errors (3)
  • NotFoundError: The customer does not exist.
  • ValidationError: The customer is not archived.
  • ConflictError: Retained accounting or related history prevents deletion.
Task DeleteCustomerAsync(string key)

Parameters

  • key: Customer key.

Returns No returned value.

Example

// acme is archived and has no retained accounting history.
await subscrio.Customers.DeleteCustomerAsync("acme");
Errors (3)
  • NotFoundException: The customer does not exist.
  • DomainException: The customer is not archived.
  • ConflictException: Retained accounting or related history prevents deletion.

Data types

Required means an input must be supplied, or an output property is guaranteed present.

CreateCustomerDto

Customer creation properties.

Field Type Required Default Meaning
key string Yes None Stable identifier.
displayName string | undefined No None Optional label, at most 255 characters.
email string | undefined No None Valid contact email address.
externalBillingId string | undefined No None Unique payment-provider customer ID, at most 255 characters.
metadata Record<string, unknown> | undefined No None Application metadata; updates replace the entire object.
Property Type Required Default Meaning
Key string Yes None Stable identifier.
DisplayName string? No null Optional label, at most 255 characters.
Email string? No null Valid contact email address.
ExternalBillingId string? No null Unique payment-provider customer ID, at most 255 characters.
Metadata Dictionary<string, object?>? No null Application metadata; updates replace the entire object.

CustomerDto

Customer details returned by queries and mutations.

Field Type Required Default Meaning
key string Yes Not applicable Stable identifier.
displayName string | null | undefined No Not applicable Optional label, at most 255 characters.
email string | null | undefined No Not applicable Valid contact email address.
externalBillingId string | null | undefined No Not applicable Unique payment-provider customer ID, at most 255 characters.
status string Yes Not applicable Stored status. These methods write active or archived.
metadata Record<string, unknown> | null | undefined No Not applicable Application metadata; updates replace the entire object.
createdAt string Yes Not applicable Creation time in UTC.
updatedAt string Yes Not applicable Last update time in UTC.
Property Type Required Default Meaning
Key string Yes Not applicable Stable identifier.
DisplayName string? Yes Not applicable Optional label, at most 255 characters.
Email string? Yes Not applicable Valid contact email address.
ExternalBillingId string? Yes Not applicable Unique payment-provider customer ID, at most 255 characters.
Status string Yes Not applicable Stored status. These methods write active or archived.
Metadata Dictionary<string, object?>? Yes Not applicable Application metadata; updates replace the entire object.
CreatedAt string Yes Not applicable Creation time in UTC.
UpdatedAt string Yes Not applicable Last update time in UTC.

UpdateCustomerDto

Customer update properties.

Field Type Required Default Meaning
displayName string | undefined No None Optional label, at most 255 characters.
email string | undefined No None Valid contact email address.
externalBillingId string | undefined No None Unique payment-provider customer ID, at most 255 characters.
metadata Record<string, unknown> | undefined No None Application metadata; updates replace the entire object.
Property Type Required Default Meaning
DisplayName string? No null Optional label, at most 255 characters.
Email string? No null Valid contact email address.
ExternalBillingId string? No null Unique payment-provider customer ID, at most 255 characters.
Metadata Dictionary<string, object?>? No null Application metadata; updates replace the entire object.

CustomerFilterDto

Customer search options. TypeScript requires limit and offset when supplying a filter object.

Field Type Required Default Meaning
limit number Yes 50 Maximum page size, 1 to 100.
offset number Yes 0 Nonnegative number of rows to skip.
status "active" | "archived" | "suspended" | "deleted" | undefined No None active, archived, suspended, or deleted.
search string | undefined No None Match the key, display name, or email.
sortBy "key" | "displayName" | "createdAt" | undefined No None displayName, key, or createdAt; defaults to createdAt.
sortOrder "asc" | "desc" | undefined No None asc or desc; defaults to desc.
Property Type Required Default Meaning
Status string? No null active, archived, suspended, or deleted.
Search string? No null Match the key, display name, or email.
SortBy string? No null displayName, key, or createdAt; defaults to createdAt.
SortOrder string? No null asc or desc; defaults to desc.
Limit int No 50 Maximum page size, 1 to 100.
Offset int No 0 Nonnegative number of rows to skip.