Credits

The Credits section of the admin panel allows you to view credit balances, adjust credits manually, and track credit transactions for users and organizations.

Features

View Credit Balances

The credits table displays credit information:

• Entity - User or organization name
• Current Balance - Current credit balance
• Total Added - Total credits added (lifetime)
• Total Used - Total credits used (lifetime)
• Last Transaction - Date of last credit transaction

Adjust Credits

Manually add or subtract credits for users or organizations:

const adjustCreditsSchema = z.object({
  type: z.enum(['add', 'subtract']),
  amount: z.number().positive('Amount must be positive'),
  description: z.string().min(1, 'Description is required').max(500)
});

const adjustMutation = trpc.admin.credit.adjustCredits.useMutation({
  onSuccess: (data) => {
    toast.success(
      `Credits adjusted. New balance: ${data.newBalance.toLocaleString()}`
    );
  }
});

Adjustment Options:

• Add Credits - Increase the credit balance
• Subtract Credits - Decrease the credit balance
• Description - Provide a reason for the adjustment (required for audit trail)

Credit History

View credit transaction history:

• Transaction Type - Add, subtract, or usage
• Amount - Credit amount (positive or negative)
• Description - Reason for the transaction
• Date - When the transaction occurred
• Balance After - Credit balance after the transaction

Using the Admin Credits API

List Credit Balances

import { trpc } from '@/trpc/client';

export function CreditsTable() {
  const { data, isPending } = trpc.admin.credit.list.useQuery({
    limit: 25,
    offset: 0,
    query: '', // Optional search query
    sortBy: 'balance', // 'organizationName' | 'balance' | 'lifetimePurchased' | 'lifetimeGranted' | 'lifetimeUsed' | 'createdAt'
    sortOrder: 'desc', // 'asc' | 'desc'
    filters: {
      balanceRange: ['low'], // Optional: 'zero' | 'low' | 'medium' | 'high'
      createdAt: ['today'] // Optional: 'today' | 'this-week' | 'this-month' | 'older'
    }
  });

  return (
    <div>
      {data?.creditBalances.map((credit) => (
        <div key={credit.organizationId}>
          {credit.organizationName} - {credit.balance} credits
        </div>
      ))}
    </div>
  );
}

Get Credit Details

const { data } = trpc.admin.credit.get.useQuery({
  organizationId: org.id
});

// Returns:
// - organizationId
// - organizationName
// - balance (current balance)
// - lifetimePurchased
// - lifetimeGranted
// - lifetimeUsed

List Credit Transactions

const { data } = trpc.admin.credit.listTransactions.useQuery({
  organizationId: org.id,
  limit: 50,
  offset: 0
});

// Returns transaction history with:
// - type (purchase, usage, adjustment, etc.)
// - amount
// - balanceAfter
// - description
// - createdAt

Adjust Credits

const adjustMutation = trpc.admin.credit.adjustCredits.useMutation({
  onSuccess: (data) => {
    toast.success(`Credits adjusted. New balance: ${data.newBalance}`);
    utils.admin.credit.list.invalidate();
  }
});

const handleAdjust = (
  organizationId: string,
  amount: number,
  description: string
) => {
  // amount can be positive (add) or negative (subtract)
  adjustMutation.mutate({
    organizationId,
    amount, // Positive to add, negative to subtract
    description
  });
};

Credit Management

When to Adjust Credits

Common scenarios for manual credit adjustments:

• Compensation - Refund credits for service issues
• Promotions - Add bonus credits for promotions
• Corrections - Fix incorrect credit calculations
• Support - Provide credits for customer support cases

Credit Audit Trail

All credit adjustments are logged with:

• Admin User - Who made the adjustment
• Timestamp - When the adjustment occurred
• Description - Reason for the adjustment
• Amount - Credit amount added or subtracted
• Balance Before/After - Credit balance changes

Best Practices

Credit Adjustments

• Always provide a clear description - Document the reason for adjustments - Review adjustments regularly - Set limits on adjustment amounts

Credit Monitoring

• Monitor credit usage patterns - Identify unusual credit activity - Track credit balances over time - Review credit transaction history

Credit Policies

• Establish clear credit policies - Document adjustment procedures - Set approval workflows for large adjustments - Maintain audit trails

Related Documentation

• Credits - Learn about the credits system
• Billing Overview - Understand billing features