Manage subscriptions and invoices

The client.billing namespace wraps /api/v1/billing/* — Stripe Checkout for new subscriptions, the Stripe Customer Portal redirect, current subscription status, invoice history, and subscription cancellation or reactivation. See the matching REST documentation at Billing API.

HTTP-level failures surface as EBonApiError — see Errors and /en/api/errors.

Start a Stripe Checkout session

Call client.billing.createSubscription(body) to create a Stripe Checkout Session your customer can complete in the browser.

async createSubscription(body: CreateSubscriptionBody): Promise<CreateSubscriptionResult>

Returns { sessionId, url, clientSecret } — redirect the browser to url, or use clientSecret with Stripe's embedded Checkout component.

const session = await client.billing.createSubscription({
  successUrl: 'https://app.example.com/billing/success',
  cancelUrl: 'https://app.example.com/billing/cancel',
});
window.location.href = session.url;

Open the Stripe customer portal

Call client.billing.getPortalUrl(body) to get a short-lived Stripe Customer Portal URL where the customer can manage payment methods, download invoices and update billing details.

async getPortalUrl(body: PortalBody): Promise<PortalResult>

Returns { url: string }.

const { url } = await client.billing.getPortalUrl({
  returnUrl: 'https://app.example.com/billing',
});

Check current subscription status

Call client.billing.getSubscription() to read the current plan and subscription state.

async getSubscription(): Promise<SubscriptionInfo>

No parameters. Returns { plan, status, subscription: { id, status, currentPeriodEnd, cancelAtPeriodEnd } | null }.

const info = await client.billing.getSubscription();
if (info.subscription?.cancelAtPeriodEnd) {
  console.warn('Subscription will not renew.');
}

List invoices

Call client.billing.getInvoices(query?) to page through past invoices using a Stripe-style cursor.

async getInvoices(query?: ListInvoicesQuery): Promise<ListInvoicesResult>

Returns { invoices: InvoiceData[], hasMore: boolean }.

const { invoices, hasMore } = await client.billing.getInvoices();

Cancel a subscription at period end

Call client.billing.cancelSubscription() to schedule cancellation at the end of the current billing period.

async cancelSubscription(): Promise<undefined>

No parameters. Returns undefined on success. The subscription stays active until currentPeriodEnd; call client.billing.resumeSubscription() to reverse the cancellation before then.

await client.billing.cancelSubscription();

Reactivate a cancelled subscription

Call client.billing.resumeSubscription() to undo a scheduled cancellation while the subscription is still inside the grace window.

async resumeSubscription(): Promise<undefined>

No parameters. Returns undefined on success. Only effective while the subscription is still within the cancellation grace window.

await client.billing.resumeSubscription();