WF-112: Subscription Downgrade

Workflow ID: WF-112 Category: Billing & Subscription Priority: P1 Last Updated: January 11, 2026

---

Overview

This workflow handles subscription plan downgrades, including seat reduction, feature restriction, and prorated billing calculations.

---

Trigger Events

• User initiates downgrade from Dashboard
• Admin requests team downgrade
• API call to subscription downgrade endpoint

---

Sequence Diagram

---

Process Steps

1. Initiation

User Action: Navigate to Subscription Settings > Change Plan

System Response:

• Display current plan details
• Show available downgrade options
• Display impact summary (features to be restricted)

2. Validation

Pre-Downgrade Checks:

Check	Condition	Action if Failed
Seat count	Active seats <= new plan limit	Prompt to remove seats
Active features	Features in use vs. new plan	Show feature impact
Billing cycle	Position in billing cycle	Calculate proration
Pending charges	Any outstanding balances	Require payment

3. Seat Reduction (If Required)

If current seat count exceeds new plan limit:

1. Display list of assigned seats
2. Admin selects seats to remove
3. System revokes selected licenses
4. Affected users notified via email
5. Workstation access terminated

4. Feature Restriction

Features not included in new plan:

Feature	Restriction Action
Advanced analytics	Hide from dashboard
Custom integrations	Disable API access
Priority support	Downgrade to standard
Additional storage	Apply new quota

Grace Period: 7 days for data export before storage reduction

5. Prorated Billing

Calculation Method:

Days Remaining = End Date - Downgrade Date
Daily Rate (Old) = Old Plan Price / Days in Period
Daily Rate (New) = New Plan Price / Days in Period
Credit = Days Remaining * (Daily Rate Old - Daily Rate New)

Credit Application:

• Applied to next invoice
• Visible in billing history
• Never expires

6. Confirmation

Actions:

• Update subscription in Stripe
• Update license entitlements
• Send confirmation email
• Update dashboard display

---

Email Notifications

To: Subscription Owner

Subject: Your CODITECT subscription has been changed

Content:

• Previous plan details
• New plan details
• Effective date
• Prorated credit amount
• Features no longer available
• Next billing date and amount

To: Affected Team Members (If Seats Removed)

Subject: Your CODITECT access has been modified

Content:

• Access revocation notice
• Data export instructions
• 7-day grace period details

---

API Endpoints

Endpoint	Method	Purpose
/api/v1/subscriptions/plans	GET	List available plans
/api/v1/subscriptions/downgrade	POST	Initiate downgrade
/api/v1/subscriptions/preview-downgrade	POST	Calculate impact
/api/v1/subscriptions/seats	DELETE	Remove seats

Request: Preview Downgrade

POST /api/v1/subscriptions/preview-downgrade
{
  "new_plan_id": "plan_pro_monthly",
  "effective_date": "immediate"
}

Response: Preview

{
  "current_plan": "enterprise_monthly",
  "new_plan": "pro_monthly",
  "seats_to_remove": 3,
  "features_restricted": ["analytics", "integrations"],
  "prorated_credit": 45.67,
  "next_charge": 99.00,
  "effective_date": "2026-01-11"
}

---

Error Handling

Error	Cause	Resolution
SEATS_EXCEED_LIMIT	Too many active seats	Remove seats first
PENDING_INVOICE	Outstanding balance	Pay invoice first
DOWNGRADE_COOLDOWN	Recent plan change	Wait 30 days
STRIPE_ERROR	Payment processor issue	Retry or contact support

---

Rollback Procedure

If downgrade fails mid-process:

1. Revert Stripe subscription status
2. Restore license entitlements
3. Log failure reason
4. Notify user of failure
5. Retry with admin intervention

---

Audit Trail

All downgrade events logged:

Field	Value
action	subscription.downgrade
user_id	Initiating user
old_plan	Previous plan ID
new_plan	New plan ID
credit_applied	Proration amount
timestamp	ISO 8601 datetime

---

Related Workflows

• WF-001: Subscription Signup
• WF-002: Subscription Upgrade
• WF-118: Billing Dispute Resolution

---

Last Updated: January 11, 2026