> ## Documentation Index
> Fetch the complete documentation index at: https://flowglad.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Customers

> Manage customer accounts, including creation, metadata, and archiving.

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:

| Identifier   | Description              | Example                                |
| ------------ | ------------------------ | -------------------------------------- |
| `id`         | Flowglad-generated UUID  | `a1b2c3d4-e5f6-7890-abcd-ef1234567890` |
| `externalId` | Your system's identifier | `user_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.

### Automatic Creation (Recommended)

When you use `FlowgladServer` with a scoped `customerExternalId`, customers are automatically created when needed. The `getCustomerDetails` callback provides the customer's name and email:

```typescript theme={null}
// 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:

```typescript theme={null}
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](https://app.flowglad.com/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`:

```typescript theme={null}
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

<Warning>
  Archiving is a significant action that cancels all active subscriptions. Review the subscription count before confirming.
</Warning>

### How to Archive

#### Via Dashboard

1. Navigate to the [Customers](https://app.flowglad.com/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

```bash theme={null}
curl -X POST https://app.flowglad.com/api/v1/customers/user_123/archive \
  -H "Authorization: Bearer $FLOWGLAD_API_KEY"
```

#### Via SDK

```typescript theme={null}
await flowglad(userId).archiveCustomer('user_123')
```

<Note>
  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.
</Note>

<Note>
  The archive operation is idempotent. Calling it multiple times on the same customer has no additional effect.
</Note>

### 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](https://app.flowglad.com/customers) page
2. Click the "Archived" tab
3. Browse or search archived customer records

<Info>
  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.
</Info>

### 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.

```typescript theme={null}
// 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.

## Related

* [Subscriptions](/features/subscriptions) - Customers are linked to subscriptions
* [Checkout Sessions](/features/checkout-sessions) - Create customers during checkout
* [Invoices](/features/invoices) - Customer billing history