@ticketboothapp/booking 1.2.186 → 1.2.187

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ticketboothapp/booking",
-  "version": "1.2.186",
+  "version": "1.2.187",
   "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 ?? [];
@@ -931,6 +934,7 @@ export function AdminChangeBookingFlow({
     adminCustomReceiptLines: appliedAdminCustomReceiptLines,
     adminStructuredAdjustments,
     adminReverseAdjustmentIds,
+    preserveExistingReceipt,
     needsAdjustmentDiscovery:
       isProviderDashboardChange && !hasHydratedExistingAdjustments,
     refundDispositionsByOperationId: activeRefundDispositionsByOperationId,
@@ -1153,6 +1157,7 @@ export function AdminChangeBookingFlow({
     mergedProviderAdditionalAdjustments,
     adminStructuredAdjustments,
     adminReverseAdjustmentIds,
+    preserveExistingReceipt,
     refundDispositionsByOperationId: activeRefundDispositionsByOperationId,
     providerApplyAuthoritativeReceipt,
     onSuccess,
@@ -1301,6 +1306,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);
@@ -367,15 +374,38 @@ export function AdminChangeReceiptComparison({
                 </p>
               ) : null}
             </div>
-            <span className="shrink-0 text-xs font-medium text-stone-500">
+            <div className="flex shrink-0 items-center gap-2">
+              {onPreserveExistingReceiptChange ? (
+                <button
+                  type="button"
+                  aria-pressed={preserveExistingReceipt}
+                  className={`rounded-md border px-2.5 py-1.5 text-xs font-semibold transition ${
+                    preserveExistingReceipt
+                      ? 'border-sky-700 bg-sky-700 text-white'
+                      : 'border-stone-300 bg-white text-stone-700 hover:border-sky-500 hover:text-sky-800'
+                  }`}
+                  onClick={() => onPreserveExistingReceiptChange(!preserveExistingReceipt)}
+                >
+                  Keep receipt unchanged
+                </button>
+              ) : null}
+              <span className="text-xs font-medium text-stone-500">
               {isProductFamilyConversion
                 ? formatCurrencyAmount(updatedTotal ?? 0, currency, displayLocale)
                 : bookingTotalChange == null
                   ? '—'
                   : formatCurrencyAmount(bookingTotalChange, currency, displayLocale)}
-            </span>
+              </span>
+            </div>
           </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 +446,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 +476,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;
 }
@@ -74,6 +75,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/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

@@ -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;
@@ -144,6 +145,7 @@ export function useAdminChangeQuotePreview({
   adminCustomReceiptLines,
   adminStructuredAdjustments,
   adminReverseAdjustmentIds,
+  preserveExistingReceipt,
   needsAdjustmentDiscovery,
   refundDispositionsByOperationId,
   useAdminFeAuthoritativeQuote,
@@ -238,6 +240,7 @@ export function useAdminChangeQuotePreview({
     promoApplicationScope,
     structuredAdjustments: adminStructuredAdjustments,
     reverseAdjustmentIds: adminReverseAdjustmentIds,
+    preserveExistingReceipt,
     refundDispositionsByOperationId,
     useAdminFeAuthoritativeQuote,
   }), [
@@ -255,6 +258,7 @@ export function useAdminChangeQuotePreview({
     promoApplicationScope,
     adminStructuredAdjustments,
     adminReverseAdjustmentIds,
+    preserveExistingReceipt,
     refundDispositionsByOperationId,
     useAdminFeAuthoritativeQuote,
   ]);
@@ -526,6 +530,7 @@ export function useAdminChangeQuotePreview({
             promoApplicationScope,
             structuredAdjustments: adminStructuredAdjustments,
             reverseAdjustmentIds: adminReverseAdjustmentIds,
+            preserveExistingReceipt,
             includeSelectableAdjustmentComponents:
               needsAdjustmentDiscovery || adminCustomReceiptLines.some(
                 (line) => line.scope === 'SELECTED_COMPONENTS',

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

@@ -808,6 +808,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 +966,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([
     {