Customers

Manage the billable users of your app. Browse customers in the Dashboard > Commerce > Customers tab or via the SDK.

A customer is the entity in your app that gets charged — usually a user, an organization, or a project. You create one in Proyecta as soon as the corresponding entity exists in your own database, then store the returned id so you can reference it later.

The Customers tab

Open Dashboard > Commerce and switch to Customers to see every billable customer for the current app. Each row shows:

• Email
• Full name
• When they were created

A search box and filtering by email or creation date are available through the SDK; richer controls in the panel are coming.

SDK

import Proyecta from '@proyecta-ai/sdk';
const proyecta = new Proyecta({ apiKey: process.env.PROYECTA_API_KEY });

Create

const customer = await proyecta.commerce.customers.create({
  email: 'alice@example.com',
  name: 'Alice Liddell',
  phone: '+14155551234',  // E.164 format
  address: {
    line1: '123 Wonderland Ave',
    city: 'San Francisco',
    state: 'CA',
    postal_code: '94110',
    country: 'US',
  },
});

You can also pass a custom id (must start with cus_) if you’d rather match your own database IDs.

Read

// Single customer
const customer = await proyecta.commerce.customers.get('cus_123');

// Search and paginate
for await (const customer of proyecta.commerce.customers.list({
  query: 'alice',           // matches name, email, or id
  email: 'alice@example.com', // exact email
  sort: '-created',         // newest first
})) {
  console.log(customer.name, customer.email);
}

Update

await proyecta.commerce.customers.update('cus_123', {
  email: 'new@example.com',
  address: { ... },
});

Billing portal

Stripe provides a hosted billing portal where customers can view invoices, update payment methods, and manage their own subscriptions:

const { url } = await proyecta.commerce.customers.billingPortal('cus_123', {
  return_url: 'https://myapp.com/account',
});
return Response.redirect(url);

This is the recommended way to give customers self-service control — it covers invoices, cards, and cancellation without you having to build any UI.

Common patterns

Create a Proyecta customer when a user signs up

When a new user finishes signup, call proyecta.commerce.customers.create
with their email and name. Store the returned id on the user record as
proyecta_customer_id.

Show a “Manage billing” button on the account page

Add a button on /account that calls proyecta.commerce.customers.billingPortal
with the user's proyecta_customer_id and redirects to the returned URL.

Build an admin customer browser

Build an admin page at /admin/customers that lists every Proyecta customer
with their email, name, created date, and a link to view their detail page.
Use proyecta.commerce.customers.list with sort=-created.

FAQ

Should I create a Proyecta customer for every user, or only paying ones?

Create one for every user. It’s free, idempotent (with a custom id), and means you’re ready the moment a user upgrades — no scrambling to backfill.

Can a customer have multiple subscriptions?

Yes. Subscriptions belong to customers, not the other way around. Use commerce.checkout() to create or update subscriptions.

How do I see what a customer is subscribed to?

Today: through the embedded Stripe dashboard or by calling commerce.check() for each feature you care about. A subscription history view in the panel is on the roadmap.