Customers

Create and manage customer records. Customers are the users of your application who have subscriptions.

Customer Creation

Customers can be created in several ways:

  • Magic link auth — Automatically created on first login (if autoCreateCustomer is enabled)
  • Checkout — Created when a new user completes checkout
  • API — Manually create customers via the API

Get Customer

Retrieve a customer by ID or email.

Using the SDK

typescript
import { StackBE } from '@stackbe/sdk';

const stackbe = new StackBE({
  apiKey: process.env.STACKBE_API_KEY!,
  appId: process.env.STACKBE_APP_ID!,
});

// Get by ID
const customer = await stackbe.customers.get('cust_abc123');

// Get by email
const customer = await stackbe.customers.getByEmail('user@example.com');

console.log(customer);
// {
//   id: 'cust_abc123',
//   email: 'user@example.com',
//   name: 'John Doe',
//   metadata: { companyName: 'Acme Inc' },
//   createdAt: '2025-01-15T10:30:00Z'
// }

Via API

bash
# Get by ID
curl "https://api.stackbe.io/v1/customers/cust_abc123" \
  -H "Authorization: Bearer sk_live_your_api_key"

# Get by email
curl "https://api.stackbe.io/v1/customers?email=user@example.com" \
  -H "Authorization: Bearer sk_live_your_api_key"

Create Customer

Manually create a customer. This is useful for importing existing users or creating customers before they sign up.

typescript
const customer = await stackbe.customers.create({
  email: 'user@example.com',
  name: 'John Doe',              // Optional
  metadata: {                    // Optional - store any custom data
    companyName: 'Acme Inc',
    plan: 'enterprise',
    source: 'sales_demo',
  },
});

console.log(customer.id);  // 'cust_xyz789'

Via API

bash
curl -X POST "https://api.stackbe.io/v1/customers" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "name": "John Doe",
    "metadata": {
      "companyName": "Acme Inc"
    }
  }'

Update Customer

Update customer details or metadata.

typescript
await stackbe.customers.update('cust_abc123', {
  name: 'Jane Doe',
  metadata: {
    companyName: 'New Company',
    tier: 'vip',
  },
});

Metadata merging: When updating metadata, new keys are added and existing keys are overwritten. To remove a key, set it to null.

List Customers

List all customers with pagination and filtering.

typescript
// List with pagination
const { data: customers, pagination } = await stackbe.customers.list({
  limit: 50,
  offset: 0,
});

// Search by email
const { data: customers } = await stackbe.customers.list({
  email: 'john@',  // Partial match
});

console.log(pagination);
// { total: 150, limit: 50, offset: 0 }

Subscription History

Retrieve all subscriptions (including canceled) for a customer.

typescript
const subscriptions = await stackbe.customers.getSubscriptionHistory('cust_abc123');

// Returns array of all subscriptions
subscriptions.forEach(sub => {
  console.log(`${sub.plan.name}: ${sub.status}`);
});

Invoice History

Retrieve invoice history from Stripe for a customer.

typescript
const invoices = await stackbe.customers.getInvoices('cust_abc123');

invoices.forEach(invoice => {
  console.log(`${invoice.created}: $${invoice.amountPaid / 100} - ${invoice.status}`);
});

Customer Object

typescript
interface Customer {
  id: string;
  email: string;
  name?: string;
  metadata?: Record<string, any>;
  stripeCustomerId?: string;    // Linked Stripe customer
  createdAt: string;
  updatedAt: string;
}

Best Practices

  • Use email as the identifier — When looking up customers from your app, use getByEmail() since you typically have the user's email from your auth system.
  • Store your user ID in metadata — Map StackBE customers to your users by storing your internal user ID in the metadata field.
  • Let magic link create customers — Enable autoCreateCustomer in your app settings so customers are automatically created on first login.

Next Steps