Subscription Billing

This workflow manages the complete SaaS subscription lifecycle from team creation through active subscription, including trial periods, grace periods, and restricted access.

Overview

Taskr uses a seat-based subscription model with the following key features:

30-day free trial with full feature access
7-day grace period after trial ends (before restrictions)
Seat-based billing synced with Stripe
Feature restrictions when billing is not set up

Subscription States

Trial

30-day free trial with full access to all features

Grace Period

7-day window after trial ends to set up billing

Restricted

Read-only access until billing is configured

Active

Paid subscription with full feature access

Workflow Diagram

Status Timeline

┌─────────────────────────────────────────────────────────────────────────────────┐
│                        SUBSCRIPTION LIFECYCLE TIMELINE                           │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                  │
│  Day 0          Day 30         Day 37                                           │
│    │              │              │                                               │
│    ▼              ▼              ▼                                               │
│  ┌──────────────────────────────────────────────────────────────────────┐       │
│  │ TRIAL (30 days)  │ GRACE PERIOD (7 days) │ RESTRICTED               │       │
│  │                  │                        │                          │       │
│  │ Full access      │ Full access           │ Read-only                │       │
│  │ No billing req   │ Warning banners       │ Upgrade required         │       │
│  │ All features     │ Email reminders       │ Cannot create entities   │       │
│  └──────────────────────────────────────────────────────────────────────┘       │
│                                                                                  │
│                     ┌──────────────────────┐                                    │
│                     │ Billing Setup at     │                                    │
│                     │ any point → ACTIVE   │                                    │
│                     └──────────────────────┘                                    │
│                                                                                  │
└─────────────────────────────────────────────────────────────────────────────────┘

Feature Restrictions by Status

Feature	Trial	Grace Period	Restricted	Active
Create Jobs	✅	✅	❌	✅
Create Quotes	✅	✅	❌	✅
Create Invoices	✅	✅	❌	✅
Add Team Members	✅	✅	❌	✅
Bank/Accounting Sync	✅	✅	❌	✅
View Existing Data	✅	✅	✅	✅
Generate Reports	✅	✅	✅	✅
Export Data	✅	✅	✅	✅

Implementation Details

Trial Status Service

The core logic lives in trial-status-service.ts:

// apps/workbooks-api/src/services/trial-status-service.ts

export const TRIAL_DAYS = 30;
export const GRACE_PERIOD_DAYS = 7;

export interface TrialStatus {
  status: "trial" | "grace_period" | "restricted" | "active" | "canceled" | "no_subscription";
  daysRemaining: number | null;
  trialEndDate: string | null;
  graceEndDate: string | null;
  isRestricted: boolean;
  canCreateJobs: boolean;
  canCreateQuotes: boolean;
  canCreateInvoices: boolean;
  canAddMembers: boolean;
  canSync: boolean;
  billingSetupComplete: boolean;
  upgradeRequired: boolean;
  message: string;
}

Creating a Trial Subscription

When a new team is created, a trial subscription is automatically provisioned:

// Called during onboarding
const result = await createTrialSubscription(db, {
  teamId: newTeam.id,
  planId: "starter",
  trialDays: 30,        // Default: 30 days
  gracePeriodDays: 7,   // Default: 7 days
  userId: currentUser.id,
});

// Returns:
// {
//   subscriptionId: "sub_xxx",
//   trialEndDate: "2025-02-03T00:00:00Z",
//   graceEndDate: "2025-02-10T00:00:00Z"
// }

Automated Status Transitions

Trial Expires

Cron job detects trials past their trialEndDate and transitions them to grace_period.

// Runs daily via Trigger.dev
await transitionToGracePeriod(db, teamId);

Grace Period Expires

Teams past their graceEndDate without billing setup are transitioned to restricted.

await transitionToRestricted(db, teamId);

Billing Setup Complete

After successful Stripe Checkout, the subscription becomes active.

await markBillingComplete(db, {
  teamId,
  stripeSubscriptionId: "sub_xxx",
  stripeCustomerId: "cus_xxx",
});

Middleware Enforcement

Feature restrictions are enforced via tRPC middleware:

// apps/workbooks-api/src/trpc/middleware/subscription-restriction.ts

export const withSubscriptionRestriction = (restrictedAction: RestrictedAction) => {
  return t.middleware(async (opts) => {
    const trialStatus = await getCachedTrialStatus(ctx.db, ctx.teamId);
    
    if (!isActionAllowed(trialStatus, restrictedAction)) {
      throw new TRPCError({
        code: "FORBIDDEN",
        message: trialStatus.message || `Upgrade required to ${restrictedAction}`,
      });
    }
    
    return opts.next({
      ctx: { ...ctx, trialStatus, isRestricted: trialStatus.isRestricted },
    });
  });
};

Frontend Integration

Trial Status Hook
Action Guard
Upgrade Banner

// apps/workbooks-dashboard/src/hooks/use-action-guard.ts

export function useTrialStatus() {
  const trpc = useTRPC();
  const { data: trialStatus, isLoading } = useQuery({
    ...trpc.subscriptions.getTrialStatus.queryOptions(),
  });
  
  return {
    trialStatus,
    isLoading,
    status: trialStatus?.status ?? "no_subscription",
    isTrial: trialStatus?.status === "trial",
    isGracePeriod: trialStatus?.status === "grace_period",
    isRestricted: trialStatus?.isRestricted ?? false,
    canCreateJobs: trialStatus?.canCreateJobs ?? true,
  };
}

// Guard component actions
const { canCreateJobs, isRestricted } = useTrialStatus();

<Button 
  onClick={handleCreateJob} 
  disabled={!canCreateJobs || isRestricted}
>
  Create Job
</Button>

// Show upgrade prompts based on status
const { status, daysRemaining, upgradeRequired } = useTrialStatus();

{status === "trial" && daysRemaining <= 7 && (
  <Banner variant="warning">
    {daysRemaining} days left in your trial. 
    <Link href="/dashboard-docs/settings/billing">Set up billing</Link>
  </Banner>
)}

{status === "grace_period" && (
  <Banner variant="error">
    Your trial has ended. Set up billing within {daysRemaining} days.
  </Banner>
)}

Seat-Based Billing

Taskr uses per-seat billing where the subscription cost scales with team size.

Seat Counting

// apps/workbooks-api/src/services/seat-service.ts

// Active seats = team members with active status
const seatCount = await db
  .select({ count: count() })
  .from(teamMembers)
  .where(
    and(
      eq(teamMembers.teamId, teamId),
      eq(teamMembers.status, "active")
    )
  );

Stripe Synchronization

Adding a Team Member

When a new member is added:

Member record created in database
Seat count incremented
Stripe subscription quantity updated
Prorated charge applied

Removing a Team Member

When a member is removed:

Member status set to inactive
Seat count decremented
Stripe subscription quantity updated
Prorated credit applied

Reconciliation Cron

Daily cron ensures seat counts match between database and Stripe:

// apps/workbooks-api/src/utils/seat-reconciliation-cron.ts

// Skip trial/grace_period subscriptions (no Stripe sync needed)
if (subscription.status === "trial" || subscription.status === "grace_period") {
  continue;
}

// Update Stripe quantity if mismatch detected
await stripe.subscriptions.update(stripeSubscriptionId, {
  items: [{ id: itemId, quantity: actualSeatCount }],
});

Email Notifications

Event	Email Template	Timing
Trial Started	`WelcomeEmail`	Immediately
Trial Expiring	`TrialExpiringEmail`	3 days before
Trial Ended	`TrialEndedEmail`	On expiration
Grace Period Ending	`GracePeriodWarningEmail`	2 days before
Account Restricted	`AccountRestrictedEmail`	On restriction
Billing Complete	`SubscriptionActiveEmail`	On activation

// packages/workbooks-jobs/src/tasks/team/onboarding.ts

await resend.send({
  to: teamOwner.email,
  subject: "Your trial is expiring soon",
  react: TrialExpiringEmail({
    teamName: team.name,
    daysRemaining: 3,
    upgradeUrl: `${baseUrl}/settings/billing`,
  }),
});

Extending Trials

Sales and support can extend trials for specific teams:

// Extend by 14 additional days
const result = await extendTrial(db, teamId, 14, supportUserId);

// Returns:
// {
//   newTrialEndDate: "2025-02-17T00:00:00Z",
//   newGraceEndDate: "2025-02-24T00:00:00Z"
// }

Trial extensions also reset the grace period end date to maintain the 7-day buffer after the new trial end date.

Database Schema

// packages/workbooks-db/src/schema/subscriptions.ts

export const teamSubscriptions = pgTable("team_subscriptions", {
  id: uuid("id").primaryKey().defaultRandom(),
  teamId: uuid("team_id").references(() => teams.id),
  planId: uuid("plan_id").references(() => subscriptionPlans.id),
  status: text("status").notNull(), // trial, grace_period, restricted, active, canceled
  
  // Trial tracking
  trialStartDate: timestamp("trial_start_date"),
  trialEndDate: timestamp("trial_end_date"),
  graceEndDate: timestamp("grace_end_date"),
  restrictedAt: timestamp("restricted_at"),
  
  // Billing
  billingSetupComplete: boolean("billing_setup_complete").default(false),
  stripeSubscriptionId: text("stripe_subscription_id"),
  stripeCustomerId: text("stripe_customer_id"),
  
  // Seat billing
  userCount: integer("user_count").default(1),
  unitPrice: integer("unit_price"),
  totalPrice: integer("total_price"),
  billingCycle: text("billing_cycle"), // monthly, annual
});

API Endpoints

Endpoint	Method	Description
`subscriptions.getTrialStatus`	Query	Get current trial/subscription status
`subscriptions.createCheckoutSession`	Mutation	Create Stripe Checkout session
`subscriptions.cancelSubscription`	Mutation	Cancel active subscription
`subscriptions.extendTrial`	Mutation	Extend trial period (admin only)

Stripe Webhook Events

Event	Handler	Action
`checkout.session.completed`	`handleCheckoutComplete`	Mark billing complete, activate subscription
`customer.subscription.updated`	`handleSubscriptionUpdate`	Sync status changes
`customer.subscription.deleted`	`handleSubscriptionDeleted`	Mark as canceled
`customer.subscription.trial_will_end`	`handleTrialWillEnd`	Send reminder email
`invoice.payment_failed`	`handlePaymentFailed`	Start grace period

Billing Setup

Configure billing and subscription settings

Team Management

Add and remove team members (affects seat count)

Developer - Overview

Core Workflows

Billing & Subscriptions

Integrations

Team Management

Onboarding Wizards

Reference

Overview

Subscription States

Trial

Grace Period

Restricted

Active

Workflow Diagram

Status Timeline

Feature Restrictions by Status

Implementation Details

Trial Status Service

Creating a Trial Subscription

Automated Status Transitions

Middleware Enforcement

Frontend Integration

Seat-Based Billing

Seat Counting

Stripe Synchronization

Email Notifications

Extending Trials

Database Schema

API Endpoints

Stripe Webhook Events

Billing Setup

Team Management

​Overview

​Subscription States

Trial

Grace Period

Restricted

Active

​Workflow Diagram

​Status Timeline

​Feature Restrictions by Status

​Implementation Details

​Trial Status Service

​Creating a Trial Subscription

​Automated Status Transitions

​Middleware Enforcement

​Frontend Integration

​Seat-Based Billing

​Seat Counting

​Stripe Synchronization

​Email Notifications

​Extending Trials

​Database Schema

​API Endpoints

​Stripe Webhook Events

​Related Documentation

Billing Setup

Team Management

Overview

Subscription States

Workflow Diagram

Status Timeline

Feature Restrictions by Status

Implementation Details

Trial Status Service

Creating a Trial Subscription

Automated Status Transitions

Middleware Enforcement

Frontend Integration

Seat-Based Billing

Seat Counting

Stripe Synchronization

Email Notifications

Extending Trials

Database Schema

API Endpoints

Stripe Webhook Events

Related Documentation