fix: reject every refund request that cannot pay out

The previous guard only refused an end-of-cycle switch, so a refund asked
for on an add-on, a first attach, a free outgoing plan, or alongside
no_billing_changes was still dropped in silence — the exact failure the
guard exists to prevent.

handleRefundLastPaymentErrors now covers all of those, so a refund either
happens or the caller is told why it cannot.

The dashboard also waits for a settled preview before clearing the toggle,
so an approval link hydrated with refund_last_payment keeps it while
hasOutgoing is still unknown.

Author: charlietlamb

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

@@ -30,9 +30,9 @@ export const finalizeAttachPlan = async ({
 		customLineItems: params.custom_line_items,
 	});
 
-	// Refund lines can appear for siblings on an add-on attach, so the outgoing
-	// plan itself is the signal — otherwise a "full" refund would return the
-	// last invoice when nothing was actually replaced.
+	// Compute runs before the error pass rejects an unpayable refund, so the
+	// outgoing plan is checked here too. Sibling refund lines on an add-on attach
+	// make line items an unreliable signal.
 	const replacesExistingPlan = Boolean(
 		attachBillingContext.currentCustomerProduct,
 	);

server/src/internal/billing/v2/actions/attach/errors/handleAttachV2Errors.ts

@@ -81,7 +81,7 @@ export const handleAttachV2Errors = async ({
 
 	// 6. Scheduled switch with one-off prepaid quantities
 	handleScheduledSwitchOneOffErrors({ ctx, billingContext });
-	handleRefundLastPaymentErrors({ billingContext });
+	handleRefundLastPaymentErrors({ billingContext, params });
 	handleBillingCycleAnchorErrors({ billingContext, params });
 	handleStartDateErrors({ billingContext, params, preview });
 	handleEndDateErrors({ billingContext, params });

server/src/internal/billing/v2/actions/attach/errors/handleRefundLastPaymentErrors.ts

@@ -1,32 +1,61 @@
 import {
 	type AttachBillingContext,
+	type AttachParamsV1,
 	ErrCode,
+	isCustomerProductFree,
 	RecaseError,
 } from "@autumn/shared";
 import { StatusCodes } from "http-status-codes";
 
+const refundRejected = ({ reason }: { reason: string }) =>
+	new RecaseError({
+		message: `refund_last_payment ${reason}`,
+		code: ErrCode.InvalidRequest,
+		statusCode: StatusCodes.BAD_REQUEST,
+	});
+
 /**
- * Validates that a requested refund can actually be paid out.
- *
- * A downgrade defaults to "end_of_cycle" when no plan_schedule is passed, so
- * the schema alone cannot catch this — the outgoing plan stays active until the
- * cycle ends, and no refund would be issued.
+ * Rejects refund requests that could not be paid out, so the caller hears about
+ * it instead of the option being silently dropped.
  */
 export const handleRefundLastPaymentErrors = ({
 	billingContext,
+	params,
 }: {
 	billingContext: AttachBillingContext;
+	params: AttachParamsV1;
 }) => {
-	const { refundLastPayment, planTiming } = billingContext;
+	const { refundLastPayment, planTiming, currentCustomerProduct } =
+		billingContext;
 
 	if (!refundLastPayment) return;
 
+	if (params.no_billing_changes === true) {
+		throw refundRejected({
+			reason:
+				"cannot be combined with no_billing_changes, which skips the billing changes the refund depends on.",
+		});
+	}
+
+	// A downgrade resolves to end_of_cycle unless plan_schedule says otherwise.
 	if (planTiming === "end_of_cycle") {
-		throw new RecaseError({
-			message:
-				"refund_last_payment requires an immediate plan switch. This attach resolves to an end-of-cycle switch, so the outgoing plan stays active until the cycle ends and its payment cannot be refunded. Pass plan_schedule: 'immediate' to switch and refund now.",
-			code: ErrCode.InvalidRequest,
-			statusCode: StatusCodes.BAD_REQUEST,
+		throw refundRejected({
+			reason:
+				"requires an immediate plan switch. This attach resolves to an end-of-cycle switch, so the outgoing plan stays active until the cycle ends and its payment cannot be refunded. Pass plan_schedule: 'immediate' to switch and refund now.",
+		});
+	}
+
+	if (!currentCustomerProduct) {
+		throw refundRejected({
+			reason:
+				"requires an outgoing plan to refund. This attach does not replace an existing plan.",
+		});
+	}
+
+	if (isCustomerProductFree(currentCustomerProduct)) {
+		throw refundRejected({
+			reason:
+				"requires a paid outgoing plan. The plan being replaced was free, so there is no payment to return.",
 		});
 	}
 };

vite/src/components/forms/attach-v2/components/AttachAdvancedSection.tsx

@@ -211,9 +211,8 @@ export function AttachAdvancedSection() {
 	const resetsBillingCycleNow =
 		resetBillingCycle && billingCycleAnchorMode === "now";
 
-	// Only an immediate, prorated switch produces credit that can go back to the card.
-	// Multi-plan attach has no refund support, and without an outgoing plan
-	// there is no credit to hand back.
+	// Only an immediate, prorated switch off an outgoing plan produces credit
+	// that can go back to the card. Multi-plan attach has no refund support.
 	const canRefundOutgoingPlan =
 		hasOutgoing &&
 		!isMultiPlan &&
@@ -223,11 +222,19 @@ export function AttachAdvancedSection() {
 		effectiveProrationBehavior === "prorate_immediately" &&
 		effectivePlanSchedule !== "end_of_cycle";
 
+	// Wait for the preview before clearing, so a hydrated approval link keeps its
+	// refund while `hasOutgoing` is still unknown.
+	const previewSettled = Boolean(previewQuery.data);
+
 	useEffect(() => {
-		if (!canRefundOutgoingPlan && refundLastPayment !== null) {
+		if (
+			previewSettled &&
+			!canRefundOutgoingPlan &&
+			refundLastPayment !== null
+		) {
 			form.setFieldValue("refundLastPayment", null);
 		}
-	}, [canRefundOutgoingPlan, refundLastPayment, form]);
+	}, [previewSettled, canRefundOutgoingPlan, refundLastPayment, form]);
 
 	const handleAddDiscount = () => {
 		form.setFieldValue("discounts", addDiscount(discounts));