feat(customer-portal): let customers update subscription units

[strandhvilliam]

The customers who has made a subscription with Unit Based pricing needs a way to manage their bought units. This PR adds customer portal increment / decrement controls for unit based pricing. Gated behind feature flag.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
orbit	Building	Preview	Aug 31, 2026 12:18pm
polar-test	Ready	Preview	Aug 31, 2026 12:18pm

[github-actions]

OpenAPI Changes

Schemas

• 🔼 CustomerSubscriptionChangePreviewUnits (added)
• 🔼 CustomerSubscriptionUpdateUnits (added)
• 🔼 UpdateSubscriptionUnitsNotAllowed (added)

[cubic-dev-ai]

3 issues found across 8 files

Confidence score: 3/5

• server/polar/models/organization.py does not migrate legacy feature_settings rows for the new organization setting, leaving existing organizations dependent on a prohibited runtime fallback; add a backfill migration.
• clients/apps/web/src/components/CustomerPortal/CustomerPortalSubscription.tsx still renders quantity controls when unit pricing is disabled for an organization with a unit subscription, but submissions are rejected by the update service; hide or disable the controls in this state.
• clients/apps/web/src/components/CustomerPortal/CustomerUnitQuantityManager.tsx reports that a subscription changed immediately when prorationBehavior is next_period, although the API only schedules the change; use pending-change wording in the toast.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="server/polar/models/organization.py">

<violation number="1" location="server/polar/models/organization.py:724">
P2: Custom agent: **Enforce ADR checks**

This new organization feature setting has no migration to backfill legacy `feature_settings` rows, so existing organizations rely on the prohibited runtime fallback. Add a migration that persists `unit_based_pricing_enabled: false` for rows where the key is absent.</violation>
</file>

<file name="clients/apps/web/src/components/CustomerPortal/CustomerPortalSubscription.tsx">

<violation number="1" location="clients/apps/web/src/components/CustomerPortal/CustomerPortalSubscription.tsx:357">
P2: When unit-based pricing is disabled for an organization that still has a unit subscription, this block still renders the quantity controls. The update service rejects submissions with `UpdateSubscriptionUnitsNotAllowed`, so the UI is unusable instead of gated. Check the organization’s unit-pricing feature flag before rendering, exposing it to the portal schema if necessary.</violation>
</file>

<file name="clients/apps/web/src/components/CustomerPortal/CustomerUnitQuantityManager.tsx">

<violation number="1" location="clients/apps/web/src/components/CustomerPortal/CustomerUnitQuantityManager.tsx:100">
P2: When `prorationBehavior` is `next_period`, the API schedules the unit change and leaves the current subscription unchanged, but this toast says the subscription has already changed. Use the pending-change wording for `next_period`, matching the seat quantity manager.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: Custom agent: Enforce ADR checks

This new organization feature setting has no migration to backfill legacy feature_settings rows, so existing organizations rely on the prohibited runtime fallback. Add a migration that persists unit_based_pricing_enabled: false for rows where the key is absent.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At server/polar/models/organization.py, line 724:

<comment>This new organization feature setting has no migration to backfill legacy `feature_settings` rows, so existing organizations rely on the prohibited runtime fallback. Add a migration that persists `unit_based_pricing_enabled: false` for rows where the key is absent.</comment>

<file context>
@@ -719,6 +719,10 @@ def is_dispute_auto_accept_enabled(self) -> bool:
 
+    @property
+    def is_unit_based_pricing_enabled(self) -> bool:
+        return self.feature_settings.get("unit_based_pricing_enabled", False)
+
     @property
</file context>

[cubic-dev-ai]

P2: When unit-based pricing is disabled for an organization that still has a unit subscription, this block still renders the quantity controls. The update service rejects submissions with UpdateSubscriptionUnitsNotAllowed, so the UI is unusable instead of gated. Check the organization’s unit-pricing feature flag before rendering, exposing it to the portal schema if necessary.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At clients/apps/web/src/components/CustomerPortal/CustomerPortalSubscription.tsx, line 357:

<comment>When unit-based pricing is disabled for an organization that still has a unit subscription, this block still renders the quantity controls. The update service rejects submissions with `UpdateSubscriptionUnitsNotAllowed`, so the UI is unusable instead of gated. Check the organization’s unit-pricing feature flag before rendering, exposing it to the portal schema if necessary.</comment>

<file context>
@@ -342,6 +354,21 @@ const CustomerPortalSubscription = ({
         />
       )}
 
+      {unitPrice && canManageBilling && !isCancelled && (
+        <div className="flex flex-col gap-y-2">
+          <h3 className="text-lg">Units</h3>
</file context>

[cubic-dev-ai]

P2: When prorationBehavior is next_period, the API schedules the unit change and leaves the current subscription unchanged, but this toast says the subscription has already changed. Use the pending-change wording for next_period, matching the seat quantity manager.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At clients/apps/web/src/components/CustomerPortal/CustomerUnitQuantityManager.tsx, line 100:

<comment>When `prorationBehavior` is `next_period`, the API schedules the unit change and leaves the current subscription unchanged, but this toast says the subscription has already changed. Use the pending-change wording for `next_period`, matching the seat quantity manager.</comment>

<file context>
@@ -0,0 +1,231 @@
+          })
+        } else {
+          const noun = data.units === 1 ? unitLabel : unitLabelPlural
+          const description = `Subscription now has ${data.units} ${noun}.`
+          toast({
+            title: 'Units updated',
</file context>

Suggested change

	const description = `Subscription now has ${data.units} ${noun}.`
	const description =
	prorationBehavior === 'next_period'
	? `Subscription will have ${data.units} ${noun} starting on your next billing cycle.`
	: `Subscription now has ${data.units} ${noun}.`