Customers in Stripe

This chapter follows Stripe API keys and the Node.js SDK.

Your app has users; Stripe has Customers. Link them once and reuse the Stripe id for Checkout, subscriptions, and saved cards. The examples store { appUserId, stripeCustomerId } in a Map—replace that with your database in production.

Create a Customer at signup

When someone registers, create a Customer in the same request flow (or immediately after):

1
/** @type {Map<string, { stripeCustomerId: string, email: string }>} */
2
export const usersById = new Map();

1
import { stripe } from '../stripe-client.js';
2
import { usersById } from '../store.js';
3

4
export async function signup(req, res) {
5
  const { userId, email, name } = req.body;
6

7
  const customer = await stripe.customers.create({
8
    email,
9
    name,
10
    metadata: { appUserId: userId },
11
  });
12

13
  usersById.set(userId, { stripeCustomerId: customer.id, email });
14
  res.status(201).json({ userId, stripeCustomerId: customer.id });
15
}

Store customer.id (for example cus_...) on your user record. If signup can retry, pass an idempotency key tied to userId.

Metadata and lookups

Metadata is key-value pairs on the Customer (up to 50 keys, string values). Use appUserId so Dashboard search and support tools match your database.

Retrieve or update later:

1
const customer = await stripe.customers.retrieve('cus_...');
2
await stripe.customers.update('cus_...', {
3
  metadata: { plan: 'pro' },
4
});

List with a filter on metadata when debugging:

1
const list = await stripe.customers.list({ limit: 10, email: 'user@example.com' });

Prefer storing stripeCustomerId in your app as the primary join key; metadata is a backup for humans and scripts.

Saving payment methods with SetupIntents

A PaymentMethod represents a card or wallet. To save without charging, use a SetupIntent (or save during Checkout with setup_future_usage on a PaymentIntent—covered in payment chapters).

Server: create a SetupIntent for the Customer:

1
import { stripe } from '../stripe-client.js';
2
import { usersById } from '../store.js';
3

4
export async function createSetupIntent(req, res) {
5
  const { userId } = req.body;
6
  const user = usersById.get(userId);
7
  if (!user) return res.status(404).json({ error: 'Unknown user' });
8

9
  const setupIntent = await stripe.setupIntents.create({
10
    customer: user.stripeCustomerId,
11
    automatic_payment_methods: { enabled: true },
12
  });
13

14
  res.json({ clientSecret: setupIntent.client_secret });
15
}

Browser: confirm with Stripe.js (same pattern as Payment Element—details in Custom payment forms with the Payment Element). After success, the PaymentMethod is attached to the Customer.

List saved methods:

1
const methods = await stripe.paymentMethods.list({
2
  customer: user.stripeCustomerId,
3
  type: 'card',
4
});

On-session versus off-session payments

On-session — The customer is present in your checkout UI and can complete 3D Secure or other authentication when the bank asks.

Off-session — You charge later without the customer in the flow (renewals, usage bills, background captures). The bank may still reject the charge if authentication is required and was not set up earlier.

When saving a card for off-session use, set usage: 'off_session' on the SetupIntent (or setup_future_usage: 'off_session' when creating a PaymentIntent). Off-session charges use payment_method and off_session: true on a PaymentIntent; failures with authentication_required should prompt the customer to return on-session.

1
await stripe.paymentIntents.create({
2
  amount: 1500,
3
  currency: 'usd',
4
  customer: user.stripeCustomerId,
5
  payment_method: savedPaymentMethodId,
6
  off_session: true,
7
  confirm: true,
8
});

Subscriptions and invoices handle much of this automatically; see Subscriptions in Stripe.

Default payment method and Customer Portal

Set invoice_settings.default_payment_method on the Customer so subscriptions and invoices pick the right card. The Customer Portal (configured in the Dashboard) lets customers update cards without custom UI—useful alongside Subscriptions in Stripe.

Next: Products and prices in Stripe.