> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hexclave.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Customer
> Reference for the Customer interface providing payment and item management capabilities.
The `Customer` interface provides payment and item management functionality that is shared between users and teams. Both [`CurrentUser`](https://docs.hexclave.com/sdk/types/user#currentuser) and [`Team`](https://docs.hexclave.com/sdk/types/team#team) types extend this interface, allowing them to create checkout URLs and manage items.This interface is automatically available on:- [`CurrentUser`](https://docs.hexclave.com/sdk/types/user#currentuser) objects
- [`Team`](https://docs.hexclave.com/sdk/types/team#team) objects
- [`ServerUser`](https://docs.hexclave.com/sdk/types/user#serveruser) objects (with additional server-side capabilities)
- [`ServerTeam`](https://docs.hexclave.com/sdk/types/team#serverteam) objects (with additional server-side capabilities)## Table of ContentsCustomer Table of Contents## Properties
\
\`customer.id`
customer
Unique identifier - the user ID for individual accounts or team ID for organizations.
Type Definition
\`typescript declare const id: string; `
\
## Methods
\
\`customer.createCheckoutUrl(options)`
customer
Creates a secure checkout URL for purchasing a product. This method integrates with Stripe to generate a payment link that handles the entire purchase flow.
Parameters
\**options.productId** `string` *required*
The ID of the product to purchase, as configured in your Hexclave project settings.
\**options.returnUrl** `string`
The URL to redirect the user to after they complete (or cancel) the checkout. If not provided, the user is redirected to the current page.
Returns
\`Promise`
A secure URL that redirects to the Stripe checkout page.
Signature
\```typescript theme={null}
declare function createCheckoutUrl(options: {
productId: string;
returnUrl?: string;
}): Promise;
\```
Examples
\```typescript theme={null}
const user = useUser({ or: "redirect" });
const handleUpgrade = async () => {
const checkoutUrl = await user.createCheckoutUrl({
productId: "prod_premium_monthly",
returnUrl: "https://myapp.com/billing",
});
window.location.href = checkoutUrl;
};
\```
\```typescript theme={null}
const team = await user.getTeam("team_123");
const purchaseSeats = async () => {
const checkoutUrl = await team.createCheckoutUrl({
productId: "prod_additional_seats",
});
window.open(checkoutUrl, "_blank");
};
\```
\
\
\`customer.createPaymentMethodSetupIntent`
customer
Creates a Stripe SetupIntent for adding a new payment method. The returned `clientSecret` and `stripeAccountId` can be used with Stripe.js to collect payment details.
Returns
\`Promise`
Signature
\```typescript theme={null}
declare function createPaymentMethodSetupIntent(): Promise<{
clientSecret: string;
stripeAccountId: string;
}>;
\```
Examples
\```typescript theme={null}
const setupIntent = await user.createPaymentMethodSetupIntent();
// Use setupIntent.clientSecret with Stripe.js
\```
\
\
\`customer.setDefaultPaymentMethodFromSetupIntent(setupIntentId)`
customer
Sets the default payment method from a completed SetupIntent. Call this after the user has successfully added a payment method through Stripe.js.
Parameters
\**setupIntentId** `string` *required*
The ID of the completed SetupIntent.
Returns
\`Promise`
Signature
\```typescript theme={null}
declare function setDefaultPaymentMethodFromSetupIntent(
setupIntentId: string
): Promise;
\```
Examples
\```typescript theme={null}
const paymentMethod = await user.setDefaultPaymentMethodFromSetupIntent(
"seti_1abc123"
);
console.log(`Set default card ending in ${paymentMethod?.last4}`);
\```
\
\
\`customer.switchSubscription(options)`
customer
Switches an existing subscription from one product to another. Useful for upgrading or downgrading plans.
Parameters
\**options.fromProductId** `string` *required*
The product ID of the current subscription to switch from.
\**options.toProductId** `string` *required*
The product ID to switch to.
\**options.priceId** `string`
The specific price ID to use for the new product.
\**options.quantity** `number`
The quantity for the new subscription.
Returns
\`Promise`
Signature
\```typescript theme={null}
declare function switchSubscription(options: {
fromProductId: string;
toProductId: string;
priceId?: string;
quantity?: number;
}): Promise;
\```
Examples
\```typescript theme={null}
await user.switchSubscription({
fromProductId: "prod_basic_monthly",
toProductId: "prod_premium_monthly",
});
\```
\
\
\`customer.getBilling`
customer
Retrieves the customer's billing information, including whether they have a Stripe customer record and their default payment method.
Returns
\`Promise`
Signature
\```typescript theme={null}
declare function getBilling(): Promise;
\```
Examples
\```typescript theme={null}
const billing = await user.getBilling();
if (billing.defaultPaymentMethod) {
console.log(`Card ending in ${billing.defaultPaymentMethod.last4}`);
}
\```
\
\
\`customer.useBilling`
customer
React hook version of `getBilling`. Returns the customer's billing information reactively.
Returns
\`CustomerBilling`
Signature
\```typescript theme={null}
declare function useBilling(): CustomerBilling;
\```
Examples
\```tsx theme={null}
function BillingInfo() {
const user = useUser({ or: "redirect" });
const billing = user.useBilling();
return (
\
\{billing.defaultPaymentMethod
? `Card ending in ${billing.defaultPaymentMethod.last4}`
: "No payment method on file"}
\
);
}
\```
\
\
\`customer.getItem(itemId)`
customer
Retrieves information about a specific item associated with this customer.
Parameters
\**itemId** `string` *required*
The ID of the item to retrieve.
Returns
\`Promise`
An [`Item`](https://docs.hexclave.com/sdk/types/item#item) object containing the display name, current quantity, and other details.
Signature
\```typescript theme={null}
declare function getItem(itemId: string): Promise;
\```
Examples
\```typescript theme={null}
const credits = await user.getItem("credits");
console.log(`Available credits: ${credits.nonNegativeQuantity}`);
console.log(`Actual balance: ${credits.quantity}`);
\```
\
\
\`customer.useItem(itemId)`
customer
React hook version of `getItem`. Provides real-time updates when the item quantity changes.
Parameters
\**itemId** `string` *required*
The ID of the item to retrieve.
Returns
\`Item`
Signature
\```typescript theme={null}
declare function useItem(itemId: string): Item;
\```
Examples
\```tsx theme={null}
function CreditsWidget() {
const user = useUser({ or: "redirect" });
const credits = user.useItem("credits");
return (
\
\
Available Credits
\
\{credits.nonNegativeQuantity}
\
\{credits.displayName}
\
);
}
\```
\
\
\`customer.listProducts([options])`
customer
Lists the products owned by this customer, including subscription status and quantities.
Parameters
\**options.cursor** `string`
Pagination cursor from a previous response's `nextCursor`.
\**options.limit** `number`
Maximum number of products to return.
Returns
\`Promise`
Signature
\```typescript theme={null}
declare function listProducts(options?: {
cursor?: string;
limit?: number;
}): Promise;
\```
Examples
\```typescript theme={null}
const products = await user.listProducts();
for (const product of products) {
console.log(`${product.displayName}: ${product.quantity}`);
}
\```
\
\
\`customer.useProducts([options])`
customer
React hook version of `listProducts`. Returns the customer's products reactively.
Parameters
\**options.cursor** `string`
Pagination cursor from a previous response's `nextCursor`.
\**options.limit** `number`
Maximum number of products to return.
Returns
\`CustomerProductsList`
Signature
\```typescript theme={null}
declare function useProducts(options?: {
cursor?: string;
limit?: number;
}): CustomerProductsList;
\```
\
\
\`customer.listInvoices([options])`
customer
Lists the invoices for this customer.
Parameters
\**options.cursor** `string`
Pagination cursor from a previous response's `nextCursor`.
\**options.limit** `number`
Maximum number of invoices to return.
Returns
\`Promise`
Signature
\```typescript theme={null}
declare function listInvoices(options?: {
cursor?: string;
limit?: number;
}): Promise;
\```
Examples
\```typescript theme={null}
const invoices = await user.listInvoices();
for (const invoice of invoices) {
console.log(`${invoice.status}: $${invoice.amountTotal / 100}`);
}
\```
\
\
\`customer.useInvoices([options])`
customer
React hook version of `listInvoices`. Returns the customer's invoices reactively.
Parameters
\**options.cursor** `string`
Pagination cursor from a previous response's `nextCursor`.
\**options.limit** `number`
Maximum number of invoices to return.
Returns
\`CustomerInvoicesList`
Signature
\```typescript theme={null}
declare function useInvoices(options?: {
cursor?: string;
limit?: number;
}): CustomerInvoicesList;
\```
\
***# Related TypesThese types are returned by the methods above. You'll encounter them when working with billing, products, and invoices.## `CustomerBilling`Returned by [`getBilling()`](#customergetbilling) / [`useBilling()`](#customerusebilling).
\
\`customer.hasCustomer`
customer
Whether the customer has a Stripe customer record.
Type Definition
\`typescript declare const hasCustomer: boolean; `
\
\
\`customer.defaultPaymentMethod`
customer
The customer's default payment method, or `null` if none is set.
When present, contains `id`, `brand`, `last4`, `exp_month`, and `exp_year`.
Type Definition
\```typescript theme={null}
declare const defaultPaymentMethod: {
id: string;
brand: string | null;
last4: string | null;
exp_month: number | null;
exp_year: number | null;
} | null;
\```
\
## `CustomerProduct`Returned by [`listProducts()`](#customerlistproducts) / [`useProducts()`](#customeruseproducts). The return value is an array of `CustomerProduct` with a `nextCursor: string | null` property for pagination.
\
\`customer.id`
customer
The product ID, or `null` for inline products.
Type Definition
\`typescript declare const id: string | null; `
\
\
\`customer.displayName`
customer
The human-readable name of the product.
Type Definition
\`typescript declare const displayName: string; `
\
\
\`customer.quantity`
customer
How many of this product the customer owns.
Type Definition
\`typescript declare const quantity: number; `
\
\
\`customer.type`
customer
Whether this is a one-time purchase or a recurring subscription.
Type Definition
\`typescript declare const type: "one_time" | "subscription"; `
\
\
\`customer.subscription`
customer
Subscription details, or `null` for one-time purchases. Includes the subscription ID, current period end date, and cancellation status.
Type Definition
\```typescript theme={null}
declare const subscription: null | {
subscriptionId: string | null;
currentPeriodEnd: Date | null;
cancelAtPeriodEnd: boolean;
isCancelable: boolean;
};
\```
\
\
\`customer.customerType`
customer
The type of customer that owns this product.
Type Definition
\`typescript declare const customerType: "user" | "team" | "custom"; `
\
\
\`customer.isServerOnly`
customer
Whether this product can only be granted server-side.
Type Definition
\`typescript declare const isServerOnly: boolean; `
\
\
\`customer.stackable`
customer
Whether multiple quantities of this product can be stacked.
Type Definition
\`typescript declare const stackable: boolean; `
\
\
\`customer.switchOptions`
customer
Available products to switch this subscription to. Only present for subscription products.
Type Definition
\```typescript theme={null}
declare const switchOptions: Array<{
productId: string;
displayName: string;
prices: InlineProduct["prices"];
}> | undefined;
\```
\
## `CustomerInvoice`Returned by [`listInvoices()`](#customerlistinvoices) / [`useInvoices()`](#customeruseinvoices). The return value is an array of `CustomerInvoice` with a `nextCursor: string | null` property for pagination.
\
\`customer.createdAt`
customer
When the invoice was created.
Type Definition
\`typescript declare const createdAt: Date; `
\
\
\`customer.status`
customer
The invoice status.
Type Definition
\`typescript declare const status: "draft" | "open" | "paid" | "uncollectible" | "void" | null; `
\
\
\`customer.amountTotal`
customer
The total amount of the invoice in the smallest currency unit (e.g. cents).
Type Definition
\`typescript declare const amountTotal: number; `
\
\
\`customer.hostedInvoiceUrl`
customer
A URL to the hosted invoice page on Stripe, or `null` if not available.
Type Definition
\`typescript declare const hostedInvoiceUrl: string | null; `
\
***## Payment Workflow**1. Create checkout URL**Call `createCheckoutUrl()` with the desired product ID.**2. Redirect to Stripe**Direct the user to the returned URL.**3. User completes payment**Stripe handles the payment process on their hosted page.**4. Webhook processing**Hexclave receives webhook notifications from Stripe.**5. Item allocation**Purchased items are automatically added to the customer's account.**6. User returns**The user is redirected back to your application.## Usage Notes- **Purchases**: When a user completes a purchase, associated items are automatically added
- **Subscriptions**: Recurring subscriptions automatically replenish items at the specified intervals
- **Manual allocation**: Server-side code can manually adjust item quantities using [`ServerItem`](https://docs.hexclave.com/sdk/types/item#serveritem) methods
- **Race conditions**: Use [`tryDecreaseQuantity()`](https://docs.hexclave.com/sdk/types/item#serveritemtrydecreasequantity) for atomic, race-condition-free item consumption