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)

Table of Contents

declare const id: string;

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

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');
};

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

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");
}

Usage Notes

Payment Flow

When using createCheckoutUrl(), the typical flow is:

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
4. Webhook processing: Stack Auth receives webhook notifications from Stripe
5. Item allocation: Purchased items are automatically added to the customer's account
6. 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