Customers

customerId is the stable app identity that Guapocado checks and bills.

It is not required to be a Stripe customer ID. In most apps, it should be the thing your product sells to.

Common Choices

Use a user ID for individual products:

customerId: `user_${user.id}`

Use an organization ID for B2B SaaS:

customerId: `org_${organization.id}`

Use a workspace ID when billing is per workspace:

customerId: `workspace_${workspace.id}`

Use a team ID when teams inside an organization buy separate plans:

customerId: `team_${team.id}`

Choose Once

The most important rule is consistency. If checkout uses org_123, feature checks and usage consumption also need to use org_123.

This is good:

const guap = createGuapocadoClient({
  apiKey: process.env.GUAPOCADO_API_KEY!,
  customerId: `org_${org.id}`,
});

await guap.checkout.create({ productKey: "pro", successUrl, cancelUrl });
await guap.has("sso");
await guap.usage.consume("api-calls", 1);

This is a bug:

await checkoutForCustomer(`org_${org.id}`);
await checkFeatureForCustomer(`user_${user.id}`);

The user might belong to the organization, but the billing state is attached to the organization.

Create or Sync a Customer

You can create a customer record before checkout or before the first runtime check:

await guap.customers.create({
  id: `org_${org.id}`,
  name: org.name,
  email: owner.email,
});

Framework integrations can often do this for you. Better Auth exposes customer.sync() for the current session.

Per-call Overrides

You can set a default customer ID on the client:

const guap = createGuapocadoClient({
  apiKey: process.env.GUAPOCADO_API_KEY!,
  customerId: `org_${org.id}`,
});

Or pass it per call:

await guap.has("advanced-analytics", {
  customerId: `org_${org.id}`,
});

Default customer IDs are convenient in request-scoped code. Per-call overrides are useful in admin jobs or batch operations.

Mapping Auth to Billing

Auth identifies who is making the request. Billing identifies which customer is being checked.

In a B2B app those are different:

const user = await requireUser(request);
const org = await requireActiveOrg(user);

const guap = createGuapocadoClient({
  apiKey: process.env.GUAPOCADO_API_KEY!,
  customerId: `org_${org.id}`,
});

The user proves access to the organization. The organization is the billing customer.