@ticketboothapp/booking 1.2.174 → 1.2.176

package/package.json

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

package/src/components/booking/AdminChangeBookingFlow.tsx

@@ -833,6 +833,28 @@ export function AdminChangeBookingFlow({
     latestChangeQuote?.allowedRefundDispositionsByOperationId,
     latestChangeQuote?.removedValueByOperationId,
   ]);
+  useEffect(() => {
+    if (!isProviderDashboardChange || responseRefundDecisionOperations.length === 0) return;
+    setRefundDispositionsByOperationId((current) =>
+      defaultPendingRefundDispositions(responseRefundDecisionOperations, current),
+    );
+  }, [isProviderDashboardChange, responseRefundDecisionOperations]);
+  const handleRefundDecisionDiscovery = useCallback((quote: AdminChangeLatestQuote) => {
+    const operations = quote.refundDecisionOperations ?? [];
+    if (operations.length === 0) return;
+    setRefundDecisionContext((current) => mergeAdminRefundDecisionContext({
+      current,
+      selectionKey: refundDecisionSelectionKey,
+      operations,
+      allowedByOperationId: quote.allowedRefundDispositionsByOperationId ?? {},
+      removedValueByOperationId: quote.removedValueByOperationId ?? {},
+    }));
+    if (isProviderDashboardChange) {
+      setRefundDispositionsByOperationId((current) =>
+        defaultPendingRefundDispositions(operations, current),
+      );
+    }
+  }, [isProviderDashboardChange, refundDecisionSelectionKey]);
   const activeRefundDecisionContext = useMemo(() => mergeAdminRefundDecisionContext({
     current: refundDecisionContext,
     selectionKey: refundDecisionSelectionKey,
@@ -851,19 +873,9 @@ export function AdminChangeBookingFlow({
       ? responseReturnPriceTreatmentOperations
       : [];
   const activeRefundDispositionsByOperationId = useMemo(() => {
-    // Provider changes default discovered refund operations to pending at
-    // settlement time. Do not write those response-derived defaults into the
-    // explicit input state: doing so changes the request key after the first
-    // quote and immediately triggers an identical second quote.
-    const dispositionsWithPendingRefundDefaults = isProviderDashboardChange
-      ? defaultPendingRefundDispositions(
-          activeRefundDecisionContext?.operations ?? [],
-          refundDispositionsByOperationId,
-        )
-      : refundDispositionsByOperationId;
     const dispositionsWithReturnPriceDefaults = defaultKeepOriginalReturnPriceDispositions(
       activeReturnPriceTreatmentOperations,
-      dispositionsWithPendingRefundDefaults,
+      refundDispositionsByOperationId,
     );
     return selectRefundDispositionsForOperations(
       activeRefundDecisionContext,
@@ -873,7 +885,6 @@ export function AdminChangeBookingFlow({
   }, [
     activeRefundDecisionContext?.operations,
     activeReturnPriceTreatmentOperations,
-    isProviderDashboardChange,
     refundDispositionsByOperationId,
   ]);
   const handleRefundDispositionChange = useCallback((
@@ -915,12 +926,11 @@ export function AdminChangeBookingFlow({
     adminReverseAdjustmentIds,
     needsAdjustmentDiscovery:
       isProviderDashboardChange && !hasHydratedExistingAdjustments,
-    // Only explicit user inputs belong to quote identity. Automatic provider
-    // defaults are derived separately for settlement/submission below.
-    refundDispositionsByOperationId,
+    refundDispositionsByOperationId: activeRefundDispositionsByOperationId,
     useAdminFeAuthoritativeQuote,
     latestChangeQuote,
     setLatestChangeQuote,
+    onRefundDecisionDiscovery: handleRefundDecisionDiscovery,
     changeQuoteLoading,
     setChangeQuoteLoading,
     changeQuoteFetchError,

package/src/components/booking/AdminChangeCheckoutPanel.tsx

@@ -21,6 +21,10 @@ import {
   AdminChangePricingMessages,
   type AdminCustomReceiptLine,
 } from './AdminChangePricingPanel';
+import {
+  adminChangeSettlementSummaryLabel,
+  dedupeAdminChangeCheckoutError,
+} from './admin-change-checkout-message';
 
 type TranslationFn = (key: string, params?: Record<string, string>) => string;
 
@@ -213,12 +217,15 @@ export function AdminChangeCheckoutPanel({
   lineLabelInputs,
 }: AdminChangeCheckoutPanelProps) {
   const authoritativeAmountDue = serverAmountDue ?? changeFlowAmountDue;
-  const totalSummaryLabel =
-    (serverRefundCandidate ?? 0) > 0.005
-      ? 'Amount to refund customer'
-      : authoritativeAmountDue > 0.005
-        ? 'Amount due from customer'
-        : 'No payment or refund due';
+  const totalSummaryLabel = adminChangeSettlementSummaryLabel({
+    amountDue: authoritativeAmountDue,
+    refundCandidate: serverRefundCandidate ?? 0,
+    serverQuoteError,
+  });
+  const checkoutError = dedupeAdminChangeCheckoutError({
+    checkoutError: error,
+    serverQuoteError,
+  });
   const pricingAdjustments = (
     <AdminChangePricingAdjustments
       showChangeFlowManualPriceLines={showChangeFlowManualPriceLines}
@@ -346,7 +353,7 @@ export function AdminChangeCheckoutPanel({
       disableAutoCommunications={disableAutoCommunications}
       onSkipConfirmationChange={onSkipConfirmationChange}
       onDisableCommunicationsChange={onDisableCommunicationsChange}
-      error={error}
+      error={checkoutError}
       loading={loading}
       totalQuantity={totalQuantity}
       onCheckout={onCheckout}

package/src/components/booking/ChangeBookingFlow.tsx

@@ -61,6 +61,7 @@ import { useBookingQuantityCapTrim } from './useBookingQuantityCapTrim';
 import { useBookingViewItemAnalytics } from './useBookingViewItemAnalytics';
 import type { ChangeBookingMergedQuoteState } from './change-booking-quote-state';
 import { AdminChangeReceiptComparison } from './AdminChangeReceiptComparison';
+import { dedupeChangeBookingCheckoutError } from './change-booking-error-message';
 
 export type { ChangeBookingFlowProps } from './booking-flow-types';
 
@@ -668,6 +669,17 @@ export function ChangeBookingFlow({
     onChangeFlowSelectionPreview,
     onPricePreviewChange,
   });
+  const displayedQuoteError = selfServeCheckoutPlaceholder
+    ? changeQuoteFetchError ?? (
+      latestChangeQuote?.canProceed === false
+        ? latestChangeQuote.reasonIfBlocked
+        : null
+    )
+    : null;
+  const visibleCheckoutFormError = dedupeChangeBookingCheckoutError({
+    checkoutError: checkoutFormError,
+    displayedQuoteError,
+  });
   /** Partner deferred-invoice path applies to {@link NewBookingFlow} only. */
   const deferredInvoiceSubmitLabel = undefined;
 
@@ -975,7 +987,7 @@ export function ChangeBookingFlow({
               termsAccepted={termsAccepted}
               onTermsAcceptedChange={setTermsAccepted}
               onTermsAcceptedAtChange={setTermsAcceptedAt}
-              error={checkoutFormError}
+              error={visibleCheckoutFormError}
               loading={loading}
               totalQuantity={totalQuantity}
               onCheckout={handleCheckout}

package/src/components/booking/PrivateShuttleBookingFlow.tsx

@@ -32,6 +32,7 @@ import { PrivateShuttleStartTimeSection } from './PrivateShuttleStartTimeSection
 import {
   getPrivateShuttleAvailabilityOptionId,
   privateShuttleBookingCutoffMessage,
+  privateShuttleEndTimeLabel,
   privateShuttleInitialDateKey,
   privateShuttleStartDateTime,
   privateShuttleStartTimeAllowed,
@@ -53,6 +54,10 @@ import {
 import { usePrivateShuttlePromoController } from './usePrivateShuttlePromoController';
 import { useBookingViewItemAnalytics } from './useBookingViewItemAnalytics';
 import { resolvePrivateShuttleCancellationPolicyId } from './private-shuttle-cancellation-policy';
+import {
+  privateShuttleTermsInitiallyAccepted,
+  resolveInitialPrivateShuttlePassengerCount,
+} from './private-shuttle-passenger-count';
 
 interface PrivateShuttleBookingFlowProps {
   product: Product;
@@ -144,7 +149,11 @@ export function PrivateShuttleBookingFlow({
   const [selectedStartTime, setSelectedStartTime] = useState<string>('');
   const [isCustomTimeMode, setIsCustomTimeMode] = useState(false);
   const [passengerCount, setPassengerCount] = useState<number>(
-    () => initialBooking?.privateShuttleDetails?.passengerCount ?? initialValues?.passengers ?? 1
+    () => resolveInitialPrivateShuttlePassengerCount({
+      privateShuttleDetails: initialBooking?.privateShuttleDetails,
+      bookingItems: initialBooking?.bookingItems,
+      initialPassengers: initialValues?.passengers,
+    })
   );
   const [email, setEmail] = useState(() => initialBooking?.customer?.email?.trim() ?? '');
   const [firstName, setFirstName] = useState(
@@ -181,7 +190,9 @@ export function PrivateShuttleBookingFlow({
   const [loading, setLoading] = useState(false);
   const [bookingCutoffNowMs, setBookingCutoffNowMs] = useState(() => Date.now());
   const [error, setError] = useState('');
-  const [termsAccepted, setTermsAccepted] = useState(false);
+  const [termsAccepted, setTermsAccepted] = useState(
+    () => privateShuttleTermsInitiallyAccepted(isProviderChangeMode)
+  );
   const [termsAcceptedAt, setTermsAcceptedAt] = useState<string | null>(null);
   const [partnerAttributionConfirmed, setPartnerAttributionConfirmed] = useState(false);
   const [skipConfirmationCommunications, setSkipConfirmationCommunications] = useState(false);
@@ -634,6 +645,17 @@ export function PrivateShuttleBookingFlow({
       timesNote?: string;
       isProposedStops?: boolean;
     }> = [];
+    const pickupLabel = pickupLocationSkipped
+      ? (t('booking.pickupLocationUnknown') || "I don't know")
+      : customPickupAddress
+        ? customPickupAddress
+        : selectedPickupLocation?.name;
+    items.push({
+      time: selectedStartTime,
+      label: pickupLabel || (t('booking.pickupAt') || 'Pickup'),
+      clickableLabel: !pickupLocationId && !customPickupAddress && !pickupLocationSkipped ? (t('pickup.title') || 'Select pickup') : undefined,
+      prefix: t('booking.pickupAtPrefix') || 'Pickup at ',
+    });
     const destMap = product.itineraryBuilder?.destinations
       ? new Map(product.itineraryBuilder.destinations.map((d) => [d.id, d.label]))
       : new Map<string, string>();
@@ -648,27 +670,35 @@ export function PrivateShuttleBookingFlow({
         timesNote: t('booking.orderAndTimesToBeConfirmed') || '(order and times to be confirmed)',
       });
     }
-    const pickupLabel = pickupLocationSkipped
-      ? (t('booking.pickupLocationUnknown') || "I don't know")
-      : customPickupAddress
-        ? customPickupAddress
-        : selectedPickupLocation?.name;
-    items.push({
-      time: selectedStartTime,
-      label: pickupLabel || (t('booking.pickupAt') || 'Pickup'),
-      clickableLabel: !pickupLocationId && !customPickupAddress && !pickupLocationSkipped ? (t('pickup.title') || 'Select pickup') : undefined,
-      prefix: t('booking.pickupAtPrefix') || 'Pickup at ',
-    });
+    const durationMinutes =
+      (privateShuttleConfig?.baseDurationMinutes ?? 0) + additionalHoursCount * 60;
+    const dropOffTime = privateShuttleEndTimeLabel(
+      selectedDate,
+      selectedStartTime,
+      companyTimezone,
+      durationMinutes,
+    );
+    if (dropOffTime) {
+      items.push({
+        time: dropOffTime,
+        label: pickupLabel || (t('booking.pickupAt') || 'Pickup'),
+        prefix: t('booking.dropOffAtPrefix') || 'Drop off at ',
+      });
+    }
     return items;
   }, [
     selectedOption,
     selectedStartTime,
+    selectedDate,
     draftItineraryDestinations,
     customPickupAddress,
     selectedPickupLocation,
     pickupLocationSkipped,
     pickupLocationId,
     product.itineraryBuilder,
+    privateShuttleConfig?.baseDurationMinutes,
+    additionalHoursCount,
+    companyTimezone,
     t,
   ]);
 

package/src/components/booking/admin-change-checkout-message.ts

@@ -0,0 +1,34 @@
+import { friendlyChangeBookingError } from './change-booking-error-message';
+
+interface AdminChangeSettlementSummaryLabelInput {
+  amountDue: number;
+  refundCandidate: number;
+  serverQuoteError?: string | null;
+}
+
+export function adminChangeSettlementSummaryLabel({
+  amountDue,
+  refundCandidate,
+  serverQuoteError,
+}: AdminChangeSettlementSummaryLabelInput): string {
+  if (friendlyChangeBookingError(serverQuoteError)) return 'Price unavailable';
+  if (refundCandidate > 0.005) return 'Amount to refund customer';
+  if (amountDue > 0.005) return 'Amount due from customer';
+  return 'No payment or refund due';
+}
+
+interface AdminChangeCheckoutErrorInput {
+  checkoutError: string;
+  serverQuoteError?: string | null;
+}
+
+export function dedupeAdminChangeCheckoutError({
+  checkoutError,
+  serverQuoteError,
+}: AdminChangeCheckoutErrorInput): string {
+  const readableCheckoutError = friendlyChangeBookingError(checkoutError);
+  const readableServerQuoteError = friendlyChangeBookingError(serverQuoteError);
+  return readableServerQuoteError && readableCheckoutError === readableServerQuoteError
+    ? ''
+    : checkoutError;
+}

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

@@ -29,6 +29,12 @@ interface AdminChangeQuoteRequestGateInput {
   missingRequiredReturnSelection: boolean;
 }
 
+interface AdminRefundDecisionDiscoveryInput {
+  isProviderDashboardChange: boolean;
+  canProceed: boolean | undefined;
+  refundDecisionCount: number;
+}
+
 /**
  * Whether the current admin inputs are complete enough to request an authoritative quote.
  * `hasEffectiveChangeSelection` deliberately includes adjustment-only changes, even when
@@ -83,3 +89,14 @@ export function canReuseCompletedAdminChangeQuote(
 ): boolean {
   return Boolean(inputKey) && lastCompletedInputKey === inputKey && hasPublishedQuote;
 }
+
+/** A blocked quote with decision operations is protocol state, not display state. */
+export function isAdminRefundDecisionDiscoveryQuote(
+  input: AdminRefundDecisionDiscoveryInput,
+): boolean {
+  return Boolean(
+    input.isProviderDashboardChange &&
+      input.canProceed === false &&
+      input.refundDecisionCount > 0,
+  );
+}

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

@@ -107,3 +107,17 @@ export async function quoteAdminChangeV2ForUi(
   const quote = await quoteFn(request);
   return sliceAndMergeChangeQuoteForUi(quote, fallbackCart, currency).mergedQuote;
 }
+
+/**
+ * Checkout must apply the immutable quote the operator reviewed in the UI. Re-quoting during
+ * submit creates a different quote identity and breaks the review/apply audit trail even when
+ * the inputs and totals happen to be identical.
+ */
+export function requireReviewedAdminChangeQuoteForCheckout<
+  T extends { quoteId?: string; canProceed: boolean; reasonIfBlocked?: string },
+>(quote: T | null): T {
+  if (!quote?.quoteId?.trim() || quote.canProceed === false) {
+    throw new Error(quote?.reasonIfBlocked || 'The reviewed change quote is not ready.');
+  }
+  return quote;
+}

package/src/components/booking/change-booking-error-message.ts

@@ -17,6 +17,8 @@ const CHANGE_BOOKING_ERROR_MESSAGES: Record<string, string> = {
     'A confirmed price is not available for the selected return. Choose another return time.',
   pricing_v2_itinerary_not_available:
     'An itinerary is not available for this selection. Choose another date, time, or pickup location.',
+  private_shuttle_itinerary_endpoints_required:
+    'The private-tour itinerary is incomplete. Reopen the change and select the pickup time and location again.',
   pricing_v2_invalid_additional_hours:
     'Review the number of additional hours before continuing.',
   pricing_v2_additional_hours_not_supported:
@@ -54,11 +56,11 @@ const CHANGE_BOOKING_ERROR_MESSAGES: Record<string, string> = {
   amendment_quote_blocked:
     'This booking change cannot be completed with the selected options.',
   admin_ledger_requires_review_or_repair:
-    'This booking needs a financial review before it can be changed.',
+    "This older booking's pricing and payment history must be reviewed before it can be changed. Please contact support.",
   amendment_ledger_summary_missing:
-    'This booking needs a financial review before it can be changed.',
+    "This older booking hasn't been prepared for changes yet. Please contact support to prepare it, then reopen the booking.",
   amendment_ledger_components_missing:
-    'This booking needs a financial review before it can be changed.',
+    "This older booking's pricing details are incomplete, so it can't be changed safely. Please contact support.",
   booking_amendment_ledger_pointer_mismatch:
     'This booking changed after the page was opened. Refresh it before trying again.',
   promo_change_only_no_eligible_new_value:
@@ -91,7 +93,7 @@ export function incompatibleAddOnChangeError(
 
 function errorCodeFromMessage(message: string): string | null {
   const match = message.match(
-    /\b(?:pricing_v2|apply_v2|promo|admin|amendment|booking_amendment|quote|structured_adjustment)_[a-z0-9_]+/i,
+    /\b(?:pricing_v2|apply_v2|promo|admin|amendment|booking_amendment|private_shuttle|quote|structured_adjustment)_[a-z0-9_]+/i,
   );
   return match?.[0]?.toLowerCase() ?? null;
 }
@@ -135,3 +137,23 @@ export function friendlyChangeBookingError(message: string | null | undefined):
 
   return 'This booking change cannot be completed with the selected options. Review the selections and try again.';
 }
+
+interface ChangeBookingCheckoutErrorInput {
+  checkoutError: string;
+  displayedQuoteError?: string | null;
+}
+
+/**
+ * The quote-status panel already renders blocked/fetch errors beside the price.
+ * Do not repeat that same friendly message in the checkout form's error slot.
+ */
+export function dedupeChangeBookingCheckoutError({
+  checkoutError,
+  displayedQuoteError,
+}: ChangeBookingCheckoutErrorInput): string {
+  const readableCheckoutError = friendlyChangeBookingError(checkoutError);
+  const readableDisplayedQuoteError = friendlyChangeBookingError(displayedQuoteError);
+  return readableDisplayedQuoteError && readableCheckoutError === readableDisplayedQuoteError
+    ? ''
+    : checkoutError;
+}

package/src/components/booking/private-shuttle-availability.ts

@@ -1,4 +1,4 @@
-import { parseISO } from 'date-fns';
+import { addMinutes, parseISO } from 'date-fns';
 import { formatInTimeZone, fromZonedTime } from 'date-fns-tz';
 
 import type { Availability } from '../../lib/booking-api';
@@ -38,6 +38,20 @@ export function privateShuttleStartDateTime(dateStr: string, timeStr: string, ti
   return fromZonedTime(parseISO(`${dateStr}T${timeStr}:00`), timezone);
 }
 
+export function privateShuttleEndTimeLabel(
+  dateStr: string,
+  timeStr: string,
+  timezone: string,
+  durationMinutes: number,
+): string | null {
+  if (!dateStr || !timeStr || !Number.isFinite(durationMinutes) || durationMinutes <= 0) return null;
+  return formatInTimeZone(
+    addMinutes(privateShuttleStartDateTime(dateStr, timeStr, timezone), durationMinutes),
+    timezone,
+    'HH:mm',
+  );
+}
+
 export function privateShuttleStartTimeAllowed(
   dateStr: string,
   timeStr: string,

package/src/components/booking/private-shuttle-passenger-count.ts

@@ -0,0 +1,50 @@
+type InitialPrivateShuttlePassengerCountInput = {
+  privateShuttleDetails?: {
+    passengerCount?: number | null;
+    requestedPassengerCount?: number | null;
+  } | null;
+  bookingItems?: ReadonlyArray<{
+    category?: string | null;
+    count?: number | null;
+  }> | null;
+  initialPassengers?: number | null;
+};
+
+function positiveWholeNumber(value: number | null | undefined): number | null {
+  if (!Number.isFinite(value) || Number(value) <= 0) return null;
+  return Math.floor(Number(value));
+}
+
+/**
+ * Seed the people count when entering the private-shuttle flow.
+ *
+ * Existing private bookings persist an explicit passenger count while standard
+ * bookings persist one booking item per passenger category. RESOURCE is the
+ * number of shuttles being sold, not the number of people, and must never be
+ * treated as a passenger count during a product-family conversion.
+ */
+export function resolveInitialPrivateShuttlePassengerCount({
+  privateShuttleDetails,
+  bookingItems,
+  initialPassengers,
+}: InitialPrivateShuttlePassengerCountInput): number {
+  const explicitPrivateCount =
+    positiveWholeNumber(privateShuttleDetails?.requestedPassengerCount) ??
+    positiveWholeNumber(privateShuttleDetails?.passengerCount);
+  if (explicitPrivateCount != null) return explicitPrivateCount;
+
+  const explicitInitialCount = positiveWholeNumber(initialPassengers);
+  if (explicitInitialCount != null) return explicitInitialCount;
+
+  const standardPassengerCount = (bookingItems ?? []).reduce((total, item) => {
+    if (item.category?.trim().toUpperCase() === 'RESOURCE') return total;
+    return total + (positiveWholeNumber(item.count) ?? 0);
+  }, 0);
+
+  return standardPassengerCount > 0 ? standardPassengerCount : 1;
+}
+
+/** Existing bookings already captured terms acceptance; fresh bookings must opt in. */
+export function privateShuttleTermsInitiallyAccepted(isProviderChangeMode: boolean): boolean {
+  return isProviderChangeMode;
+}

package/src/components/booking/private-shuttle-reservation-runner.ts

@@ -88,7 +88,7 @@ export function buildPrivateShuttleItineraryDisplayForStorage(
   itineraryDisplayItems: PrivateShuttleCheckoutItineraryItem[]
 ): ItineraryDisplayStep[] {
   let hasPickup = false;
-  return itineraryDisplayItems.map((item) => {
+  const steps = itineraryDisplayItems.map((item) => {
     if (item.isProposedStops) {
       return {
         stepType: ItineraryStepType.draft,
@@ -104,6 +104,14 @@ export function buildPrivateShuttleItineraryDisplayForStorage(
       place: item.clickableLabel ?? item.label,
     };
   });
+  if (
+    steps.length > 0 &&
+    (steps[0]?.stepType !== ItineraryStepType.pickup ||
+      steps[steps.length - 1]?.stepType !== ItineraryStepType.drop_off)
+  ) {
+    throw new Error('Private shuttle itinerary requires fixed pickup and drop-off endpoints.');
+  }
+  return steps;
 }
 
 export async function reservePrivateShuttleForCheckout({

package/src/components/booking/useAdminChangeCheckoutController.ts

@@ -71,8 +71,7 @@ import {
   quoteAdminCustomerChangeForCheckout,
 } from './admin-change-customer-quote-runner';
 import {
-  buildAdminChangeV2QuoteRequest,
-  quoteAdminChangeV2ForUi,
+  requireReviewedAdminChangeQuoteForCheckout,
 } from './admin-change-v2-quote-request';
 import {
   reservationHoldHasExpired,
@@ -482,40 +481,11 @@ export function useAdminChangeCheckoutController({
       let authoritativeChangeQuoteForCheckout = latestChangeQuote;
 
       if (isProviderDashboardChange && isChangeBookingContext) {
-        const bookingReference = initialValues?.bookingReference?.trim();
-        if (!bookingReference) throw new Error('Missing booking reference.');
-        authoritativeChangeQuoteForCheckout = await quoteAdminChangeV2ForUi(
-          buildAdminChangeV2QuoteRequest({
-            bookingReference,
-            lastName,
-            parentProductId: product.productId,
-            optionId: availabilityProductOptionId,
-            selectedAvailability,
-            pickupLocationId,
-            returnAvailabilityId: selectedReturnOption?.returnAvailabilityId ?? null,
-            bookingItems,
-            addOnSelections,
-            cancellationPolicyId,
-            promoCode: appliedPromoCode,
-            promoApplicationScope,
-            structuredAdjustments: adminStructuredAdjustments,
-            reverseAdjustmentIds: adminReverseAdjustmentIds,
-            includeSelectableAdjustmentComponents: adminStructuredAdjustments.some(
-              (adjustment) => adjustment.scope === 'SELECTED_COMPONENTS',
-            ),
-            refundDispositionsByOperationId,
-            previousPassengerCount: changeFlowInitialTicketCount,
-            previousAvailabilityId: initialValues?.availabilityId ?? null,
-            previousReturnAvailabilityId: initialValues?.returnAvailabilityId ?? null,
-          }),
-          {
-            total: changeFlowNewBookingTotal,
-            subtotal: effectiveSubtotalForCheckout,
-            tax: effectiveTax,
-          },
-          currency,
+        // Preview owns quote creation and invalidates it whenever a quote input changes.
+        // Submit must carry that exact reviewed identity through provider apply/payment.
+        authoritativeChangeQuoteForCheckout = requireReviewedAdminChangeQuoteForCheckout(
+          latestChangeQuote,
         );
-        setLatestChangeQuote(authoritativeChangeQuoteForCheckout);
       } else if (isCustomerSelfServeChange) {
         const quoteResult = await quoteAdminCustomerChangeForCheckout({
           bookingReference: initialValues?.bookingReference,

package/src/components/booking/useAdminChangeQuotePreview.ts

@@ -31,6 +31,7 @@ import {
   buildAdminChangeQuoteRequestKey,
   canRequestAdminChangeQuote,
   canReuseCompletedAdminChangeQuote,
+  isAdminRefundDecisionDiscoveryQuote,
 } from './admin-change-quote-request-key';
 import {
   buildAdminChangeV2QuoteRequest,
@@ -84,6 +85,7 @@ export interface UseAdminChangeQuotePreviewParams {
   useAdminFeAuthoritativeQuote: boolean;
   latestChangeQuote: AdminChangeLatestQuote | null;
   setLatestChangeQuote: Dispatch<SetStateAction<AdminChangeLatestQuote | null>>;
+  onRefundDecisionDiscovery?: (quote: AdminChangeLatestQuote) => void;
   changeQuoteLoading: boolean;
   setChangeQuoteLoading: Dispatch<SetStateAction<boolean>>;
   changeQuoteFetchError: string | null;
@@ -147,6 +149,7 @@ export function useAdminChangeQuotePreview({
   useAdminFeAuthoritativeQuote,
   latestChangeQuote,
   setLatestChangeQuote,
+  onRefundDecisionDiscovery,
   changeQuoteLoading,
   setChangeQuoteLoading,
   changeQuoteFetchError,
@@ -188,17 +191,38 @@ export function useAdminChangeQuotePreview({
     latestChangeQuote?.canProceed === false &&
     (latestChangeQuote.refundDecisionOperations?.length ?? 0) === 0;
   const refundDecisionRequired = (latestChangeQuote?.refundDecisionOperations?.length ?? 0) > 0;
-  const hasPublishedChangeQuoteRef = useRef(latestChangeQuote !== null);
-  hasPublishedChangeQuoteRef.current = latestChangeQuote !== null;
-  // Quote only against a live availability. Existing-adjustment discovery is
-  // bundled into the first real change quote; it must not issue a quote merely
-  // because the modal is hydrating.
-  const quoteAvailability = selectedAvailability;
+  const hasPublishedChangeQuote = latestChangeQuote !== null;
+  /**
+   * Existing admin adjustments must be discoverable before the operator makes a change.
+   * Initial selection hydration can briefly leave the live availability/return unset, so use
+   * the persisted booking identities for this read-only discovery quote instead of waiting for
+   * the editable target controls to become complete.
+   */
+  const quoteAvailability = useMemo<Availability | null>(() => {
+    if (selectedAvailability) return selectedAvailability;
+    if (!needsAdjustmentDiscovery || !initialValues?.dateTime?.trim()) return null;
+    const optionId = initialValues.productOptionId?.trim() || initialValues.productId?.trim();
+    if (!optionId) return null;
+    return {
+      dateTime: initialValues.dateTime.trim(),
+      availabilityId: initialValues.availabilityId?.trim() || undefined,
+      productOptionId: optionId,
+      vacancies: Math.max(totalQuantity, 1),
+      currency,
+    };
+  }, [
+    selectedAvailability,
+    needsAdjustmentDiscovery,
+    initialValues?.dateTime,
+    initialValues?.availabilityId,
+    initialValues?.productOptionId,
+    initialValues?.productId,
+    totalQuantity,
+    currency,
+  ]);
   const quoteReturnAvailabilityId =
     selectedReturnOption?.returnAvailabilityId ??
-    (quoteAvailability && needsAdjustmentDiscovery
-      ? initialValues?.returnAvailabilityId?.trim() || null
-      : null);
+    (needsAdjustmentDiscovery ? initialValues?.returnAvailabilityId?.trim() || null : null);
   const changeQuoteInputsKey = useMemo(() => buildAdminChangeQuoteRequestKey({
     bookingReference: initialValues?.bookingReference,
     lastName,
@@ -236,19 +260,16 @@ export function useAdminChangeQuotePreview({
   ]);
   const destinationRequiresReturnSelection = Boolean(selectedAvailability?.returnOptions?.length);
   const missingRequiredReturnSelection = destinationRequiresReturnSelection && !selectedReturnOption;
-  const quoteMissingRequiredReturnSelection = missingRequiredReturnSelection;
+  const quoteMissingRequiredReturnSelection =
+    missingRequiredReturnSelection && !needsAdjustmentDiscovery;
   const canRequestChangeQuote = canRequestAdminChangeQuote({
     isCustomerSelfServeChange,
-    // Opening the change flow is not itself a change. Existing adjustment
-    // discovery can be included with the first real quote instead of issuing a
-    // quote during modal hydration.
     hasEffectiveChangeSelection,
     hasSelectedAvailability: quoteAvailability != null,
     bookingReference: initialValues?.bookingReference,
     lastName,
     missingRequiredReturnSelection: quoteMissingRequiredReturnSelection,
   });
-
   const changeFlowSubmitDisabled =
     missingRequiredReturnSelection ||
     (isCustomerSelfServeChange &&
@@ -461,7 +482,7 @@ export function useAdminChangeQuotePreview({
     if (canReuseCompletedAdminChangeQuote(
       changeQuoteInputsKey,
       lastCompletedQuoteInputsKeyRef.current,
-      hasPublishedChangeQuoteRef.current,
+      hasPublishedChangeQuote,
     )) {
       setChangeQuoteLoading(false);
       return;
@@ -484,6 +505,7 @@ export function useAdminChangeQuotePreview({
     const bookingReferenceForQuote = initialValues.bookingReference.trim();
     const timer = window.setTimeout(() => {
       void (async () => {
+        let awaitingRefundDecisionRequote = false;
         inFlightQuoteInputsKeyRef.current = changeQuoteInputsKey;
         const bookingItems = Object.entries(quantities)
           .filter(([, count]) => count > 0)
@@ -535,7 +557,19 @@ export function useAdminChangeQuotePreview({
           // Commit the completed identity before publishing its result. This keeps a
           // render caused by setLatestChangeQuote from being interpreted as a new request.
           lastCompletedQuoteInputsKeyRef.current = changeQuoteInputsKey;
-          setLatestChangeQuote(mergedQuote);
+          awaitingRefundDecisionRequote = Boolean(
+            onRefundDecisionDiscovery &&
+              isAdminRefundDecisionDiscoveryQuote({
+                isProviderDashboardChange,
+                canProceed: mergedQuote.canProceed,
+                refundDecisionCount: mergedQuote.refundDecisionOperations?.length ?? 0,
+              }),
+          );
+          if (awaitingRefundDecisionRequote) {
+            onRefundDecisionDiscovery?.(mergedQuote);
+          } else {
+            setLatestChangeQuote(mergedQuote);
+          }
         } catch (e) {
           if (seq !== changeQuoteRequestSeq.current) return;
           setLatestChangeQuote(null);
@@ -545,7 +579,7 @@ export function useAdminChangeQuotePreview({
           if (inFlightQuoteInputsKeyRef.current === changeQuoteInputsKey) {
             inFlightQuoteInputsKeyRef.current = null;
           }
-          if (seq === changeQuoteRequestSeq.current) {
+          if (seq === changeQuoteRequestSeq.current && !awaitingRefundDecisionRequote) {
             setChangeQuoteLoading(false);
           }
         }
@@ -562,6 +596,8 @@ export function useAdminChangeQuotePreview({
     canRequestChangeQuote,
     missingRequiredReturnSelection,
     changeQuoteInputsKey,
+    hasPublishedChangeQuote,
+    onRefundDecisionDiscovery,
   ]);
 
   return {

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

@@ -31,6 +31,7 @@ import {
   buildAdminChangeQuoteRequestKey,
   canRequestAdminChangeQuote,
   canReuseCompletedAdminChangeQuote,
+  isAdminRefundDecisionDiscoveryQuote,
 } from '../src/components/booking/admin-change-quote-request-key';
 import {
   authoritativeItineraryDisplayFromChangeQuote,
@@ -45,6 +46,7 @@ import {
 import {
   buildAdminChangeV2QuoteRequest,
   quoteAdminChangeV2ForUi,
+  requireReviewedAdminChangeQuoteForCheckout,
 } from '../src/components/booking/admin-change-v2-quote-request';
 import {
   noRefundRemovedValue,
@@ -63,6 +65,7 @@ import {
 } from '../src/components/booking/admin-refund-decision-context';
 import {
   applyResourceAdjustments,
+  privateShuttleEndTimeLabel,
   privateShuttleInitialDateKey,
   privateShuttlePriceChanged,
   resolveHydratedPrivateShuttleAvailability,
@@ -95,11 +98,21 @@ import {
   removeAddOnSelections,
 } from '../src/components/booking/incompatible-add-on-selections';
 import {
+  dedupeChangeBookingCheckoutError,
   friendlyChangeBookingError,
   incompatibleAddOnChangeError,
 } from '../src/components/booking/change-booking-error-message';
+import {
+  adminChangeSettlementSummaryLabel,
+  dedupeAdminChangeCheckoutError,
+} from '../src/components/booking/admin-change-checkout-message';
+import { shouldRefreshAfterChangeDialogClose } from '../../../src/lib/manage-booking-post-checkout';
 import { applyPrivateShuttleProviderChange } from '../src/components/booking/private-shuttle-provider-change-runner';
 import { resolvePrivateShuttleCancellationPolicyId } from '../src/components/booking/private-shuttle-cancellation-policy';
+import {
+  privateShuttleTermsInitiallyAccepted,
+  resolveInitialPrivateShuttlePassengerCount,
+} from '../src/components/booking/private-shuttle-passenger-count';
 import { hasEffectiveAdminChangeSelection } from '../src/components/booking/useAdminProviderPricingAdjustments';
 import {
   lineFromActiveAdjustment,
@@ -612,7 +625,20 @@ test('admin quote dedupe refetches unchanged inputs after the published quote is
   assert.equal(canReuseCompletedAdminChangeQuote(inputKey, 'different-inputs', true), false);
 });
 
-test('admin quote gate requires a real change while allowing adjustment-only changes', () => {
+test('admin refund discovery response is protocol state, not display state', () => {
+  assert.equal(isAdminRefundDecisionDiscoveryQuote({
+    isProviderDashboardChange: true,
+    canProceed: false,
+    refundDecisionCount: 1,
+  }), true);
+  assert.equal(isAdminRefundDecisionDiscoveryQuote({
+    isProviderDashboardChange: true,
+    canProceed: true,
+    refundDecisionCount: 0,
+  }), false);
+});
+
+test('admin quote gate allows adjustment-only changes', () => {
   assert.equal(canRequestAdminChangeQuote({
     isCustomerSelfServeChange: true,
     hasEffectiveChangeSelection: true,
@@ -624,7 +650,6 @@ test('admin quote gate requires a real change while allowing adjustment-only cha
 
   assert.equal(canRequestAdminChangeQuote({
     isCustomerSelfServeChange: true,
-    // A fully hydrated modal is still not quoteable until something changes.
     hasEffectiveChangeSelection: false,
     hasSelectedAvailability: true,
     bookingReference: 'DIFG66OF',
@@ -677,7 +702,7 @@ test('admin preview and checkout share the Pricing V2 request shape', () => {
   assert.equal('clientProposedTotal' in request, false);
 });
 
-test('admin checkout maps the fresh Pricing V2 quote id instead of a legacy response', async () => {
+test('admin Pricing V2 quote mapper preserves the server quote identity', async () => {
   const request = buildAdminChangeV2QuoteRequest({
     bookingReference: 'VFSCAEKQ',
     lastName: 'Tauro',
@@ -722,6 +747,34 @@ test('admin checkout maps the fresh Pricing V2 quote id instead of a legacy resp
   assert.equal(mergedQuote.quotedTotal, 768.11);
 });
 
+test('admin checkout reuses the exact quote reviewed by the operator', () => {
+  const reviewedQuote = {
+    quoteId: 'quote_reviewed',
+    canProceed: true,
+    priceDiff: 0,
+  };
+
+  const checkoutQuote = requireReviewedAdminChangeQuoteForCheckout(reviewedQuote);
+
+  assert.equal(checkoutQuote, reviewedQuote);
+  assert.equal(checkoutQuote.quoteId, 'quote_reviewed');
+});
+
+test('admin checkout fails closed when no applicable reviewed quote exists', () => {
+  assert.throws(
+    () => requireReviewedAdminChangeQuoteForCheckout(null),
+    /reviewed change quote is not ready/i,
+  );
+  assert.throws(
+    () => requireReviewedAdminChangeQuoteForCheckout({
+      quoteId: 'quote_blocked',
+      canProceed: false,
+      reasonIfBlocked: 'Booking requires review.',
+    }),
+    /Booking requires review/,
+  );
+});
+
 test('admin no-charge provider payload carries the selected pickup itinerary', () => {
   const itineraryDisplay: NonNullable<
     Parameters<typeof buildAdminChangeProviderPayload>[0]['itineraryDisplay']
@@ -1392,6 +1445,39 @@ test('private conversion replaces an incompatible source cancellation policy wit
   );
 });
 
+test('standard-to-private conversion preserves the original passenger total', () => {
+  assert.equal(
+    resolveInitialPrivateShuttlePassengerCount({
+      bookingItems: [
+        { category: 'ADULT', count: 4 },
+        { category: 'CHILD', count: 1 },
+      ],
+    }),
+    5,
+  );
+});
+
+test('private passenger count wins and RESOURCE is never treated as people', () => {
+  assert.equal(
+    resolveInitialPrivateShuttlePassengerCount({
+      privateShuttleDetails: { passengerCount: 5, requestedPassengerCount: 14 },
+      bookingItems: [{ category: 'RESOURCE', count: 2 }],
+    }),
+    14,
+  );
+  assert.equal(
+    resolveInitialPrivateShuttlePassengerCount({
+      bookingItems: [{ category: 'RESOURCE', count: 2 }],
+    }),
+    1,
+  );
+});
+
+test('private change bookings inherit terms acceptance but fresh bookings do not', () => {
+  assert.equal(privateShuttleTermsInitiallyAccepted(true), true);
+  assert.equal(privateShuttleTermsInitiallyAccepted(false), false);
+});
+
 test('admin standard-to-private conversion sends complete private target identity and state', async () => {
   let captured: Parameters<typeof applyPrivateShuttleProviderChange>[0] extends {
     onChangeBooking: (data: infer T) => Promise<void>;
@@ -1456,17 +1542,9 @@ test('admin standard-to-private conversion sends complete private target identit
   ]);
 });
 
-test('private conversion stores the first actual location as pickup when proposed stops come first', async () => {
-  let captured: Parameters<typeof applyPrivateShuttleProviderChange>[0] extends {
-    onChangeBooking: (data: infer T) => Promise<void>;
-  }
-    ? T
-    : never;
-
-  await applyPrivateShuttleProviderChange({
-    onChangeBooking: async (data) => {
-      captured = data;
-    },
+test('private conversion rejects an itinerary without fixed pickup and drop-off endpoints', async () => {
+  await assert.rejects(() => applyPrivateShuttleProviderChange({
+    onChangeBooking: async () => {},
     parentProductId: 'p_private',
     selectedOption: 'po_private',
     selectedAvailabilityId: 'a_private',
@@ -1498,12 +1576,14 @@ test('private conversion stores the first actual location as pickup when propose
     ],
     isAdmin: true,
     providerChangeAuthoritativeReceipt: undefined,
-  });
+  }), /requires fixed pickup and drop-off endpoints/i);
+});
 
-  assert.deepEqual(captured!.itineraryDisplay, [
-    { stepType: 'draft', time: 'Proposed stops', place: 'Moraine Lake, Lake Louise' },
-    { stepType: 'pickup', time: '7:00 AM', place: 'Banff Hotel' },
-  ]);
+test('private shuttle end time includes the selected option duration', () => {
+  assert.equal(
+    privateShuttleEndTimeLabel('2026-10-01', '03:00', 'America/Edmonton', 360),
+    '09:00',
+  );
 });
 
 test('private shuttle checkout detects a quote total that differs from the displayed total', () => {
@@ -2000,6 +2080,18 @@ test('translates booking-change reason codes into operator-facing messages', ()
     friendlyChangeBookingError('structured_adjustment_basis_is_zero'),
     'This credit needs a value to apply to. Make a priced booking change, or choose All active tickets, Entire active booking, or Selected components.',
   );
+  assert.equal(
+    friendlyChangeBookingError('amendment_ledger_summary_missing'),
+    "This older booking hasn't been prepared for changes yet. Please contact support to prepare it, then reopen the booking.",
+  );
+  assert.equal(
+    friendlyChangeBookingError('admin_ledger_requires_review_or_repair'),
+    "This older booking's pricing and payment history must be reviewed before it can be changed. Please contact support.",
+  );
+  assert.equal(
+    friendlyChangeBookingError('private_shuttle_itinerary_endpoints_required'),
+    'The private-tour itinerary is incomplete. Reopen the change and select the pickup time and location again.',
+  );
   assert.equal(
     friendlyChangeBookingError('Remove the unavailable add-on before recalculating this amendment.'),
     'Remove the unavailable add-on before recalculating this amendment.',
@@ -2010,6 +2102,51 @@ test('translates booking-change reason codes into operator-facing messages', ()
   );
 });
 
+test('blocked admin quotes show one actionable error and no settlement claim', () => {
+  const serverQuoteError = 'amendment_ledger_summary_missing';
+  const checkoutError = friendlyChangeBookingError(serverQuoteError);
+  assert.equal(
+    adminChangeSettlementSummaryLabel({ amountDue: 0, refundCandidate: 0, serverQuoteError }),
+    'Price unavailable',
+  );
+  assert.equal(
+    dedupeAdminChangeCheckoutError({ checkoutError, serverQuoteError }),
+    '',
+  );
+  assert.equal(
+    dedupeAdminChangeCheckoutError({
+      checkoutError: 'Enter the customer email before continuing.',
+      serverQuoteError,
+    }),
+    'Enter the customer email before continuing.',
+  );
+});
+
+test('blocked public quotes show the readiness message only in the quote status panel', () => {
+  const displayedQuoteError = 'amendment_ledger_summary_missing';
+  const checkoutError = friendlyChangeBookingError(displayedQuoteError);
+  assert.equal(
+    dedupeChangeBookingCheckoutError({ checkoutError, displayedQuoteError }),
+    '',
+  );
+  assert.equal(
+    dedupeChangeBookingCheckoutError({
+      checkoutError: 'Enter your email before continuing.',
+      displayedQuoteError,
+    }),
+    'Enter your email before continuing.',
+  );
+});
+
+test('closing public change booking refreshes only after a completed change', () => {
+  assert.equal(shouldRefreshAfterChangeDialogClose(undefined), false);
+  assert.equal(shouldRefreshAfterChangeDialogClose(null), true);
+  assert.equal(
+    shouldRefreshAfterChangeDialogClose({ dateChanged: false, ticketsChanged: true }),
+    true,
+  );
+});
+
 test('names the incompatible add-on and target tour in the operator error', () => {
   assert.equal(
     incompatibleAddOnChangeError(