Subscriptions

The Subscriptions section of the admin panel allows you to view, monitor, and manage all subscriptions in your application, including active subscriptions, canceled subscriptions, and subscription metadata.

Features

View All Subscriptions

The subscriptions table displays all subscriptions with key information:

• User/Organization - The subscriber (user or organization)
• Plan - The subscription plan name
• Status - Current subscription status (active, canceled, past_due, etc.)
• Price - Subscription price and billing interval
• Current Period - Current billing period dates
• Created Date - When the subscription was created
• Stripe Subscription ID - External subscription identifier

Filter Subscriptions

Filter subscriptions by various criteria:

• Search Query - Search by user email, organization name, or subscription ID
• Status - Filter by subscription status (active, canceled, past_due, etc.)
• Plan - Filter by subscription plan
• Billing Interval - Filter by billing frequency (month, year)
• Creation Date - Filter by when the subscription was created

Bulk Actions

Perform actions on multiple subscriptions:

• Cancel Subscriptions - Cancel multiple subscriptions at once
• Bulk Updates - Update subscription settings in bulk

Using the Admin Subscriptions API

List Subscriptions

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

export function SubscriptionsTable() {
  const { data, isPending } = trpc.admin.subscription.list.useQuery({
    limit: 25,
    offset: 0,
    query: '', // Optional search query
    sortBy: 'createdAt', // 'organizationName' | 'status' | 'interval' | 'currentPeriodEnd' | 'createdAt'
    sortOrder: 'desc', // 'asc' | 'desc'
    filters: {
      status: ['active'], // Optional: 'active' | 'trialing' | 'canceled' | 'past_due' | 'paused' | 'incomplete' | 'incomplete_expired' | 'unpaid'
      interval: ['month'], // Optional: 'month' | 'year'
      createdAt: ['today'] // Optional: 'today' | 'this-week' | 'this-month' | 'older'
    }
  });

  return (
    <div>
      {data?.subscriptions.map((subscription) => (
        <div key={subscription.id}>
          {subscription.organizationName} - {subscription.status}
        </div>
      ))}
    </div>
  );
}

Cancel Subscription

const cancelMutation = trpc.admin.subscription.cancel.useMutation({
  onSuccess: () => {
    toast.success('Subscription canceled successfully');
    utils.admin.subscription.list.invalidate();
  }
});

const handleCancel = (subscriptionId: string, cancelAtPeriodEnd: boolean) => {
  cancelMutation.mutate({
    subscriptionId,
    cancelAtPeriodEnd
  });
};

Sync from Stripe

const syncMutation = trpc.admin.subscription.syncFromStripe.useMutation({
  onSuccess: () => {
    toast.success('Subscriptions synced from Stripe');
    utils.admin.subscription.list.invalidate();
  }
});

const handleSync = (subscriptionIds: string[]) => {
  syncMutation.mutate({ subscriptionIds });
};

Subscription Management

Monitoring Subscriptions

Use the admin panel to:

• Track Revenue - Monitor subscription revenue and trends
• Identify Churn - Find canceled or at-risk subscriptions
• Monitor Status Changes - Track subscription status transitions
• Audit Billing - Review subscription billing history

Subscription Statuses

Common subscription statuses:

• active - Subscription is active and billing normally
• canceled - Subscription has been canceled
• past_due - Payment failed, subscription is past due
• unpaid - Payment failed, subscription is unpaid
• trialing - Subscription is in trial period
• paused - Subscription is temporarily paused

Best Practices

Subscription Monitoring

• Regularly review active subscriptions - Monitor churn rates and trends - Track revenue metrics - Identify payment issues early

Subscription Cancellations

• Understand why subscriptions are canceled - Reach out to at-risk customers
• Offer retention incentives when appropriate - Document cancellation reasons

Billing Issues

• Monitor past_due subscriptions - Set up alerts for payment failures - Have a process for handling billing disputes - Maintain clear communication with customers

Related Documentation

• Billing Overview - Learn about billing
• Subscriptions - Understand subscription management
• Webhooks - Learn about billing webhooks