The Customer interface provides payment and item management functionality that is shared between users and teams. Both CurrentUser and Team types extend this interface, allowing them to create checkout URLs and manage items.

On this page:

Customer

`Customer`

The Customer interface defines the payment-related functionality available to both users and teams. It provides methods for creating checkout URLs for purchases and managing quantifiable items like credits, API calls, or subscription allowances.

This interface is automatically available on:

CurrentUser objects
Team objects
ServerUser objects (with additional server-side capabilities)
ServerTeam objects (with additional server-side capabilities)

The unique identifier for the customer. For users, this is the user ID; for teams, this is the team ID.

Type Definition

declare const id: string;

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.

The checkout URL will redirect users to a Stripe-hosted payment page where they can complete their purchase. After successful payment, users will be redirected back to your application.

Parameters

optionsobjectrequired

Options for creating the checkout URL.

Show Properties

productIdstringrequired

The ID of the product to purchase, as configured in your Stack Auth project settings.

Returns

Promise<string>: A secure URL that redirects to the Stripe checkout page for the specified product.

Signature

declare function createCheckoutUrl(options: {
  productId: string;
}): Promise<string>;

Examples

const user = useUser({ or: "redirect" });

const handleUpgrade = async () => {
  try {
    const checkoutUrl = await user.createCheckoutUrl({
      productId: "prod_premium_monthly",
    });
    
    // Redirect to Stripe checkout
    window.location.href = checkoutUrl;
  } catch (error) {
    console.error("Failed to create checkout URL:", error);
  }
};

const team = await user.getTeam("team_123");

const purchaseSeats = async () => {
  const checkoutUrl = await team.createCheckoutUrl({
    productId: "prod_additional_seats",
  });
  
  // Open checkout in new tab
  window.open(checkoutUrl, '_blank');
};

Retrieves information about a specific item associated with this customer. Items represent quantifiable resources such as credits, API calls, storage quotas, or subscription allowances.

Parameters

itemIdstringrequired

The ID of the item to retrieve, as configured in your Stack Auth project settings.

Returns

Promise<Item>: An Item object containing the display name, current quantity, and other details.

Signature

declare function getItem(itemId: string): Promise<Item>;

Examples

const user = useUser({ or: "redirect" });

const checkCredits = async () => {
  const credits = await user.getItem("credits");
  console.log(`Available credits: ${credits.nonNegativeQuantity}`);
  console.log(`Actual balance: ${credits.quantity}`);
};

const team = await user.getTeam("team_123");
const apiQuota = await team.getItem("api_calls");

if (apiQuota.nonNegativeQuantity < 100) {
  console.warn("Team is running low on API calls");
}

Retrieves information about a specific item associated with this customer, used as a React hook. This provides real-time updates when the item quantity changes.

Parameters

itemIdstringrequired

The ID of the item to retrieve.

Returns

Item: An Item object containing the display name, current quantity, and other details.

Signature

declare function useItem(itemId: string): Item;

Examples

function CreditsWidget() {
  const user = useUser({ or: "redirect" });
  const credits = user.useItem("credits");
  
  return (
    <div className="credits-widget">
      <h3>Available Credits</h3>
      <div className="credits-count">
        {credits.nonNegativeQuantity}
      </div>
      <small>{credits.displayName}</small>
    </div>
  );
}

function TeamQuotaStatus({ teamId }: { teamId: string }) {
  const user = useUser({ or: "redirect" });
  const team = user.useTeam(teamId);
  const apiCalls = team.useItem("api_calls");
  
  const usagePercentage = (apiCalls.quantity / 10000) * 100;
  
  return (
    <div className="quota-status">
      <div className="progress-bar">
        <div 
          className="progress-fill" 
          style={{ width: `${Math.min(usagePercentage, 100)}%` }}
        />
      </div>
      <p>
        {apiCalls.quantity.toLocaleString()} / 10,000 API calls used
      </p>
    </div>
  );
}

Usage Notes

Payment Flow

When using createCheckoutUrl(), the typical flow is:

Create checkout URL: Call createCheckoutUrl() with the desired product ID
Redirect to Stripe: Direct the user to the returned URL
User completes payment: Stripe handles the payment process
Webhook processing: Stack Auth receives webhook notifications from Stripe
Item allocation: Purchased items are automatically added to the customer's account
User returns: User is redirected back to your application

Item Management

Items are automatically managed through the payment system:

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 methods

Security Considerations

Client-side safety: All payment operations are designed to be safe for client-side use
Server validation: Critical operations should always be validated on the server side
Race conditions: Use tryDecreaseQuantity() for atomic, race-condition-free item consumption

On this page:

Customer

`Customer`

This interface is automatically available on:

CurrentUser objects
Team objects
ServerUser objects (with additional server-side capabilities)
ServerTeam objects (with additional server-side capabilities)

The unique identifier for the customer. For users, this is the user ID; for teams, this is the team ID.

Type Definition

declare const id: string;

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.

The checkout URL will redirect users to a Stripe-hosted payment page where they can complete their purchase. After successful payment, users will be redirected back to your application.

Parameters

optionsobjectrequired

Options for creating the checkout URL.

Show Properties

productIdstringrequired

The ID of the product to purchase, as configured in your Stack Auth project settings.

Returns

Promise<string>: A secure URL that redirects to the Stripe checkout page for the specified product.

Signature

declare function createCheckoutUrl(options: {
  productId: string;
}): Promise<string>;

Examples

const user = useUser({ or: "redirect" });

const handleUpgrade = async () => {
  try {
    const checkoutUrl = await user.createCheckoutUrl({
      productId: "prod_premium_monthly",
    });
    
    // Redirect to Stripe checkout
    window.location.href = checkoutUrl;
  } catch (error) {
    console.error("Failed to create checkout URL:", error);
  }
};

const team = await user.getTeam("team_123");

const purchaseSeats = async () => {
  const checkoutUrl = await team.createCheckoutUrl({
    productId: "prod_additional_seats",
  });
  
  // Open checkout in new tab
  window.open(checkoutUrl, '_blank');
};

Retrieves information about a specific item associated with this customer. Items represent quantifiable resources such as credits, API calls, storage quotas, or subscription allowances.

Parameters

itemIdstringrequired

The ID of the item to retrieve, as configured in your Stack Auth project settings.

Returns

Promise<Item>: An Item object containing the display name, current quantity, and other details.

Signature

declare function getItem(itemId: string): Promise<Item>;

Examples

const user = useUser({ or: "redirect" });

const checkCredits = async () => {
  const credits = await user.getItem("credits");
  console.log(`Available credits: ${credits.nonNegativeQuantity}`);
  console.log(`Actual balance: ${credits.quantity}`);
};

const team = await user.getTeam("team_123");
const apiQuota = await team.getItem("api_calls");

if (apiQuota.nonNegativeQuantity < 100) {
  console.warn("Team is running low on API calls");
}

Retrieves information about a specific item associated with this customer, used as a React hook. This provides real-time updates when the item quantity changes.

Parameters

itemIdstringrequired

The ID of the item to retrieve.

Returns

Item: An Item object containing the display name, current quantity, and other details.

Signature

declare function useItem(itemId: string): Item;

Examples

function CreditsWidget() {
  const user = useUser({ or: "redirect" });
  const credits = user.useItem("credits");
  
  return (
    <div className="credits-widget">
      <h3>Available Credits</h3>
      <div className="credits-count">
        {credits.nonNegativeQuantity}
      </div>
      <small>{credits.displayName}</small>
    </div>
  );
}

function TeamQuotaStatus({ teamId }: { teamId: string }) {
  const user = useUser({ or: "redirect" });
  const team = user.useTeam(teamId);
  const apiCalls = team.useItem("api_calls");
  
  const usagePercentage = (apiCalls.quantity / 10000) * 100;
  
  return (
    <div className="quota-status">
      <div className="progress-bar">
        <div 
          className="progress-fill" 
          style={{ width: `${Math.min(usagePercentage, 100)}%` }}
        />
      </div>
      <p>
        {apiCalls.quantity.toLocaleString()} / 10,000 API calls used
      </p>
    </div>
  );
}

Usage Notes

Payment Flow

When using createCheckoutUrl(), the typical flow is:

Create checkout URL: Call createCheckoutUrl() with the desired product ID
Redirect to Stripe: Direct the user to the returned URL
User completes payment: Stripe handles the payment process
Webhook processing: Stack Auth receives webhook notifications from Stripe
Item allocation: Purchased items are automatically added to the customer's account
User returns: User is redirected back to your application

Item Management

Items are automatically managed through the payment system:

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 methods

Security Considerations

Client-side safety: All payment operations are designed to be safe for client-side use
Server validation: Critical operations should always be validated on the server side
Race conditions: Use tryDecreaseQuantity() for atomic, race-condition-free item consumption

Customer

`Customer`

Table of Contents

Parameters

Returns

Parameters

Returns

Parameters

Returns

Usage Notes

Payment Flow

Item Management

Security Considerations

Stack Auth AI

How can I help?

Customer

`Customer`

Table of Contents

Parameters

Returns

Parameters

Returns

Parameters

Returns

Usage Notes

Payment Flow

Item Management

Security Considerations

Stack Auth AI

How can I help?