@ticketboothapp/booking 1.2.74 → 1.2.76

package/CHANGE_BOOKING_BE_HANDOFF.md

@@ -84,3 +84,19 @@ Pickers show **catalog** prices by default (same booking **currency** as the ori
 - **Currency**: align optional maps and line `amount` values with `currency` / receipt currency; change booking stays in the booking’s sold currency end-to-end on FE.  
 - **Cancellation policy on change**: FE sends the booked policy on reserve/confirm paths; it is **not** chosen from product config during change — preserve the booking’s policy server-side unless product rules say otherwise.  
 - **`serverPreview.completeness`**: the package sets this to **`full`** whenever a preview is built (informational); UI does not gate on `totals_only` vs `full`.
+
+---
+
+## Admin / provider manual line items (signed adjustments)
+
+**Frontend (this package):** `AdminChangeBookingFlow` lets staff add custom receipt lines (label + signed amount). The same values are:
+
+1. **`POST …/change/quote`** — optional request field **`manualLineAdjustments`**: `Array<{ label: string; amount: number }>` in **major units** (same currency as the booking). Amounts are signed (credits negative). Omitted when there are no custom lines.
+2. **Provider apply** — `onChangeBooking` payload field **`pricingAdjustment`**, with **`mode: 'MANUAL_LINES'`** and **`additionalAdjustments`** equal to the **provider** inline editor rows **plus** these admin custom lines (concatenated). `newTotalAmount` remains the full proposed total (already includes those lines on the client).
+
+**Backend expectations**
+
+- **Quote:** When `manualLineAdjustments` is present, add each line to the server’s priced subtotal (before tax) for the change intent, and return quote totals / `amountDue` / line items that **include** these rows so the UI and `clientProposedTotal` stay in tolerance.
+- **Provider change API:** When `pricingAdjustment.additionalAdjustments` includes the same rows, persist them on the new receipt and charge the **same** total as `newTotalAmount` (within your rounding rules).
+
+If the server ignores `manualLineAdjustments` or `additionalAdjustments`, the customer will see the FE total but pay a different amount.

package/README.md

@@ -0,0 +1,9 @@
+# `@ticketboothapp/booking`
+
+Published as `@ticketboothapp/booking` (see `package.json`).
+
+**Local development in TicketBooth provider-dashboard** (link this package without publishing):
+
+- [docs/local-ticketbooth-provider-dashboard.md](./docs/local-ticketbooth-provider-dashboard.md)
+
+**In this monorepo:** apps use `workspace:*` / `transpilePackages`; run e.g. `npm run dev:booking` or `npm run dev:staff` from the website repo root.

package/docs/local-ticketbooth-provider-dashboard.md

@@ -0,0 +1,60 @@
+# Test `@ticketboothapp/booking` in TicketBooth provider-dashboard (local link)
+
+Use this when developing in **viavia-website** and you want **provider-dashboard** (`ticketbooth-fe`) to load your **workspace package** without publishing to npm.
+
+Provider-dashboard already sets `transpilePackages: ['@ticketboothapp/booking']`, so Next will compile the linked package from source.
+
+## Option A — `npm link` (quick toggle)
+
+**1. Register this package globally**
+
+From this repo’s booking package directory:
+
+```bash
+cd /path/to/viavia-website/packages/viavia-booking
+npm link
+```
+
+**2. Point provider-dashboard at that link**
+
+```bash
+cd /path/to/ticketbooth-fe/apps/provider-dashboard
+npm link @ticketboothapp/booking
+```
+
+**3. Run provider-dashboard**
+
+From the TicketBooth frontend monorepo root (typical for that repo):
+
+```bash
+cd /path/to/ticketbooth-fe
+npm run dev:provider
+```
+
+**Undo** (back to the version from the registry):
+
+```bash
+cd /path/to/ticketbooth-fe/apps/provider-dashboard
+npm unlink @ticketboothapp/booking
+npm install
+```
+
+If the workspace layout is odd, run `npm install` once at the `ticketbooth-fe` root after unlink.
+
+---
+
+## Option B — `file:` in `package.json` (stays on until you revert)
+
+In `apps/provider-dashboard/package.json`, set:
+
+```json
+"@ticketboothapp/booking": "file:/absolute/path/to/viavia-website/packages/viavia-booking"
+```
+
+Then from `ticketbooth-fe` root: `npm install` and `npm run dev:provider`.
+
+---
+
+## Option C — `overrides` in `ticketbooth-fe` root `package.json`
+
+Add an `overrides` entry for `@ticketboothapp/booking` pointing at the same `file:` path, then `npm install` at the monorepo root.

package/package.json

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

package/src/components/booking/AdminChangeBookingFlow.tsx

@@ -126,6 +126,9 @@ function mergeQuoteSliceWithServerPreview(
     serverPreview: buildChangeBookingServerPreview(quote, fallbackCart, currency),
     pricingDriftDetail: normalizePricingDriftDetailFromQuote(quote),
     ticketPricingTrace: normalizeTicketPricingTraceFromQuote(quote),
+    /** Same cent pair the BE uses for `amountDueCents` / intent & receipt "New Booking Difference" — use for signed refund display. */
+    quotePreviousTotalCents: quote.previousTotalCents,
+    quoteNewTotalCents: quote.newTotalCents,
   };
 }
 
@@ -726,6 +729,11 @@ export function AdminChangeBookingFlow({
   );
   /** Fetched add-ons for the selected product option */
   const [addOns, setAddOns] = useState<AddOn[]>([]);
+  /** Admin receipt-only adjustments (signed amount); affects FE subtotal/tax/total until persisted server-side. */
+  const [adminCustomReceiptLines, setAdminCustomReceiptLines] = useState<
+    Array<{ id: string; label: string; amountInput: string; amountSign: 1 | -1 }>
+  >([]);
+  const adminCustomLineIdRef = useRef(0);
 
   // Auto-apply promo code when parent page passes one (e.g. partner pages).
   // Seed input only; validate/apply runs after date/time + tickets exist (debounced + handleApplyPromo).
@@ -847,9 +855,10 @@ export function AdminChangeBookingFlow({
   const lockedPromoCode = initialValues?.promoCode?.trim()
     ? initialValues.promoCode.trim().toUpperCase()
     : null;
-  /** Public self-serve only: cannot reduce tickets below original counts. */
+  /** Public self-serve only: cannot reduce tickets below original counts. Provider-dashboard admins may reduce party size. */
   const changeBookingMinimumQuantities = useMemo(() => {
     if (!isCustomerSelfServeChange || !initialValues?.bookingItems?.length) return undefined;
+    if (isAdmin && isProviderDashboardChange) return undefined;
     const m: Record<string, number> = {};
     for (const item of initialValues.bookingItems) {
       const key = item.category?.trim();
@@ -857,7 +866,7 @@ export function AdminChangeBookingFlow({
       m[key] = Math.max(0, Number(item.count) || 0);
     }
     return m;
-  }, [isCustomerSelfServeChange, initialValues?.bookingItems]);
+  }, [isCustomerSelfServeChange, initialValues?.bookingItems, isAdmin, isProviderDashboardChange]);
   const [adminChoiceData, setAdminChoiceData] = useState<{
     reservationReference: string;
     reservationExpiration?: string;
@@ -890,6 +899,9 @@ export function AdminChangeBookingFlow({
     quotedTotal?: number;
     /** From `quoteChangeBooking` receipt fields — drives PriceSummary when self-serve. */
     serverDisplay?: { total: number; subtotal: number; tax: number };
+    /** Server quote cents — authoritative vs `serverDisplay` scaling (aligns with receipt difference line). */
+    quotePreviousTotalCents?: number;
+    quoteNewTotalCents?: number;
     /** Parsed from last quote — unified server-owned preview for lines + picker overrides. */
     serverPreview: ReturnType<typeof buildChangeBookingServerPreview>;
     pricingDriftDetail?: ChangeBookingQuotePricingDriftDetail;
@@ -2909,6 +2921,22 @@ export function AdminChangeBookingFlow({
       : subtotal;
   const effectiveSubtotal = effectiveSubtotalBeforeAddOns + addOnTotal;
 
+  const adminCustomAdjustmentTotal = useMemo(
+    () =>
+      roundMoney(
+        adminCustomReceiptLines.reduce((sum, line) => {
+          const raw = line.amountInput.trim();
+          if (raw === '' || raw === '+' || raw === '-') return sum;
+          const n = Number(raw);
+          if (!Number.isFinite(n)) return sum;
+          const sign = line.amountSign ?? 1;
+          return sum + sign * Math.abs(n);
+        }, 0)
+      ),
+    [adminCustomReceiptLines]
+  );
+  const effectiveSubtotalForCheckout = roundMoney(effectiveSubtotal + adminCustomAdjustmentTotal);
+
   /** Stable signature for promo discount API (avoid effect re-fire on object identity churn). */
   const quantitiesSignature = useMemo(
     () =>
@@ -3123,7 +3151,7 @@ export function AdminChangeBookingFlow({
       selectedAvailability.availabilityId ?? '',
       currency,
       quantitiesSignature,
-      String(Math.round(effectiveSubtotal * 100)),
+      String(Math.round(effectiveSubtotalForCheckout * 100)),
       lockedPromoCode ? String(Math.round((originalReceipt?.promoAmount ?? 0) * 100)) : '',
     ].join('::');
   }, [
@@ -3136,7 +3164,7 @@ export function AdminChangeBookingFlow({
     product.productId,
     currency,
     quantitiesSignature,
-    effectiveSubtotal,
+    effectiveSubtotalForCheckout,
     lockedPromoCode,
     originalReceipt?.promoAmount,
   ]);
@@ -3144,7 +3172,7 @@ export function AdminChangeBookingFlow({
   promoDiscountParamsRef.current = {
     selectedAvailability,
     ticketLineItems: ticketLineItems.map((l) => ({ category: l.category, qty: l.qty })),
-    effectiveSubtotal,
+    effectiveSubtotal: effectiveSubtotalForCheckout,
     appliedPromoCode,
     changeBookingPromo: lockedPromoCode
       ? { priorAmount: originalReceipt?.promoAmount }
@@ -3225,12 +3253,12 @@ export function AdminChangeBookingFlow({
       : 0;
   const effectivePromoDiscountAmount =
     promoDiscountAmount > 0 ? promoDiscountAmount : lockedPromoFallbackAmount;
-  const taxOnSubtotal = isTaxIncludedInPrice ? 0 : effectiveSubtotal * (pricingConfig?.taxRate ?? 0);
+  const taxOnSubtotal = isTaxIncludedInPrice ? 0 : effectiveSubtotalForCheckout * (pricingConfig?.taxRate ?? 0);
   const effectiveTax =
     effectivePromoDiscountAmount > 0 && !isGiftCard && !isVoucher
-      ? (effectiveSubtotal - effectivePromoDiscountAmount) * (pricingConfig?.taxRate ?? 0)
+      ? (effectiveSubtotalForCheckout - effectivePromoDiscountAmount) * (pricingConfig?.taxRate ?? 0)
       : taxOnSubtotal;
-  const totalPrice = effectiveSubtotal + effectiveTax - effectivePromoDiscountAmount;
+  const totalPrice = effectiveSubtotalForCheckout + effectiveTax - effectivePromoDiscountAmount;
   /**
    * FE cart rollup for line math, breakdowns, and `clientProposedTotal` hint to the API. Self-serve **footer** totals
    * prefer `latestChangeQuote` once quote succeeds — this value is not an alternate source of truth for checkout.
@@ -3661,9 +3689,29 @@ export function AdminChangeBookingFlow({
       return currentAmount !== originalAmount || currentLabel !== originalLabel || currentMode !== originalMode;
     });
   const hasEffectiveChangeSelection =
-    hasChangeSelection || providerHasEditedLineOverrides || providerHasAdditionalAdjustments;
+    hasChangeSelection ||
+    providerHasEditedLineOverrides ||
+    providerHasAdditionalAdjustments ||
+    Math.abs(adminCustomAdjustmentTotal) >= 0.005;
+
+  /**
+   * True until `quoteChangeBooking` returns a confirmed `serverDisplay` for the current selection.
+   * Named so manual price-line UI can align with “still settling final price” without touching ticket/receipt math.
+   */
+  const changeFlowFinalPricePending =
+    suppressSelfServeCurrencyUi &&
+    selectedAvailability != null &&
+    totalQuantity > 0 &&
+    !selfServePricingConfirmed;
+
+  /**
+   * Provider inline edits + admin custom lines: show while waiting on or after the authoritative quote.
+   * UI-only gate — does not alter ticket line items or receipt-floor rules.
+   */
+  const showChangeFlowManualPriceLines =
+    changeFlowFinalPricePending || selfServePricingConfirmed;
 
-  const displayedChangeAmounts = resolveChangeFlowDisplayedAmounts({
+  const displayedChangeAmountsRaw = resolveChangeFlowDisplayedAmounts({
     providerPreview: providerTotalsPreview,
     serverQuotePreview:
       isCustomerSelfServeChange && latestChangeQuote?.serverDisplay
@@ -3671,30 +3719,130 @@ export function AdminChangeBookingFlow({
         : null,
     fromCart: {
       total: changeFlowNewBookingTotal,
-      subtotal: effectiveSubtotal,
+      subtotal: effectiveSubtotalForCheckout,
       tax: effectiveTax,
     },
   });
-  const displayChangeFlowProposedTotal = displayedChangeAmounts.total;
-  const displayChangeFlowSubtotal = displayedChangeAmounts.subtotal;
-  const displayChangeFlowTax = displayedChangeAmounts.tax;
+  /** When cart drives display, {@link effectiveSubtotalForCheckout} already includes admin adjustments — do not add twice. */
+  const displayLayerUsesExternalPricing =
+    Boolean(providerTotalsPreview) ||
+    (isCustomerSelfServeChange && Boolean(latestChangeQuote?.serverDisplay));
+  const adminTaxDeltaForExternalDisplay =
+    displayLayerUsesExternalPricing && !isTaxIncludedInPrice && Math.abs(adminCustomAdjustmentTotal) >= 0.0005
+      ? roundMoney(adminCustomAdjustmentTotal * (pricingConfig?.taxRate ?? 0))
+      : 0;
+  const displayChangeFlowSubtotal = roundMoney(
+    displayedChangeAmountsRaw.subtotal +
+      (displayLayerUsesExternalPricing ? adminCustomAdjustmentTotal : 0)
+  );
+  const displayChangeFlowTax = roundMoney(displayedChangeAmountsRaw.tax + adminTaxDeltaForExternalDisplay);
+  const displayChangeFlowProposedTotal = roundMoney(
+    displayLayerUsesExternalPricing
+      ? displayedChangeAmountsRaw.total + adminCustomAdjustmentTotal + adminTaxDeltaForExternalDisplay
+      : displayedChangeAmountsRaw.total
+  );
 
   const changeFlowClientEstimateDue = (() => {
     if (!originalReceipt) return totalPrice;
-    // Customer self-serve: amount due comes from POST .../change/quote (`amountDueCents` / priceDiff), not FE delta math.
+    // Self-serve quote: match BE receipt / intent: (newTotalCents − previousTotalCents) / 100.
     if (isCustomerSelfServeChange && latestChangeQuote != null && !changeQuoteFetchError) {
+      const pq = latestChangeQuote.quotePreviousTotalCents;
+      const nq = latestChangeQuote.quoteNewTotalCents;
+      if (pq != null && nq != null) {
+        return normalizeNearZeroOwed(roundMoney((nq - pq) / 100));
+      }
+      if (latestChangeQuote.serverDisplay != null) {
+        return normalizeNearZeroOwed(
+          roundMoney(latestChangeQuote.serverDisplay.total - originalReceipt.total),
+        );
+      }
       return normalizeNearZeroOwed(latestChangeQuote.priceDiff);
     }
     return changeFlowBalanceVsOriginal({
       newTotal: displayChangeFlowProposedTotal,
       originalReceiptTotal: originalReceipt.total,
-      audience: isProviderDashboardChange ? 'provider' : 'customer',
+      audience: 'admin',
     });
   })();
 
   const changeFlowAmountDueRaw = changeFlowClientEstimateDue;
   const changeFlowAmountDue = normalizeNearZeroOwed(changeFlowAmountDueRaw);
 
+  const changeFlowAdminPricingDebugPanel = useMemo(() => {
+    if (!isAdmin || !selectedAvailability || totalQuantity <= 0) return null;
+    const fmt = (n: number) => formatCurrencyAmount(roundMoney(n), currency, locale as 'en' | 'fr');
+    const path = (() => {
+      if (!originalReceipt) return 'totalPrice (no original receipt)';
+      if (isCustomerSelfServeChange && latestChangeQuote != null && !changeQuoteFetchError) {
+        if (
+          latestChangeQuote.quotePreviousTotalCents != null &&
+          latestChangeQuote.quoteNewTotalCents != null
+        ) {
+          return 'POST /change/quote: (quoteNewTotalCents − quotePreviousTotalCents) / 100';
+        }
+        if (latestChangeQuote.serverDisplay != null) {
+          return 'POST /change/quote: serverDisplay.total − originalReceipt.total';
+        }
+        return 'POST /change/quote: priceDiff (API balance delta)';
+      }
+      return 'FE: displayChangeFlowProposedTotal − originalReceipt.total (signed; used when quote not driving amount-due)';
+    })();
+    const quoteTotalPreview =
+      latestChangeQuote?.serverDisplay != null ? fmt(latestChangeQuote.serverDisplay.total) : '—';
+    return (
+      <details className="mt-3 rounded-md border border-amber-200/80 bg-amber-50/50 p-2 text-left text-xs text-amber-950">
+        <summary className="cursor-pointer select-none font-medium text-stone-800">
+          Price calculation (admin debug)
+        </summary>
+        <pre className="mt-2 max-h-64 overflow-auto whitespace-pre-wrap break-words font-mono text-[11px] leading-relaxed text-stone-800">
+          {[
+            `Amount-due path: ${path}`,
+            `displayLayerUsesExternalPricing: ${String(displayLayerUsesExternalPricing)} (server/provider totals omit FE admin lines until overlaid)`,
+            `selfServePricingConfirmed: ${String(selfServePricingConfirmed)} · changeQuoteLoading: ${String(changeQuoteLoading)}`,
+            `Cart subtotal (excl. admin custom lines): ${fmt(effectiveSubtotal)}`,
+            `Admin custom lines (sum): ${fmt(adminCustomAdjustmentTotal)}`,
+            `Checkout subtotal (incl. admin lines): ${fmt(effectiveSubtotalForCheckout)}`,
+            `effectiveTax · promo discount: ${fmt(effectiveTax)} · ${fmt(effectivePromoDiscountAmount)}`,
+            `totalPrice (subtotal + tax − promo): ${fmt(totalPrice)}`,
+            `changeFlowNewBookingTotal (after cent reconcile vs receipt): ${fmt(changeFlowNewBookingTotal)}`,
+            `Displayed layer subtotal / tax / total: ${fmt(displayedChangeAmountsRaw.subtotal)} / ${fmt(displayedChangeAmountsRaw.tax)} / ${fmt(displayedChangeAmountsRaw.total)}`,
+            `displayChangeFlowProposedTotal (summary / preview footer): ${fmt(displayChangeFlowProposedTotal)}`,
+            originalReceipt ? `originalReceipt.total: ${fmt(originalReceipt.total)}` : 'originalReceipt: —',
+            `Quote serverDisplay.total (if any): ${quoteTotalPreview}`,
+            `changeFlowClientEstimateDue (before near-zero): ${fmt(changeFlowClientEstimateDue)}`,
+            `changeFlowAmountDue (PriceSummary total row): ${fmt(changeFlowAmountDue)}`,
+          ].join('\n')}
+        </pre>
+      </details>
+    );
+  }, [
+    isAdmin,
+    selectedAvailability,
+    totalQuantity,
+    currency,
+    locale,
+    originalReceipt,
+    isCustomerSelfServeChange,
+    latestChangeQuote,
+    changeQuoteFetchError,
+    displayLayerUsesExternalPricing,
+    selfServePricingConfirmed,
+    changeQuoteLoading,
+    effectiveSubtotal,
+    adminCustomAdjustmentTotal,
+    effectiveSubtotalForCheckout,
+    effectiveTax,
+    effectivePromoDiscountAmount,
+    totalPrice,
+    changeFlowNewBookingTotal,
+    displayedChangeAmountsRaw.subtotal,
+    displayedChangeAmountsRaw.tax,
+    displayedChangeAmountsRaw.total,
+    displayChangeFlowProposedTotal,
+    changeFlowClientEstimateDue,
+    changeFlowAmountDue,
+  ]);
+
   const changeCheckoutButtonLabel = (() => {
     if (!hasEffectiveChangeSelection) return undefined;
     if (isProviderDashboardChange) {
@@ -3722,7 +3870,9 @@ export function AdminChangeBookingFlow({
         const d = Math.round(changeFlowClientEstimateDue * 100) / 100;
         return d > 0
           ? `Change booking (${formatCurrencyAmount(d, currency, locale as 'en' | 'fr')})`
-          : 'Change booking (no charge)';
+          : d < 0
+            ? `Change booking (${formatCurrencyAmount(d, currency, locale as 'en' | 'fr')})`
+            : 'Change booking (no charge)';
       }
       const tr = t('booking.changeBooking');
       return tr !== 'booking.changeBooking' ? tr : 'Change booking';
@@ -3730,7 +3880,9 @@ export function AdminChangeBookingFlow({
     const est = Math.round(changeFlowClientEstimateDue * 100) / 100;
     return est > 0
       ? `Change booking (${formatCurrencyAmount(est, currency, locale as 'en' | 'fr')})`
-      : 'Change booking (no charge)';
+      : est < 0
+        ? `Change booking (${formatCurrencyAmount(est, currency, locale as 'en' | 'fr')})`
+        : 'Change booking (no charge)';
   })();
   /** Partner deferred-invoice path applies to {@link NewBookingFlow} only. */
   const deferredInvoiceSubmitLabel = undefined;
@@ -3772,6 +3924,25 @@ export function AdminChangeBookingFlow({
           .filter((v): v is { label: string; amount: number } => v != null)
       : [];
 
+  /** Same rows as checkout breakdown — sent on provider apply + optional public change-quote for BE parity. */
+  const adminCustomLinesAsAdditionalAdjustments = useMemo((): Array<{ label: string; amount: number }> => {
+    return adminCustomReceiptLines.flatMap((line) => {
+      const raw = line.amountInput.trim();
+      if (raw === '' || raw === '+' || raw === '-') return [];
+      const n = Number(raw);
+      if (!Number.isFinite(n) || Math.abs(n) < 0.0005) return [];
+      const sign = line.amountSign ?? 1;
+      const amount = roundMoney(sign * Math.abs(n));
+      if (Math.abs(amount) < 0.005) return [];
+      return [{ label: line.label.trim() || 'Adjustment', amount }];
+    });
+  }, [adminCustomReceiptLines]);
+
+  const mergedProviderAdditionalAdjustments = useMemo(
+    () => [...providerAdditionalAdjustments, ...adminCustomLinesAsAdditionalAdjustments],
+    [providerAdditionalAdjustments, adminCustomLinesAsAdditionalAdjustments]
+  );
+
   const changeFlowSelectionPreview = useMemo((): ChangeFlowSelectionPreview | null => {
     if (!selectedAvailability || totalQuantity <= 0) return null;
     const ticketsLine = formatTicketLineItemsForSummary(
@@ -3847,7 +4018,7 @@ export function AdminChangeBookingFlow({
       return;
     }
     onPricePreviewChange({
-      subtotal: originalReceipt ? displayChangeFlowSubtotal : effectiveSubtotal,
+      subtotal: originalReceipt ? displayChangeFlowSubtotal : effectiveSubtotalForCheckout,
       tax:
         !isTaxIncludedInPrice
           ? originalReceipt
@@ -3861,7 +4032,7 @@ export function AdminChangeBookingFlow({
     onPricePreviewChange,
     selectedAvailability,
     totalQuantity,
-    effectiveSubtotal,
+    effectiveSubtotalForCheckout,
     effectiveTax,
     displayChangeFlowProposedTotal,
     displayChangeFlowSubtotal,
@@ -3926,6 +4097,9 @@ export function AdminChangeBookingFlow({
             newPassengerCounts: bookingItems,
             // Omit when empty: backend treats [] as "clear all"; missing = preserve stored selections (BookingChangeIntentService).
             ...(addOnSelections.length > 0 ? { newAddOnSelections: addOnSelections } : {}),
+            ...(adminCustomLinesAsAdditionalAdjustments.length > 0
+              ? { manualLineAdjustments: adminCustomLinesAsAdditionalAdjustments }
+              : {}),
             clientProposedTotal: changeFlowNewBookingTotal,
             capacitySeatCredit: {
               enabled: true,
@@ -3939,7 +4113,7 @@ export function AdminChangeBookingFlow({
             quote,
             {
               total: changeFlowNewBookingTotal,
-              subtotal: effectiveSubtotal,
+              subtotal: effectiveSubtotalForCheckout,
               tax: effectiveTax,
             },
             currency
@@ -3947,7 +4121,7 @@ export function AdminChangeBookingFlow({
           setLatestChangeQuote(
             mergeQuoteSliceWithServerPreview(slice, quote, {
               total: changeFlowNewBookingTotal,
-              subtotal: effectiveSubtotal,
+              subtotal: effectiveSubtotalForCheckout,
               tax: effectiveTax,
             }, currency),
           );
@@ -3981,13 +4155,14 @@ export function AdminChangeBookingFlow({
     addOnSelections,
     changeFlowInitialTicketCount,
     changeFlowNewBookingTotal,
-    effectiveSubtotal,
+    effectiveSubtotalForCheckout,
     effectiveTax,
     totalPrice,
     currency,
     activeOptions,
     initialValues?.availabilityId,
     initialValues?.returnAvailabilityId,
+    adminCustomLinesAsAdditionalAdjustments,
   ]);
 
   // Auto-select product option when date is selected: most popular if set, otherwise first available.
@@ -4518,6 +4693,9 @@ export function AdminChangeBookingFlow({
           newReturnAvailabilityId: selectedReturnOption?.returnAvailabilityId ?? null,
           newPassengerCounts: bookingItems,
           ...(addOnSelections.length > 0 ? { newAddOnSelections: addOnSelections } : {}),
+          ...(adminCustomLinesAsAdditionalAdjustments.length > 0
+            ? { manualLineAdjustments: adminCustomLinesAsAdditionalAdjustments }
+            : {}),
           clientProposedTotal:
             latestChangeQuote?.serverDisplay?.total ?? changeFlowNewBookingTotal,
         });
@@ -4525,7 +4703,7 @@ export function AdminChangeBookingFlow({
           quote,
           {
             total: changeFlowNewBookingTotal,
-            subtotal: effectiveSubtotal,
+            subtotal: effectiveSubtotalForCheckout,
             tax: effectiveTax,
           },
           currency
@@ -4536,7 +4714,7 @@ export function AdminChangeBookingFlow({
         setLatestChangeQuote(
           mergeQuoteSliceWithServerPreview(quoteSlice, quote, {
             total: changeFlowNewBookingTotal,
-            subtotal: effectiveSubtotal,
+            subtotal: effectiveSubtotalForCheckout,
             tax: effectiveTax,
           }, currency),
         );
@@ -4548,30 +4726,41 @@ export function AdminChangeBookingFlow({
           quote.proposed?.total ??
           quote.newReceipt?.total ??
           changeFlowNewBookingTotal;
-        const feChangeDue = changeFlowBalanceVsOriginal({
-          newTotal: serverNewTotalForGuard,
-          originalReceiptTotal: originalReceipt?.total ?? 0,
-          audience: 'customer',
-        });
-        const serverAmountDue =
-          quote.amountDueCents != null
-            ? Math.max(0, quote.amountDueCents / 100)
-            : Math.max(0, quote.priceDiff ?? 0);
-        if (feChangeDue > 0.02 && serverAmountDue <= 0.009) {
+        /** Signed proposed − previous (major units). Matches quote slices when cents present; refund owed < 0. */
+        const signedBalanceMajor =
+          quote.previousTotalCents != null && quote.newTotalCents != null
+            ? (quote.newTotalCents - quote.previousTotalCents) / 100
+            : quote.balanceDeltaMajorUnits ?? null;
+        const chargeDue =
+          signedBalanceMajor != null
+            ? Math.max(0, signedBalanceMajor)
+            : quote.amountDueCents != null
+              ? quote.amountDueCents / 100
+              : Math.max(0, quote.priceDiff ?? 0);
+        const feChangeDue =
+          signedBalanceMajor ??
+          changeFlowBalanceVsOriginal({
+            newTotal: serverNewTotalForGuard,
+            originalReceiptTotal: originalReceipt?.total ?? 0,
+            audience: 'admin',
+          });
+        if (feChangeDue > 0.02 && chargeDue <= 0.009) {
           throw new Error(
             'This change requires payment, but the price could not be confirmed. Please refresh and try again.'
           );
         }
-        // No-payment change: FE shows nothing owed — still require server agreement so we never confirm free when a charge is due.
-        if (serverAmountDue <= 0.009) {
+        // No additional charge (includes refund-owed / downgrade): confirm-free apply only when server agrees no payment due.
+        if (chargeDue <= 0.009) {
           if (feChangeDue > 0.02) {
             throw new Error(
               'This change requires payment, but the price could not be confirmed. Please refresh and try again.'
             );
           }
-          const p = quote.proposed?.total ?? quote.newReceipt?.total;
-          const o = quote.original?.total ?? quote.originalReceipt?.total;
-          if (p != null && o != null && p - o > 0.01) {
+          const upgradeWithoutCharge =
+            quote.newTotalCents != null &&
+            quote.previousTotalCents != null &&
+            quote.newTotalCents > quote.previousTotalCents + 1;
+          if (upgradeWithoutCharge) {
             throw new Error(
               'This change requires payment, but the price could not be confirmed. Please refresh and try again.'
             );
@@ -4623,11 +4812,14 @@ export function AdminChangeBookingFlow({
       // Backend will charge totalAmount and store this as the receipt so /manage matches.
       const taxForBreakdown = effectivePromoDiscountAmount > 0 ? effectiveTax : tax;
       const amountDueForCheckout = isCustomerSelfServeChange
-        ? changeFlowBalanceVsOriginal({
-            newTotal: changeFlowNewBookingTotal,
-            originalReceiptTotal: originalReceipt?.total ?? 0,
-            audience: 'customer',
-          })
+        ? Math.max(
+            0,
+            changeFlowBalanceVsOriginal({
+              newTotal: changeFlowNewBookingTotal,
+              originalReceiptTotal: originalReceipt?.total ?? 0,
+              audience: 'admin',
+            }),
+          )
         : totalPrice;
       const lines = [
         ...ticketLineItemsForChangeFlowDisplay.map((line) => ({
@@ -4679,6 +4871,21 @@ export function AdminChangeBookingFlow({
           type: 'FEE' as const,
           quantity: totalQuantity,
         })),
+        ...adminCustomReceiptLines.flatMap((adjLine) => {
+          const raw = adjLine.amountInput.trim();
+          if (raw === '' || raw === '+' || raw === '-') return [];
+          const n = Number(raw);
+          if (!Number.isFinite(n) || Math.abs(n) < 0.0005) return [];
+          const sign = adjLine.amountSign ?? 1;
+          const amount = sign * Math.abs(n);
+          return [
+            {
+              label: adjLine.label.trim() || 'Adjustment',
+              amount,
+              type: 'FEE' as const,
+            },
+          ];
+        }),
         ...(!isTaxIncludedInPrice && taxForBreakdown > 0
           ? [
               {
@@ -4772,7 +4979,7 @@ export function AdminChangeBookingFlow({
           returnPriceAdjustment: checkoutReturnLineAmount,
           cancellationPolicyFee,
           cancellationPolicyLabel: effectiveCancellationPolicyLabel,
-          subtotal: effectiveSubtotal,
+          subtotal: effectiveSubtotalForCheckout,
           tax: effectivePromoDiscountAmount > 0 ? effectiveTax : tax,
           totalQuantity,
           isTaxIncludedInPrice,
@@ -4833,7 +5040,7 @@ export function AdminChangeBookingFlow({
         returnPriceAdjustment: checkoutReturnLineAmount,
         cancellationPolicyFee,
         cancellationPolicyLabel: effectiveCancellationPolicyLabel,
-        subtotal: effectiveSubtotal,
+        subtotal: effectiveSubtotalForCheckout,
         tax: effectivePromoDiscountAmount > 0 ? effectiveTax : tax,
         total: amountDueForCheckout,
         totalQuantity,
@@ -4954,11 +5161,13 @@ export function AdminChangeBookingFlow({
           newTotalAmount: displayChangeFlowProposedTotal,
           additionalHoursCount: null,
           pricingAdjustment:
-            providerPricingOverrides.length > 0 || providerAdditionalAdjustments.length > 0
+            providerPricingOverrides.length > 0 || mergedProviderAdditionalAdjustments.length > 0
               ? {
                   mode: 'MANUAL_LINES',
-                  lineOverrides: providerPricingOverrides,
-                  additionalAdjustments: providerAdditionalAdjustments,
+                  ...(providerPricingOverrides.length > 0 ? { lineOverrides: providerPricingOverrides } : {}),
+                  ...(mergedProviderAdditionalAdjustments.length > 0
+                    ? { additionalAdjustments: mergedProviderAdditionalAdjustments }
+                    : {}),
                 }
               : undefined,
           capacitySeatCredit: {
@@ -5326,10 +5535,12 @@ export function AdminChangeBookingFlow({
                 replacePriceSummary={selfServeCheckoutPlaceholder}
                 totalPrice={changeFlowAmountDue}
                 totalSummaryLabel={
-                  t('booking.totalOwedForBookingChange') &&
-                  t('booking.totalOwedForBookingChange') !== 'booking.totalOwedForBookingChange'
-                    ? t('booking.totalOwedForBookingChange')
-                    : 'Total owed for booking difference'
+                  changeFlowAmountDue < -0.005
+                    ? 'Refund owed (vs original booking)'
+                    : t('booking.totalOwedForBookingChange') &&
+                        t('booking.totalOwedForBookingChange') !== 'booking.totalOwedForBookingChange'
+                      ? t('booking.totalOwedForBookingChange')
+                      : 'Total owed for booking difference'
                 }
                 subtotal={displayChangeFlowSubtotal}
                 taxAmount={
@@ -5358,76 +5569,194 @@ export function AdminChangeBookingFlow({
                     !providerPricingUi.error ? (
                       <div className="mt-2 text-xs text-stone-500">{providerPricingUi.helperText}</div>
                     ) : null}
+                    {changeFlowAdminPricingDebugPanel}
                   </>
                 }
                 extraBeforeSubtotal={
-                  showProviderPricingInlineEditor && (providerPricingUi?.additionalAdjustments?.length ?? 0) > 0 ? (
-                    <div className="space-y-1">
-                      {providerPricingUi?.additionalAdjustments?.map((adj) => (
-                        <div key={adj.id} className="flex items-center justify-between gap-2 text-sm">
-                          <div className="flex min-w-0 items-center gap-1">
-                            <button
-                              type="button"
-                              className="rounded border border-stone-300 px-1 text-xs text-stone-600 hover:bg-stone-100"
-                              onClick={() => providerPricingUi?.onRemoveAdditionalAdjustment?.(adj.id)}
-                            >
-                              -
-                            </button>
+                  showChangeFlowManualPriceLines ? (
+                  <>
+                    {showProviderPricingInlineEditor && (providerPricingUi?.additionalAdjustments?.length ?? 0) > 0 ? (
+                      <div className="space-y-1">
+                        {providerPricingUi?.additionalAdjustments?.map((adj) => (
+                          <div key={adj.id} className="flex items-center justify-between gap-2 text-sm">
+                            <div className="flex min-w-0 items-center gap-1">
+                              <button
+                                type="button"
+                                className="rounded border border-stone-300 px-1 text-xs text-stone-600 hover:bg-stone-100"
+                                onClick={() => providerPricingUi?.onRemoveAdditionalAdjustment?.(adj.id)}
+                              >
+                                -
+                              </button>
+                              <input
+                                type="text"
+                                className="w-40 rounded border border-stone-300 px-2 py-0.5 text-sm"
+                                placeholder="Line description"
+                                value={adj.label}
+                                onChange={(e) =>
+                                  providerPricingUi?.onUpdateAdditionalAdjustment?.(adj.id, { label: e.target.value })
+                                }
+                              />
+                            </div>
+                            <div className="flex items-center gap-1">
+                              <select
+                                className="rounded border border-stone-300 px-1 py-0.5 text-xs"
+                                value={adj.mode}
+                                onChange={(e) =>
+                                  providerPricingUi?.onUpdateAdditionalAdjustment?.(adj.id, {
+                                    mode: e.target.value as 'DISCOUNT' | 'CHARGE',
+                                  })
+                                }
+                              >
+                                <option value="DISCOUNT">-</option>
+                                <option value="CHARGE">+</option>
+                              </select>
+                              <input
+                                type="text"
+                                inputMode="decimal"
+                                className="h-6 w-24 rounded border border-stone-300 bg-white px-2 py-0.5 text-right text-sm font-medium leading-none text-stone-700"
+                                placeholder="0.00"
+                                value={adj.amountInput}
+                                onChange={(e) =>
+                                  providerPricingUi?.onUpdateAdditionalAdjustment?.(adj.id, {
+                                    amountInput: e.target.value,
+                                  })
+                                }
+                              />
+                            </div>
+                          </div>
+                        ))}
+                        <button
+                          type="button"
+                          className="rounded border border-stone-300 px-2 py-0.5 text-xs text-stone-600 hover:bg-stone-100"
+                          onClick={() => providerPricingUi?.onAddAdditionalAdjustment?.()}
+                        >
+                          + add line item
+                        </button>
+                      </div>
+                    ) : showProviderPricingInlineEditor ? (
+                      <button
+                        type="button"
+                        className="rounded border border-stone-300 px-2 py-0.5 text-xs text-stone-600 hover:bg-stone-100"
+                        onClick={() => providerPricingUi?.onAddAdditionalAdjustment?.()}
+                      >
+                        + add line item
+                      </button>
+                    ) : null}
+                    <div className="space-y-3">
+                      <div className="flex justify-center">
+                        <button
+                          type="button"
+                          className="admin-custom-receipt-line-add inline-flex items-center gap-1.5 rounded-full border border-dashed border-stone-300 bg-stone-50/80 text-xs font-medium text-stone-600 hover:border-stone-400 hover:bg-stone-100"
+                          onClick={() => {
+                            adminCustomLineIdRef.current += 1;
+                            setAdminCustomReceiptLines((prev) => [
+                              ...prev,
+                              {
+                                id: `admin-rcpt-${adminCustomLineIdRef.current}`,
+                                label: '',
+                                amountInput: '',
+                                amountSign: 1,
+                              },
+                            ]);
+                          }}
+                        >
+                          <span className="text-base font-semibold leading-none text-stone-700" aria-hidden>
+                            +
+                          </span>
+                          Add custom line
+                        </button>
+                      </div>
+                      {adminCustomReceiptLines.map((adj) => {
+                        const sign = adj.amountSign ?? 1;
+                        return (
+                          <div
+                            key={adj.id}
+                            className="admin-custom-receipt-line flex flex-wrap items-center gap-2 text-sm sm:flex-nowrap"
+                          >
                             <input
                               type="text"
-                              className="w-40 rounded border border-stone-300 px-2 py-0.5 text-sm"
-                              placeholder="Line description"
+                              className="admin-custom-receipt-input min-w-[8rem] flex-1 rounded-md border border-stone-300 bg-white text-sm text-stone-800 placeholder:text-stone-400"
+                              placeholder="Description"
                               value={adj.label}
                               onChange={(e) =>
-                                providerPricingUi?.onUpdateAdditionalAdjustment?.(adj.id, { label: e.target.value })
+                                setAdminCustomReceiptLines((prev) =>
+                                  prev.map((l) => (l.id === adj.id ? { ...l, label: e.target.value } : l))
+                                )
                               }
                             />
-                          </div>
-                          <div className="flex items-center gap-1">
-                            <select
-                              className="rounded border border-stone-300 px-1 py-0.5 text-xs"
-                              value={adj.mode}
-                              onChange={(e) =>
-                                providerPricingUi?.onUpdateAdditionalAdjustment?.(adj.id, {
-                                  mode: e.target.value as 'DISCOUNT' | 'CHARGE',
-                                })
-                              }
+                            <div
+                              className="flex shrink-0 rounded-lg border border-stone-300 bg-stone-100/90 p-0.5 shadow-sm"
+                              role="group"
+                              aria-label="Line adds to total or reduces it"
                             >
-                              <option value="DISCOUNT">-</option>
-                              <option value="CHARGE">+</option>
-                            </select>
+                              <button
+                                type="button"
+                                className={`admin-custom-receipt-segment rounded-md text-xs font-semibold transition-colors sm:text-sm ${
+                                  sign === 1
+                                    ? 'bg-white text-emerald-800 shadow-sm ring-1 ring-stone-200/80'
+                                    : 'text-stone-500 hover:bg-stone-200/60 hover:text-stone-700'
+                                }`}
+                                aria-pressed={sign === 1}
+                                onClick={() =>
+                                  setAdminCustomReceiptLines((prev) =>
+                                    prev.map((l) => (l.id === adj.id ? { ...l, amountSign: 1 } : l))
+                                  )
+                                }
+                              >
+                                Charge (+)
+                              </button>
+                              <button
+                                type="button"
+                                className={`admin-custom-receipt-segment rounded-md text-xs font-semibold transition-colors sm:text-sm ${
+                                  sign === -1
+                                    ? 'bg-white text-red-800 shadow-sm ring-1 ring-stone-200/80'
+                                    : 'text-stone-500 hover:bg-stone-200/60 hover:text-stone-700'
+                                }`}
+                                aria-pressed={sign === -1}
+                                onClick={() =>
+                                  setAdminCustomReceiptLines((prev) =>
+                                    prev.map((l) => (l.id === adj.id ? { ...l, amountSign: -1 } : l))
+                                  )
+                                }
+                              >
+                                Credit (−)
+                              </button>
+                            </div>
                             <input
                               type="text"
                               inputMode="decimal"
-                              className="h-6 w-24 rounded border border-stone-300 bg-white px-2 py-0.5 text-right text-sm font-medium leading-none text-stone-700"
+                              className="admin-custom-receipt-input-amount w-[7rem] shrink-0 rounded-md border border-stone-300 bg-white text-right text-sm font-medium tabular-nums text-stone-800 placeholder:text-stone-400 focus:outline-none focus:ring-2 focus:ring-stone-400/80"
                               placeholder="0.00"
+                              aria-label="Amount"
                               value={adj.amountInput}
-                              onChange={(e) =>
-                                providerPricingUi?.onUpdateAdditionalAdjustment?.(adj.id, {
-                                  amountInput: e.target.value,
-                                })
-                              }
+                              onChange={(e) => {
+                                const v = e.target.value.replace(/[^0-9.]/g, '');
+                                const parts = v.split('.');
+                                const normalized =
+                                  parts.length <= 1 ? v : `${parts[0]}.${parts.slice(1).join('').replace(/\./g, '')}`;
+                                setAdminCustomReceiptLines((prev) =>
+                                  prev.map((l) => (l.id === adj.id ? { ...l, amountInput: normalized } : l))
+                                );
+                              }}
                             />
+                            <button
+                              type="button"
+                              className="admin-custom-receipt-remove ml-auto shrink-0 rounded-md text-stone-400 hover:bg-stone-100 hover:text-stone-700 sm:ml-0"
+                              aria-label="Remove this line"
+                              onClick={() =>
+                                setAdminCustomReceiptLines((prev) => prev.filter((l) => l.id !== adj.id))
+                              }
+                            >
+                              <span className="block text-xl leading-none" aria-hidden>
+                                ×
+                              </span>
+                            </button>
                           </div>
-                        </div>
-                      ))}
-                      <button
-                        type="button"
-                        className="rounded border border-stone-300 px-2 py-0.5 text-xs text-stone-600 hover:bg-stone-100"
-                        onClick={() => providerPricingUi?.onAddAdditionalAdjustment?.()}
-                      >
-                        + add line item
-                      </button>
+                        );
+                      })}
                     </div>
-                  ) : showProviderPricingInlineEditor ? (
-                    <button
-                      type="button"
-                      className="rounded border border-stone-300 px-2 py-0.5 text-xs text-stone-600 hover:bg-stone-100"
-                      onClick={() => providerPricingUi?.onAddAdditionalAdjustment?.()}
-                    >
-                      + add line item
-                    </button>
-                  ) : undefined
+                  </>
+                  ) : null
                 }
                 firstName={firstName}
                 lastName={lastName}

package/src/components/booking/CheckoutForm.tsx

@@ -146,6 +146,7 @@ export function CheckoutForm({
       <div className={styles.summaryWrapper}>
         {replacePriceSummary ? (
           <>
+            {extraBeforeSubtotal ? <div className="mb-4 min-w-0">{extraBeforeSubtotal}</div> : null}
             {replacePriceSummary}
             <div className="mt-4">{extraBetweenTaxAndTotal}</div>
           </>

package/src/components/booking/PriceSummary.tsx

@@ -147,6 +147,17 @@ export function PriceSummary({
 
   let subtotalShown = false;
 
+  /** When lines include a TAX row, subtotal is rendered inside the loop before that row — slot content must sit there too, not after all lines (else it ends up below tax). */
+  const firstTaxLineIndex = lines.findIndex(
+    (r) => r.kind === 'line' && String(r.type ?? '').toUpperCase() === 'TAX',
+  );
+  const embedSubtotalBeforeTaxInLines =
+    firstTaxLineIndex >= 0 && subtotal != null && subtotal > 0;
+  const extraSlotBeforeEmbeddedSubtotal =
+    embedSubtotalBeforeTaxInLines && extraBeforeSubtotal ? extraBeforeSubtotal : null;
+  const extraSlotBeforeCheckoutSubtotal =
+    !embedSubtotalBeforeTaxInLines && extraBeforeSubtotal ? extraBeforeSubtotal : null;
+
   return (
     <div className={`space-y-2 min-w-0 ${className}`}>
       {lines.map((row, index) => {
@@ -185,8 +196,11 @@ export function PriceSummary({
         const isTaxLine = type === 'TAX';
         const showSubtotalBeforeTax = isTaxLine && subtotal != null && subtotal > 0 && !subtotalShown;
         if (showSubtotalBeforeTax) subtotalShown = true;
+        const slotHere =
+          showSubtotalBeforeTax && index === firstTaxLineIndex ? extraSlotBeforeEmbeddedSubtotal : null;
         return (
           <div key={`${label}-${index}`}>
+            {slotHere}
             {showSubtotalBeforeTax && (
               <div className={`flex justify-between gap-3 min-w-0 ${textSize} ${subtotalRowClass}`}>
                 <span className="text-stone-600 min-w-0 truncate">{t('booking.subtotal') || 'Subtotal'}</span>
@@ -233,7 +247,7 @@ export function PriceSummary({
           </div>
         );
       })}
-      {extraBeforeSubtotal}
+      {extraSlotBeforeCheckoutSubtotal}
 
       {/* Checkout mode: subtotal/tax/discount not in lines (e.g. Stripe Review & pay modal) */}
       {subtotal != null && !subtotalShown && !hideSubtotal && (subtotal !== total || discountAmount > 0) && (

package/src/components/booking/booking-flow.css

@@ -279,6 +279,42 @@
   box-shadow: 0 0 0 2px rgba(5, 150, 105, 0.2);
 }
 
+/**
+ * Admin “custom receipt line” row: scoped preflight sets `input, button { padding: 0 }` with
+ * higher specificity than Tailwind padding utilities, so insets must be restored here.
+ */
+.booking-flow-preflight .admin-custom-receipt-line input.admin-custom-receipt-input[type='text'] {
+  box-sizing: border-box;
+  padding: 0.625rem 0.875rem;
+  min-height: 2.75rem;
+}
+.booking-flow-preflight .admin-custom-receipt-line input.admin-custom-receipt-input-amount[type='text'] {
+  box-sizing: border-box;
+  padding: 0.5rem 0.75rem;
+  min-height: 2.75rem;
+}
+.booking-flow-preflight .admin-custom-receipt-line .admin-custom-receipt-segment {
+  box-sizing: border-box;
+  padding: 0.5rem 0.65rem;
+  min-height: 2.75rem;
+}
+@media (min-width: 360px) {
+  .booking-flow-preflight .admin-custom-receipt-line .admin-custom-receipt-segment {
+    padding: 0.5rem 0.75rem;
+  }
+}
+.booking-flow-preflight .admin-custom-receipt-line .admin-custom-receipt-remove {
+  box-sizing: border-box;
+  padding: 0.5rem;
+  min-height: 2.75rem;
+  min-width: 2.75rem;
+}
+.booking-flow-preflight .admin-custom-receipt-line-add {
+  box-sizing: border-box;
+  padding: 0.5rem 0.85rem;
+  min-height: 2.5rem;
+}
+
 /* Labels */
 .booking-flow-preflight label {
   font-family: var(--booking-font-sans);

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

@@ -20,6 +20,7 @@ export type ProviderDashboardChangeBookingPayload = {
   pricingAdjustment?: {
     mode: 'AUTO' | 'MANUAL_LINES';
     lineOverrides?: Array<{ lineKey: string; amount: number; reason?: string }>;
+    /** Signed major-unit rows; may include admin custom receipt lines merged with provider inline adjustments. */
     additionalAdjustments?: Array<{ label: string; amount: number }>;
   } | null;
   capacitySeatCredit?: {

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

@@ -178,16 +178,16 @@ export function resolveChangeFlowNewBookingTotal(input: {
 
 /**
  * Product: **What the customer owes** for the difference is `max(0, newTotal − oldReceipt)`.
- * **Provider dashboard** may show a signed delta (credits/refunds as negative).
+ * **Provider dashboard** and **admin change booking** may show a signed delta (refund owed as negative).
  */
 export function changeFlowBalanceVsOriginal(input: {
   newTotal: number;
   originalReceiptTotal: number;
-  /** `customer` = self-serve & admin change; `provider` = provider inline editor (can owe the guest). */
-  audience: 'customer' | 'provider';
+  /** `customer` = self-serve change only; `provider` | `admin` = signed newTotal − original receipt total. */
+  audience: 'customer' | 'provider' | 'admin';
 }): number {
   const delta = input.newTotal - input.originalReceiptTotal;
-  return input.audience === 'provider' ? delta : Math.max(0, delta);
+  return input.audience === 'customer' ? Math.max(0, delta) : delta;
 }
 
 /**
@@ -255,8 +255,13 @@ export function sliceChangeQuoteForUi(
   fallbackCart: { total: number; subtotal: number; tax: number },
   currencyFallback: string
 ): ChangeQuoteUiSlice {
+  /** Staff JWT on quote: signed new − previous (refund owed negative). Otherwise same as legacy nonnegative amount-due. */
   const priceDiff =
-    quote.amountDueCents != null ? quote.amountDueCents / 100 : quote.priceDiff ?? 0;
+    quote.balanceDeltaMajorUnits != null
+      ? quote.balanceDeltaMajorUnits
+      : quote.amountDueCents != null
+        ? quote.amountDueCents / 100
+        : quote.priceDiff ?? 0;
   const serverDisplay = serverTotalsFromChangeQuoteResponse(quote, fallbackCart);
   return {
     priceDiff,

package/src/lib/booking-api.ts

@@ -855,6 +855,12 @@ export interface ChangeBookingQuoteRequest {
   newAddOnSelections?: Array<{ addOnId: string; variantId?: string; quantity?: number }>;
   /** Full new-booking total shown in the UI; server verifies within tolerance then uses this for the session so charge matches screen. */
   clientProposedTotal?: number;
+  /**
+   * Optional signed manual lines (admin/provider custom receipt rows). When present, the server should fold these
+   * amounts into pricing / stored receipt so totals align with the client (same semantics as provider dashboard
+   * `pricingAdjustment.additionalAdjustments`).
+   */
+  manualLineAdjustments?: Array<{ label: string; amount: number }>;
   /** Optional change-flow capacity hint so API can exclude current booking seats from sold counts. */
   capacitySeatCredit?: {
     enabled: boolean;
@@ -981,6 +987,11 @@ export interface ChangeBookingQuoteResponse {
   originalReceipt?: ChangeBookingQuoteReceipt;
   newReceipt?: ChangeBookingQuoteReceipt;
   priceDiff: number;
+  /**
+   * Present when the quote was requested with a **staff** JWT: signed (new total − previous receipt total) in major units.
+   * Negative = refund owed to the guest. Omitted for unauthenticated / customer-only quotes.
+   */
+  balanceDeltaMajorUnits?: number;
   currency?: string;
   canProceed?: boolean;
   reasonIfBlocked?: string;