Pricing Change Impact Report

Review status: completed with three internal review passes for coverage, consistency, and clarity.

1. Purpose

This report details the operational and technical impact of the April 5, 2026 pricing adjustments on the existing MysticX backend and outlines necessary architectural shifts to support the revised membership and credit framework.

This document is based on:

• The requirement document in z-2-reqirements/20260405 会员和积分 价格调整 包含IOS第一版本.docx
• Current runtime configuration and product code in this repository
• Existing mobile-planning documents in docs/mobile-app-development-plan.md

This document serves as a technical investigation and preliminary planning guide; it does not reflect direct application code modifications.

2. Requirement Summary

2.1 Target Commercial Model From the Requirement

Web

Retain the existing four credit packs at their current price points.

Target membership structure:

Offer	Target Price	Target Credits	Notes
Gold Monthly	$19.99	6,000	Recurring subscription
Diamond Monthly	$69.99	30,000	Recurring subscription
Gold Yearly	$89.99	100,000	Credits distributed upfront in a single allocation
Diamond Yearly	$299.99	1,000,000	Credits distributed upfront in a single allocation

Mobile v1 (iOS & Android)

Credit packs will not be offered on the Mobile platform.

The Diamond tier will not be available on iOS or Android.

The mobile platforms (iOS & Android) will exclusively offer Gold tier subscriptions:

Offer	Target Price	Target Credits	Notes
Gold Weekly	$7.99	1,500	Includes 3-day free trial
Gold Monthly	$19.99	6,000	Subscription
Gold Yearly	$89.99	100,000	Credits granted instantly in full

2.2 Product Direction Implied By the Requirement

• The Web platform will continue to serve as the comprehensive, flexible storefront.
• The mobile applications will transition to a streamlined, subscription-centric storefront.
• Annual subscription plans will be positioned as highly leveraged value offerings.
• Included subscription credits will serve as a primary lever for user conversion.
• System recommendations and default UI selections should pivot to favor the Gold annual plan.

3. Important Ambiguities In the Requirement

While the source requirements provide clear directional intent, they contain several internal contradictions and undocumented decisions that require resolution prior to development.

3.1 Weekly Plan Scope Is Conflicting

The main pricing proposal clearly adds a weekly Gold plan to Mobile only.

However, the technical reminder section also suggests the web membership page may need weekly, monthly, and yearly switching for Gold and Diamond. That conflicts with the earlier platform split.

3.2 Annual Credit Recovery Logic Is Unclear

The source notes that annual-plan credits should be granted in full immediately, and also hints that credit recovery may be needed if the plan is canceled or refunded.

Pending clarifications include:

• Whether credits should be clawed back on cancellation
• Whether credits should be clawed back only on refund or chargeback
• What happens if the user already spent part of the upfront credits

3.3 Daily Reward Changes Are Not Clearly Defined

The current system still uses tier-based daily Card of the Day credits.

The requirement mostly changes subscription grants, but one part of the source still mentions older daily values such as 80 or 100. That does not match the live code or the rest of the proposal.

3.4 Cross-Platform Entitlement Rules Are Missing

The requirement says Mobile should not sell Diamond, but it does not say whether Mobile should recognize Diamond if the user bought Diamond on web.

The operational baseline assumption should dictate that:

• Mobile does not sell Diamond
• Mobile still honors Diamond if purchased elsewhere

That assumption should be confirmed.

4. Current System Baseline

4.1 Confirmed Live Pricing And Credit Baseline

The current web runtime still uses the older pricing structure:

Area	Current Live State
Web Gold Monthly	$19.99
Web Diamond Monthly	$69.99
Web Gold Yearly	$167.92
Web Diamond Yearly	$587.92
Gold Monthly Grant	4,000
Diamond Monthly Grant	24,000
Credit Packs	2,000 / 5,000 / 12,000 / 30,000
Daily Card of the Day Credits	Free 300 / Gold 500 / Diamond 1,000

4.2 Confirmed Runtime Architecture

The current membership system is web-first and Stripe-first.

Confirmed characteristics:

• Web subscriptions are driven by Better Auth plus Stripe.
• Monthly recurring credits are granted through Stripe-related subscription events.
• One-time credit packs are sold through Stripe checkout.
• The membership page is built around Free, Gold, and Diamond with monthly and yearly switching.
• The current database only models three tiers: FREE, GOLD, and DIAMOND.

4.3 Confirmed Mobile (iOS & Android) State

Mobile commerce support (Apple StoreKit & Google Play Billing) is not implemented in this repository today.

Confirmed findings:

• No RevenueCat runtime integration is present.
• No StoreKit, App Store Server, Google Play Billing, or equivalent server integration is present.
• No Mobile product catalog exists in runtime code.
• No Mobile-specific subscription webhook flow exists.
• Existing Mobile references live in planning documents, not in shipping integration code.

Consequently, Mobile compatibility represents a substantial new engineering workstream rather than a minor configuration adjustment.

4.4 Confirmed Affected Surfaces

The following repository areas are confirmed to be directly relevant to this pricing change.

Surface	Current Role	Why It Is Affected
config/stripe.ts	Subscription display pricing, price IDs, pack definitions, plan mapping	Main web pricing source and plan mapping must change
lib/credits.ts	Daily rewards and subscription grant amounts	Grant amounts and grant timing assumptions must change
lib/auth.tsx	Stripe subscription lifecycle and webhook-driven credit granting	Yearly upfront grants, weekly Gold, and future mobile-origin subscriptions affect this layer
app/[locale]/(main)/membership/_components/PricingSection.tsx	Public membership pricing cards	Prices, included credits, recommendation logic, and copy must change
app/[locale]/(main)/membership/_components/ComparePlansSection.tsx	Membership comparison matrix	Included credits and plan positioning must change
app/[locale]/(main)/membership/_components/FAQSection.tsx	Membership FAQ copy	Plan explanations and billing wording must change
components/CreditPurchaseModal.tsx	Web credit-pack purchase UX	Value messaging must be recalculated; Mobile should not mirror this UX
app/api/v1/credits/purchase/route.ts	Stripe checkout for one-time packs	Web packs remain valid; platform strategy must stay explicit
app/api/v1/credits/route.ts and app/api/v1/card-of-day/route.ts	Credit balance and daily credit display/granting	Daily credit values may need confirmation or adjustment
app/api/v1/membership/route.ts	Membership status API	Cross-platform entitlement behavior may require expansion
prisma/schema.prisma	Tier and credit-transaction models	May need extension if implementation wants richer grant-source tracking
docs/credit-system*.md, docs/stripe-integration*.md, README.md	Public and internal documentation	All old pricing references must be updated
docs/mobile-app-development-plan*.md	Mobile roadmap and IAP strategy	Must be aligned to the actual Mobile v1 (iOS & Android) commercial plan

5. Impact Analysis By System Area

5.1 Billing And Subscription Configuration

Billing Impact

High.

The current subscription layer assumes:

• Two sellable paid plans on web: Gold and Diamond
• Monthly and yearly variants only
• Monthly recurring credit grants keyed to the subscription plan

The new commercial model introduces:

• Much lower yearly web prices
• Much higher included-credit values
• Annual plans that grant credits instantly instead of by monthly cadence
• A mobile-only weekly Gold plan with trial
• Mobile product structure that does not match web product structure

Billing Adjustments

• Update web pricing constants and display pricing.
• Redesign grant logic so yearly plans can issue one-time upfront credits.
• Add explicit plan metadata that distinguishes:
  • recurring monthly grants
  • annual upfront grants
  • weekly mobile grants
  • platform-specific sellability
• Introduce a platform-aware product model instead of assuming one universal catalog.

Billing Risk

If implementation merely updates front-end display pricing without synchronizing backend grant logic, the system will experience a severe business misalignment—charging updated rates while fulfilling legacy credit quotas.

5.2 Credit Ledger And Grant Logic

Ledger Impact

Critical.

The requirement is not just a pricing change. It changes the meaning of subscription credits.

Current behavior:

• Monthly subscription plans grant credits on billing events.
• One-time purchases grant credits through payment completion.

Target behavior:

• Web Gold yearly grants 100,000 instantly.
• Web Diamond yearly grants 1,000,000 instantly.
• Mobile Gold yearly grants 100,000 instantly.
• Mobile Gold weekly grants 1,500 on the weekly cycle.

Ledger Adjustments

• Separate monthly-grant logic from upfront-grant logic.
• Add transaction descriptions that clearly identify:
  • web yearly upfront grants
  • mobile weekly grants
  • Mobile yearly upfront grants
  • renewals versus initial purchases
• Define refund and clawback policy before implementation.
• Add abuse controls for large upfront grants.

Ledger Risks

• Users receive repeated upfront grants on webhook retries.
• Refunds occur after large upfront-credit spend.
• Upgrade or downgrade flows generate duplicate or incorrect credits.

Ledger Solution

• Keep idempotency keys per transaction source.
• Treat annual upfront grants as a separate grant type in implementation logic.
• Define negative-credit recovery policy before launch.
• Add finance-safe audit visibility for any reversal path.

5.3 Web Membership UX

Web UX Impact

High.

The membership page currently assumes a simple monthly/yearly comparison across Free, Gold, and Diamond. The new strategy changes the value story significantly.

Web UX Adjustments

• Update displayed prices and included-credit values.
• Update comparison copy to explain annual upfront-credit behavior clearly.
• Add stronger emphasis on yearly plans.
• Update recommendation badges and default selection behavior.
• Update any unit-price messaging around best value.
• Keep credit-pack messaging aligned with the new subscription economics.

Web UX Notes From The Requirement

The source asks for:

• Gold as the default focus
• Gold yearly as the default recommendation
• Diamond value framed as a strong discount or high-efficiency option
• Clear warnings that yearly credits are granted all at once

Web UX Risk

If web UI is only partially updated, users will see inconsistent prices, inconsistent included credits, or misleading comparisons versus credit packs.

5.4 Credit Packs And Pack Positioning

Pack Positioning Impact

Medium on web, high on positioning.

The credit packs remain on web with the same prices, but their relationship to subscriptions changes.

Pack Positioning Adjustments

• Recalculate all “best value” and “bonus” messaging.
• Recheck any pack-versus-membership price comparisons.
• Update FAQ and explanatory copy so users understand:
  • packs are still for flexible top-up use
  • subscriptions now provide much stronger included-credit value

Pack Positioning Risk

The exact inversion that triggered this project can reappear if pack copy or subscription copy is not recalculated after the new grant values go live.

5.5 Mobile v1 (iOS & Android) Compatibility

Mobile Compatibility Impact

Critical.

The current repo does not have a live Mobile commerce integration. Supporting Mobile v1 (iOS & Android) pricing means creating or finishing a real mobile billing architecture.

Mobile Compatibility Adjustments

• Implement Apple- and Google-compliant in-app subscription purchases.
• Add product handling for:
  • Gold weekly with 3-day trial
  • Gold monthly
  • Gold yearly
• Exclude credit packs from the mobile purchase surface.
• Exclude Diamond from the mobile purchase surface.
• Support restore purchases.
• Support trial status handling.
• Support App Store and Google Play renewal, cancellation, grace-period, and refund events.

Mobile Compatibility Direction

The existing planning docs already point toward RevenueCat. That remains the best fit unless a deliberate decision is made to own App Store and Google Play purchase handling directly.

Mobile Compatibility Risks

• Apple App Store and Google Play review rejection if purchase flows are incomplete or misleading.
• Subscription state drift between web and Mobile.
• Trial-state bugs.
• Missing restore-purchase support.

App Store And Google Play Paywall Policy Constraints

This is a hard platform-policy boundary, not a design preference. It has direct consequences for how the paywall is built and how web-paying users are handled inside the app.

Apple App Store guideline 3.1.1 requires that all digital goods and subscriptions sold within an iOS app must go through Apple In-App Purchase. Apps may not:

• Include a button, link, or any text directing users to an external website (including your own) to complete a purchase.
• Tell users that a subscription is cheaper or available elsewhere.
• Say "Subscribe at mysticx.com" or "Manage billing on the web" in a context that could be interpreted as steering users away from IAP.

Google Play Billing policy enforces the same requirement for Android apps distributed through the Play Store.

Practical consequences for MysticX:

User State	What the App May Show	What the App Must Not Show
Free user (never paid anywhere)	Gold Weekly / Monthly / Yearly IAP buttons	Any link or mention of web subscription, Stripe, or external checkout
Gold subscriber via IAP	Active Gold status, cancel via OS subscription settings	Any prompt to "manage on web" for billing purposes
Gold subscriber via web/Stripe	Active Gold status (honor it)	A Gold IAP purchase button (double-charge risk); an external billing link
Diamond subscriber via web/Stripe	Active Diamond status (honor it)	A Gold IAP prompt; any external upgrade link

The "reader app" exemption does not apply here. Apple's guideline 3.1.3a allows apps whose primary function is consuming previously purchased content (like Netflix) to omit an in-app purchase flow and omit external purchase links. MysticX is an interactive AI service where the app itself generates value on demand, which is unlikely to qualify.

What "Manage your subscription on the web" can and cannot mean:

• Acceptable: Telling an existing paid user (Gold or Diamond) where to cancel or view billing history — this is account management, not a new purchase solicitation.
• Not acceptable: Showing this message to a Free user as a hint that they can subscribe on the web to avoid paying through Apple.

RevenueCat handles the IAP side correctly — it abstracts StoreKit and Google Play Billing and provides a unified entitlement layer. However, RevenueCat only knows about subscriptions made through it. Web-origin Stripe subscriptions must be synced to RevenueCat (or to the backend entitlement API) so the app does not show a purchase UI to users who are already paid.

5.6 Entitlements Across Web And Mobile

Entitlement Impact

High.

Once Mobile is introduced, the product catalog becomes asymmetric:

• Web sells Gold, Diamond, packs
• Mobile platforms sell Gold-only subscriptions and no packs

Entitlement Adjustments

• Define entitlement precedence for cross-platform users.
• Allow web-bought Diamond to remain valid on iOS or Android.
• Decide whether a mobile Gold user can top up only on web, or not at all from Mobile.
• Ensure backend membership APIs report the correct effective tier regardless of purchase origin.

Diamond User Experience On Mobile

This scenario requires explicit design because the mobile app does not sell Diamond and a new user has no way to discover what Diamond even is from inside the app. Yet a significant portion of paying web users will be Diamond members who also log into the mobile app.

What a Diamond user should see on mobile:

• Their account tier is correctly identified as Diamond by the backend membership API, regardless of purchase origin.
• Any credits, daily bonuses, or feature gates that depend on the Diamond tier are applied at the Diamond level.
• The upgrade/subscription screen should not show an empty or broken state. Since Diamond is not sold on mobile, the screen should either hide the upgrade prompt entirely for active Diamond users, or display a read-only status card stating "You are a Diamond member. Manage your subscription on the web."
• No upsell pressure toward Gold should be shown to a Diamond user, as that would imply a downgrade.

What must not happen:

• A Diamond user must not appear as Free or Gold because the mobile entitlement layer failed to recognize the web-origin Diamond subscription.
• A Diamond user must not be presented with a Gold purchase flow implying their existing plan is invalid.
• The app must not silently cap Diamond credit grants at Gold levels simply because the IAP catalog only defines Gold SKUs.

Backend requirement:

The membership API (app/api/v1/membership/route.ts) must return the correct tier for the authenticated user based on the server-side database record, regardless of which platform issued the subscription. The mobile app must treat this API response as the authoritative source of truth — not derive tier from the local IAP receipt alone.

Entitlement Risk

Without a unified entitlement layer, users can become Gold on one platform and appear Free or partially entitled on another.

5.7 Notifications, CRM, And Analytics

Analytics Impact

Medium to high.

The source explicitly asks for stronger notification handling and mentions reminders for daily credit collection.

Analytics Adjustments

• Add membership-upgrade announcement messaging.
• Add mobile push strategy for daily credit reminders if that remains part of the product direction.
• Track trial start, trial conversion, weekly-plan conversion, yearly-plan conversion, refund, and chargeback metrics.
• Update internal dashboards or event naming if those metrics are already in use elsewhere.

Analytics Risk

The business will not be able to evaluate whether the new pricing actually works if analytics continue to reflect the old product model.

5.8 Legal, Support, And Documentation

Legal And Support Impact

High.

This change affects customer expectations, billing semantics, and refund questions.

Legal And Support Adjustments

• Update pricing documentation.
• Update support FAQ.
• Review terms and refund language.
• Add clear yearly-plan language for instant-credit delivery.
• Add platform-specific wording for Mobile where necessary.

Legal And Support Risk

If the product grants 100,000 or 1,000,000 credits instantly but the legal and support copy is vague, support load and refund disputes will increase.

6. Necessary Adjustments

6.1 Product And Business Decisions

• Finalize whether weekly exists on web or only on iOS or Android.
• Finalize annual refund and credit-clawback policy.
• Finalize daily reward values after the pricing change.
• Finalize whether Mobile should honor Diamond purchased on web.
• Finalize the exact recommendation logic on web pricing surfaces.

6.2 Web Runtime Adjustments

• Update pricing constants.
• Update included-credit values.
• Update grant timing logic for yearly plans.
• Update comparison logic and plan labels.
• Recalculate all price-per-credit copy.

6.3 Mobile Runtime Adjustments

• Implement real Mobile billing integration.
• Add trial support.
• Add weekly Gold SKU handling.
• Add restore-purchase support.
• Add unified backend entitlement sync.

6.4 UX And Content Adjustments

• Update membership page positioning.
• Update FAQ and support language.
• Update marketing copy for yearly plans.
• Add clear one-time-grant warnings.
• Update mobile planning docs and rollout notes.

6.5 Operational Adjustments

• Add refund handling policy and process.
• Add support playbooks for annual-plan disputes.
• Add analytics events for new product types.
• Add launch monitoring for subscription and credit anomalies.

7. Suggested Work Plan

Phase 0: Decision Lock

• Resolve all open product questions in Section 10.
• Freeze the final product matrix before coding starts.
• Define refund and credit-recovery rules.

Phase 1: Web Pricing And Grant Refactor

• Refactor pricing and grant configuration into one reliable source of truth.
• Implement yearly upfront-credit logic.
• Update all web membership and credit-pack copy.
• Validate upgrade, downgrade, cancellation, and renewal behavior.

Phase 2: Mobile Commerce Foundation

• Implement RevenueCat or an equivalent IAP layer to unify Apple App Store and Google Play Billing.
• Add Mobile Gold weekly, monthly, yearly products.
• Add 3-day trial support.
• Add restore purchases and lifecycle handling.

Phase 3: Cross-Platform Entitlements

• Unify subscription state from web and Mobile.
• Test sign-in across platforms.
• Confirm Diamond recognition on iOS or Android.

Phase 4: Docs, Support, And Monitoring

• Update all pricing and billing docs.
• Update support responses and FAQ.
• Add launch dashboards and anomaly alerts.

8. Potential Challenges And Solutions

Challenge	Why It Matters	Recommended Solution
Upfront annual credits create refund abuse risk	Users may spend a very large balance before refund resolution	Define clawback rules before launch and support negative-balance handling if necessary
Web and Mobile catalogs differ	Product confusion and entitlement drift become likely	Build a platform-aware product catalog and unified entitlement service
Weekly Gold adds a new billing cadence	Current runtime assumes monthly or yearly logic	Treat weekly as its own plan type, not as a monthly variant
Trial support does not exist yet	Trial bugs can cause support and billing issues	Implement explicit trial-state handling and sandbox testing before release
Current copy is scattered	Partial updates will leave inconsistent messaging live	Run a full pricing-content sweep before launch
Existing users may be on old yearly plans	Migration rules can become messy	Decide whether legacy subscribers are grandfathered or migrated
Annual value becomes extremely aggressive	Margin and abuse profile change materially	Monitor conversion, refund, chargeback, and consumption after launch
Mobile credit packs are removed	Users may still expect top-up on mobile	Make the product strategy explicit in app copy and support docs

9. Suggested Todo Checklist

• Lock the final commercial matrix for web and Mobile.
• Confirm whether web weekly plans are in scope.
• Confirm annual refund and credit-clawback policy.
• Refactor pricing and grant configuration to a single source of truth.
• Implement yearly upfront-credit logic.
• Re-test Stripe subscription lifecycle behavior with the new grants.
• Update all web membership, pack, FAQ, and billing copy.
• Implement Mobile IAP infrastructure.
• Implement Mobile Gold weekly plan and 3-day trial.
• Implement restore purchases and cross-platform entitlement sync.
• Add analytics for weekly, yearly, trial, refund, and platform source.
• Prepare support and monitoring for launch week.

10. Questions To Ask Before Implementation

1. Is the weekly plan mobile-only, or should web also sell weekly Gold and weekly Diamond?
2. When an annual plan is canceled, refunded, or charged back, should any unused upfront credits be clawed back?
3. If clawback is required, what happens when the user has already spent part or all of those upfront credits?
4. Are the current daily Card of the Day credits staying the same, or are they also changing?
5. Should Mobile recognize Diamond if the user purchased Diamond on web, even though Mobile will not sell Diamond?
6. Should Mobile users have any path to buy extra credits outside subscriptions, or is top-up intentionally web-only?
7. Should annual upfront credits be granted only on first purchase, or also on every annual renewal?
8. What is the migration policy for existing yearly subscribers on the old prices?
9. Should the web pricing page always default to Gold yearly, or only for logged-out and Free users?
10. Should Diamond yearly be marketed as “75% off,” “best value,” or with a different framing?
11. Is the Mobile 3-day trial only for Gold weekly, or should it also apply to Mobile Gold monthly?
12. Which system will own Mobile subscription lifecycle events: RevenueCat, direct App Store and Google Play handling, or another service?
13. Do affiliate, referral, or commission systems need to react differently to Mobile purchases?
14. Do legal and support teams want a separate policy section specifically for instant annual credits?

11. Final Assessment

While the proposed pricing adjustment represents a major shift, Web implementation remains viable provided the engineering strategy frames it as a holistic product-model refactor rather than a superficial price tag update.

The web portion is primarily:

• pricing refactor
• grant-logic refactor
• UX and copy updates
• policy clarification

The Mobile portion is materially larger because the underlying billing infrastructure is not live yet. Supporting Mobile v1 (iOS & Android) with weekly Gold, trialing, no packs, and no Diamond requires a real mobile billing implementation and a unified entitlement strategy.

Recommended rollout posture:

1. Lock business rules first.
2. Refactor web pricing and credit-grant logic second.
3. Build Mobile billing as a dedicated track, not as a minor extension of web Stripe flows.
4. Launch only after refund handling, entitlement sync, and support messaging are all defined.