fix(billing): allocate stored refunds to one charge

Prevent historical refunds from reducing multiple replacement charges when reconstructing prorated invoice credits.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: johnyeocx

server/src/internal/billing/v2/utils/lineItems/storedInvoiceCreditForPrice.ts

@@ -9,7 +9,7 @@ import type { AutumnContext } from "@/honoUtils/HonoEnv";
 import { augmentBillingContextForAnchorResetRefund } from "./augmentBillingContextForAnchorResetRefund";
 import { chargeRowToRefundLineItem } from "./chargeRowToRefundLineItem";
 import {
-	computeAlreadyRefundedForCharge,
+	computeAlreadyRefundedByCharge,
 	computeProratedCredit,
 	splitMultiEntityAmount,
 } from "./storedLineItemUtils";
@@ -78,6 +78,10 @@ export const storedInvoiceCreditForPrice = ({
 	const creditableRows = consumedChargeRowIds
 		? usableRows.filter((row) => !consumedChargeRowIds.has(row.id))
 		: usableRows;
+	const alreadyRefundedByCharge = computeAlreadyRefundedByCharge({
+		chargeRows: usableRows,
+		refundRows: currentPeriodRefunds,
+	});
 
 	for (const chargeRow of creditableRows) {
 		const periodStart = chargeRow.effective_period_start;
@@ -93,10 +97,7 @@ export const storedInvoiceCreditForPrice = ({
 		consumedChargeRowIds?.add(chargeRow.id);
 		const effectiveNow =
 			action.type === "use_snapped_now" ? action.snappedNow : now;
-		const alreadyRefunded = computeAlreadyRefundedForCharge({
-			chargeRow,
-			refundRows: currentPeriodRefunds,
-		});
+		const alreadyRefunded = alreadyRefundedByCharge.get(chargeRow.id) ?? 0;
 		const creditAmount = computeProratedCredit({
 			chargeRow: {
 				...chargeRow,

server/src/internal/billing/v2/utils/lineItems/storedLineItemUtils.ts

@@ -19,6 +19,9 @@ export const hasSamePrice = (
 	(a.price_id != null && a.price_id === b.price_id) ||
 	(a.stripe_price_id != null && a.stripe_price_id === b.stripe_price_id);
 
+const sharesInvoice = (a: DbInvoiceLineItem, b: DbInvoiceLineItem): boolean =>
+	a.invoice_id != null && b.invoice_id != null && a.invoice_id === b.invoice_id;
+
 export const computeProratedCredit = ({
 	chargeRow,
 	now,
@@ -49,25 +52,40 @@ export const computeProratedCredit = ({
 	return prorationFraction.mul(refundable).neg().toNumber();
 };
 
-export const computeAlreadyRefundedForCharge = ({
-	chargeRow,
+export const computeAlreadyRefundedByCharge = ({
+	chargeRows,
 	refundRows,
 }: {
-	chargeRow: DbInvoiceLineItem;
+	chargeRows: DbInvoiceLineItem[];
 	refundRows: DbInvoiceLineItem[];
-}): number => {
-	const matchingRefunds = refundRows.filter(
-		(refund) =>
-			isWithinPeriod(refund, chargeRow) && hasSamePrice(refund, chargeRow),
+}): Map<string, number> => {
+	const alreadyRefundedByCharge = new Map<string, number>();
+	const chronologicalRefunds = [...refundRows].sort(
+		(a, b) => a.created_at - b.created_at,
 	);
 
-	return matchingRefunds.reduce(
-		(sum, r) =>
-			new Decimal(sum)
-				.plus(Math.abs(splitMultiEntityAmount(r)))
+	for (const refund of chronologicalRefunds) {
+		const matchingCharge = chargeRows
+			.filter(
+				(charge) =>
+					charge.created_at < refund.created_at &&
+					!sharesInvoice(charge, refund) &&
+					isWithinPeriod(refund, charge) &&
+					hasSamePrice(refund, charge),
+			)
+			.sort((a, b) => b.created_at - a.created_at)[0];
+		if (!matchingCharge) continue;
+
+		const alreadyRefunded = alreadyRefundedByCharge.get(matchingCharge.id) ?? 0;
+		alreadyRefundedByCharge.set(
+			matchingCharge.id,
+			new Decimal(alreadyRefunded)
+				.plus(Math.abs(splitMultiEntityAmount(refund)))
 				.toNumber(),
-		0,
-	);
+		);
+	}
+
+	return alreadyRefundedByCharge;
 };
 
 export const splitMultiEntityAmount = (

server/tests/integration/licenses/billing/update/update-license-quantity.test.ts

@@ -15,6 +15,8 @@
  *     -$60/+$100 — assigned-seat portions must NOT collapse into a
  *     delta-only line.
  *   - quantity 3 -> 5 partially assigned (1 included): pair -$40/+$80.
+ *   - sequential 5 -> 7 -> 9: the old 5-seat refund is not reused against
+ *     the 7-seat replacement charge; the second update bills only 2 seats.
  *   - same quantity: pair cancels -> no line items, no new invoice.
  *   - included-only pool (0 paid) grown: charge line only, no $0 refund.
  *   - quantity below live assignments -> 400.
@@ -104,6 +106,45 @@ test.concurrent(
 	},
 );
 
+test.concurrent(
+	`${chalk.yellowBright("license-update-quantity: sequential 5 -> 7 -> 9 changes credit each prior charge once")}`,
+	async () => {
+		const customerId = "license-update-quantity-sequential";
+		const { autumnV2_3, parent, devSeat, advancedTo } =
+			await setupLicenseUpdateScenario({
+				customerId,
+				idPrefix: "lic-qty-sequential",
+				seatPrice: DEV_SEAT_PRICE,
+				includedSeats: 0,
+				attachedSeats: 5,
+			});
+
+		await autumnV2_3.billing.update<UpdateSubscriptionV1ParamsInput>({
+			customer_id: customerId,
+			plan_id: parent.id,
+			license_quantities: [{ license_plan_id: devSeat.id, quantity: 7 }],
+		});
+
+		const preview =
+			await autumnV2_3.subscriptions.previewUpdate<UpdateSubscriptionV1ParamsInput>(
+				{
+					customer_id: customerId,
+					plan_id: parent.id,
+					license_quantities: [{ license_plan_id: devSeat.id, quantity: 9 }],
+				},
+			);
+
+		await expectLicenseUpdatePreviewCorrect({
+			preview,
+			customerId,
+			advancedTo,
+			oldRecurringTotal: 7 * DEV_SEAT_PRICE,
+			newRecurringTotal: 9 * DEV_SEAT_PRICE,
+			expectQuantityLineItemPair: { oldQuantity: 7, newQuantity: 9 },
+		});
+	},
+);
+
 test.concurrent(
 	`${chalk.yellowBright("license-update-quantity: qty 3 -> 2 shrinks the pool in place")}`,
 	async () => {

server/tests/unit/billing/invoice-matched-credits/invoice-credit-matcher.spec.ts

@@ -11,7 +11,7 @@ import chalk from "chalk";
 import { getRefundLineItemsForPrice } from "@/internal/billing/v2/utils/lineItems/getRefundLineItemsForPrice";
 import { invoiceCreditFromStoredLineItems } from "@/internal/billing/v2/utils/lineItems/invoiceCreditFromStoredLineItems";
 import {
-	computeAlreadyRefundedForCharge,
+	computeAlreadyRefundedByCharge,
 	computeProratedCredit,
 	splitMultiEntityAmount,
 } from "@/internal/billing/v2/utils/lineItems/storedLineItemUtils";
@@ -25,6 +25,7 @@ const makeChargeRow = (
 ): DbInvoiceLineItem =>
 	({
 		id: "li_charge_1",
+		created_at: PERIOD_START,
 		amount: 20,
 		amount_after_discounts: 20,
 		effective_period_start: PERIOD_START,
@@ -42,6 +43,7 @@ const makeRefundRow = (
 ): DbInvoiceLineItem =>
 	({
 		id: "li_refund_1",
+		created_at: PERIOD_START + 1000,
 		amount: -10,
 		amount_after_discounts: -10,
 		effective_period_start: PERIOD_START,
@@ -129,33 +131,40 @@ describe(chalk.yellowBright("computeProratedCredit"), () => {
 	});
 });
 
-describe(chalk.yellowBright("computeAlreadyRefundedForCharge"), () => {
+describe(chalk.yellowBright("computeAlreadyRefundedByCharge"), () => {
 	test("sums matching refund rows by price and period", () => {
-		const result = computeAlreadyRefundedForCharge({
-			chargeRow: makeChargeRow(),
+		const chargeRow = makeChargeRow();
+		const result = computeAlreadyRefundedByCharge({
+			chargeRows: [chargeRow],
 			refundRows: [
 				makeRefundRow({ amount_after_discounts: -5 }),
-				makeRefundRow({ id: "li_refund_2", amount_after_discounts: -3 }),
+				makeRefundRow({
+					id: "li_refund_2",
+					created_at: PERIOD_START + 2000,
+					amount_after_discounts: -3,
+				}),
 			],
 		});
 
-		expect(result).toBe(8);
+		expect(result.get(chargeRow.id)).toBe(8);
 	});
 
 	test("excludes refunds with different price_id", () => {
-		const result = computeAlreadyRefundedForCharge({
-			chargeRow: makeChargeRow(),
+		const chargeRow = makeChargeRow();
+		const result = computeAlreadyRefundedByCharge({
+			chargeRows: [chargeRow],
 			refundRows: [
 				makeRefundRow({ price_id: "price_other", stripe_price_id: "other" }),
 			],
 		});
 
-		expect(result).toBe(0);
+		expect(result.get(chargeRow.id)).toBeUndefined();
 	});
 
 	test("excludes refunds outside the charge period", () => {
-		const result = computeAlreadyRefundedForCharge({
-			chargeRow: makeChargeRow(),
+		const chargeRow = makeChargeRow();
+		const result = computeAlreadyRefundedByCharge({
+			chargeRows: [chargeRow],
 			refundRows: [
 				makeRefundRow({
 					effective_period_start: PERIOD_END + 1000,
@@ -164,16 +173,44 @@ describe(chalk.yellowBright("computeAlreadyRefundedForCharge"), () => {
 			],
 		});
 
-		expect(result).toBe(0);
+		expect(result.get(chargeRow.id)).toBeUndefined();
 	});
 
-	test("returns 0 with no refund rows", () => {
-		const result = computeAlreadyRefundedForCharge({
-			chargeRow: makeChargeRow(),
+	test("returns no allocations with no refund rows", () => {
+		const result = computeAlreadyRefundedByCharge({
+			chargeRows: [makeChargeRow()],
 			refundRows: [],
 		});
 
-		expect(result).toBe(0);
+		expect(result.size).toBe(0);
+	});
+
+	test("allocates a refund only to the latest matching earlier charge", () => {
+		const originalCharge = makeChargeRow({
+			id: "li_charge_5",
+			created_at: PERIOD_START,
+			invoice_id: "inv_initial",
+			amount_after_discounts: 100,
+		});
+		const refund = makeRefundRow({
+			created_at: PERIOD_START + 1000,
+			invoice_id: "inv_update",
+			amount_after_discounts: -100,
+		});
+		const replacementCharge = makeChargeRow({
+			id: "li_charge_7",
+			created_at: PERIOD_START + 500,
+			invoice_id: "inv_update",
+			amount_after_discounts: 140,
+		});
+
+		const result = computeAlreadyRefundedByCharge({
+			chargeRows: [originalCharge, replacementCharge],
+			refundRows: [refund],
+		});
+
+		expect(result.get(originalCharge.id)).toBe(100);
+		expect(result.get(replacementCharge.id)).toBeUndefined();
 	});
 });