Skip to main content

​
createCustomer

const customer = await billing.createCustomer({
  externalUserId: "user_123",
  email: "jane@example.com",
  name: "Jane Smith",
  metadata: { company: "Acme Inc" },
});

​
Parameters

NameTypeRequiredDescription
externalUserIdstringYesYour user’s unique ID
externalOrganizationIdstringNoOrganization ID for B2B
emailstringNoCustomer email
namestringNoCustomer name
metadataRecord<string, any>NoCustom key-value pairs

​
getCustomer

const customer = await billing.getCustomer("cus_123");

​
getCustomerByExternalId

Look up a customer by their ID in your system. 
const customer = await billing.getCustomerByExternalId("user_123");

​
updateCustomer

const updated = await billing.updateCustomer("cus_123", {
  name: "Jane Doe",
  metadata: { company: "Acme Inc" },
});

​
deleteCustomer

await billing.deleteCustomer("cus_123");

​
listUnresolvedCustomers

List customers imported from Stripe that don’t yet have an external_id bound to your user ID. Pair with bindCustomer() to resolve them. See Migrating from Stripe for context. 
const { customers } = await billing.listUnresolvedCustomers();

for (const c of customers) {
  if (!c.email) continue;
  const user = await db.users.findByEmail(c.email);
  if (user) {
    await billing.bindCustomer(c.id, user.id);
  }
}

​
Response

{
  customers: Array<{
    id: string
    stripe_customer_id: string | null
    email: string | null
    name: string | null
    created_at: string
  }>
}

​
bindCustomer

Bind an imported customer to your internal user ID. The customer must currently have no external_id set; binding is one-way and immutable. 
await billing.bindCustomer(unresolved.id, user.id);

​
Parameters

NameTypeRequiredDescription
customerIdstringYesBillingOS customer ID (from listUnresolvedCustomers)
externalIdstringYesYour user’s ID from your database
External IDs are immutable once set. There’s no unbind operation — double-check before binding.

​
Customer object

interface Customer {
  id: string
  externalUserId: string
  externalOrganizationId?: string
  email?: string
  name?: string
  stripeCustomerId?: string
  metadata?: Record<string, any>
  createdAt: Date
  updatedAt: Date
}