Billing & Credits
The billing feature handles Stripe checkout, credit balance management, pre-operation credit validation, and billing error detection.
Checkout
Hook: useCheckout (lib/hooks/useCheckout.ts)
Orchestrates the Stripe subscription checkout flow:
- User selects a plan (and optional promo code)
- Hook determines whether to use company or personal checkout
- Redirects to Stripe Checkout session
- On return, subscription is activated
Method: startCheckout(planId, promoCodeId?)
Requires an authenticated user.
Credit Check
Hook: useCreditCheck (lib/hooks/useCreditCheck.ts)
Pre-operation credit balance validation. Called before AI operations to ensure sufficient credits:
| Option | Type | Purpose |
|---|---|---|
estimatedCost | number | Expected credit cost of the operation |
customMessage | string | Custom warning message |
Returns: CreditCheckResult with balance, warningThreshold, and showWarning flags.
Billing Error Detection
Hook: useBillingError (lib/hooks/useBillingError.ts)
Intercepts GraphQL errors and maps them to user-friendly billing messages:
| Error Code | HTTP Status | Meaning |
|---|---|---|
INSUFFICIENT_CREDITS | 402 | Not enough credits for the operation |
PLAN_LIMIT_EXCEEDED | 403 | Feature limit reached on current plan |
SUBSCRIPTION_INACTIVE | -- | No active subscription |
INVALID_PLAN_PRICING | -- | Plan pricing configuration error |
Methods: detectBillingError(), showBillingToastIfNeeded()
The BillingErrorToastHandler component (in the provider hierarchy) automatically intercepts these errors and shows toast notifications.
Credit Balance
Hook: useCreditBalance (lib/hooks/useCreditBalance.ts)
Fetches the current credit balance, automatically routing to the correct balance (company or personal) based on the authenticated context.
Other Billing Hooks
| Hook | File | Purpose |
|---|---|---|
useBillingConfig | useBillingConfig.ts | Fetch billing configuration and pricing |
useCreditPurchase | useCreditPurchase.ts | Credit pack purchase flow |
useSubscriptionStatus | useSubscriptionStatus.ts | Check subscription status and feature eligibility |
Components
| Component | File | Purpose |
|---|---|---|
| PromoCodeInput | components/reusable/payments/PromoCodeInput.tsx | Promo code entry with validation |
| BillingErrorToastHandler | In provider hierarchy | Auto-intercepts billing errors |
Pages
| Route | Purpose |
|---|---|
app/company/credits/ | Company credit management and billing |
app/jobseeker/credits/ | Personal credit management |
app/jobseeker/pricing/ | Subscription plan selection |