Skip to main content
Customers represent the people or organizations that purchase your products and subscriptions. Flowglad automatically creates customer records when users complete checkout, but you can also create and manage customers programmatically.

​
What is a Customer?

A Customer in Flowglad tracks the identity and billing relationship with someone who uses your product. Each customer has:
  • Identifiers: A Flowglad-generated id and your own externalId for linking to your system
  • Contact info: Name and email address
  • Billing data: Associated subscriptions, invoices, and payment methods
  • State: Active or archived status

​
Customer Identifiers

Customers have two key identifiers:
IdentifierDescriptionExample
idFlowglad-generated UUIDa1b2c3d4-e5f6-7890-abcd-ef1234567890
externalIdYour system’s identifieruser_123, org_456
The externalId is how you’ll typically reference customers in your code. It must be unique among active customers, but can be reused after archiving a customer.

​
Creating Customers

Customers are typically created automatically—you don’t need to explicitly create them in most cases. When you use FlowgladServer with a scoped customerExternalId, customers are automatically created when needed. The getCustomerDetails callback provides the customer’s name and email: 
// Set up the server with your user's ID
const server = new FlowgladServer({
  customerExternalId: user.id, // Your app's user ID
  getCustomerDetails: async (id) => {
    const user = await db.users.findOne({ id })
    return { name: user.name, email: user.email }
  },
})

// Customer is automatically created if they don't exist
const billing = await server.getBilling()
This also works when creating checkout sessions—if the customer doesn’t exist, they’re created automatically: 
const checkoutSession = await flowglad(userId).createCheckoutSession({
  priceSlug: 'pro_plan',
  successUrl: 'https://example.com/success',
  cancelUrl: 'https://example.com/cancel',
})

​
Via Dashboard

For manual customer creation:
  1. Navigate to the Customers page
  2. Click “Create Customer”
  3. Fill in the customer details
  4. Click “Create”

​
Updating Customers

Update customer details like name and email using updateCustomer. This method updates the customer associated with the scoped customerExternalId: 
await flowglad(userId).updateCustomer({
  customer: {
    name: 'Jane Smith',
    email: 'jane.smith@example.com',
  },
})
Updated customer data is returned when you call getBilling() or other customer methods.

​
Archiving Customers

Archiving removes a customer from active use while preserving their historical data. This is the recommended way to handle customer churn, duplicates, or test data cleanup.

​
Why Archive?

  • Customer churned: When a customer cancels and you want to clean up
  • Duplicate cleanup: Consolidate multiple customer records
  • Test data: Remove test customers from your active data
  • Free up externalId: Reuse the externalId for a new customer

​
What Happens When You Archive

When you archive a customer:
  1. Active subscriptions are canceled - Subscriptions with active status are immediately canceled
  2. The customer is marked as archived - The archived field is set to true
  3. The externalId becomes available - You can create a new customer with the same externalId
  4. API returns 404 - The GET /customers/:externalId endpoint returns 404 for archived customers
Archiving is a significant action that cancels all active subscriptions. Review the subscription count before confirming.

​
How to Archive

​
Via Dashboard

  1. Navigate to the Customers page
  2. Find the customer you want to archive
  3. Click the actions menu (⋮) on the customer row
  4. Select “Archive Customer”
  5. Review the confirmation modal (shows subscription cancellation warning)
  6. Click “Archive” to confirm

​
Via API

curl -X POST https://app.flowglad.com/api/v1/customers/user_123/archive \
  -H "Authorization: Bearer $FLOWGLAD_API_KEY"

​
Via SDK

await flowglad(userId).archiveCustomer('user_123')
Unlike updateCustomer which operates on the scoped customer, archiveCustomer requires an explicit externalId parameter. This archives the customer with externalId of 'user_123', not necessarily the scoped customer.
The archive operation is idempotent. Calling it multiple times on the same customer has no additional effect.

​
Viewing Archived Customers

Archived customers are intentionally not accessible via the API. This provides clean data isolation and matches the behavior of other billing platforms like Stripe. To view archived customers:
  1. Navigate to the Customers page
  2. Click the “Archived” tab
  3. Browse or search archived customer records
The dashboard’s “Archived” tab is the only way to access archived customer data. This is by design to keep your active customer data clean.

​
Restore

Restore functionality is not currently supported. Once a customer is archived, they cannot be unarchived. If you need to work with a previously archived customer, create a new customer record.

​
Best Practices

​
Use externalId Consistently

Always provide an externalId that maps to your user or organization ID. This makes it easy to look up customers and keeps your data synchronized. 
// Good: Use your system's user ID as the customerExternalId
const flowgladServer = new FlowgladServer({
  customerExternalId: user.id, // e.g., 'user_123'
  getCustomerDetails: async (id) => {
    const user = await db.users.findOne({ id })
    return { name: user.name, email: user.email }
  },
})

// The customer is automatically created with externalId = user.id
const billing = await flowgladServer.getBilling()

​
Archive Instead of Ignoring

When customers churn, archive them rather than leaving them in an ambiguous state. This:
  • Cancels subscriptions cleanly
  • Frees up the externalId for reuse
  • Keeps your active customer list accurate

​
Review Before Archiving

Always check the subscription count before archiving a customer, especially for customers with multiple subscriptions. The dashboard modal shows this count, but if archiving via API, query the customer’s subscriptions first.