Overview

All paid subscriptions are managed through Stripe. Users can upgrade, downgrade, change billing cycles, update payment methods, and access invoices — all from within the ValidGraph dashboard.

How It Works

1. User selects a plan during signup or upgrade
2. Stripe handles payment processing
3. Subscription management includes:
– Monthly or annual billing cycles
– Plan upgrades (immediate) and downgrades (end of cycle)
– Payment method updates via Stripe portal
– Invoice history and receipts
4. Subscription status syncs automatically with ValidGraph

Tier Availability

All tiers (Free users can upgrade from the dashboard).

Related Features

– Plan Tiers & Limits: What each plan includes
– Usage Quotas: Real-time usage tracking

Mini-Tutorial

Step 1: Access Billing Portal

Go to Settings > Billing. Click “Manage Subscription” to open the Stripe customer portal.

Step 2: View Current Subscription

You’ll see your current plan, billing cycle (monthly/annual), and next renewal date.

Step 3: Upgrade Plan

Click “Change Plan” and select a higher tier. Your card is charged the pro-rated difference immediately.

Step 4: Downgrade Plan

Similarly, downgrade to a lower tier. The change takes effect at the end of your current billing cycle (no immediate charge).

Step 5: Change Billing Cycle

Toggle between monthly and annual billing. Annual billing typically offers a discount (save ~2 months).

Step 6: Update Payment Method

Click “Update Payment Method” to add or change your credit card.

Step 7: View Invoice History

See all past invoices and download receipts for accounting purposes.

Step 8: Cancel Subscription

If needed, click “Cancel” at the bottom. Your account reverts to Free tier after the current period ends.

Technical Details

Get Subscription Status

GET /api/v1/user/profile

Response:

{
  "id": "user_123",
  "email": "[email protected]",
  "subscription": {
    "status": "active",
    "plan": "pro",
    "plan_name": "Pro Plan",
    "billing_cycle": "monthly",
    "amount": 2900,
    "currency": "usd",
    "interval": "month",
    "current_period_start": "2025-03-01T00:00:00Z",
    "current_period_end": "2025-03-31T23:59:59Z",
    "renewal_date": "2025-03-31",
    "next_billing_date": "2025-03-31",
    "payment_method": "card_ending_4242",
    "stripe_customer_id": "cus_abc123"
  }
}

Initiate Checkout (Upgrade)

POST /api/v1/checkout
Content-Type: application/json

{
  "plan": "agency",
  "interval": "monthly"
}

Response:

{
  "checkout_url": "https://checkout.stripe.com/pay/cs_live_abc123...",
  "session_id": "cs_live_abc123"
}

Redirect user to checkout_url. After payment, Stripe webhook updates their subscription.

Manage via Customer Portal

POST /api/v1/customer-portal

Response:

{
  "portal_url": "https://billing.stripe.com/p/session/abc123"
}

User is redirected to Stripe’s hosted customer portal where they can manage everything.

Webhook Events (Server-Side)

ValidGraph listens for Stripe webhooks to sync subscription state:

checkout.session.completed

{
  "event": "checkout.session.completed",
  "data": {
    "customer_id": "cus_abc123",
    "subscription_id": "sub_xyz789",
    "plan": "pro",
    "amount": 2900
  }
}

customer.subscription.updated

{
  "event": "customer.subscription.updated",
  "data": {
    "customer_id": "cus_abc123",
    "plan": "agency",
    "amount": 7900,
    "updated_at": "2025-03-22T14:30:00Z"
  }
}

customer.subscription.deleted

{
  "event": "customer.subscription.deleted",
  "data": {
    "customer_id": "cus_abc123",
    "plan_downgrade": "free"
  }
}

Billing Cycle Impact

– Monthly: Billed on the same day each month. Charges reset daily for Free tier (5/day limit).
– Annual: Billed once per year (next bill date = today + 365 days). Usually 15-20% savings.
– Pro-Rating: Upgrades charge the difference for the remainder of current cycle. Downgrades adjust at next renewal.

References

– Stripe Billing API
– Recurring Billing Best Practices
– PCI Compliance for Payment Processing
– Subscription Management UX