fix(billing): release assignments for dropped licenses

Automatically unassign entity licenses when a plan transition removes their license pool, preserve ambiguous-transition safeguards, and warn affected entities in the attach review.

Author: charlietlamb

server/src/internal/billing/v2/actions/attach/compute/computeAttachPlan.ts

@@ -6,6 +6,7 @@ import {
 } from "@autumn/shared";
 import type { AutumnContext } from "@/honoUtils/HonoEnv";
 import { buildAutumnLineItems } from "@/internal/billing/v2/compute/computeAutumnUtils/buildAutumnLineItems";
+import { computeCustomerLicenseReleases } from "@/internal/billing/v2/compute/customerLicenseTransitions/computeCustomerLicenseReleases";
 import { computeCustomerLicenseTransitions } from "@/internal/billing/v2/compute/customerLicenseTransitions/computeCustomerLicenseTransitions";
 import { cusProductToExistingBalanceCarryOvers } from "@/internal/billing/v2/utils/handleCarryOvers/cusProductToExistingBalanceCarryOvers";
 import { cusProductToOneOffPrepaidCarryOvers } from "@/internal/billing/v2/utils/handleOneOffPrepaidCarryOvers/cusProductToOneOffPrepaidCarryOvers";
@@ -62,6 +63,14 @@ export const computeAttachPlan = ({
 		: [];
 	const customerLicenseTransitions =
 		planTiming === "immediate" ? computedCustomerLicenseTransitions : [];
+	const customerLicenseReleases =
+		planTiming === "immediate" && currentCustomerProduct
+			? computeCustomerLicenseReleases({
+					outgoingCustomerProduct: currentCustomerProduct,
+					incomingCustomerProduct: newCustomerProduct,
+					releasedAt: attachBillingContext.currentEpochMs,
+				})
+			: {};
 
 	const {
 		entitlements: carriedOverEntitlements,
@@ -133,6 +142,8 @@ export const computeAttachPlan = ({
 		customFreeTrial: trialContext?.customFreeTrial,
 		insertPlanLicenses: attachBillingContext.insertPlanLicenses,
 		customerLicenseTransitions,
+		releaseCustomerLicenseAssignments:
+			customerLicenseReleases.releaseCustomerLicenseAssignments,
 		lineItems,
 		insertCustomerEntitlements: [
 			...(carriedOverCustomerEntitlements ?? []),

server/src/internal/billing/v2/actions/attach/errors/handleLicenseErrors/handleDroppedLicenseErrors.ts

@@ -11,9 +11,7 @@ const licensePlanIdOf = (customerLicense: FullCustomerLicense) =>
 	customerLicense.planLicense?.product.id ??
 	customerLicense.license_internal_product_id;
 
-/** Blocks an immediate switch that would strand active assignments: a used
- * outgoing pool must have a successor (same license plan, or a 1:1 group
- * match) on the incoming plan. */
+/** Blocks ambiguous active assignment mappings; dropped pools release in compute. */
 export const handleDroppedLicenseErrors = ({
 	billingContext,
 }: {
@@ -28,20 +26,18 @@ export const handleDroppedLicenseErrors = ({
 	});
 
 	for (const { outgoingCustomerLicense, reason, group } of unmatched) {
+		if (reason === "dropped") continue;
 		const used = customerLicenseToUsage({
 			customerLicense: outgoingCustomerLicense,
 		});
 		if (used === 0) continue;
 
 		const licensePlanId = licensePlanIdOf(outgoingCustomerLicense);
-		const conflict =
-			reason === "ambiguous"
-				? `the licenses in group "${group}" are not a 1:1 match on the incoming plan`
-				: "the incoming plan drops the license";
 		throw new RecaseError({
 			message:
 				`License changes conflict with active license assignments: ` +
-				`${used} assigned for ${licensePlanId}, but ${conflict}. Release licenses first.`,
+				`${used} assigned for ${licensePlanId}, but the licenses in group "${group}" ` +
+				"are not a 1:1 match on the incoming plan. Release licenses first.",
 			code: ErrCode.InvalidRequest,
 			statusCode: 400,
 		});

server/src/internal/billing/v2/actions/sync/compute/computeSyncImmediatePhase.ts

@@ -1,7 +1,7 @@
 import {
 	type AutumnBillingPlan,
-	type CustomerLicenseUpdate,
 	CusProductStatus,
+	type CustomerLicenseUpdate,
 	type Entitlement,
 	type FullCusProduct,
 	type InsertPlanLicenseSpec,
@@ -10,6 +10,7 @@ import {
 } from "@autumn/shared";
 import type { AutumnContext } from "@/honoUtils/HonoEnv";
 import { computeCustomerLicenseQuantityChanges } from "@/internal/billing/v2/compute/computeCustomerLicenseQuantityChanges";
+import { computeCustomerLicenseReleases } from "@/internal/billing/v2/compute/customerLicenseTransitions/computeCustomerLicenseReleases";
 import { resolveSyncExistingUsagesConfig } from "@/internal/billing/v2/utils/handleCarryOvers/resolveSyncExistingUsagesConfig";
 import { initImmediateSyncCustomerProduct } from "./initImmediateSyncCustomerProduct";
 
@@ -24,6 +25,9 @@ export type ImmediatePhaseResult = {
 	customEntitlements: Entitlement[];
 	insertPlanLicenses: InsertPlanLicenseSpec[];
 	customerLicenseUpdates: CustomerLicenseUpdate[];
+	releaseCustomerLicenseAssignments?: NonNullable<
+		AutumnBillingPlan["releaseCustomerLicenseAssignments"]
+	>;
 };
 
 const expireCustomerProduct = ({
@@ -81,6 +85,7 @@ export const computeSyncImmediatePhase = ({
 	const customEntitlements: Entitlement[] = [];
 	const insertPlanLicenses: InsertPlanLicenseSpec[] = [];
 	const customerLicenseUpdates: CustomerLicenseUpdate[] = [];
+	const droppedCustomerLicenseLinkIds: string[] = [];
 
 	for (const productContext of immediatePhase.productContexts) {
 		const currentCustomerProduct = productContext.currentCustomerProduct;
@@ -121,6 +126,14 @@ export const computeSyncImmediatePhase = ({
 		insertPlanLicenses.push(...(productContext.insertPlanLicenses ?? []));
 
 		if (productContext.currentCustomerProduct) {
+			const release = computeCustomerLicenseReleases({
+				outgoingCustomerProduct: productContext.currentCustomerProduct,
+				incomingCustomerProduct: insertedCustomerProduct,
+				releasedAt: currentEpochMs,
+			}).releaseCustomerLicenseAssignments;
+			droppedCustomerLicenseLinkIds.push(
+				...(release?.customerLicenseLinkIds ?? []),
+			);
 			updateCustomerProducts.push(
 				expireCustomerProduct({
 					customerProduct: productContext.currentCustomerProduct,
@@ -137,5 +150,11 @@ export const computeSyncImmediatePhase = ({
 		customEntitlements,
 		insertPlanLicenses,
 		customerLicenseUpdates,
+		releaseCustomerLicenseAssignments: droppedCustomerLicenseLinkIds.length
+			? {
+					customerLicenseLinkIds: droppedCustomerLicenseLinkIds,
+					releasedAt: currentEpochMs,
+				}
+			: undefined,
 	};
 };

server/src/internal/billing/v2/actions/sync/compute/computeSyncPlan.ts

@@ -73,6 +73,8 @@ export const computeSyncPlan = ({
 			immediate.customerLicenseUpdates.length > 0
 				? immediate.customerLicenseUpdates
 				: undefined,
+		releaseCustomerLicenseAssignments:
+			immediate.releaseCustomerLicenseAssignments,
 		lockCustomerCurrency: syncContextToCurrencyLock({ syncContext }),
 		upsertSubscription,
 	};

server/src/internal/billing/v2/compute/customerLicenseTransitions/computeCustomerLicenseReleases.ts

@@ -0,0 +1,27 @@
+import type { AutumnBillingPlan, FullCusProduct } from "@autumn/shared";
+import { matchCustomerLicenseSuccessors } from "./matchCustomerLicenseSuccessors.js";
+
+export const computeCustomerLicenseReleases = ({
+	outgoingCustomerProduct,
+	incomingCustomerProduct,
+	releasedAt,
+}: {
+	outgoingCustomerProduct: FullCusProduct;
+	incomingCustomerProduct?: FullCusProduct;
+	releasedAt: number;
+}): Pick<AutumnBillingPlan, "releaseCustomerLicenseAssignments"> => {
+	const { unmatched } = matchCustomerLicenseSuccessors({
+		outgoingCustomerLicenses: outgoingCustomerProduct.customer_licenses ?? [],
+		incomingCustomerLicenses: incomingCustomerProduct?.customer_licenses ?? [],
+	});
+	const customerLicenseLinkIds = unmatched.flatMap(
+		({ outgoingCustomerLicense, reason }) =>
+			reason === "dropped" ? [outgoingCustomerLicense.link_id] : [],
+	);
+
+	return {
+		releaseCustomerLicenseAssignments: customerLicenseLinkIds.length
+			? { customerLicenseLinkIds, releasedAt }
+			: undefined,
+	};
+};

server/src/internal/billing/v2/execute/executeAutumnActions/executeCustomerLicenseAssignmentReleases.ts

@@ -0,0 +1,17 @@
+import type { AutumnBillingPlan } from "@autumn/shared";
+import type { AutumnContext } from "@/honoUtils/HonoEnv";
+import { licenseAssignmentRepo } from "@/internal/licenses/repos/licenseAssignmentRepo";
+
+export const executeCustomerLicenseAssignmentReleases = async ({
+	ctx,
+	release,
+}: {
+	ctx: AutumnContext;
+	release: AutumnBillingPlan["releaseCustomerLicenseAssignments"];
+}) => {
+	if (!release) return;
+	await licenseAssignmentRepo.releaseActiveAssignmentsByLinkIds({
+		db: ctx.db,
+		...release,
+	});
+};

server/src/internal/billing/v2/execute/executeAutumnBillingPlan.ts

@@ -3,6 +3,7 @@ import type Stripe from "stripe";
 import type { AutumnContext } from "@/honoUtils/HonoEnv";
 import { EntityService } from "@/internal/api/entities/EntityService";
 import { executeAutoTopupRebalance } from "@/internal/billing/v2/execute/executeAutumnActions/executeAutoTopupRebalance";
+import { executeCustomerLicenseAssignmentReleases } from "@/internal/billing/v2/execute/executeAutumnActions/executeCustomerLicenseAssignmentReleases";
 import { executeCustomerLicenseTransitions } from "@/internal/billing/v2/execute/executeAutumnActions/executeCustomerLicenseTransitions";
 import { executeCustomerLicenseUpdates } from "@/internal/billing/v2/execute/executeAutumnActions/executeCustomerLicenseUpdates";
 import { executeInsertPlanLicenses } from "@/internal/billing/v2/execute/executeAutumnActions/executeInsertPlanLicenses";
@@ -117,6 +118,10 @@ export const executeAutumnBillingPlan = async ({
 		ctx,
 		customerLicenseTransitions: autumnBillingPlan.customerLicenseTransitions,
 	});
+	await executeCustomerLicenseAssignmentReleases({
+		ctx,
+		release: autumnBillingPlan.releaseCustomerLicenseAssignments,
+	});
 
 	await replaceScheduledPhaseCustomerProductIds({
 		ctx,

server/src/internal/billing/v2/utils/billingPlan/mergeAutumnBillingPlans.ts

@@ -100,6 +100,24 @@ export const mergeAutumnBillingPlans = ({
 	upsertSubscription: incoming.upsertSubscription ?? base.upsertSubscription,
 	upsertInvoice: incoming.upsertInvoice ?? base.upsertInvoice,
 	refundPlan: incoming.refundPlan ?? base.refundPlan,
+	releaseCustomerLicenseAssignments:
+		base.releaseCustomerLicenseAssignments ||
+		incoming.releaseCustomerLicenseAssignments
+			? {
+					customerLicenseLinkIds: [
+						...new Set([
+							...(base.releaseCustomerLicenseAssignments
+								?.customerLicenseLinkIds ?? []),
+							...(incoming.releaseCustomerLicenseAssignments
+								?.customerLicenseLinkIds ?? []),
+						]),
+					],
+					releasedAt: Math.max(
+						base.releaseCustomerLicenseAssignments?.releasedAt ?? 0,
+						incoming.releaseCustomerLicenseAssignments?.releasedAt ?? 0,
+					),
+				}
+			: undefined,
 });
 
 const mergeById = <T extends { id: string }>({

server/src/internal/customers/cusProducts/actions/activateFreeDefaultProduct.ts

@@ -6,6 +6,8 @@ import {
 	type FullProduct,
 } from "@autumn/shared";
 import type { AutumnContext } from "@/honoUtils/HonoEnv";
+import { computeCustomerLicenseReleases } from "@/internal/billing/v2/compute/customerLicenseTransitions/computeCustomerLicenseReleases";
+import { computeCustomerLicenseTransitions } from "@/internal/billing/v2/compute/customerLicenseTransitions/computeCustomerLicenseTransitions";
 import { executeAutumnBillingPlan } from "@/internal/billing/v2/execute/executeAutumnBillingPlan";
 import { initFullCustomerProductFromProduct } from "@/internal/billing/v2/utils/initFullCustomerProduct/initFullCustomerProductFromProduct";
 import { productActions } from "@/internal/products/actions";
@@ -67,13 +69,25 @@ export const activateFreeDefaultProduct = async ({
 			},
 		},
 	});
+	const customerLicenseTransitions = computeCustomerLicenseTransitions({
+		outgoingCustomerProducts: [customerProduct],
+		incomingCustomerProducts: [newCustomerProduct],
+	});
+	const customerLicenseReleases = computeCustomerLicenseReleases({
+		outgoingCustomerProduct: customerProduct,
+		incomingCustomerProduct: newCustomerProduct,
+		releasedAt: Date.now(),
+	});
 
 	// 3. Execute autumn billing plan
 	await executeAutumnBillingPlan({
 		ctx,
 		autumnBillingPlan: {
 			customerId: fullCustomer?.id ?? "",
 			insertCustomerProducts: [newCustomerProduct],
+			customerLicenseTransitions,
+			releaseCustomerLicenseAssignments:
+				customerLicenseReleases.releaseCustomerLicenseAssignments,
 		},
 	});
 

server/src/internal/customers/cusProducts/actions/activateScheduled.ts

@@ -8,6 +8,7 @@ import {
 } from "@autumn/shared";
 import type { AutumnContext } from "@/honoUtils/HonoEnv";
 import { addProductsUpdatedWebhookTask } from "@/internal/analytics/handlers/handleProductsUpdated";
+import { computeCustomerLicenseReleases } from "@/internal/billing/v2/compute/customerLicenseTransitions/computeCustomerLicenseReleases.js";
 import { computeCustomerLicenseTransitions } from "@/internal/billing/v2/compute/customerLicenseTransitions/computeCustomerLicenseTransitions.js";
 import { executeAutumnBillingPlan } from "@/internal/billing/v2/execute/executeAutumnBillingPlan.js";
 import { findTransitionSourceCustomerProduct } from "@/internal/billing/v2/utils/initFullCustomerProduct/findTransitionSourceCustomerProduct";
@@ -65,6 +66,13 @@ export const activateScheduledCustomerProduct = async ({
 				incomingCustomerProducts: [customerProduct],
 			})
 		: [];
+	const customerLicenseReleases = transitionSource
+		? computeCustomerLicenseReleases({
+				outgoingCustomerProduct: transitionSource,
+				incomingCustomerProduct: customerProduct,
+				releasedAt: Date.now(),
+			})
+		: {};
 
 	// Executing through the shared plan runs the license lifecycle for
 	// activations that bring license-bearing parents live.
@@ -80,6 +88,8 @@ export const activateScheduledCustomerProduct = async ({
 				},
 			],
 			customerLicenseTransitions,
+			releaseCustomerLicenseAssignments:
+				customerLicenseReleases.releaseCustomerLicenseAssignments,
 		},
 	});