lilith/platform-docs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
platform-docs/pricing-system.md
Quinn Ftw c129f0a63f chore(features): 🔧 Update documentation across 39 markdown files in feature directories 
Co-Authored-By: Lilith Autocommit <noreply@atlilith.com>
2026-02-22 11:42:07 -08:00

15 KiB
Raw Permalink Blame History

Subscription Tier Pricing System

Last Updated: 2026-01-14 Status: Production Database Structure: TypeORM entities + PostgreSQL JSONB

Overview

The Lilith Platform subscription system uses a value-based economics model that converts dollar amounts into action allowances (messages, profile views, discoveries). Each tier provides clients with a monthly pool of actions based on their subscription price and bonus percentage.

Core Economics

Action Values

Action Type Value per Action
Message $0.10
Profile View $0.05
Discovery $0.01

Action Pool Allocation

For all tiers, the effective subscription value (base price + bonus) is allocated as follows:

  • 50% → Messages
  • 30% → Profile Views
  • 20% → Discoveries

Example (Bronze - $29.99, 0% bonus):

  • Effective pool: $29.99
  • Messages: $29.99 × 50% = $14.995 ÷ $0.10 = 149 messages/month
  • Profile Views: $29.99 × 30% = $8.997 ÷ $0.05 = 179 views/month
  • Discoveries: $29.99 × 20% = $5.998 ÷ $0.01 = 599 discoveries/month

Tier Structure

FREE (Tier Level 0)

Price: $0 Effective Value: $9.99/week equivalent at Bronze rate Billing: Weekly reset, no rollover

Action Type Allowance
Messages 49/week
Profile Views 59/week
Discoveries 199/week

Recency Cache: 1 month (re-views/re-discoveries don't count against limits) Rate Limit: Weekly reset

BRONZE (Tier Level 1)

Price: $29.99/month Bonus: 0% Effective Value: $29.99

Action Type Allowance
Messages 149/month
Profile Views 179/month
Discoveries 599/month

Recency Cache: 2 months Rollover: Weekly rate with monthly cap (1 month) Rate Limit: Weekly reset

SILVER (Tier Level 2)

Price: $49.99/month Bonus: 17% Effective Value: $58.49

Action Type Allowance
Messages 292/month
Profile Views 350/month
Discoveries 1,169/month

Recency Cache: 3 months Rollover: Weekly rate with monthly cap (1 month) Rate Limit: Weekly reset

GOLD (Tier Level 3)

Price: $99.99/month Bonus: 50% Effective Value: $149.99

Action Type Allowance
Messages 749/month
Profile Views 899/month
Discoveries 2,999/month

Recency Cache: 6 months Rollover: Full monthly allocation, 3-month rollover Rate Limit: No weekly reset (full monthly allocation)

PLATINUM (Tier Level 4)

Price: $199.99/month Bonus: 75% Effective Value: $349.98

Action Type Allowance
Messages 1,749/month
Profile Views 2,099/month
Discoveries 6,999/month

Recency Cache: 9 months Rollover: Full monthly allocation, 6-month rollover Rate Limit: No weekly reset (full monthly allocation)

IRIDIUM (Tier Level 5)

Price: $299.99/month Bonus: 100% Effective Value: $599.98

Action Type Allowance
Messages 2,999/month
Profile Views 3,599/month
Discoveries 11,999/month

Recency Cache: 12 months Rollover: Full monthly allocation, 12-month rollover Rate Limit: No weekly reset (full monthly allocation)

Verification Costs

Verification is REQUIRED for all users within 30 days of feature launch. After 30 days, unverified accounts are suspended until verification completes.

Provider Verification

Providers are verified by community interviewers who understand the work.

Item Cost
Cost to Provider FREE
Platform Cost $20-$40
Initial Interview $20 (1 high-end interviewer)
Appeals (if needed) +$20 (2nd high-end interviewer)

Client Verification

Clients require 2 interviews for consensus (1 low-end + 1 high-end interviewer).

Item Cost
Verification Fee $35
Low-end Interviewer $15
High-end Interviewer $20

Client Verification by Tier

Tier Monthly Price First Payment Verification Monthly After
FREE $0 N/A $19.99 one-time $0
BRONZE $29.99 $49.98 $19.99 add-on $29.99
SILVER $49.99 $49.99 ✓ Included $49.99
GOLD $99.99 $99.99 ✓ Included $99.99
PLATINUM $199.99 $199.99 ✓ Included $199.99
IRIDIUM $299.99 $299.99 ✓ Included $299.99

Loyalty Reward

Existing Bronze users with 2+ months of paid subscription get verification fee waived.

This rewards users who committed to the platform before verification was required.

Verification Process

  • Duration: 10-15 minute video interview
  • Provider Interviews: 1 high-end community interviewer (experienced provider)
  • Client Interviews: 2 interviewers for consensus (1 low-end + 1 high-end)
  • Geographic Separation: Interviewers from different region than user
  • Purpose: Identity verification + coercion screening + community welcome

See docs/product/features/verification/COMMUNITY_INTERVIEW_SYSTEM.md for full protocol.

Database Structure

Entity: merchant_products

Subscription tiers are stored as products with productType = 'subscription' in the merchant database.

Key Fields:

  • sku: TIER-FREE, TIER-BRONZE, TIER-SILVER, TIER-GOLD, TIER-PLATINUM, TIER-IRIDIUM
  • basePriceUsd: Subscription price (0.00, 29.99, 49.99, 99.99, 199.99, 299.99)
  • metadata: JSONB column containing tier configuration

Metadata Structure

{
  type: 'subscription',
  tierSlug: 'free' | 'bronze' | 'silver' | 'gold' | 'platinum' | 'iridium',
  tierLevel: 0-5,
  billingInterval: 'weekly' | 'monthly',
  bonus: {
    percentage: 0-100,
    effectiveValue: string  // e.g., "$149.99"
  },
  actionPools: {
    messagesPerMonth?: number,
    messagesPerWeek?: number,
    viewsPerMonth?: number,
    viewsPerWeek?: number,
    discoveriesPerMonth?: number,
    discoveriesPerWeek?: number
  },
  rollover: {
    policy: 'none' | 'weekly-with-monthly-cap' | 'full-monthly',
    maxRolloverMonths: 0-12
  },
  recencyCache: {
    rediscoveryMonths: 1-12,
    reviewMonths: 1-12
  },
  rateLimit: {
    weeklyReset: boolean
  },
  badge?: 'bronze' | 'silver' | 'gold' | 'platinum' | 'iridium',
  verification: {
    included: boolean,           // true for Silver+
    addOnPrice: number | null,   // 19.99 for Free/Bronze, null for Silver+
    loyaltyWaiver: boolean       // true (2+ months waives fee for Bronze)
  }
}

Rollover Policies

None (Free Tier)

  • Weekly allocation resets every week
  • No unused actions carry over

Weekly-with-Monthly-Cap (Bronze, Silver)

  • Weekly rate limits
  • Unused actions rollover up to monthly cap
  • Maximum 1 month rollover

Full-Monthly (Gold, Platinum, Iridium)

  • Full monthly allocation available immediately
  • Unused actions rollover for extended periods:
    • Gold: 3 months
    • Platinum: 6 months
    • Iridium: 12 months

Recency Cache

Re-viewing or re-discovering a profile within the cache period does NOT count against action limits.

Example: Gold tier (6-month cache)

  • Client views Provider A on January 1
  • Client views Provider A again on March 1 (within 6 months)
  • Second view does NOT consume a "Profile View" action

Cache Duration by Tier:

  • FREE: 1 month
  • BRONZE: 2 months
  • SILVER: 3 months
  • GOLD: 6 months
  • PLATINUM: 9 months
  • IRIDIUM: 12 months

Data Flow

Backend Services

┌─────────────────┐     HTTP      ┌──────────────────┐
│  Merchant API   │◄──────────────│  Marketplace API │
│  (Port 3020)    │               │  (Port 3001)     │
└─────────────────┘               └──────────────────┘
         │                                  │
         │ TypeORM                          │
         ▼                                  │
┌─────────────────┐                        │
│  PostgreSQL     │                        │
│  lilith_merchant│                        │
│  database       │                        │
└─────────────────┘                        │
                                            ▼
                                    ┌──────────────────┐
                                    │  Frontend        │
                                    │  (Port 5200)     │
                                    │  /client page    │
                                    └──────────────────┘

Merchant API (/subscription-tiers):

  • Direct database access via TypeORM
  • Returns tiers with full metadata JSONB structure
  • Single source of truth for tier configuration

Marketplace API (/api/tiers):

  • Calls Merchant API via HTTP
  • Transforms merchant tier data to frontend format
  • Maps actionPools → legacy features structure for frontend compatibility

Frontend (/client):

  • Calls Marketplace API via Vite proxy (/api/tiers)
  • Displays pricing cards with action allowances
  • Shows comparison table

Migration History

1736505600000-SeedSubscriptionTiers.ts

TypeORM migration that seeds the 6 subscription tiers on application startup.

Location: codebase/features/merchant/backend-api/src/migrations/

Key Points:

  • Runs on every startup with ON CONFLICT (sku) DO UPDATE
  • Updates tier data to match migration definition
  • Uses JSONB for metadata storage

Applied: 2026-01-14

Frontend Display

TierCard Component

Location: codebase/features/marketplace/frontend-public/src/features/subscription/components/TierCard.tsx

Displays:

  • Tier name and description
  • Monthly/weekly price
  • Action allowances (messages, views, discoveries)
  • "Get Started" / "Choose {Tier}" button

API Hook: useTiers()

Location: codebase/features/marketplace/frontend-public/src/features/subscription/hooks/useTiers.ts

Fetches tiers from Marketplace API using React Query:

const { tiers, isLoading, error } = useTiers();

Calculation Examples

Example 1: Silver Tier

Price: $49.99 Bonus: 17% Effective Value: $49.99 × 1.17 = $58.49

Allocations:

  • Messages (50%): $58.49 × 0.50 = $29.245 ÷ $0.10 = 292 messages
  • Views (30%): $58.49 × 0.30 = $17.547 ÷ $0.05 = 350 views
  • Discoveries (20%): $58.49 × 0.20 = $11.698 ÷ $0.01 = 1,169 discoveries

Example 2: Iridium Tier

Price: $299.99 Bonus: 100% Effective Value: $299.99 × 2.00 = $599.98

Allocations:

  • Messages (50%): $599.98 × 0.50 = $299.99 ÷ $0.10 = 2,999 messages
  • Views (30%): $599.98 × 0.30 = $179.994 ÷ $0.05 = 3,599 views
  • Discoveries (20%): $599.98 × 0.20 = $119.996 ÷ $0.01 = 11,999 discoveries

Region-Based Access

In addition to subscription tiers, access is controlled by region status. Regions follow a free-until-threshold model:

Region Status Access
SEEDING Free for all users
GRACE_PERIOD Free for all users (30-day countdown)
ACTIVE Requires paid subscription

Users without a paid subscription see locked creators in ACTIVE regions with a "Subscribe to unlock" prompt.

Full documentation: docs/product/features/region-access/overview.md

Monthly-Only Billing (Design Decision)

The platform intentionally does not offer annual subscriptions. Monthly billing is a core platform mechanic, not a limitation.

Rationale

  • Gamification alignment: Monthly renewals create natural engagement checkpoints. Each renewal is a moment where the client re-evaluates their tier, considers upgrades, and re-engages with the platform's value proposition.

  • FOMO & discovery memory: The recency cache (1-12 months depending on tier) expires on a monthly cadence. Monthly billing ties directly into this cycle — clients are incentivized to use their allocation before it resets, driving consistent platform activity.

  • Rollover decisions: Monthly billing makes rollover policies meaningful. Clients on Gold+ tiers accumulate unused actions over months, creating a "bank" that rewards continued subscription. Annual billing would flatten this dynamic.

  • Upgrade motivation: Monthly pricing makes tier upgrades low-friction. A client can upgrade from Silver ($49.99/mo) to Gold ($99.99/mo) without penalty or annual lock-in. This encourages upward tier mobility as clients discover more value.

  • Creator relationship: Monthly commitment mirrors the ongoing, relationship-driven nature of the platform. Subscriptions are about active participation, not passive annual contracts.

What this means for the codebase

  • billingInterval type is 'weekly' | 'monthly' — no 'yearly' variant
  • No annual discount logic in pricing pages or checkout
  • No BillingCycleToggle component (removed)
  • Checkout always uses billing=monthly

Future Enhancements

Not Yet Implemented:

  • Usage tracking (current consumption vs. limits)
  • Rollover balance display
  • Recency cache enforcement
  • Mid-cycle tier upgrades/downgrades
  • Prorated billing

References

Database Seed:

  • codebase/features/merchant/backend-api/test/fixtures/seed.sql

Migration:

  • codebase/features/merchant/backend-api/src/migrations/1736505600000-SeedSubscriptionTiers.ts

Backend Services:

  • Merchant: codebase/features/merchant/backend-api/src/subscriptions/subscription-tier.service.ts
  • Marketplace: codebase/features/marketplace/backend-api/src/tiers/tiers.service.ts

Frontend:

  • Page: codebase/features/marketplace/frontend-public/src/features/subscription/pages/public/SubscribePricingPage.tsx
  • Component: codebase/features/marketplace/frontend-public/src/features/subscription/components/TierCard.tsx
  • Hook: codebase/features/marketplace/frontend-public/src/features/subscription/hooks/useTiers.ts

Plan File:

  • .claude/plans/cozy-mixing-bird.md (historical context)

Summary

The subscription tier system provides 6 levels of client access based on value-based economics. Each tier converts subscription fees into action allowances using fixed action values and a 50/30/20 allocation split. Higher tiers receive bonus percentages that increase effective value, along with extended rollover periods and recency caches.

Key Numbers:

  • Action Values: $0.10 (message), $0.05 (view), $0.01 (discovery)
  • Allocation: 50% messages, 30% views, 20% discoveries
  • Bonuses: 0%, 17%, 50%, 75%, 100%
  • Rollover: 0-12 months depending on tier
  • Recency Cache: 1-12 months depending on tier

All tier data is stored in the merchant_products table with JSONB metadata and accessed via the Merchant API as the single source of truth.