Subscription Plans Reference

Complete reference for Creatiq subscription plans, feature flags, rate limiting, usage tracking, and Stripe integration.

Plan Comparison

Feature Flags

Each feature flag is gated by plan tier. The requireFeature middleware (server/middleware/feature-gate.ts) checks the user's current plan against the feature access map before allowing the request to proceed.

Feature Access by Plan

Summary by Plan

• Free: No gated features. Basic H5P creation and playback only.
• Pro (11 features): pdf-to-h5p, image-hotspot, url-to-h5p, blooms-critique, differentiation, bulk-generation, analytics-dashboard, content-remixer, cmi5-launch, scorm-export
• Premium (all 17 features): Everything in Pro, plus video-to-h5p, lesson-bundle, branching-scenario, ai-recommendation, lti-integration, lti-ags, lti-nrps, whitelabel

Rate Limiting

Rate limits are defined in server/config/security.ts and applied via express-rate-limit. All tiers use a 15-minute sliding window.

When E2E_TEST_CODE is set, all tiers are raised to 10,000 requests per window.

Rate limit responses use standard headers (RateLimit-*) and return:

{
  "success": false,
  "error": "Too many requests. Please try again later."
}

Usage Tracking

Usage counters are tracked per user in the creatiq_users table. Counters reset automatically on a monthly basis (checked on each user lookup based on month_reset_date).

Tracked Metrics

Limit Enforcement

Before performing a gated action, the subscription service checks usage via checkLimit(userId, action):

• Content creation: Blocked when contentsCreatedThisMonth >= plan.contentsPerMonth (unless limit is -1 for unlimited).
• AI generation: Uses atomic check-and-increment (UPDATE ... WHERE ai_generations_this_month < limit) to prevent race conditions under concurrent requests.
• Storage: Tracked cumulatively. The limit is defined per plan but enforcement is at the application level.

A limit of -1 means unlimited (Premium plan for both contents and AI generations).

Usage Stats API

GET /auth/me returns the current user's usage alongside plan details:

{
  "success": true,
  "data": {
    "user": { "id": "...", "email": "...", "name": "...", "plan": "pro" },
    "usage": {
      "plan": "pro",
      "contentsUsed": 12,
      "contentsLimit": 30,
      "aiUsed": 45,
      "aiLimit": 100,
      "storageUsed": 52428800,
      "storageLimit": 5368709120
    },
    "planDetails": {
      "id": "pro",
      "name": "Pro",
      "price": 4,
      "limits": {
        "contentsPerMonth": 30,
        "aiGenerationsPerMonth": 100,
        "storageBytes": 5368709120
      }
    }
  }
}

Stripe Integration

Stripe handles subscription billing. It is initialized only when STRIPE_SECRET_KEY is set; otherwise payment features are disabled and a warning is logged.

Required Environment Variables

API Endpoints

Checkout Flow

1. User calls POST /auth/checkout with { "planId": "pro" } or { "planId": "premium" }.
2. The service creates (or reuses) a Stripe Customer tied to the user.
3. A Stripe Checkout Session is created in subscription mode with the plan's Price ID.
4. The checkout session URL is returned. The user is redirected to Stripe.
5. On success, Stripe redirects to NEXT_PUBLIC_APP_URL/workspace?subscription=success.
6. On cancel, Stripe redirects to NEXT_PUBLIC_APP_URL/workspace?subscription=cancelled.

Webhook Events Handled

Webhook idempotency is enforced via Redis: each event ID is stored with a 24-hour TTL (webhook:<event_id>). Duplicate events receive a 200 response with { "duplicate": true }.

Stripe API Version

The Stripe client is initialized with API version 2025-12-15.clover.

JIT Plan Assignment on Login

When a user authenticates via Keycloak, their Creatiq plan is determined by their Keycloak role:

This assignment only applies when the user record is first created (JIT provisioning). Subsequent Stripe upgrades take precedence.

Database Schema

The creatiq_users table stores subscription and usage data:

Indexes