US-205: Subscription Plan Upgrade¶

1. Story Title¶

Upgrade tenant subscription plan with proration

2. Context / Background¶

Allows monetization scaling; tenants need ability to move to higher tier features.

3. User Persona¶

Primary: Priya – Tenant Admin

4. Problem Statement¶

Static initial plan prevents access to premium features; manual upgrades cause billing inaccuracies.

5. Desired Outcome¶

Admin selects new plan; system calculates proration, updates subscription with gateway, and records change event.

6. Business Value¶

Enables upsell revenue capture while maintaining billing integrity.

7. Scope (In / Out)¶

In: plan selection UI, proration calculation, gateway API call, subscription status update, audit event. Out: Downgrade with credit (phase 2), multi-currency billing, usage-based metering.

8. Acceptance Criteria (BDD)¶

Scenario: Successful upgrade with proration
  Given tenant on Basic plan mid-cycle
  When admin selects Pro plan
  Then proration amount is calculated
  And gateway subscription updated
  And subscription status reflects Pro

Scenario: Upgrade blocked by invalid payment method
  Given stored payment method is invalid
  When upgrade attempted
  Then error displayed
  And no gateway change occurs

Scenario: Webhook reconciliation
  Given gateway sends subscription.updated webhook
  When processing occurs
  Then local subscription matches gateway status

Scenario: Duplicate upgrade prevented
  Given tenant already on Pro
  When selecting Pro again
  Then system shows already on plan message

9. UX Notes / References¶

Plan cards with feature summary, upgrade button, confirmation modal showing proration details.

10. Data / Domain Model Impact¶

Subscription entity extended: planId, currentPeriodStart, currentPeriodEnd, status, prorationApplied flag.

11. NFR Touchpoints¶

Performance: upgrade operation < 2s p95.
Observability: SubscriptionUpgradeRequested, SubscriptionUpgraded events.
Security: validate admin role only.

12. Dependencies¶

Billing Controller & Integration service; payment gateway; tenant service.

13. Risks & Mitigations¶

Risk	Impact	Probability	Mitigation
Incorrect proration math	Revenue leakage	Medium	Reference gateway calculator API
Webhook race conditions	Data inconsistency	Low	Idempotent processing + event ordering

14. Estimation Support¶

Plan catalog fetch
Proration calc module
Upgrade endpoint
Webhook handler

15. Analytics / Success Metrics¶

Upgrade conversion rate; time to upgrade; proration accuracy (delta vs gateway).

16. Rollout / Release Strategy¶

Internal test tenants then phased external rollout.

17. Definition of Ready Checklist¶

Plan catalog finalized
Proration formula validated

18. Definition of Done Checklist¶

All scenarios tested
Events observable
Docs updated (billing section)

19. Open Questions¶

Immediate invoice or deferred to cycle end?
Need audit of previous plan features deactivation?

Version: 1.0