basalt / subscriptions/src / Subscriptions
Class: Subscriptions
Defined in: subscriptions/src/subscriptions.ts:93
Constructors
Constructor
> new Subscriptions(options): Subscriptions
Defined in: subscriptions/src/subscriptions.ts:103
Parameters
options
Returns
Subscriptions
Methods
cancel()
> cancel(billableId, options?): Promise<SubscriptionRecord>
Defined in: subscriptions/src/subscriptions.ts:277
Parameters
billableId
string
options?
atPeriodEnd?
boolean
Returns
Promise<SubscriptionRecord>
checkout()
> checkout(billableId, planName, options): Promise<{ url: string; }>
Defined in: subscriptions/src/subscriptions.ts:165
Starts a hosted Checkout flow for a paid plan. Records the intended subscription locally as incomplete — it becomes active when the gateway confirms payment via webhook (payment.succeeded). Returns the URL to redirect the customer to.
Parameters
billableId
string
planName
string
options
cancelUrl
string
period?
successUrl
string
Returns
Promise<{ url: string; }>
expireTrials()
> expireTrials(): Promise<SubscriptionRecord[]>
Defined in: subscriptions/src/subscriptions.ts:526
Maintenance (run from the scheduler): settles expired local trials. Gateway-backed trials are settled by the gateway's webhook, not here.
Returns
Promise<SubscriptionRecord[]>
features()
> features(billableId): object
Defined in: subscriptions/src/subscriptions.ts:325
Feature checks and consumption, Soulbscription-style.
Parameters
billableId
string
Returns
object
can
> can: (feature) => Promise<boolean>
Parameters
feature
string
Returns
Promise<boolean>
consume
> consume: (feature, amount) => Promise<number>
Parameters
feature
string
amount?
number = 1
Returns
Promise<number>
limit
> limit: (feature) => Promise<number>
Parameters
feature
string
Returns
Promise<number>
remaining
> remaining: (feature) => Promise<number>
Parameters
feature
string
Returns
Promise<number>
usage
> usage: (feature) => Promise<number>
Parameters
feature
string
Returns
Promise<number>
get()
> get(billableId): Promise<SubscriptionRecord | null>
Defined in: subscriptions/src/subscriptions.ts:208
Parameters
billableId
string
Returns
Promise<SubscriptionRecord | null>
handleWebhook()
> handleWebhook(event): Promise<boolean>
Defined in: subscriptions/src/subscriptions.ts:388
Applies a gateway webhook: idempotent by event id, updates local state and emits domain hooks. Local state is the read model — feature checks never call the gateway.
Parameters
event
Returns
Promise<boolean>
onTrial()
> onTrial(billableId): Promise<boolean>
Defined in: subscriptions/src/subscriptions.ts:220
Parameters
billableId
string
Returns
Promise<boolean>
plan()
> plan(name): PlanDefinition
Defined in: subscriptions/src/subscriptions.ts:115
Parameters
name
string
Returns
portal()
> portal(billableId, options): Promise<{ url: string; }>
Defined in: subscriptions/src/subscriptions.ts:203
Opens a Customer Portal session for self-service billing (update card, change plan, cancel). Returns the URL to redirect the customer to.
Parameters
billableId
string
options
returnUrl
string
Returns
Promise<{ url: string; }>
resume()
> resume(billableId): Promise<SubscriptionRecord>
Defined in: subscriptions/src/subscriptions.ts:309
Undoes a cancel({ atPeriodEnd: true }). For a gateway-backed subscription the scheduled cancellation is withdrawn at the gateway too — otherwise the gateway still ends the subscription at the period end and its subscription.canceled webhook would cancel the "resumed" one locally. Throws GatewayUnsupportedError when the gateway cannot resume.
Parameters
billableId
string
Returns
Promise<SubscriptionRecord>
subscribe()
> subscribe(billableId, planName, options?): Promise<SubscriptionRecord>
Defined in: subscriptions/src/subscriptions.ts:123
Parameters
billableId
string
planName
string
options?
period?
Returns
Promise<SubscriptionRecord>
subscribed()
> subscribed(billableId, plan?): Promise<boolean>
Defined in: subscriptions/src/subscriptions.ts:213
Active = status active, or trialing with the trial still running.
Parameters
billableId
string
plan?
string
Returns
Promise<boolean>
swap()
> swap(billableId, planName, options?): Promise<SubscriptionRecord>
Defined in: subscriptions/src/subscriptions.ts:245
Changes the plan on an active subscription. When the subscription is gateway-backed, the change is pushed to the gateway with proration so the customer is credited/charged the mid-cycle difference (pass { prorate: false } to switch at the next renewal with no immediate settlement).
Fails closed when nothing would be charged: a subscription without a gateway subscription (a local/free one) cannot be swapped onto a paid (or 'custom') plan — that throws PaymentRequiredError; start a checkout() instead. Pass { allowUnpaid: true } only when payment is collected outside the gateway (manual invoicing, reference payments, sales-led deals). A gateway-backed subscription whose gateway cannot swap throws GatewayUnsupportedError rather than changing only the local plan while the gateway keeps charging the old price.
Parameters
billableId
string
planName
string
options?
allowUnpaid?
boolean
prorate?
boolean
Returns
Promise<SubscriptionRecord>