Customers & portal

Look up customers, understand the per-provider email-filter caveats, and mint short-lived customer portal sessions that expire quickly.

Customers are the provider-side identity a subscription belongs to. revenue-sdk normalizes them into one shape and gives you a single call for the provider’s self-service billing portal.

The Customer model

Reading customers

const customer = await client.customers.get({ id: 'CUSTOMER_ID' });

const { items, cursor } = await client.customers.list({ limit: 50 });

for await (const entry of client.customers.listAll()) {
  console.log(entry.id, entry.email);
}

The email filter and its caveats

customers.list accepts an exact-match email filter:

const { items } = await client.customers.list({ email: '[email protected]' });
const customer = items[0];

It is supported by all five providers, but it does not behave identically:

A defensive lookup that survives duplicates:

const { items } = await client.customers.list({ email, limit: 100 });

if (items.length > 1) {
  // Ambiguous — prefer the customer that already has a subscription.
  logger.warn(`Multiple customers share ${email}`, { ids: items.map((c) => c.id) });
}

Customer portal sessions

The customer portal is the provider-hosted page where a customer updates their payment method, views invoices, and cancels. customerPortal.createSession mints a session and returns its URL:

const session = await client.customerPortal.createSession({
  customerId: customer.id,
  returnUrl: 'https://example.com/account', // requires the portalReturnUrl capability
});

redirect(session.url);

Mint one per click — the URLs expire

Portal URLs are short-lived, signed links. Generate one when the customer clicks the button, never at page render and never in a cached response or an email.

// A route that redirects straight into a freshly minted portal session.
export async function GET(request: Request): Promise<Response> {
  const customerId = await resolveCustomerId(request);
  const session = await client.customerPortal.createSession({ customerId });
  return Response.redirect(session.url, 302);
}

returnUrl support

returnUrl is gated by the portalReturnUrl capability:

Passing it to Lemon Squeezy or Paddle throws RevenueError with code unsupported. In provider-agnostic code, gate it:

const session = await client.customerPortal.createSession({
  customerId,
  returnUrl: client.capabilities.portalReturnUrl ? 'https://example.com/account' : undefined,
});