Subscription Management

Overview

Reportr uses PayPal subscriptions for billing. Your subscription includes:

Monthly report quota
Client limit
White-label branding access (on eligible plans)
14-day free trial for new paid subscribers

This guide covers upgrading, canceling, and managing your subscription.

Available Plans

Free

$0/month

1 client
5 reports/month
❌ No white-label
Perfect for testing

Starter

$29/month

5 clients
25 reports/month
❌ White-label: +$20/mo
Great for freelancers

Professional

$79/month

15 clients
75 reports/month
✅ White-label included
For small agencies

Agency

$199/month

50 clients
250 reports/month
✅ White-label included
For large agencies

Plan limits are defined in /workspace/source/src/lib/plan-limits.ts:15-43

Billing Cycle System

Reportr uses 30-day rolling billing cycles instead of calendar months:

Cycle start: Date you subscribed or upgraded
Cycle end: 30 days from cycle start
Usage resets: Automatically when cycle ends
Renewal: Charges on cycle end date

Example:

Subscribed: February 5, 2026
Cycle 1: Feb 5 - Mar 7, 2026
Cycle 2: Mar 7 - Apr 6, 2026
Cycle 3: Apr 6 - May 6, 2026

The billing cycle system automatically resets your report quota every 30 days. See implementation in /workspace/source/src/lib/billing-cycle.ts

Checking Your Usage

Dashboard Overview

Your dashboard shows current usage:

📊 Reports: 12 / 25 used (48%)
   Resets in 18 days

👥 Clients: 3 / 5 used (60%)
   2 clients remaining

Via API

Get detailed usage stats: Endpoint: GET /api/user/billing Response:

{
  "subscription": {
    "plan": "STARTER",
    "status": "active",
    "billingCycleStart": "2026-02-05T00:00:00Z",
    "billingCycleEnd": "2026-03-07T00:00:00Z",
    "paypalSubscriptionId": "I-ABC123XYZ"
  },
  "payments": [
    {
      "id": "...",
      "amount": 29.00,
      "currency": "USD",
      "status": "COMPLETED",
      "plan": "STARTER",
      "createdAt": "2026-02-05T10:30:00Z"
    }
  ]
}

See implementation in /workspace/source/src/app/api/user/billing/route.ts

Upgrading Your Plan

Access upgrade options

Click Upgrade from:

Dashboard header (if near quota)
Settings → Billing
Modal when you hit plan limits

Choose your plan

Select the plan tier that fits your needs:

Compare client and report limits
Check white-label availability
Review pricing

Start trial or subscribe

New subscribers get options:

Start 14-day trial - Free trial, then $X/mo
Subscribe now - Start paying immediately (no trial)

Trial users get full access to their plan tier, including white-label branding for testing.

Complete PayPal checkout

Click Subscribe button
Redirected to PayPal
Sign in to PayPal or pay as guest
Approve subscription
Redirected back to Reportr

Verify upgrade

After successful payment:

✅ Plan updates immediately
✅ New quotas apply
✅ White-label unlocks (if included)
📧 Confirmation email sent

PayPal Plan IDs

Reportr uses different PayPal plans for trials vs. direct subscriptions (see /workspace/source/.env.example:45-59):

Plan	Trial Plan ID	Direct Plan ID
Starter	`PAYPAL_STARTER_TRIAL_PLAN_ID`	`PAYPAL_STARTER_DIRECT_PLAN_ID`
Professional	`PAYPAL_PRO_TRIAL_PLAN_ID`	`PAYPAL_PRO_DIRECT_PLAN_ID`
Agency	`PAYPAL_AGENCY_TRIAL_PLAN_ID`	`PAYPAL_AGENCY_DIRECT_PLAN_ID`

Trial plans charge $0 for the first 14 days, then automatically convert to paid subscription. Direct plans charge immediately.

Trial Period Details

How Trials Work

Duration: 14 days from signup
Full access: Complete plan features including white-label
No payment: Credit card required, but not charged until trial ends
Auto-conversion: Becomes paid subscription after 14 days
Cancel anytime: Cancel during trial for no charges

Trial Tracking

Trial data is stored in User model (see /workspace/source/prisma/schema.prisma:36-40):

trialStartDate    DateTime?
trialEndDate      DateTime?
trialUsed         Boolean @default(false)
trialType         String?  // 'EMAIL' | 'PAYPAL'
signupFlow        String?  // 'FREE' | 'PAID_TRIAL'

What Happens When Trial Expires?

When your trial ends:

Auto-charge: PayPal charges your payment method
Plan continues: No interruption in service
Status update: subscriptionStatus changes to "active"
Email notification: Confirmation of first payment

If payment fails:

PayPal retries charge
Account may be downgraded to Free plan
Email notification sent

Canceling Your Subscription

Canceling your subscription will downgrade you to the Free plan at the end of your billing cycle.

Navigate to billing settings

Go to Settings → Billing → Manage Subscription

Click Cancel Subscription

Click the Cancel Subscription button at the bottom of the page.

Confirm cancellation

A modal appears:

Shows your current plan
Explains when access ends
Confirms downgrade to Free plan

Click Confirm Cancellation to proceed.

Cancellation processed

On success:

✅ PayPal subscription canceled
✅ Access continues until cycle end
✅ Subscription marked as "cancelled"
📧 Confirmation email sent

What Happens After Cancellation?

When you cancel (see /workspace/source/src/app/api/subscription/cancel/route.ts:84-92):

Immediate updates:

subscriptionStatus: 'cancelled'
cancelledAt: new Date()
subscriptionEndDate: billingCycleEnd

Retained access:
- Keep current plan features until subscriptionEndDate
- Can still generate reports and add clients
- White-label remains active (if applicable)
At cycle end:
- Plan downgrades to Free
- Client limit reduces to 1
- Report quota reduces to 5/month
- White-label disabled
- Existing clients/reports remain but read-only if over Free limits

You can re-subscribe at any time before or after the cycle ends.

Managing PayPal Subscription

You can also manage your subscription directly in PayPal:

Log in to PayPal
Go to Settings → Payments → Manage automatic payments
Find “Reportr” subscription
View details, update payment method, or cancel

Changes made in PayPal sync to Reportr via webhooks. Allow up to 5 minutes for updates to reflect.

White-Label Add-On (Starter Plan)

Starter plan users can add white-label branding for $20/month:

Adding White-Label

Go to Branding Settings

Navigate to Settings → Branding

Click Add White-Label

You’ll see a prompt: “White-label branding is available on Professional and Agency plans. You can also access it during your trial period.”Click Add White-Label (+$20/mo)

Complete PayPal checkout

Redirected to PayPal to approve the add-on subscription.

Verify activation

After payment:

whiteLabelEnabled set to true
Branding settings become editable
Total billing: $29 (Starter) +$ 20 (White-label) = $49/mo

Alternatively, upgrade to Professional plan ($79/mo) which includes white-label plus higher limits.

Billing Cycle Auto-Reset

Reportr automatically manages billing cycles (see /workspace/source/src/lib/billing-cycle.ts:20-60):

Reset Logic

export async function checkAndResetBillingCycle(userId: string) {
  const now = new Date();
  
  // Check if cycle needs reset
  if (!user.billingCycleEnd || now > user.billingCycleEnd) {
    const newCycleStart = now;
    const newCycleEnd = new Date(now.getTime() + 30 * 24 * 60 * 60 * 1000);
    
    await prisma.user.update({
      where: { id: userId },
      data: {
        billingCycleStart: newCycleStart,
        billingCycleEnd: newCycleEnd,
      }
    });
  }
}

This runs automatically:

When checking report quota
When viewing billing info
When generating reports

Manual Cycle Reset

Admins can manually reset cycles if needed:

import { initializeBillingCycle } from '@/lib/billing-cycle';

await initializeBillingCycle(userId);

Troubleshooting

Subscription Shows as “Inactive”

Problem: Dashboard shows inactive subscription despite having paid Possible causes:

PayPal payment pending: Check PayPal for payment status
Webhook delay: Wait 5 minutes for PayPal webhook to process
Subscription ID mismatch: Verify paypalSubscriptionId in database

Solution:

Refresh page after 5 minutes
Check PayPal for subscription status
Contact support with PayPal subscription ID

Cannot Add Clients Despite Upgrade

Problem: Client limit still shows old plan limits Solution:

Verify plan field updated in database
Log out and log back in to refresh session
Check canAddClient() function is using correct plan limits

See limit check in /workspace/source/src/lib/plan-limits.ts:49-83

Report Quota Not Resetting

Problem: Still showing old quota despite cycle ending Solution:

Check billingCycleEnd date in database
Verify auto-reset logic ran (check console logs)

Manually trigger reset:

await checkAndResetBillingCycle(userId);

See /workspace/source/src/lib/billing-cycle.ts:20-60

PayPal Subscription Not Found

Problem: Error when canceling: “Subscription not found in PayPal” Possible causes:

Subscription already canceled in PayPal
Subscription ID invalid or expired
PayPal account access revoked

Solution: Reportr automatically updates database to mark subscription as inactive. Verify in Settings → Billing. See error handling in /workspace/source/src/app/api/subscription/cancel/route.ts:108-129

Trial Not Applying

Problem: Charged immediately instead of starting trial Possible causes:

Direct plan used: Ensure using trial plan ID in checkout
Trial already used: Users can only use trial once
Incorrect plan configuration: Check PayPal plan settings

Solution:

Verify trialUsed: false in database
Check correct plan ID used: PAYPAL_*_TRIAL_PLAN_ID
Contact support for trial credit if incorrectly charged

Payment History

View your payment history: Location: Settings → Billing → Payment History Shows:

Payment date and time
Amount and currency
PayPal order ID
Plan tier
Payment status

Data comes from payments table (see /workspace/source/prisma/schema.prisma:53-71)

Database Schema Reference

Subscription data in User model (from /workspace/source/prisma/schema.prisma:11-50):

Field	Type	Description
`plan`	Enum	FREE, STARTER, PROFESSIONAL, AGENCY
`planExpires`	DateTime?	When plan access ends (for trials)
`billingCycleStart`	DateTime	Start of current 30-day cycle
`billingCycleEnd`	DateTime?	End of current cycle
`paypalCustomerId`	String?	PayPal customer identifier
`paypalSubscriptionId`	String?	PayPal subscription identifier
`subscriptionStatus`	String	”free”, “active”, “cancelled”, “inactive”
`cancelledAt`	DateTime?	When subscription was cancelled
`subscriptionEndDate`	DateTime?	When access actually ends after cancellation
`trialStartDate`	DateTime?	Trial start timestamp
`trialEndDate`	DateTime?	Trial end timestamp
`trialUsed`	Boolean	Whether user has used their free trial
`whiteLabelEnabled`	Boolean	White-label access flag

Get Started

Core Features

Guides

Plans & Pricing

​Overview

​Available Plans

Free

Starter

Professional

Agency

​Billing Cycle System

​Checking Your Usage

​Dashboard Overview

​Via API

​Upgrading Your Plan

​PayPal Plan IDs

​Trial Period Details

​How Trials Work

​Trial Tracking

​What Happens When Trial Expires?

​Canceling Your Subscription

​What Happens After Cancellation?

​Managing PayPal Subscription

​White-Label Add-On (Starter Plan)

​Adding White-Label

​Billing Cycle Auto-Reset

​Reset Logic

​Manual Cycle Reset

​Troubleshooting

​Subscription Shows as “Inactive”

​Cannot Add Clients Despite Upgrade

​Report Quota Not Resetting

​PayPal Subscription Not Found

​Trial Not Applying

​Payment History

​Database Schema Reference

​Next Steps

Customize Branding

Generate Reports

Build docs developers (and LLMs) love

Overview

Available Plans

Billing Cycle System

Checking Your Usage

Dashboard Overview

Via API

Upgrading Your Plan

PayPal Plan IDs

Trial Period Details

How Trials Work

Trial Tracking

What Happens When Trial Expires?

Canceling Your Subscription

What Happens After Cancellation?

Managing PayPal Subscription

White-Label Add-On (Starter Plan)

Adding White-Label

Billing Cycle Auto-Reset

Reset Logic

Manual Cycle Reset

Troubleshooting

Subscription Shows as “Inactive”

Cannot Add Clients Despite Upgrade

Report Quota Not Resetting

PayPal Subscription Not Found

Trial Not Applying

Payment History

Database Schema Reference

Next Steps