Billing — Plans, Subscriptions & Entitlements

ES Reference: Phase 4 (INTOS-ES-P4-001) — Billing and Entitlements, Section 6

Overview

The Billing page manages your Interview OS subscription, payment method, usage, and plan entitlements. Phase 4 introduces a complete entitlement service with plan catalog, subscription lifecycle management, idempotent usage ledger, provider reconciliation, and transparent upgrade/downgrade previews.

Every protected feature call evaluates entitlements server-side. Feature denials explain exactly what plan is needed without losing your work.

Key Principles

• Server-side entitlement enforcement — client-side flags are for UX only; real gates are server-side
• Plan catalog is internal, not hardcoded in UI — plans can evolve without frontend changes
• Usage is tracked with idempotent ledger — corrections use compensating entries, never overwrites
• Understandable units — users see "kits remaining" or "practice minutes," not raw AI tokens
• Daily reconciliation — provider state compared to database; differences alerted
• Transparent upgrade/downgrade — preview impact, effective date, proration, and preserved data
• Grandfathering is explicit and testable — plan-version changes have documented migration paths

Entitlement Decision Model

Entitlement = Plan Grants + Add-ons + Promotional Grants - Consumed/Expired Limits

Every protected use case calls the server-side entitlement service. The entitlement decision accounts for:

Factor	Description
Plan Grants	Base entitlements from your subscription plan
Add-ons	Purchased additional capacity (extra kits, practice minutes)
Promotional Grants	Time-limited promotional credits or feature access
Consumed	Used quota (kits generated, practice minutes, etc.)
Expired	Time-expired grants or credits

Screens in This Feature Area

1. Billing Overview (/billing)

Your billing dashboard showing current plan, usage, and subscription status.

Buttons & Actions:

Button	Behavior
View Plans	See available subscription tiers with feature comparison
Upgrade / Downgrade	Change your current plan (with impact preview)
Manage Payment Method	Add, update, or remove payment methods (provider-hosted)
View Invoices	Access billing history and receipts
View Usage	See current consumption against plan limits
Cancel Subscription	Cancel your paid plan (reverts to free tier with data preservation)
Reactivate	Restart a cancelled subscription

2. Plan Catalog

Available subscription plans represented internally (not hardcoded in UI).

Tier	Best For	Key Features
Free	Casual job seekers	Limited kits, basic role match, limited practice sessions
Professional	Active job seekers	Expanded kits, Role Match v2, unlimited practice, Story Bank
Executive	Senior professionals	All Professional + Executive Mode, Dream Job Navigator, NBA, Offer Comparison
Institutional	Organizations & teams	All Executive + organization workspace, cohorts, advisor tools, aggregate analytics, SSO

Buttons & Actions:

Button	Behavior
Compare Plans	Side-by-side feature comparison
Select Plan	Choose a plan (goes to provider checkout)
Preview Impact	See what changes with upgrade/downgrade before committing

3. Subscription Lifecycle

Your subscription transitions through these states:

TRIAL → ACTIVE → PAST_DUE → ACTIVE (payment resolved)
                    ↓
                  CANCELLED → EXPIRED
                    ↓
                  PAUSED (if supported by provider)

Buttons & Actions:

Button	Behavior
Update Payment	Fix a past-due subscription by updating payment method
Resume	Reactivate a paused subscription
Cancel	Cancel with data preservation and effective date shown
Download Invoice	Get PDF receipt for any billing period

4. Usage & Credits

Track your consumption against plan limits in understandable units.

Usage Categories:

Category	Unit	Description
Kit Generations	Kits / month	Interview kit generation and regeneration
Practice Minutes	Minutes / month	Audio practice session duration
Role Match Assessments	Assessments / month	Full Role Match v2 analysis runs
Coach Seats	Active coaches	Active coach relationships
Evidence Storage	Records	Career Vault evidence items
AI Reviews	Reviews / month	AI-powered content reviews and suggestions

Buttons & Actions:

Button	Behavior
View Usage Details	See per-category consumption and remaining quota
Purchase Add-on	Buy additional capacity for a specific category
View Usage History	Historical usage trends

5. Upgrade / Downgrade Flow

When changing plans, you see a preview before committing:

Upgrade Preview Shows:

• New features you'll gain
• Effective date (immediate or next billing cycle)
• Prorated charge (if upgrading mid-cycle)
• What stays the same (data, settings, active jobs/kits)

Downgrade Preview Shows:

• Features you'll lose access to
• What happens to existing data (preserved, not deleted)
• Effective date (end of current billing cycle)
• What to expect (reduced limits, feature gating)

6. Entitlement Denial UX

When you attempt a feature not in your plan:

• Upgrade banner appears explaining what's needed — clear, not aggressive
• Dismiss option available — banner doesn't block your view
• Upgrade button links directly to relevant plan comparison
• Your work is preserved — denial doesn't delete or corrupt in-progress content
• Specific explanation — "This feature requires the Professional plan" not "Access denied"

7. Payment Methods

Payment processing handled by secure provider (Stripe). Interview OS never stores raw card details.

Buttons & Actions:

Button	Behavior
Add Payment Method	Redirect to provider-hosted secure form
Set Default	Choose primary payment method
Remove	Delete a saved payment method
Update	Change card/account details (provider-hosted)

8. Invoice History

Complete billing history with downloadable PDF receipts.

Invoice Details:

• Date, amount, and status (paid, pending, failed)
• Plan and period covered
• Proration and credits applied
• Provider invoice ID for reference
• PDF download

Provider Webhook Security

Billing provider webhooks are validated for:

• Signature verification — every webhook is cryptographically signed
• Idempotency — duplicate webhooks don't double-charge
• Ordering tolerance — events processed correctly even if arriving out of order
• Daily reconciliation — provider state compared to database; differences alerted

Institution Billing

For organization accounts (Phase 4):

• Seat-based or active-user metric — defined in institution contract
• Admin visibility — org admins see seat utilization, not individual billing
• Audit trail — all billing and entitlement changes logged

Security

• Payment processing handled by secure payment provider (Stripe)
• No raw card details stored on Interview OS servers
• Billing webhooks protected against replay, forgery, and race conditions
• Invoice history available for 12+ months
• Usage ledger entries are immutable and idempotent

Related ES Requirements

ID	Requirement
P4-E03	Plans, limits, credits, provider sync and reconciliation
P4 Billing	Plan catalog: Free, Professional, Executive, Institutional
P4 Billing	Subscription lifecycle: trial, active, past due, paused (if supported), cancelled, expired
P4 Billing	Entitlements: feature access and limits evaluated server-side through one service
P4 Billing	Usage/credits: track generations, mock minutes, reviews or approved units with idempotent ledger
P4 Billing	Provider webhooks: signature, idempotency, ordering tolerance, reconciliation
P4 Billing	Upgrade/downgrade: preview impact, effective date, proration, preserved data
P4 Billing	Daily provider-to-database reconciliation; alert differences
AC-03	Plans, subscriptions, entitlements and usage ledger reconcile with provider

Related Docs

• [[admin]] — Admins can manage entitlements and view billing for users
• [[settings]] — Account settings complement billing management
• [[organization]] — Institutional billing, seats, and contracts