@ticketboothapp/booking 1.2.186 → 1.2.188

package/package.json

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

package/src/components/booking/AdminChangeBookingContent.tsx

@@ -197,6 +197,8 @@ const checkoutPanelPropKeys = [
   'onRemoveAdminCustomReceiptLine',
   'onApplyAdminCustomReceiptLines',
   'onSetAdminReceiptLineOverride',
+  'preserveExistingReceipt',
+  'onPreserveExistingReceiptChange',
   'firstName',
   'lastName',
   'email',

package/src/components/booking/AdminChangeBookingFlow.tsx

@@ -348,6 +348,7 @@ export function AdminChangeBookingFlow({
   >({});
   const [changeQuoteLoading, setChangeQuoteLoading] = useState(false);
   const [changeQuoteFetchError, setChangeQuoteFetchError] = useState<string | null>(null);
+  const [preserveExistingReceipt, setPreserveExistingReceipt] = useState(false);
   /** Dedupe quote calls while user input payload is unchanged. */
   const lastCompletedQuoteInputsKeyRef = useRef<string | null>(null);
   const inFlightQuoteInputsKeyRef = useRef<string | null>(null);
@@ -804,6 +805,7 @@ export function AdminChangeBookingFlow({
     adminCustomReceiptLines: appliedAdminCustomReceiptLines,
     structuredAdjustments: adminStructuredAdjustments,
     reverseAdjustmentIds: adminReverseAdjustmentIds,
+    preserveExistingReceipt,
     useAdminFeAuthoritativeQuote,
   }), [
     initialValues?.bookingReference,
@@ -820,6 +822,7 @@ export function AdminChangeBookingFlow({
     appliedAdminCustomReceiptLines,
     adminStructuredAdjustments,
     adminReverseAdjustmentIds,
+    preserveExistingReceipt,
     useAdminFeAuthoritativeQuote,
   ]);
   const responseRefundDecisionOperations = latestChangeQuote?.refundDecisionOperations ?? [];
@@ -894,6 +897,12 @@ export function AdminChangeBookingFlow({
     activeReturnPriceTreatmentOperations,
     refundDispositionsByOperationId,
   ]);
+  const initialSelectionHydratedForQuote = Boolean(
+    selectedAvailability &&
+      totalQuantity > 0 &&
+      addOnCatalogLoaded &&
+      ((selectedAvailability.returnOptions?.length ?? 0) === 0 || selectedReturnOption),
+  );
   const handleRefundDispositionChange = useCallback((
     operationId: string,
     disposition: AdminReleaseRefundDisposition | null,
@@ -915,8 +924,8 @@ export function AdminChangeBookingFlow({
   } = useAdminChangeQuotePreview({
     isCustomerSelfServeChange,
     isProviderDashboardChange,
-    hasChangeSelection,
     hasEffectiveChangeSelection,
+    initialSelectionHydrated: initialSelectionHydratedForQuote,
     selectedAvailability,
     selectedReturnOption,
     initialValues,
@@ -931,6 +940,7 @@ export function AdminChangeBookingFlow({
     adminCustomReceiptLines: appliedAdminCustomReceiptLines,
     adminStructuredAdjustments,
     adminReverseAdjustmentIds,
+    preserveExistingReceipt,
     needsAdjustmentDiscovery:
       isProviderDashboardChange && !hasHydratedExistingAdjustments,
     refundDispositionsByOperationId: activeRefundDispositionsByOperationId,
@@ -1153,6 +1163,7 @@ export function AdminChangeBookingFlow({
     mergedProviderAdditionalAdjustments,
     adminStructuredAdjustments,
     adminReverseAdjustmentIds,
+    preserveExistingReceipt,
     refundDispositionsByOperationId: activeRefundDispositionsByOperationId,
     providerApplyAuthoritativeReceipt,
     onSuccess,
@@ -1301,6 +1312,8 @@ export function AdminChangeBookingFlow({
         onRemoveAdminCustomReceiptLine: handleRemoveAdminCustomReceiptLine,
         onApplyAdminCustomReceiptLines: handleApplyAdminCustomReceiptLines,
         onSetAdminReceiptLineOverride: handleSetAdminReceiptLineOverride,
+        preserveExistingReceipt,
+        onPreserveExistingReceiptChange: setPreserveExistingReceipt,
         onFirstNameChange: setFirstName, onLastNameChange: setLastName, onEmailChange: setEmail,
         onClearError: () => setError(''),
         pickupLocations: product.pickupLocations, destinations: product.destinations, highlightedPickupLocationIds,

package/src/components/booking/AdminChangeCheckoutPanel.tsx

@@ -87,6 +87,8 @@ export interface AdminChangeCheckoutPanelProps {
     baseAmount: number;
     targetAmount: number;
   }) => void;
+  preserveExistingReceipt: boolean;
+  onPreserveExistingReceiptChange: (preserve: boolean) => void;
   firstName: string;
   lastName: string;
   email: string;
@@ -179,6 +181,8 @@ export function AdminChangeCheckoutPanel({
   onRemoveAdminCustomReceiptLine,
   onApplyAdminCustomReceiptLines,
   onSetAdminReceiptLineOverride,
+  preserveExistingReceipt,
+  onPreserveExistingReceiptChange,
   firstName,
   lastName,
   email,
@@ -282,6 +286,8 @@ export function AdminChangeCheckoutPanel({
         promoEditor={promoEditor}
         promoCode={promoCode}
         adjustments={pricingAdjustments}
+        preserveExistingReceipt={preserveExistingReceipt}
+        onPreserveExistingReceiptChange={onPreserveExistingReceiptChange}
         adminCustomReceiptLines={adminCustomReceiptLines}
         onSetReceiptLineOverride={onSetAdminReceiptLineOverride}
       />

package/src/components/booking/AdminChangeReceiptComparison.tsx

@@ -1,4 +1,4 @@
-import { useState, type ReactNode } from 'react';
+import { useEffect, useState, type ReactNode } from 'react';
 import type {
   AdminAmendmentOperationSnapshot,
   AdminAmendmentRefundDisposition,
@@ -72,6 +72,8 @@ export interface AdminChangeReceiptComparisonProps {
     baseAmount: number;
     targetAmount: number;
   }) => void;
+  preserveExistingReceipt?: boolean;
+  onPreserveExistingReceiptChange?: (preserve: boolean) => void;
 }
 
 function normalizeLocale(locale: string): Locale {
@@ -128,8 +130,13 @@ export function AdminChangeReceiptComparison({
   refundQuoteLoading = false,
   adminCustomReceiptLines = [],
   onSetReceiptLineOverride,
+  preserveExistingReceipt = false,
+  onPreserveExistingReceiptChange,
 }: AdminChangeReceiptComparisonProps) {
   const [overrideDrafts, setOverrideDrafts] = useState<Record<string, string>>({});
+  useEffect(() => {
+    if (preserveExistingReceipt) setOverrideDrafts({});
+  }, [preserveExistingReceipt]);
   const readableQuoteError = friendlyChangeBookingError(quoteError);
   const displayLocale = normalizeLocale(locale);
   const existingLines = originalLines(originalReceipt);
@@ -356,7 +363,7 @@ export function AdminChangeReceiptComparison({
         </section>
 
         <section className="min-w-0 overflow-visible rounded-lg border border-sky-200 bg-sky-50/50 p-3">
-          <div className="mb-3 flex items-center justify-between gap-3">
+          <div className="mb-3">
             <div>
               <h3 className="text-sm font-semibold text-stone-900">
                 {isProductFamilyConversion ? 'New purchase' : 'Current change'}
@@ -367,15 +374,29 @@ export function AdminChangeReceiptComparison({
                 </p>
               ) : null}
             </div>
-            <span className="shrink-0 text-xs font-medium text-stone-500">
-              {isProductFamilyConversion
-                ? formatCurrencyAmount(updatedTotal ?? 0, currency, displayLocale)
-                : bookingTotalChange == null
-                  ? '—'
-                  : formatCurrencyAmount(bookingTotalChange, currency, displayLocale)}
-            </span>
+            {onPreserveExistingReceiptChange ? (
+              <button
+                type="button"
+                aria-pressed={preserveExistingReceipt}
+                className={`mt-3 inline-flex w-full items-center justify-center rounded-lg border px-3 py-2 text-sm font-semibold shadow-sm transition sm:w-auto ${
+                  preserveExistingReceipt
+                    ? 'border-sky-700 bg-sky-700 text-white hover:bg-sky-800'
+                    : 'border-sky-300 bg-white text-sky-800 hover:border-sky-500 hover:bg-sky-50'
+                }`}
+                onClick={() => onPreserveExistingReceiptChange(!preserveExistingReceipt)}
+              >
+                Keep receipt unchanged
+              </button>
+            ) : null}
           </div>
-          {promoEditor}
+          {preserveExistingReceipt ? (
+            <div className="mb-3 rounded-md border border-sky-200 bg-white px-3 py-2">
+              <p className="text-sm font-semibold text-stone-800">Receipt and balance will stay unchanged</p>
+              <p className="mt-0.5 text-xs text-stone-600">
+                Only the booking details will change. No charge, refund, or balance adjustment will be created.
+              </p>
+            </div>
+          ) : promoEditor}
           {!selectionChanged ? (
             <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 changes selected</p>
@@ -416,10 +437,10 @@ export function AdminChangeReceiptComparison({
                 subtotal={summarySubtotal}
                 size="sm"
                 t={t}
-                lineAmountInputs={{ ...quotedOverrideAmountInputs, ...overrideDrafts }}
-                onLineAmountInputChange={handleOverrideChange}
-                onLineAmountInputBlur={handleOverrideBlur}
-                onLineRemove={handleOverrideRemove}
+                lineAmountInputs={preserveExistingReceipt ? undefined : { ...quotedOverrideAmountInputs, ...overrideDrafts }}
+                onLineAmountInputChange={preserveExistingReceipt ? undefined : handleOverrideChange}
+                onLineAmountInputBlur={preserveExistingReceipt ? undefined : handleOverrideBlur}
+                onLineRemove={preserveExistingReceipt ? undefined : handleOverrideRemove}
               />
               {removedSummaryDisplayLines.length > 0 ? (
                 <div className="mt-3 border-t border-stone-200 pt-2 text-xs text-stone-500">
@@ -446,7 +467,7 @@ export function AdminChangeReceiptComparison({
         </section>
       </div>
 
-      {adjustments ? (
+      {!preserveExistingReceipt && adjustments ? (
         <section className="rounded-lg border border-amber-200 bg-amber-50/40 p-3">
           <h3 className="mb-2 text-sm font-semibold text-stone-900">Add custom line items</h3>
           {adjustments}

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

@@ -40,6 +40,7 @@ export interface BuildAdminChangeProviderPayloadParams {
   mergedProviderAdditionalAdjustments: AdminChangeProviderAdditionalAdjustment[];
   adminStructuredAdjustments: NonNullable<ProviderDashboardChangeBookingPayload['structuredAdjustments']>;
   adminReverseAdjustmentIds?: string[];
+  preserveExistingReceipt?: boolean;
   refundDispositionsByOperationId: NonNullable<
     ProviderDashboardChangeBookingPayload['refundDispositionsByOperationId']
   >;
@@ -69,6 +70,7 @@ export function buildAdminChangeProviderPayload({
   mergedProviderAdditionalAdjustments,
   adminStructuredAdjustments,
   adminReverseAdjustmentIds = [],
+  preserveExistingReceipt = false,
   refundDispositionsByOperationId,
   pricingV2QuoteId,
   pricingV2QuotedTotal,
@@ -84,6 +86,7 @@ export function buildAdminChangeProviderPayload({
     : null;
 
   return {
+    preserveExistingReceipt,
     productId: availabilityProductOptionId,
     parentProductId: product.productId,
     availabilityId: selectedAvailability.availabilityId ?? null,
@@ -102,10 +105,11 @@ export function buildAdminChangeProviderPayload({
     cancellationPolicyId: cancellationPolicyId ?? initialCancellationPolicyId ?? null,
     promoCode: appliedPromoCode ?? null,
     promoApplicationScope: appliedPromoCode ? promoApplicationScope : null,
-    newTotalAmount,
+    newTotalAmount: preserveExistingReceipt ? undefined : newTotalAmount,
     additionalHoursCount: null,
     pricingAdjustment:
-      providerPricingOverrides.length > 0 || mergedProviderAdditionalAdjustments.length > 0
+      !preserveExistingReceipt &&
+      (providerPricingOverrides.length > 0 || mergedProviderAdditionalAdjustments.length > 0)
         ? {
             mode: 'MANUAL_LINES',
             ...(providerPricingOverrides.length > 0 ? { lineOverrides: providerPricingOverrides } : {}),
@@ -115,9 +119,9 @@ export function buildAdminChangeProviderPayload({
           }
         : undefined,
     authoritativeReceipt: providerApplyAuthoritativeReceipt,
-    structuredAdjustments: adminStructuredAdjustments,
-    reverseAdjustmentIds: adminReverseAdjustmentIds,
-    refundDispositionsByOperationId,
+    structuredAdjustments: preserveExistingReceipt ? [] : adminStructuredAdjustments,
+    reverseAdjustmentIds: preserveExistingReceipt ? [] : adminReverseAdjustmentIds,
+    refundDispositionsByOperationId: preserveExistingReceipt ? {} : refundDispositionsByOperationId,
     pricingV2QuoteId: pricingV2QuoteId ?? null,
     pricingV2QuotedTotal: pricingV2QuotedTotal ?? null,
     capacitySeatCredit: {

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

@@ -16,6 +16,7 @@ interface AdminChangeQuoteRequestKeyInput {
   promoApplicationScope?: AdminPromoApplicationScope | null;
   structuredAdjustments?: unknown[];
   reverseAdjustmentIds?: string[];
+  preserveExistingReceipt?: boolean;
   refundDispositionsByOperationId?: Record<string, string>;
   useAdminFeAuthoritativeQuote: boolean;
 }
@@ -23,6 +24,7 @@ interface AdminChangeQuoteRequestKeyInput {
 interface AdminChangeQuoteRequestGateInput {
   isCustomerSelfServeChange: boolean;
   hasEffectiveChangeSelection: boolean;
+  initialSelectionHydrated?: boolean;
   hasSelectedAvailability: boolean;
   bookingReference?: string | null;
   lastName: string;
@@ -44,6 +46,7 @@ export function canRequestAdminChangeQuote(input: AdminChangeQuoteRequestGateInp
   return Boolean(
     input.isCustomerSelfServeChange &&
       input.hasEffectiveChangeSelection &&
+      input.initialSelectionHydrated !== false &&
       input.hasSelectedAvailability &&
       input.bookingReference?.trim() &&
       input.lastName.trim() &&
@@ -74,6 +77,7 @@ export function buildAdminChangeQuoteRequestKey(input: AdminChangeQuoteRequestKe
     promoApplicationScope: input.promoCode ? (input.promoApplicationScope ?? 'CHANGE_ONLY') : null,
     structuredAdjustments: input.structuredAdjustments ?? [],
     reverseAdjustmentIds: [...(input.reverseAdjustmentIds ?? [])].sort(),
+    preserveExistingReceipt: input.preserveExistingReceipt === true,
     refundDispositionsByOperationId: Object.fromEntries(
       Object.entries(input.refundDispositionsByOperationId ?? {}).sort(([a], [b]) => a.localeCompare(b)),
     ),

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

@@ -32,6 +32,7 @@ export interface BuildAdminChangeV2QuoteRequestParams {
   promoApplicationScope?: AdminPromoApplicationScope;
   structuredAdjustments: NonNullable<ChangeBookingQuoteRequest['structuredAdjustments']>;
   reverseAdjustmentIds?: string[];
+  preserveExistingReceipt?: boolean;
   includeSelectableAdjustmentComponents?: boolean;
   refundDispositionsByOperationId: Record<string, AdminAmendmentRefundDisposition>;
   previousPassengerCount: number;
@@ -59,6 +60,7 @@ export function buildAdminChangeV2QuoteRequest({
   promoApplicationScope = 'CHANGE_ONLY',
   structuredAdjustments,
   reverseAdjustmentIds = [],
+  preserveExistingReceipt = false,
   includeSelectableAdjustmentComponents = false,
   refundDispositionsByOperationId,
   previousPassengerCount,
@@ -80,12 +82,13 @@ export function buildAdminChangeV2QuoteRequest({
     cancellationPolicyId,
     promoCode: promoCode?.trim() || null,
     promoApplicationScope: promoCode?.trim() ? promoApplicationScope : null,
-    structuredAdjustments,
-    reverseAdjustmentIds,
+    structuredAdjustments: preserveExistingReceipt ? [] : structuredAdjustments,
+    reverseAdjustmentIds: preserveExistingReceipt ? [] : reverseAdjustmentIds,
+    preserveExistingReceipt,
     ...(includeSelectableAdjustmentComponents
       ? { includeSelectableAdjustmentComponents: true }
       : {}),
-    ...(Object.keys(refundDispositionsByOperationId).length > 0
+    ...(!preserveExistingReceipt && Object.keys(refundDispositionsByOperationId).length > 0
       ? { refundDispositionsByOperationId }
       : {}),
     capacitySeatCredit: {

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

@@ -93,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|private_shuttle|quote|structured_adjustment)_[a-z0-9_]+/i,
+    /\b(?:(?:missing_(?:add|remove)_operation):[a-z0-9_]+|(?:pricing_v2|apply_v2|promo|admin|amendment|booking_amendment|private_shuttle|quote|structured_adjustment)_[a-z0-9_]+)/i,
   );
   return match?.[0]?.toLowerCase() ?? null;
 }
@@ -112,6 +112,10 @@ export function friendlyChangeBookingError(message: string | null | undefined):
   const exact = CHANGE_BOOKING_ERROR_MESSAGES[code];
   if (exact) return exact;
 
+  if (code.startsWith('missing_add_operation:return') || code.startsWith('missing_remove_operation:return')) {
+    return 'The return portion of this booking could not be priced. Re-select the return time and try again.';
+  }
+
   if (code.startsWith('admin_adjustment_refund_disposition_required')) {
     return 'Choose how to handle the removed adjustment value before continuing.';
   }

package/src/components/booking/provider-dashboard-change-booking.ts

@@ -33,6 +33,8 @@ export type AdminAmendmentStructuredAdjustment = {
 
 /** Payload passed to `onChangeBooking` when applying a dashboard-managed booking change. */
 export type ProviderDashboardChangeBookingPayload = {
+  /** Apply operational changes while preserving the existing receipt and balance exactly. */
+  preserveExistingReceipt?: boolean;
   /** Parent catalog product id. Present when admin changes the booking to a different product. */
   parentProductId?: string;
   /** Product option id selected for the new booking. */

package/src/components/booking/useAdminChangeCheckoutController.ts

@@ -155,6 +155,7 @@ export interface UseAdminChangeCheckoutControllerParams {
   mergedProviderAdditionalAdjustments: AdminChangeProviderAdditionalAdjustment[];
   adminStructuredAdjustments: NonNullable<ProviderDashboardChangeBookingPayload['structuredAdjustments']>;
   adminReverseAdjustmentIds: string[];
+  preserveExistingReceipt: boolean;
   refundDispositionsByOperationId: NonNullable<
     ProviderDashboardChangeBookingPayload['refundDispositionsByOperationId']
   >;
@@ -258,6 +259,7 @@ export function useAdminChangeCheckoutController({
   mergedProviderAdditionalAdjustments,
   adminStructuredAdjustments,
   adminReverseAdjustmentIds,
+  preserveExistingReceipt,
   refundDispositionsByOperationId,
   providerApplyAuthoritativeReceipt,
   onSuccess,
@@ -381,6 +383,7 @@ export function useAdminChangeCheckoutController({
       mergedProviderAdditionalAdjustments,
       adminStructuredAdjustments,
       adminReverseAdjustmentIds,
+      preserveExistingReceipt,
       refundDispositionsByOperationId,
       pricingV2QuoteId: authoritativeQuote?.quoteId ?? null,
       pricingV2QuotedTotal: authoritativeQuote?.quotedTotal ?? authoritativeQuote?.serverDisplay?.total ?? null,

package/src/components/booking/useAdminChangeQuotePreview.ts

@@ -64,8 +64,8 @@ interface ChangeSelectionDetailsForPreview {
 export interface UseAdminChangeQuotePreviewParams {
   isCustomerSelfServeChange: boolean;
   isProviderDashboardChange: boolean;
-  hasChangeSelection: boolean;
   hasEffectiveChangeSelection: boolean;
+  initialSelectionHydrated: boolean;
   selectedAvailability: Availability | null;
   selectedReturnOption: ReturnOption | null;
   initialValues: ChangeBookingFlowProps['initialValues'];
@@ -80,6 +80,7 @@ export interface UseAdminChangeQuotePreviewParams {
   adminCustomReceiptLines: AdminCustomReceiptLine[];
   adminStructuredAdjustments: NonNullable<ProviderDashboardChangeBookingPayload['structuredAdjustments']>;
   adminReverseAdjustmentIds: string[];
+  preserveExistingReceipt: boolean;
   needsAdjustmentDiscovery: boolean;
   refundDispositionsByOperationId: Record<string, AdminAmendmentRefundDisposition>;
   useAdminFeAuthoritativeQuote: boolean;
@@ -128,8 +129,8 @@ export interface UseAdminChangeQuotePreviewResult {
 export function useAdminChangeQuotePreview({
   isCustomerSelfServeChange,
   isProviderDashboardChange,
-  hasChangeSelection,
   hasEffectiveChangeSelection,
+  initialSelectionHydrated,
   selectedAvailability,
   selectedReturnOption,
   initialValues,
@@ -144,6 +145,7 @@ export function useAdminChangeQuotePreview({
   adminCustomReceiptLines,
   adminStructuredAdjustments,
   adminReverseAdjustmentIds,
+  preserveExistingReceipt,
   needsAdjustmentDiscovery,
   refundDispositionsByOperationId,
   useAdminFeAuthoritativeQuote,
@@ -192,37 +194,10 @@ export function useAdminChangeQuotePreview({
     (latestChangeQuote.refundDecisionOperations?.length ?? 0) === 0;
   const refundDecisionRequired = (latestChangeQuote?.refundDecisionOperations?.length ?? 0) > 0;
   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 ??
-    (needsAdjustmentDiscovery ? initialValues?.returnAvailabilityId?.trim() || null : null);
+  // Existing-adjustment discovery is still a real quote. Never send it with the temporary
+  // empty ticket/return state produced while the saved booking is being rehydrated.
+  const quoteAvailability = selectedAvailability;
+  const quoteReturnAvailabilityId = selectedReturnOption?.returnAvailabilityId ?? null;
   const changeQuoteInputsKey = useMemo(() => buildAdminChangeQuoteRequestKey({
     bookingReference: initialValues?.bookingReference,
     lastName,
@@ -238,6 +213,7 @@ export function useAdminChangeQuotePreview({
     promoApplicationScope,
     structuredAdjustments: adminStructuredAdjustments,
     reverseAdjustmentIds: adminReverseAdjustmentIds,
+    preserveExistingReceipt,
     refundDispositionsByOperationId,
     useAdminFeAuthoritativeQuote,
   }), [
@@ -255,20 +231,20 @@ export function useAdminChangeQuotePreview({
     promoApplicationScope,
     adminStructuredAdjustments,
     adminReverseAdjustmentIds,
+    preserveExistingReceipt,
     refundDispositionsByOperationId,
     useAdminFeAuthoritativeQuote,
   ]);
   const destinationRequiresReturnSelection = Boolean(selectedAvailability?.returnOptions?.length);
   const missingRequiredReturnSelection = destinationRequiresReturnSelection && !selectedReturnOption;
-  const quoteMissingRequiredReturnSelection =
-    missingRequiredReturnSelection && !needsAdjustmentDiscovery;
   const canRequestChangeQuote = canRequestAdminChangeQuote({
     isCustomerSelfServeChange,
-    hasEffectiveChangeSelection,
+    hasEffectiveChangeSelection: hasEffectiveChangeSelection || needsAdjustmentDiscovery,
+    initialSelectionHydrated,
     hasSelectedAvailability: quoteAvailability != null,
     bookingReference: initialValues?.bookingReference,
     lastName,
-    missingRequiredReturnSelection: quoteMissingRequiredReturnSelection,
+    missingRequiredReturnSelection,
   });
   const changeFlowSubmitDisabled =
     missingRequiredReturnSelection ||
@@ -526,6 +502,7 @@ export function useAdminChangeQuotePreview({
             promoApplicationScope,
             structuredAdjustments: adminStructuredAdjustments,
             reverseAdjustmentIds: adminReverseAdjustmentIds,
+            preserveExistingReceipt,
             includeSelectableAdjustmentComponents:
               needsAdjustmentDiscovery || adminCustomReceiptLines.some(
                 (line) => line.scope === 'SELECTED_COMPONENTS',

package/src/components/booking/useChangeBookingInitialHydration.ts

@@ -45,6 +45,16 @@ export interface UseChangeBookingInitialHydrationOptions {
   setError: Dispatch<SetStateAction<string>>;
 }
 
+export function initialPromoCodeToApply(
+  initialPromoCode: string | null | undefined,
+  lockedPromoCode: string | null,
+): string | null {
+  if (!lockedPromoCode) return null;
+  const normalizedInitial = initialPromoCode?.trim().toUpperCase() ?? '';
+  const normalizedLocked = lockedPromoCode.trim().toUpperCase();
+  return normalizedInitial && normalizedInitial === normalizedLocked ? normalizedInitial : null;
+}
+
 export function useChangeBookingInitialHydration({
   initialValues,
   lockedPromoCode,
@@ -84,7 +94,7 @@ export function useChangeBookingInitialHydration({
     const trimmedEmail = initialValues.customer?.email?.trim();
     const trimmedFirstName = initialValues.customer?.firstName?.trim();
     const trimmedLastName = initialValues.customer?.lastName?.trim();
-    const trimmedPromo = initialValues.promoCode?.trim().toUpperCase();
+    const initialPromoToApply = initialPromoCodeToApply(initialValues.promoCode, lockedPromoCode);
     if (trimmedEmail) setEmail(trimmedEmail);
     if (trimmedFirstName) setFirstName(trimmedFirstName);
     if (trimmedLastName) setLastName(trimmedLastName);
@@ -92,13 +102,16 @@ export function useChangeBookingInitialHydration({
       setPickupLocationId(initialValues.pickupLocationId.trim());
       setPickupLocationSkipped(false);
     }
-    if (trimmedPromo) {
-      setPromoCodeInput(trimmedPromo);
-      setAppliedPromoCode(trimmedPromo);
+    // Provider amendments show the historical code separately and require the operator to
+    // explicitly apply it again. Only public/self-serve flows pass a locked promo here.
+    if (initialPromoToApply) {
+      setPromoCodeInput(initialPromoToApply);
+      setAppliedPromoCode(initialPromoToApply);
     }
     hasAppliedInitialValuesRef.current = true;
   }, [
     initialValues,
+    lockedPromoCode,
     setAppliedPromoCode,
     setEmail,
     setFirstName,

package/src/lib/booking-api.ts

@@ -1475,6 +1475,8 @@ export interface ChangeBookingQuoteRequest {
   }>;
   /** Existing immutable adjustment ids to reverse as part of this amendment. */
   reverseAdjustmentIds?: string[];
+  /** Admin only: change operations without changing the receipt or outstanding balance. */
+  preserveExistingReceipt?: boolean;
 }
 
 /** FE-authored receipt payload for admin quote path (major units, booking currency). */

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

@@ -35,6 +35,7 @@ import {
   canReuseCompletedAdminChangeQuote,
   isAdminRefundDecisionDiscoveryQuote,
 } from '../src/components/booking/admin-change-quote-request-key';
+import { initialPromoCodeToApply } from '../src/components/booking/useChangeBookingInitialHydration';
 import {
   authoritativeItineraryDisplayFromChangeQuote,
   sliceAndMergeChangeQuoteForUi,
@@ -762,6 +763,21 @@ test('admin quote gate allows adjustment-only changes', () => {
     lastName: 'Tauro',
     missingRequiredReturnSelection: false,
   }), false);
+
+  assert.equal(canRequestAdminChangeQuote({
+    isCustomerSelfServeChange: true,
+    hasEffectiveChangeSelection: true,
+    initialSelectionHydrated: false,
+    hasSelectedAvailability: true,
+    bookingReference: 'DIFG66OF',
+    lastName: 'Tauro',
+    missingRequiredReturnSelection: false,
+  }), false);
+});
+
+test('provider reopen does not automatically reapply the historical promo', () => {
+  assert.equal(initialPromoCodeToApply(' LOCKEDIN2026 ', null), null);
+  assert.equal(initialPromoCodeToApply(' LOCKEDIN2026 ', 'LOCKEDIN2026'), 'LOCKEDIN2026');
 });
 
 test('admin preview and checkout share the Pricing V2 request shape', () => {
@@ -808,6 +824,38 @@ test('admin preview and checkout share the Pricing V2 request shape', () => {
   assert.equal('clientProposedTotal' in request, false);
 });
 
+test('preserve-receipt quote is a first-class backend mode and excludes price edits', () => {
+  const request = buildAdminChangeV2QuoteRequest({
+    bookingReference: 'VFSCAEKQ',
+    lastName: 'Tauro',
+    parentProductId: 'product_1',
+    optionId: 'option_2',
+    selectedAvailability: {
+      availabilityId: 'availability_2',
+      productId: 'option_2',
+      dateTime: '2026-07-29T08:35:00-06:00',
+      vacancies: 10,
+    } as Parameters<typeof buildAdminChangeV2QuoteRequest>[0]['selectedAvailability'],
+    pickupLocationId: 'pickup_1',
+    returnAvailabilityId: null,
+    bookingItems: [{ category: 'ADULT', count: 2 }],
+    addOnSelections: [],
+    cancellationPolicyId: 'policy_1',
+    structuredAdjustments: [{ adjustmentId: 'ignored_draft' }],
+    reverseAdjustmentIds: ['ignored_reversal'],
+    preserveExistingReceipt: true,
+    refundDispositionsByOperationId: { ignored_removal: 'PENDING_REFUND' },
+    previousPassengerCount: 2,
+    previousAvailabilityId: 'availability_1',
+    previousReturnAvailabilityId: null,
+  });
+
+  assert.equal(request.preserveExistingReceipt, true);
+  assert.deepEqual(request.structuredAdjustments, []);
+  assert.deepEqual(request.reverseAdjustmentIds, []);
+  assert.equal(request.refundDispositionsByOperationId, undefined);
+});
+
 test('admin Pricing V2 quote mapper preserves the server quote identity', async () => {
   const request = buildAdminChangeV2QuoteRequest({
     bookingReference: 'VFSCAEKQ',
@@ -934,6 +982,49 @@ test('admin no-charge provider payload carries the selected pickup itinerary', (
   assert.equal(payload?.promoApplicationScope, null);
 });
 
+test('preserve-receipt provider payload carries the mode without price mutations', () => {
+  const payload = buildAdminChangeProviderPayload({
+    selectedAvailability: {
+      availabilityId: 'availability_2',
+      productId: 'option_2',
+      dateTime: '2026-07-29T08:35:00-06:00',
+      vacancies: 10,
+    } as Parameters<typeof buildAdminChangeProviderPayload>[0]['selectedAvailability'],
+    availabilityProductOptionId: 'option_2',
+    bookingItems: [{ category: 'ADULT', count: 2 }],
+    product: { productId: 'product_1', name: 'Changed tour' } as Parameters<
+      typeof buildAdminChangeProviderPayload
+    >[0]['product'],
+    pickupLocationId: null,
+    selectedReturnOption: null,
+    addOnSelections: [],
+    cancellationPolicyId: null,
+    appliedPromoCode: null,
+    newTotalAmount: 999,
+    providerPricingOverrides: [{ lineKey: 'ticket', amount: 999 }],
+    mergedProviderAdditionalAdjustments: [{ label: 'Draft fee', amount: 10 }],
+    adminStructuredAdjustments: [{
+      adjustmentId: 'draft',
+      mode: 'FIXED_AMOUNT',
+      fixedAmount: 10,
+      scope: 'CURRENT_ACTIVE_BOOKING',
+      taxBehavior: 'NON_TAXABLE',
+      reasonCode: 'STAFF_ADJUSTMENT',
+    }],
+    adminReverseAdjustmentIds: ['old_adjustment'],
+    preserveExistingReceipt: true,
+    refundDispositionsByOperationId: { removal: 'PENDING_REFUND' },
+    previousPassengerCount: 2,
+  });
+
+  assert.equal(payload?.preserveExistingReceipt, true);
+  assert.equal(payload?.newTotalAmount, undefined);
+  assert.equal(payload?.pricingAdjustment, undefined);
+  assert.deepEqual(payload?.structuredAdjustments, []);
+  assert.deepEqual(payload?.reverseAdjustmentIds, []);
+  assert.deepEqual(payload?.refundDispositionsByOperationId, {});
+});
+
 test('public paid change preview shows amendment-only charges before combined tax', () => {
   const summary = buildPublicChangeAmountDueSummary([
     {
@@ -2197,6 +2288,10 @@ test('translates booking-change reason codes into operator-facing messages', ()
     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('missing_add_operation:return'),
+    'The return portion of this booking could not be priced. Re-select the return time and try again.',
+  );
   assert.equal(
     friendlyChangeBookingError('Remove the unavailable add-on before recalculating this amendment.'),
     'Remove the unavailable add-on before recalculating this amendment.',