@ticketboothapp/booking 1.2.152 → 1.2.153

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ticketboothapp/booking",
-  "version": "1.2.152",
+  "version": "1.2.153",
   "private": false,
   "sideEffects": [
     "**/*.css",

package/src/components/booking/AdminChangeBookingContent.tsx

@@ -159,6 +159,12 @@ const checkoutPanelPropKeys = [
   'serverAmountDue',
   'serverUpdatedTotal',
   'serverQuoteError',
+  'refundDecisionOperations',
+  'allowedRefundDispositionsByOperationId',
+  'removedValueByOperationId',
+  'refundDispositionsByOperationId',
+  'onRefundDispositionChange',
+  'refundQuoteLoading',
   'isTaxIncludedInPrice',
   'taxRate',
   'currency',

package/src/components/booking/AdminChangeBookingFlow.tsx

@@ -2,6 +2,7 @@
 
 import { useState, useEffect, useMemo, useRef, useCallback } from 'react';
 import {
+  type AdminAmendmentRefundDisposition,
   type Availability,
   type ReturnOption,
 } from '../../lib/booking-api';
@@ -54,6 +55,15 @@ import { useSeedPromoCodeInput } from './useSeedPromoCodeInput';
 import { useAdminChangeProductReset } from './useAdminChangeProductReset';
 import { useBookingQuantityCapTrim } from './useBookingQuantityCapTrim';
 import { useBookingViewItemAnalytics } from './useBookingViewItemAnalytics';
+import { buildAdminChangeQuoteRequestKey } from './admin-change-quote-request-key';
+import type { AdminReleaseRefundDisposition } from './admin-refund-disposition';
+
+type AdminRefundDecisionContext = {
+  selectionKey: string;
+  operations: NonNullable<AdminChangeLatestQuote['refundDecisionOperations']>;
+  allowedByOperationId: NonNullable<AdminChangeLatestQuote['allowedRefundDispositionsByOperationId']>;
+  removedValueByOperationId: NonNullable<AdminChangeLatestQuote['removedValueByOperationId']>;
+};
 
 /**
  * ## Pricing contract (customer self-serve)
@@ -229,6 +239,10 @@ export function AdminChangeBookingFlow({
     [isCustomerSelfServeChange, initialValues?.bookingItems, isAdmin],
   );
   const [latestChangeQuote, setLatestChangeQuote] = useState<AdminChangeLatestQuote | null>(null);
+  const [refundDecisionContext, setRefundDecisionContext] = useState<AdminRefundDecisionContext | null>(null);
+  const [refundDispositionsByOperationId, setRefundDispositionsByOperationId] = useState<
+    Record<string, AdminAmendmentRefundDisposition>
+  >({});
   const [changeQuoteLoading, setChangeQuoteLoading] = useState(false);
   const [changeQuoteFetchError, setChangeQuoteFetchError] = useState<string | null>(null);
   /** Dedupe quote calls while user input payload is unchanged. */
@@ -238,7 +252,8 @@ export function AdminChangeBookingFlow({
     suppressSelfServeCurrencyUi &&
     latestChangeQuote != null &&
     changeQuoteFetchError == null &&
-    latestChangeQuote.canProceed !== false &&
+    (latestChangeQuote.canProceed !== false ||
+      (latestChangeQuote.refundDecisionOperations?.length ?? 0) > 0) &&
     latestChangeQuote.serverDisplay != null;
   const changeQuoteRequestSeq = useRef(0);
   const { activeOptions, activeOptionIdsKey, optionsMap } = useActiveProductOptions(product.options);
@@ -667,6 +682,72 @@ export function AdminChangeBookingFlow({
     changeFlowAmountDue,
   });
 
+  const refundDecisionSelectionKey = useMemo(() => buildAdminChangeQuoteRequestKey({
+    bookingReference: initialValues?.bookingReference,
+    lastName,
+    productId: product.productId,
+    selectedAvailability,
+    pickupLocationId,
+    returnAvailabilityId: selectedReturnOption?.returnAvailabilityId ?? null,
+    quantities,
+    addOnSelections,
+    adminCustomReceiptLines,
+    useAdminFeAuthoritativeQuote,
+  }), [
+    initialValues?.bookingReference,
+    lastName,
+    product.productId,
+    selectedAvailability,
+    pickupLocationId,
+    selectedReturnOption?.returnAvailabilityId,
+    quantities,
+    addOnSelections,
+    adminCustomReceiptLines,
+    useAdminFeAuthoritativeQuote,
+  ]);
+  const responseRefundDecisionOperations = latestChangeQuote?.refundDecisionOperations ?? [];
+  useEffect(() => {
+    if (responseRefundDecisionOperations.length === 0) return;
+    setRefundDecisionContext({
+      selectionKey: refundDecisionSelectionKey,
+      operations: responseRefundDecisionOperations,
+      allowedByOperationId: latestChangeQuote?.allowedRefundDispositionsByOperationId ?? {},
+      removedValueByOperationId: latestChangeQuote?.removedValueByOperationId ?? {},
+    });
+  }, [
+    refundDecisionSelectionKey,
+    responseRefundDecisionOperations,
+    latestChangeQuote?.allowedRefundDispositionsByOperationId,
+    latestChangeQuote?.removedValueByOperationId,
+  ]);
+  const activeRefundDecisionContext = responseRefundDecisionOperations.length > 0
+    ? {
+        selectionKey: refundDecisionSelectionKey,
+        operations: responseRefundDecisionOperations,
+        allowedByOperationId: latestChangeQuote?.allowedRefundDispositionsByOperationId ?? {},
+        removedValueByOperationId: latestChangeQuote?.removedValueByOperationId ?? {},
+      }
+    : refundDecisionContext?.selectionKey === refundDecisionSelectionKey
+      ? refundDecisionContext
+      : null;
+  const activeRefundDispositionsByOperationId = useMemo(() => Object.fromEntries(
+    (activeRefundDecisionContext?.operations ?? []).flatMap((operation) => {
+      const disposition = refundDispositionsByOperationId[operation.operationId];
+      return disposition ? [[operation.operationId, disposition] as const] : [];
+    }),
+  ), [activeRefundDecisionContext?.operations, refundDispositionsByOperationId]);
+  const handleRefundDispositionChange = useCallback((
+    operationId: string,
+    disposition: AdminReleaseRefundDisposition | null,
+  ) => {
+    setRefundDispositionsByOperationId((current) => {
+      if (disposition) return { ...current, [operationId]: disposition };
+      const next = { ...current };
+      delete next[operationId];
+      return next;
+    });
+  }, []);
+
   const {
     missingRequiredReturnSelection,
     isChangeQuoteBlocked,
@@ -687,6 +768,7 @@ export function AdminChangeBookingFlow({
     quantities,
     addOnSelections,
     adminCustomReceiptLines,
+    refundDispositionsByOperationId: activeRefundDispositionsByOperationId,
     useAdminFeAuthoritativeQuote,
     latestChangeQuote,
     setLatestChangeQuote,
@@ -870,6 +952,7 @@ export function AdminChangeBookingFlow({
     providerPricingOverrides,
     mergedProviderAdditionalAdjustments,
     adminStructuredAdjustments,
+    refundDispositionsByOperationId: activeRefundDispositionsByOperationId,
     providerApplyAuthoritativeReceipt,
     onSuccess,
     totalPrice,
@@ -976,6 +1059,14 @@ export function AdminChangeBookingFlow({
         serverAmountDue: latestChangeQuote?.serverPreview?.amountDue ?? null,
         serverUpdatedTotal: latestChangeQuote?.serverPreview?.totalNewBooking ?? null,
         serverQuoteError: changeQuoteFetchError,
+        refundDecisionOperations: activeRefundDecisionContext?.operations ?? [],
+        allowedRefundDispositionsByOperationId:
+          activeRefundDecisionContext?.allowedByOperationId ?? {},
+        removedValueByOperationId:
+          activeRefundDecisionContext?.removedValueByOperationId ?? {},
+        refundDispositionsByOperationId: activeRefundDispositionsByOperationId,
+        onRefundDispositionChange: handleRefundDispositionChange,
+        refundQuoteLoading: changeQuoteLoading,
         ...{ priceSummaryLinesIncludeTaxRow, isTaxIncludedInPrice, showProviderPricingInlineEditor },
         taxRate: pricingConfig?.taxRate,
         ...{ providerPricingUi, providerQuotedLines },

package/src/components/booking/AdminChangeCheckoutPanel.tsx

@@ -1,5 +1,10 @@
 import type { ReactNode } from 'react';
-import type { Destination, PickupLocation } from '../../lib/booking-api';
+import type {
+  AdminAmendmentOperationSnapshot,
+  AdminAmendmentRefundDisposition,
+  Destination,
+  PickupLocation,
+} from '../../lib/booking-api';
 import { CheckoutForm } from './CheckoutForm';
 import type { ChangeBookingFlowProps } from './booking-flow-types';
 import type { Currency } from './CurrencySwitcher';
@@ -9,6 +14,7 @@ import type {
   ProviderDashboardPricingLine,
 } from './booking-flow-ui';
 import { AdminChangeReceiptComparison } from './AdminChangeReceiptComparison';
+import type { AdminReleaseRefundDisposition } from './admin-refund-disposition';
 import {
   AdminChangePricingAdjustments,
   AdminChangePricingMessages,
@@ -34,6 +40,15 @@ export interface AdminChangeCheckoutPanelProps {
   serverAmountDue: number | null;
   serverUpdatedTotal: number | null;
   serverQuoteError?: string | null;
+  refundDecisionOperations?: AdminAmendmentOperationSnapshot[];
+  allowedRefundDispositionsByOperationId?: Record<string, AdminAmendmentRefundDisposition[]>;
+  removedValueByOperationId?: Record<string, number>;
+  refundDispositionsByOperationId?: Record<string, AdminAmendmentRefundDisposition>;
+  onRefundDispositionChange?: (
+    operationId: string,
+    disposition: AdminReleaseRefundDisposition | null,
+  ) => void;
+  refundQuoteLoading?: boolean;
   isTaxIncludedInPrice: boolean;
   taxRate?: number;
   currency: Currency;
@@ -107,6 +122,12 @@ export function AdminChangeCheckoutPanel({
   serverAmountDue,
   serverUpdatedTotal,
   serverQuoteError,
+  refundDecisionOperations,
+  allowedRefundDispositionsByOperationId,
+  removedValueByOperationId,
+  refundDispositionsByOperationId,
+  onRefundDispositionChange,
+  refundQuoteLoading,
   isTaxIncludedInPrice,
   taxRate,
   currency,
@@ -194,6 +215,12 @@ export function AdminChangeCheckoutPanel({
         updatedTotal={serverUpdatedTotal}
         selectionChanged={hasEffectiveChangeSelection}
         quoteError={serverQuoteError}
+        refundDecisionOperations={refundDecisionOperations}
+        allowedRefundDispositionsByOperationId={allowedRefundDispositionsByOperationId}
+        removedValueByOperationId={removedValueByOperationId}
+        refundDispositionsByOperationId={refundDispositionsByOperationId}
+        onRefundDispositionChange={onRefundDispositionChange}
+        refundQuoteLoading={refundQuoteLoading}
         amountDueLabel={totalSummaryLabel}
         currency={currency}
         locale={locale}

package/src/components/booking/AdminChangeReceiptComparison.tsx

@@ -1,10 +1,21 @@
 import type { ReactNode } from 'react';
+import type {
+  AdminAmendmentOperationSnapshot,
+  AdminAmendmentRefundDisposition,
+} from '../../lib/booking-api';
 import { mapQuoteLineItemsToPriceSummaryLines } from '../../lib/booking/change-booking-server-preview';
 import { formatCurrencyAmount } from '../../lib/currency';
 import type { Locale } from '../../lib/booking/i18n/config';
 import type { ChangeBookingFlowProps } from './booking-flow-types';
 import type { Currency } from './CurrencySwitcher';
 import { PriceSummary, type PriceSummaryLine } from './PriceSummary';
+import {
+  adminRemovalOperationLabel,
+  noRefundRemovedValue,
+  refundDecisionsComplete,
+  releaseRefundDispositionOptions,
+  type AdminReleaseRefundDisposition,
+} from './admin-refund-disposition';
 
 type TranslationFn = (key: string, params?: Record<string, string>) => string;
 type OriginalReceipt = NonNullable<ChangeBookingFlowProps['originalReceipt']>;
@@ -25,6 +36,15 @@ export interface AdminChangeReceiptComparisonProps {
   t: TranslationFn;
   taxRate?: number;
   adjustments?: ReactNode;
+  refundDecisionOperations?: AdminAmendmentOperationSnapshot[];
+  allowedRefundDispositionsByOperationId?: Record<string, AdminAmendmentRefundDisposition[]>;
+  removedValueByOperationId?: Record<string, number>;
+  refundDispositionsByOperationId?: Record<string, AdminAmendmentRefundDisposition>;
+  onRefundDispositionChange?: (
+    operationId: string,
+    disposition: AdminReleaseRefundDisposition | null,
+  ) => void;
+  refundQuoteLoading?: boolean;
 }
 
 function normalizeLocale(locale: string): Locale {
@@ -65,11 +85,29 @@ export function AdminChangeReceiptComparison({
   t,
   taxRate,
   adjustments,
+  refundDecisionOperations = [],
+  allowedRefundDispositionsByOperationId = {},
+  removedValueByOperationId = {},
+  refundDispositionsByOperationId = {},
+  onRefundDispositionChange,
+  refundQuoteLoading = false,
 }: AdminChangeReceiptComparisonProps) {
   const displayLocale = normalizeLocale(locale);
   const existingLines = originalLines(originalReceipt);
   const originalCurrency = originalReceipt.currency ?? currency;
   const quoteReady = amendmentLines != null && amountDue != null && updatedTotal != null;
+  const hasRefundDecisions = refundDecisionOperations.length > 0;
+  const refundSelectionsComplete = refundDecisionsComplete(
+    refundDecisionOperations,
+    refundDispositionsByOperationId,
+  );
+  const settlementPending = hasRefundDecisions && (!refundSelectionsComplete || refundQuoteLoading);
+  const displayedAmountDue = settlementPending ? null : amountDue;
+  const removedWithoutRefund = noRefundRemovedValue(
+    refundDecisionOperations,
+    refundDispositionsByOperationId,
+    removedValueByOperationId,
+  );
   const amendmentTax = amendmentLines?.reduce(
     (sum, line) =>
       line.kind === 'line' && String(line.type ?? '').toUpperCase() === 'TAX'
@@ -104,14 +142,66 @@ export function AdminChangeReceiptComparison({
       ]
     : [];
   const amountDueClass =
-    amountDue != null && amountDue < -0.005
+    displayedAmountDue != null && displayedAmountDue < -0.005
       ? 'text-emerald-700'
-      : amountDue != null && amountDue > 0.005
+      : displayedAmountDue != null && displayedAmountDue > 0.005
         ? 'text-stone-900'
         : 'text-stone-700';
 
   return (
     <div className="min-w-0 space-y-3 overflow-visible">
+      {hasRefundDecisions ? (
+        <section className="rounded-lg border border-amber-300 bg-amber-50 p-3" aria-label="Refund treatment">
+          <div className="mb-3">
+            <h3 className="text-sm font-semibold text-stone-900">Choose refund treatment</h3>
+            <p className="mt-1 text-xs text-stone-600">
+              Removed paid value is never refunded automatically. Choose an explicit treatment, then the server will recalculate the settlement.
+            </p>
+          </div>
+          <div className="space-y-3">
+            {refundDecisionOperations.map((operation) => {
+              const options = releaseRefundDispositionOptions(
+                allowedRefundDispositionsByOperationId[operation.operationId],
+              );
+              const selectedValue = refundDispositionsByOperationId[operation.operationId];
+              const selected = options.find((option) => option.value === selectedValue);
+              const removedValue = removedValueByOperationId[operation.operationId];
+              return (
+                <div key={operation.operationId} className="rounded-md border border-amber-200 bg-white p-3">
+                  <div className="mb-2 flex flex-wrap items-start justify-between gap-2 text-sm font-medium text-stone-900">
+                    <span className="capitalize">{adminRemovalOperationLabel(operation)}</span>
+                    {Number.isFinite(removedValue) ? (
+                      <span>{formatCurrencyAmount(removedValue, currency, displayLocale)}</span>
+                    ) : null}
+                  </div>
+                  <select
+                    className="w-full rounded-md border border-stone-300 bg-white px-3 py-2 text-sm text-stone-900"
+                    value={selectedValue ?? ''}
+                    onChange={(event) => {
+                      const value = event.target.value;
+                      onRefundDispositionChange?.(
+                        operation.operationId,
+                        value ? value as AdminReleaseRefundDisposition : null,
+                      );
+                    }}
+                    aria-label={`Refund treatment for ${adminRemovalOperationLabel(operation)}`}
+                  >
+                    <option value="">Choose refund treatment…</option>
+                    {options.map((option) => (
+                      <option key={option.value} value={option.value}>{option.label}</option>
+                    ))}
+                  </select>
+                  {selected ? <p className="mt-2 text-xs text-stone-600">{selected.description}</p> : null}
+                </div>
+              );
+            })}
+          </div>
+          {refundQuoteLoading && refundSelectionsComplete ? (
+            <p className="mt-3 text-xs font-medium text-amber-800">Recalculating settlement…</p>
+          ) : null}
+        </section>
+      ) : null}
+
       <div className="grid gap-4 md:grid-cols-2">
         <section className="min-w-0 overflow-visible rounded-lg border border-stone-200 bg-stone-50/70 p-3">
           <div className="mb-3 flex items-center justify-between gap-3">
@@ -140,7 +230,7 @@ export function AdminChangeReceiptComparison({
               <p className="mt-0.5 text-xs text-stone-500">Server-priced amendment</p>
             </div>
             <span className="shrink-0 text-xs font-medium text-stone-500">
-              {amountDue == null ? '—' : formatCurrencyAmount(amountDue, currency, displayLocale)}
+              {displayedAmountDue == null ? '—' : formatCurrencyAmount(displayedAmountDue, currency, displayLocale)}
             </span>
           </div>
           {!selectionChanged ? (
@@ -156,6 +246,18 @@ export function AdminChangeReceiptComparison({
             <div className="rounded-md border border-dashed border-stone-300 bg-white/70 px-3 py-4 text-center">
               <p className="text-sm font-medium text-stone-700">Waiting for server price…</p>
             </div>
+          ) : settlementPending ? (
+            <div className="rounded-md border border-dashed border-amber-300 bg-white/70 px-3 py-4 text-center">
+              <p className="text-sm font-medium text-amber-900">Refund treatment required</p>
+              <p className="mt-1 text-xs text-stone-600">Choose how to handle the removed paid value above.</p>
+            </div>
+          ) : amendmentDisplayLines.length === 0 && Math.abs(amountDue) < 0.005 && removedWithoutRefund > 0 ? (
+            <div className="rounded-md border border-dashed border-stone-300 bg-white/70 px-3 py-4 text-center">
+              <p className="text-sm font-medium text-stone-800">No refund will be created</p>
+              <p className="mt-1 text-xs text-stone-600">
+                {formatCurrencyAmount(removedWithoutRefund, currency, displayLocale)} of booking value will be removed without customer credit.
+              </p>
+            </div>
           ) : amendmentDisplayLines.length === 0 && Math.abs(amountDue) < 0.005 ? (
             <div className="rounded-md border border-dashed border-stone-300 bg-white/70 px-3 py-4 text-center">
               <p className="text-sm font-medium text-stone-700">No pricing changes</p>
@@ -196,7 +298,9 @@ export function AdminChangeReceiptComparison({
       <div className="flex flex-wrap items-center justify-between gap-2 rounded-lg border border-stone-200 bg-stone-50 px-3 py-2">
         <span className="text-sm font-semibold text-stone-900">{amountDueLabel}</span>
         <span className={`text-lg font-semibold tabular-nums ${amountDueClass}`}>
-          {!selectionChanged || amountDue == null ? '—' : formatCurrencyAmount(amountDue, currency, displayLocale)}
+          {!selectionChanged || displayedAmountDue == null
+            ? '—'
+            : formatCurrencyAmount(displayedAmountDue, currency, displayLocale)}
         </span>
       </div>
     </div>

package/src/components/booking/admin-change-provider-payload.ts

@@ -33,6 +33,9 @@ export interface BuildAdminChangeProviderPayloadParams {
   providerPricingOverrides: AdminChangeProviderLineOverride[];
   mergedProviderAdditionalAdjustments: AdminChangeProviderAdditionalAdjustment[];
   adminStructuredAdjustments: NonNullable<ProviderDashboardChangeBookingPayload['structuredAdjustments']>;
+  refundDispositionsByOperationId: NonNullable<
+    ProviderDashboardChangeBookingPayload['refundDispositionsByOperationId']
+  >;
   providerApplyAuthoritativeReceipt?: ProviderDashboardChangeBookingPayload['authoritativeReceipt'];
   previousPassengerCount: number;
   previousAvailabilityId?: string | null;
@@ -54,6 +57,7 @@ export function buildAdminChangeProviderPayload({
   providerPricingOverrides,
   mergedProviderAdditionalAdjustments,
   adminStructuredAdjustments,
+  refundDispositionsByOperationId,
   providerApplyAuthoritativeReceipt,
   previousPassengerCount,
   previousAvailabilityId,
@@ -93,6 +97,7 @@ export function buildAdminChangeProviderPayload({
         : undefined,
     authoritativeReceipt: providerApplyAuthoritativeReceipt,
     structuredAdjustments: adminStructuredAdjustments,
+    refundDispositionsByOperationId,
     capacitySeatCredit: {
       enabled: true,
       previousPassengerCount,

package/src/components/booking/admin-change-quote-request-key.ts

@@ -11,6 +11,7 @@ interface AdminChangeQuoteRequestKeyInput {
   quantities: Record<string, number>;
   addOnSelections: Array<{ addOnId: string; variantId?: string; quantity?: number }>;
   adminCustomReceiptLines: Array<{ label: string; amountInput: string; amountSign?: number }>;
+  refundDispositionsByOperationId?: Record<string, string>;
   useAdminFeAuthoritativeQuote: boolean;
 }
 
@@ -32,6 +33,9 @@ export function buildAdminChangeQuoteRequestKey(input: AdminChangeQuoteRequestKe
     quantities: input.quantities,
     addOnSelections: input.addOnSelections,
     adminCustomReceiptLines: input.adminCustomReceiptLines,
+    refundDispositionsByOperationId: Object.fromEntries(
+      Object.entries(input.refundDispositionsByOperationId ?? {}).sort(([a], [b]) => a.localeCompare(b)),
+    ),
     useAdminFeAuthoritativeQuote: input.useAdminFeAuthoritativeQuote,
   });
 }

package/src/components/booking/admin-refund-disposition.ts

@@ -0,0 +1,62 @@
+import type {
+  AdminAmendmentOperationSnapshot,
+  AdminAmendmentRefundDisposition,
+} from '../../lib/booking-api';
+
+export type AdminReleaseRefundDisposition = Exclude<
+  AdminAmendmentRefundDisposition,
+  'REFUND_TO_ORIGINAL_PAYMENT'
+>;
+
+export type AdminRefundDispositionOption = {
+  value: AdminReleaseRefundDisposition;
+  label: string;
+  description: string;
+};
+
+const RELEASE_OPTIONS: AdminRefundDispositionOption[] = [
+  {
+    value: 'PENDING_REFUND',
+    label: 'Record a pending refund',
+    description: 'Save the change with a pending refund for a separate reviewed Stripe action.',
+  },
+  {
+    value: 'NO_REFUND',
+    label: 'No refund',
+    description: 'Remove the paid value without creating a refund or customer credit.',
+  },
+];
+
+export function releaseRefundDispositionOptions(
+  allowed: readonly AdminAmendmentRefundDisposition[] | undefined,
+): AdminRefundDispositionOption[] {
+  if (!allowed) return RELEASE_OPTIONS;
+  return RELEASE_OPTIONS.filter((option) => allowed.includes(option.value));
+}
+
+export function adminRemovalOperationLabel(operation: AdminAmendmentOperationSnapshot): string {
+  const component = operation.componentKey.split(':').slice(1).join(':') || operation.componentKey;
+  const quantity = operation.quantityDelta ? ` (${Math.abs(operation.quantityDelta)})` : '';
+  return `${operation.type.replaceAll('_', ' ').toLowerCase()}: ${component}${quantity}`;
+}
+
+export function refundDecisionsComplete(
+  operations: readonly AdminAmendmentOperationSnapshot[],
+  selections: Readonly<Record<string, AdminAmendmentRefundDisposition>>,
+): boolean {
+  return operations.length > 0 && operations.every((operation) => selections[operation.operationId] != null);
+}
+
+export function noRefundRemovedValue(
+  operations: readonly AdminAmendmentOperationSnapshot[],
+  selections: Readonly<Record<string, AdminAmendmentRefundDisposition>>,
+  removedValueByOperationId: Readonly<Record<string, number>>,
+): number {
+  return operations.reduce(
+    (sum, operation) =>
+      selections[operation.operationId] === 'NO_REFUND'
+        ? sum + (removedValueByOperationId[operation.operationId] ?? 0)
+        : sum,
+    0,
+  );
+}

package/src/components/booking/useAdminChangeCheckoutController.ts

@@ -8,6 +8,8 @@ import {
   isInsufficientCapacityReserveError,
   reportReserveCapacityConflictClientContext,
   type AddOn,
+  type AdminAmendmentOperationSnapshot,
+  type AdminAmendmentRefundDisposition,
   type AdminFeAuthoritativeReceipt,
   type Availability,
   type ChangeBookingQuotePricingDriftDetail,
@@ -82,6 +84,9 @@ export interface AdminChangeLatestQuote {
   pricingVersion?: string;
   quotedTotal?: number;
   paymentCreditTotal?: number;
+  refundDecisionOperations?: AdminAmendmentOperationSnapshot[];
+  allowedRefundDispositionsByOperationId?: Record<string, AdminAmendmentRefundDisposition[]>;
+  removedValueByOperationId?: Record<string, number>;
   serverDisplay?: { total: number; subtotal: number; tax: number };
   quotePreviousTotalCents?: number;
   quoteNewTotalCents?: number;
@@ -131,6 +136,9 @@ export interface UseAdminChangeCheckoutControllerParams {
   providerPricingOverrides: AdminChangeProviderLineOverride[];
   mergedProviderAdditionalAdjustments: AdminChangeProviderAdditionalAdjustment[];
   adminStructuredAdjustments: NonNullable<ProviderDashboardChangeBookingPayload['structuredAdjustments']>;
+  refundDispositionsByOperationId: NonNullable<
+    ProviderDashboardChangeBookingPayload['refundDispositionsByOperationId']
+  >;
   providerApplyAuthoritativeReceipt?: ProviderDashboardChangeBookingPayload['authoritativeReceipt'];
   onSuccess?: ChangeBookingFlowProps['onSuccess'];
   totalPrice: number;
@@ -229,6 +237,7 @@ export function useAdminChangeCheckoutController({
   providerPricingOverrides,
   mergedProviderAdditionalAdjustments,
   adminStructuredAdjustments,
+  refundDispositionsByOperationId,
   providerApplyAuthoritativeReceipt,
   onSuccess,
   totalPrice,
@@ -327,6 +336,7 @@ export function useAdminChangeCheckoutController({
       providerPricingOverrides,
       mergedProviderAdditionalAdjustments,
       adminStructuredAdjustments,
+      refundDispositionsByOperationId,
       providerApplyAuthoritativeReceipt,
       previousPassengerCount: changeFlowInitialTicketCount,
       previousAvailabilityId: initialValues?.availabilityId ?? null,

package/src/components/booking/useAdminChangeQuotePreview.ts

@@ -9,6 +9,7 @@ import {
 import {
   quoteChangeBooking,
   quoteAdminChangeBookingV2,
+  type AdminAmendmentRefundDisposition,
   type AdminFeAuthoritativeReceipt,
   type Availability,
   type ItineraryDisplayStep,
@@ -51,6 +52,7 @@ export interface UseAdminChangeQuotePreviewParams {
   quantities: Record<string, number>;
   addOnSelections: AddOnSelection[];
   adminCustomReceiptLines: AdminCustomReceiptLine[];
+  refundDispositionsByOperationId: Record<string, AdminAmendmentRefundDisposition>;
   useAdminFeAuthoritativeQuote: boolean;
   latestChangeQuote: AdminChangeLatestQuote | null;
   setLatestChangeQuote: Dispatch<SetStateAction<AdminChangeLatestQuote | null>>;
@@ -108,6 +110,7 @@ export function useAdminChangeQuotePreview({
   quantities,
   addOnSelections,
   adminCustomReceiptLines,
+  refundDispositionsByOperationId,
   useAdminFeAuthoritativeQuote,
   latestChangeQuote,
   setLatestChangeQuote,
@@ -151,6 +154,7 @@ export function useAdminChangeQuotePreview({
     !!lastName.trim();
 
   const isChangeQuoteBlocked = isCustomerSelfServeChange && latestChangeQuote?.canProceed === false;
+  const refundDecisionRequired = (latestChangeQuote?.refundDecisionOperations?.length ?? 0) > 0;
   const changeQuoteInputsKey = useMemo(() => buildAdminChangeQuoteRequestKey({
     bookingReference: initialValues?.bookingReference,
     lastName,
@@ -161,6 +165,7 @@ export function useAdminChangeQuotePreview({
     quantities,
     addOnSelections,
     adminCustomReceiptLines,
+    refundDispositionsByOperationId,
     useAdminFeAuthoritativeQuote,
   }), [
     initialValues?.bookingReference,
@@ -172,6 +177,7 @@ export function useAdminChangeQuotePreview({
     quantities,
     addOnSelections,
     adminCustomReceiptLines,
+    refundDispositionsByOperationId,
     useAdminFeAuthoritativeQuote,
   ]);
   const destinationRequiresReturnSelection = Boolean(selectedAvailability?.returnOptions?.length);
@@ -228,7 +234,9 @@ export function useAdminChangeQuotePreview({
   const checkoutFormError =
     (error || '') ||
     (missingRequiredReturnSelection ? 'Please select a return time for this product.' : '') ||
-    (isCustomerSelfServeChange && isChangeQuoteBlocked ? (latestChangeQuote?.reasonIfBlocked ?? '') : '') ||
+    (isCustomerSelfServeChange && isChangeQuoteBlocked && !refundDecisionRequired
+      ? (latestChangeQuote?.reasonIfBlocked ?? '')
+      : '') ||
     (isCustomerSelfServeChange ? changeQuoteFetchError ?? '' : '');
 
   const changeFlowSelectionPreview = useMemo((): ChangeFlowSelectionPreview | null => {
@@ -407,6 +415,9 @@ export function useAdminChangeQuotePreview({
             ...(adminCustomLinesAsAdditionalAdjustments.length > 0
               ? { manualLineAdjustments: adminCustomLinesAsAdditionalAdjustments }
               : {}),
+            ...(Object.keys(refundDispositionsByOperationId).length > 0
+              ? { refundDispositionsByOperationId }
+              : {}),
             clientProposedTotal: changeFlowNewBookingTotal,
             capacitySeatCredit: {
               enabled: true,

package/src/lib/booking/change-flow-pricing.ts

@@ -256,6 +256,9 @@ export interface ChangeQuoteUiSlice {
   pricingVersion?: string;
   quotedTotal?: number;
   paymentCreditTotal?: number;
+  refundDecisionOperations?: ChangeBookingQuoteResponse['refundDecisionOperations'];
+  allowedRefundDispositionsByOperationId?: ChangeBookingQuoteResponse['allowedRefundDispositionsByOperationId'];
+  removedValueByOperationId?: ChangeBookingQuoteResponse['removedValueByOperationId'];
   serverDisplay?: { total: number; subtotal: number; tax: number };
 }
 
@@ -291,6 +294,9 @@ export function sliceChangeQuoteForUi(
     pricingVersion: pricingQuote?.pricingVersion ?? undefined,
     quotedTotal: pricingQuote?.payableTotal ?? pricingQuote?.totalAmount ?? quote.proposed?.total ?? quote.newReceipt?.total,
     paymentCreditTotal: pricingQuote?.paymentCreditTotal ?? quote.paymentCreditTotal,
+    refundDecisionOperations: quote.refundDecisionOperations,
+    allowedRefundDispositionsByOperationId: quote.allowedRefundDispositionsByOperationId,
+    removedValueByOperationId: quote.removedValueByOperationId,
     ...(serverDisplay ? { serverDisplay } : {}),
   };
 }

package/src/lib/booking-api.ts

@@ -1246,6 +1246,22 @@ export interface CreatePaymentIntentResponse {
   pricingQuoteInputsHash?: string | null;
 }
 
+export type AdminAmendmentRefundDisposition =
+  | 'REFUND_TO_ORIGINAL_PAYMENT'
+  | 'PENDING_REFUND'
+  | 'NO_REFUND';
+
+export interface AdminAmendmentOperationSnapshot {
+  operationId: string;
+  type: string;
+  componentKey: string;
+  quantityDelta?: number;
+  oldIdentity?: string | null;
+  targetIdentity?: string | null;
+  changedFields?: string[];
+  metadata?: Record<string, string>;
+}
+
 export interface ChangeBookingQuoteRequest {
   bookingReference: string;
   lastName: string;
@@ -1275,6 +1291,8 @@ export interface ChangeBookingQuoteRequest {
     previousAvailabilityId?: string | null;
     previousReturnAvailabilityId?: string | null;
   } | null;
+  /** Explicit admin treatment for server-classified removed paid value. Never defaulted by the client. */
+  refundDispositionsByOperationId?: Record<string, AdminAmendmentRefundDisposition>;
 }
 
 /** FE-authored receipt payload for admin quote path (major units, booking currency). */
@@ -1316,6 +1334,9 @@ export interface AdminChangeBookingQuoteV2Data {
   canApply: boolean;
   reasonIfBlocked?: string | null;
   unsupportedFeatures?: string[];
+  refundDecisionOperations?: AdminAmendmentOperationSnapshot[];
+  allowedRefundDispositionsByOperationId?: Record<string, AdminAmendmentRefundDisposition[]>;
+  removedValueByOperationId?: Record<string, number>;
 }
 
 export interface ChangeBookingQuoteReceipt {
@@ -1452,6 +1473,12 @@ export interface ChangeBookingQuoteResponse {
   currency?: string;
   canProceed?: boolean;
   reasonIfBlocked?: string;
+  /** Admin-only removal decisions required before this quote can be applied. */
+  refundDecisionOperations?: AdminAmendmentOperationSnapshot[];
+  /** Server-authorized choices. Release UI intentionally filters out immediate refund. */
+  allowedRefundDispositionsByOperationId?: Record<string, AdminAmendmentRefundDisposition[]>;
+  /** Original paid basis plus allocated refundable tax for each removal operation. */
+  removedValueByOperationId?: Record<string, number>;
   /** When price check fails / disagrees: optional breakdown for UI line-vs-line comparison. */
   pricingDriftDetail?: ChangeBookingQuotePricingDriftDetail;
   /** Optional BE debug: receipt-floor vs catalog ticket math (same-parent Rule A/B). */
@@ -1621,6 +1648,41 @@ export async function quoteChangeBookingAdminFeReceipt(
     data) as ChangeBookingQuoteResponse;
 }
 
+export function mapAdminChangeBookingQuoteV2Data(
+  data: AdminChangeBookingQuoteV2Data,
+): ChangeBookingQuoteResponse {
+  const oldReceipt = data.oldReceipt;
+  const newQuote = data.newQuote ?? null;
+  const currency = newQuote?.currency ?? oldReceipt.currency ?? undefined;
+  return {
+    pricingQuote: newQuote,
+    quote: newQuote,
+    balanceDelta: data.balanceDelta ?? newQuote?.balanceDelta ?? undefined,
+    amountToCharge: data.amountToCharge ?? newQuote?.amountToCharge ?? undefined,
+    refundCandidate: data.refundCandidate ?? newQuote?.refundCandidate ?? undefined,
+    priceDiff: data.balanceDelta ?? newQuote?.balanceDelta ?? 0,
+    currency: currency ?? undefined,
+    canProceed: data.canApply,
+    reasonIfBlocked: data.reasonIfBlocked ?? undefined,
+    refundDecisionOperations: data.refundDecisionOperations ?? [],
+    allowedRefundDispositionsByOperationId:
+      data.allowedRefundDispositionsByOperationId ?? {},
+    removedValueByOperationId: data.removedValueByOperationId ?? {},
+    originalReceipt: {
+      subtotal: oldReceipt.grossSubtotal ?? undefined,
+      tax: oldReceipt.taxAmount ?? undefined,
+      total: oldReceipt.payableTotal ?? 0,
+      currency: oldReceipt.currency ?? undefined,
+      lineItems: oldReceipt.lines?.map((line) => ({
+        label: line.label ?? undefined,
+        amount: line.amount ?? undefined,
+        type: line.type ?? undefined,
+        quantity: line.quantity ?? undefined,
+      })),
+    },
+  };
+}
+
 /** Server-authoritative Pricing V2 quote used by the provider-dashboard amendment preview. */
 export async function quoteAdminChangeBookingV2(
   request: ChangeBookingQuoteRequest
@@ -1665,33 +1727,7 @@ export async function quoteAdminChangeBookingV2(
   ) {
     throw new Error('Invalid admin Pricing V2 quote response');
   }
-  const data = candidate as AdminChangeBookingQuoteV2Data;
-  const oldReceipt = data.oldReceipt;
-  const newQuote = data.newQuote ?? null;
-  const currency = newQuote?.currency ?? oldReceipt.currency ?? undefined;
-  return {
-    pricingQuote: newQuote,
-    quote: newQuote,
-    balanceDelta: data.balanceDelta ?? newQuote?.balanceDelta ?? undefined,
-    amountToCharge: data.amountToCharge ?? newQuote?.amountToCharge ?? undefined,
-    refundCandidate: data.refundCandidate ?? newQuote?.refundCandidate ?? undefined,
-    priceDiff: data.balanceDelta ?? newQuote?.balanceDelta ?? 0,
-    currency: currency ?? undefined,
-    canProceed: data.canApply,
-    reasonIfBlocked: data.reasonIfBlocked ?? undefined,
-    originalReceipt: {
-      subtotal: oldReceipt.grossSubtotal ?? undefined,
-      tax: oldReceipt.taxAmount ?? undefined,
-      total: oldReceipt.payableTotal ?? 0,
-      currency: oldReceipt.currency ?? undefined,
-      lineItems: oldReceipt.lines?.map((line) => ({
-        label: line.label ?? undefined,
-        amount: line.amount ?? undefined,
-        type: line.type ?? undefined,
-        quantity: line.quantity ?? undefined,
-      })),
-    },
-  };
+  return mapAdminChangeBookingQuoteV2Data(candidate as AdminChangeBookingQuoteV2Data);
 }
 
 export async function createChangeBookingPaymentIntent(

package/test/change-booking-helpers.test.ts

@@ -5,9 +5,20 @@ import {
 } from '../src/components/booking/change-booking-payment-modal-builders';
 import { evaluateChangeBookingQuoteForCheckout } from '../src/components/booking/change-booking-quote-guards';
 import { buildCheckoutModalSummaryFromPricingV2Quote } from '../src/components/booking/pricing-v2-checkout-summary';
-import type { ChangeQuoteUiSlice } from '../src/lib/booking/change-flow-pricing';
-import type { ChangeBookingQuoteResponse } from '../src/lib/booking-api';
+import {
+  sliceChangeQuoteForUi,
+  type ChangeQuoteUiSlice,
+} from '../src/lib/booking/change-flow-pricing';
+import {
+  mapAdminChangeBookingQuoteV2Data,
+  type ChangeBookingQuoteResponse,
+} from '../src/lib/booking-api';
 import { buildAdminChangeQuoteRequestKey } from '../src/components/booking/admin-change-quote-request-key';
+import {
+  noRefundRemovedValue,
+  refundDecisionsComplete,
+  releaseRefundDispositionOptions,
+} from '../src/components/booking/admin-refund-disposition';
 import {
   applyResourceAdjustments,
   privateShuttlePriceChanged,
@@ -127,6 +138,87 @@ test('admin quote response display state cannot invalidate its request identity'
   assert.equal(keyAfterResponse, keyBeforeResponse);
 });
 
+test('admin removal quote preserves explicit release refund decisions for the preview', () => {
+  const operation = {
+    operationId: 'op_remove_adult',
+    type: 'REMOVE_QUANTITY',
+    componentKey: 'ticket:ADULT',
+    quantityDelta: -1,
+  };
+  const mapped = mapAdminChangeBookingQuoteV2Data({
+    oldReceipt: { currency: 'CAD', grossSubtotal: 357.46, taxAmount: 30.38, payableTotal: 387.84 },
+    newQuote: { currency: 'CAD', payableTotal: 193.92, balanceDelta: 0, amountToCharge: 0, refundCandidate: 0 },
+    canApply: false,
+    reasonIfBlocked: 'admin_refund_disposition_required',
+    refundDecisionOperations: [operation],
+    allowedRefundDispositionsByOperationId: {
+      [operation.operationId]: [
+        'REFUND_TO_ORIGINAL_PAYMENT',
+        'PENDING_REFUND',
+        'NO_REFUND',
+      ],
+    },
+    removedValueByOperationId: { [operation.operationId]: 193.92 },
+  });
+  const slice = sliceChangeQuoteForUi(
+    mapped,
+    { total: 193.92, subtotal: 178.73, tax: 15.19 },
+    'CAD',
+  );
+
+  assert.deepEqual(slice.refundDecisionOperations, [operation]);
+  assert.equal(slice.removedValueByOperationId?.[operation.operationId], 193.92);
+  assert.deepEqual(
+    releaseRefundDispositionOptions(
+      slice.allowedRefundDispositionsByOperationId?.[operation.operationId],
+    ).map((option) => option.value),
+    ['PENDING_REFUND', 'NO_REFUND'],
+  );
+  assert.equal(refundDecisionsComplete([operation], {}), false);
+  assert.equal(refundDecisionsComplete([operation], { [operation.operationId]: 'NO_REFUND' }), true);
+  assert.equal(
+    noRefundRemovedValue(
+      [operation],
+      { [operation.operationId]: 'NO_REFUND' },
+      { [operation.operationId]: 193.92 },
+    ),
+    193.92,
+  );
+});
+
+test('changing admin refund treatment creates a distinct authoritative quote request', () => {
+  const base = {
+    bookingReference: 'DE8H04DX',
+    lastName: 'Tauro',
+    productId: 'p_1',
+    selectedAvailability: {
+      availabilityId: 'a_1',
+      productId: 'po_1',
+      dateTime: '2026-07-21T03:00:00-06:00',
+      vacancies: 10,
+    } as Parameters<typeof buildAdminChangeQuoteRequestKey>[0]['selectedAvailability'],
+    pickupLocationId: 'pickup_1',
+    returnAvailabilityId: 'return_1',
+    quantities: { ADULT: 1 },
+    addOnSelections: [],
+    adminCustomReceiptLines: [],
+    useAdminFeAuthoritativeQuote: true,
+  };
+
+  const undecided = buildAdminChangeQuoteRequestKey(base);
+  const pending = buildAdminChangeQuoteRequestKey({
+    ...base,
+    refundDispositionsByOperationId: { op_remove_adult: 'PENDING_REFUND' },
+  });
+  const noRefund = buildAdminChangeQuoteRequestKey({
+    ...base,
+    refundDispositionsByOperationId: { op_remove_adult: 'NO_REFUND' },
+  });
+
+  assert.notEqual(undecided, pending);
+  assert.notEqual(pending, noRefund);
+});
+
 test('private shuttle pricing replaces the selected calendar summary with hydrated rate details', () => {
   const selectedSummary = {
     availabilityId: 'a_private',