[PM-29598] Create Subscription Upgrade Endpoint #6787

cyprain-okeke · 2025-12-31T18:35:35Z

🎟️ Tracking

https://bitwarden.atlassian.net/browse/PM-29598

📔 Objective

Objective: Create a backend endpoint to process the upgrade from a Premium subscription to a new Organization plan, ensuring the existing subscription is modified rather than creating a new one.

Endpoint: POST account/billing/vnext/upgrade
Command: UpgradePremiumToOrganizationCommand
Implementation Details:
1. The command will receive the user's ID and the details of the target organization plan.
2. It will first validate that the user has an active, valid Premium subscription.
3. Using the Stripe API, it will fetch the user's current subscription.
4. It will then add new subscription items (the same currently added for creating the new organization subscription) and marking premium subscription items for delete
5. A trial period will be applied to the updated subscription by setting the trial_end property date
6. premium_upgrade_metadata will be added to the Stripe subscription object. This metadata should store the ID of the original Premium plan to facilitate a potential reversion.

Given a user has an active Premium subscription

When they submit a request to upgrade to an organization

Then the system updates their Stripe subscription, applies a trial, and adds reversion metadata.

📸 Screenshots

⏰ Reminders before review

Contributor guidelines followed
All formatters and local linters executed and passed
Written new unit and / or integration tests where applicable
Protected functional changes with optionality (feature flags)
Used internationalization (i18n) for all UI strings
CI builds passed
Communicated to DevOps any deployment requirements
Updated any necessary documentation (Confluence, contributing docs) or informed the documentation team

🦮 Reviewer guidelines

👍 (:+1:) or similar for great changes
📝 (:memo:) or ℹ️ (:information_source:) for notes or general info
❓ (:question:) for questions
🤔 (:thinking:) or 💭 (:thought_balloon:) for more open inquiry that's not quite a confirmed issue and could potentially benefit from discussion
🎨 (:art:) for suggestions / improvements
❌ (:x:) or ⚠️ (:warning:) for more significant problems or concerns needing attention
🌱 (:seedling:) or ♻️ (:recycle:) for future improvements or indications of technical debt
⛏ (:pick:) for minor or nitpick changes

…-endpoint

github-actions · 2025-12-31T18:48:05Z

Checkmarx One – Scan Summary & Details – 52f19c2f-ee42-4eba-b50f-db9f9785cacb

New Issues (2)

Checkmarx found the following issues in this Pull Request

#	Severity	Issue	Source File / Package	Checkmarx Insight
1		CSRF	/src/Api/Vault/Controllers/CiphersController.cs: 1527	details Method at line 1527 of /src/Api/Vault/Controllers/CiphersController.cs gets a parameter from a user request from id. This parameter value flows ... Attack Vector
2		CSRF	/src/Api/Vault/Controllers/CiphersController.cs: 1403	details Method at line 1403 of /src/Api/Vault/Controllers/CiphersController.cs gets a parameter from a user request from id. This parameter value flows ... Attack Vector

Fixed Issues (1)

Great job! The following issues were fixed in this Pull Request

Severity	Issue	Source File / Package
	~~CSRF~~	/src/Api/Vault/Controllers/CiphersController.cs: 293

…-endpoint

amorask-bitwarden · 2025-12-31T20:14:27Z

src/Api/Billing/Models/Requests/Premium/UpgradePremiumToOrganizationRequest.cs

+public class UpgradePremiumToOrganizationRequest
+{
+    [Required]
+    public required PlanType PlanType { get; set; }


❌ Our newer client-side code is not operating off of PlanType. Let's send Tier and Cadence like we do here: https://github.com/bitwarden/server/blob/main/src/Api/Billing/Models/Requests/Organizations/OrganizationSubscriptionPurchaseRequest.cs

amorask-bitwarden · 2025-12-31T20:22:49Z

src/Api/Billing/Models/Requests/Premium/UpgradePremiumToOrganizationRequest.cs

+    public required PlanType PlanType { get; set; }
+
+    [Range(1, int.MaxValue)]
+    public int Seats { get; set; }


❌ When upgrading from Premium, we're only going to have 1 seat. The designs do not support seat increases at the moment.

amorask-bitwarden · 2025-12-31T20:23:01Z

src/Api/Billing/Models/Requests/Premium/UpgradePremiumToOrganizationRequest.cs

+    [Range(1, int.MaxValue)]
+    public int Seats { get; set; }
+
+    public bool PremiumAccess { get; set; } = false;


❓ What current plan still has premium access?

amorask-bitwarden · 2025-12-31T20:23:25Z

src/Api/Billing/Models/Requests/Premium/UpgradePremiumToOrganizationRequest.cs

+    public bool PremiumAccess { get; set; } = false;
+
+    [Range(0, 99)]
+    public int Storage { get; set; } = 0;


❌ This can be removed as the designs also don't support storage selection in the upgrade modal.

amorask-bitwarden · 2025-12-31T20:23:40Z

src/Api/Billing/Models/Requests/Premium/UpgradePremiumToOrganizationRequest.cs

+    [Range(0, 99)]
+    public int Storage { get; set; } = 0;
+
+    public DateTime? TrialEndDate { get; set; }


❓ Why are we passing this in?

amorask-bitwarden · 2025-12-31T20:24:31Z

src/Core/Billing/Premium/Commands/UpgradePremiumToOrganizationCommand.cs

+        if (!user.Premium)
+        {
+            return new BadRequest("User does not have an active Premium subscription.");
+        }
+
+        if (string.IsNullOrEmpty(user.GatewaySubscriptionId))
+        {
+            return new BadRequest("User does not have a Stripe subscription.");
+        }


⛏️ if (user is { Premium: true, GatewaySubscriptionId: not null and not "" })

amorask-bitwarden · 2025-12-31T20:25:38Z

src/Core/Billing/Premium/Commands/UpgradePremiumToOrganizationCommand.cs

+        // Fetch the current Premium subscription from Stripe
+        var currentSubscription = await subscriberService.GetSubscriptionOrThrow(user, new SubscriptionGetOptions
+        {
+            Expand = ["items.data.price"]


❌ This is not expandable: https://docs.stripe.com/api/subscriptions/object?api-version=2025-08-27.basil&lang=cli#subscription_object-items-data-price

amorask-bitwarden · 2025-12-31T20:26:11Z

src/Core/Billing/Premium/Commands/UpgradePremiumToOrganizationCommand.cs

+        }
+
+        // Fetch the current Premium subscription from Stripe
+        var currentSubscription = await subscriberService.GetSubscriptionOrThrow(user, new SubscriptionGetOptions


⛏️ If this is the only use of the SubscriberService you can use StripeAdapter since that will automatically throw an exception if the subscription does not exist.

amorask-bitwarden · 2025-12-31T20:28:08Z

src/Core/Billing/Premium/Commands/UpgradePremiumToOrganizationCommand.cs

+        user.PremiumExpirationDate = trialEndDate ?? currentSubscription.GetCurrentPeriodEnd();
+        user.RevisionDate = DateTime.UtcNow;
+        await userService.SaveUserAsync(user);


❌ This results in a User record being attached to an Organization subscription, which would not be renderable or usable on the client. The idea is to create an Organization record and attach the modified subscription to that Organization while removing the subscription from the User.

…-endpoint

codecov · 2026-01-01T11:44:56Z

Codecov Report

❌ Patch coverage is 89.44724% with 21 lines in your changes missing coverage. Please review.
✅ Project coverage is 55.28%. Comparing base (b1cf59b) to head (d2f197a).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
...sts/Premium/UpgradePremiumToOrganizationRequest.cs	0.00%	16 Missing ⚠️
...Controllers/VNext/AccountBillingVNextController.cs	28.57%	5 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #6787      +/-   ##
==========================================
+ Coverage   55.19%   55.28%   +0.08%     
==========================================
  Files        1937     1939       +2     
  Lines       86026    86224     +198     
  Branches     7702     7705       +3     
==========================================
+ Hits        47481    47665     +184     
- Misses      36754    36767      +13     
- Partials     1791     1792       +1

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

sbrown-livefront

A few questions and changes

src/Api/Billing/Controllers/VNext/AccountBillingVNextController.cs

src/Core/Billing/Premium/Commands/UpgradePremiumToOrganizationCommand.cs

sbrown-livefront · 2026-01-05T14:51:42Z

src/Api/Billing/Models/Requests/Premium/UpgradePremiumToOrganizationRequest.cs

+
+namespace Bit.Api.Billing.Models.Requests.Premium;
+
+public class UpgradePremiumToOrganizationRequest


❓ Would we not include seats in the request(even though we assume it will be 1 for now)?

@sbrown-livefront I recommended not doing so - since the business requirements are for a 1-seat upgrade, I feel like that would primarily just give the client extra, unnecessary responsibility.

sbrown-livefront · 2026-01-05T14:56:26Z

src/Core/Billing/Premium/Commands/UpgradePremiumToOrganizationCommand.cs

+        var subscriptionItemOptions = new List<SubscriptionItemOptions>();
+
+        // Mark existing Premium subscription items for deletion
+        foreach (var item in currentSubscription.Items.Data)


❌ We may need to be more precise in identifying subscription items by narrowing our search specifically to the items we want to delete related to premium (plan id, etc.) I'm not sure if there are some items we'd want to retain.

sbrown-livefront · 2026-01-05T15:09:01Z

src/Core/Billing/Premium/Commands/UpgradePremiumToOrganizationCommand.cs

+        };
+
+        // Apply trial period if specified
+        if (trialEndDate.HasValue)


❓ Shouldn't this date be calculated using the TrialPeriodDays property of the target plan?

src/Core/Billing/Premium/Commands/UpgradePremiumToOrganizationCommand.cs

sbrown-livefront · 2026-01-05T15:23:06Z

test/Core.Test/Billing/Premium/Commands/UpgradePremiumToOrganizationCommandTests.cs

+
+        // Assert
+        Assert.True(result.IsT1);
+        var badRequest = result.AsT1;


📝 Alex made some great helper methods that are more descriptive here. This is out of scope for this PR, but I wonder if we could clean up command logic a bit with it.

src/Api/Billing/Models/Requests/Premium/UpgradePremiumToOrganizationRequest.cs

src/Api/Billing/Controllers/VNext/AccountBillingVNextController.cs

src/Core/Billing/Premium/Commands/UpgradePremiumToOrganizationCommand.cs

…-endpoint

src/Core/Billing/Premium/Commands/UpgradePremiumToOrganizationCommand.cs

…-endpoint

src/Core/Billing/Premium/Commands/UpgradePremiumToOrganizationCommand.cs

amorask-bitwarden · 2026-01-07T15:02:15Z

src/Core/Billing/Premium/Commands/UpgradePremiumToOrganizationCommand.cs

+            UseCustomPermissions = targetPlan.HasCustomPermissions,
+            UseScim = targetPlan.HasScim,
+            Plan = targetPlan.Name,
+            Gateway = null,


Last thing: This needs to be Stripe in order for the Admin Portal links to the Customer and Subscription to work.

amorask-bitwarden · 2026-01-07T15:04:16Z

src/Core/Billing/Premium/Commands/UpgradePremiumToOrganizationCommand.cs

+        var currentSubscription = await stripeAdapter.GetSubscriptionAsync(user.GatewaySubscriptionId);
+
+        // Get the premium plan to identify which price IDs to delete
+        var premiumPlan = await pricingClient.GetAvailablePremiumPlan();


❌ I missed this, but what happens if the User is not on the currently available premium plan?

This is an excellent catch

amorask-bitwarden · 2026-01-07T20:00:03Z

src/Core/Billing/Premium/Commands/UpgradePremiumToOrganizationCommand.cs

+        var premiumPlans = await pricingClient.ListPremiumPlans();
+        var availablePremiumPlan = premiumPlans.FirstOrDefault(p => p.Available);
+
+        if (availablePremiumPlan == null)


I don't think this is necessary. Really what we're trying to do here is find the specific Premium plan the user is on. We do that by looking for the subscription item for Password Manager that matches one of the premium plans. Then, when we have that subscription item, we can delete it because it will be transitioning to an organization. Let me know if this makes sense. I think you did something similar on your recent storage command you can reference.

amorask-bitwarden · 2026-01-07T20:00:38Z

src/Core/Billing/Premium/Commands/UpgradePremiumToOrganizationCommand.cs

+            Metadata = new Dictionary<string, string>
+            {
+                [StripeConstants.MetadataKeys.OrganizationId] = organizationId.ToString(),
+                [StripeConstants.MetadataKeys.PreviousPremiumPriceId] = availablePremiumPlan.Seat.StripePriceId,


This is what I mean: The user might not actually have been on this plan. We need the plan the user was on from the premium plans that come back from the Pricing service.

…-endpoint

src/Core/Billing/Premium/Commands/UpgradePremiumToOrganizationCommand.cs

…-endpoint

sbrown-livefront

✅

cyprain-okeke added 2 commits December 31, 2025 13:24

Add the ticket implementation

35d8812

Add the unit test

8276423

cyprain-okeke requested a review from a team as a code owner December 31, 2025 18:35

cyprain-okeke requested a review from sbrown-livefront December 31, 2025 18:35

Merge branch 'main' into billing/pm-29598/create-subscription-upgrade…

ffdef93

…-endpoint

cyprain-okeke and others added 2 commits December 31, 2025 20:00

Fix the lint and test issues

dc93149

Merge branch 'main' into billing/pm-29598/create-subscription-upgrade…

bca4274

…-endpoint

amorask-bitwarden requested changes Dec 31, 2025

View reviewed changes

Merge branch 'main' into billing/pm-29598/create-subscription-upgrade…

64fa791

…-endpoint

resolve pr comments

2c6c2fe

cyprain-okeke requested a review from amorask-bitwarden January 1, 2026 13:38

sbrown-livefront requested changes Jan 5, 2026

View reviewed changes

amorask-bitwarden requested changes Jan 5, 2026

View reviewed changes

cyprain-okeke and others added 4 commits January 6, 2026 11:36

Merge branch 'main' into billing/pm-29598/create-subscription-upgrade…

383530d

…-endpoint

Fix the error on the test file

79a8be0

Review suggestion and fixes

d8ebcc9

Merge branch 'main' into billing/pm-29598/create-subscription-upgrade…

00f4ad6

…-endpoint

cyprain-okeke requested review from amorask-bitwarden and sbrown-livefront January 6, 2026 12:54

amorask-bitwarden requested changes Jan 6, 2026

View reviewed changes

cyprain-okeke and others added 3 commits January 7, 2026 09:39

Merge branch 'main' into billing/pm-29598/create-subscription-upgrade…

025e3e0

…-endpoint

resolve the api access comments

9ba9ef1

Merge branch 'main' into billing/pm-29598/create-subscription-upgrade…

0687f31

…-endpoint

cyprain-okeke requested a review from amorask-bitwarden January 7, 2026 12:45

amorask-bitwarden requested changes Jan 7, 2026

View reviewed changes

src/Core/Billing/Premium/Commands/UpgradePremiumToOrganizationCommand.cs Show resolved Hide resolved

src/Core/Billing/Premium/Commands/UpgradePremiumToOrganizationCommand.cs Outdated Show resolved Hide resolved

Gte the key from the client

a64e0a0

cyprain-okeke requested a review from amorask-bitwarden January 7, 2026 14:58

amorask-bitwarden requested changes Jan 7, 2026

View reviewed changes

cyprain-okeke added 2 commits January 7, 2026 16:12

Add the gateway type as stripe

9b54c2e

Address the legacy plans issues

244ca57

cyprain-okeke requested a review from amorask-bitwarden January 7, 2026 15:29

amorask-bitwarden requested changes Jan 7, 2026

View reviewed changes

Resolve the misunderstanding

cbdec08

cyprain-okeke requested a review from amorask-bitwarden January 7, 2026 20:19

amorask-bitwarden previously approved these changes Jan 8, 2026

View reviewed changes

Merge branch 'main' into billing/pm-29598/create-subscription-upgrade…

823db8c

…-endpoint

sbrown-livefront reviewed Jan 8, 2026

View reviewed changes

src/Core/Billing/Premium/Commands/UpgradePremiumToOrganizationCommand.cs Show resolved Hide resolved

Add additional storage that we will need if they revert

5299129

cyprain-okeke dismissed amorask-bitwarden’s stale review via 5299129 January 9, 2026 08:53

Merge branch 'main' into billing/pm-29598/create-subscription-upgrade…

f728816

…-endpoint

cyprain-okeke requested review from amorask-bitwarden and sbrown-livefront January 9, 2026 08:54

cyprain-okeke and others added 2 commits January 9, 2026 16:16

Add the previous premium UserId

9b3a68f

Merge branch 'main' into billing/pm-29598/create-subscription-upgrade…

d2f197a

…-endpoint

sbrown-livefront approved these changes Jan 9, 2026

View reviewed changes

cyprain-okeke merged commit e705fe3 into main Jan 9, 2026
49 checks passed

cyprain-okeke deleted the billing/pm-29598/create-subscription-upgrade-endpoint branch January 9, 2026 15:34


		namespace Bit.Api.Billing.Models.Requests.Premium;

		public class UpgradePremiumToOrganizationRequest

[PM-29598] Create Subscription Upgrade Endpoint #6787

[PM-29598] Create Subscription Upgrade Endpoint #6787

Conversation

cyprain-okeke commented Dec 31, 2025

🎟️ Tracking

📔 Objective

📸 Screenshots

⏰ Reminders before review

🦮 Reviewer guidelines

Uh oh!

github-actions bot commented Dec 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

codecov bot commented Jan 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

sbrown-livefront left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sbrown-livefront left a comment

Choose a reason for hiding this comment

github-actions bot commented Dec 31, 2025 •

edited

Loading

codecov bot commented Jan 1, 2026 •

edited

Loading