@code-collective/booking-widget 1.0.7 → 1.0.8

package/src/lib/Checkout.svelte

@@ -3,16 +3,19 @@
   import type { WizardPages } from './config';
   import { DEFAULT_WIZARD_PAGES } from './config';
   import type { CheckoutCartDetailDto } from './client-types';
-  import { postMessage } from './messages';
+  import { onWidgetMessage, postMessage } from './messages';
+  import type { CartManager } from './cart-manager';
   import CheckoutModal from './CheckoutModal.svelte';
 
   interface Props {
     api: BookingApi;
+    cartManager?: CartManager;
     wizardPages?: WizardPages;
     editPages?: WizardPages;
     autoSelectSingleTimeSlot?: boolean;
   }
-  let { api, wizardPages = DEFAULT_WIZARD_PAGES, editPages: editPagesProp, autoSelectSingleTimeSlot = false }: Props = $props();
+  let { api, cartManager, wizardPages = DEFAULT_WIZARD_PAGES, editPages: editPagesProp,
+    autoSelectSingleTimeSlot = false }: Props = $props();
   let editPages = $derived(editPagesProp ?? wizardPages);
 
   let cart = $state<CheckoutCartDetailDto | null>(null);
@@ -34,17 +37,9 @@
   // would otherwise only ever see the cart as it was on first mount. The event already carries the fresh
   // cart (see TicketConfigurator/CheckoutModal's own posting sites), so this applies it directly rather than
   // triggering a second, redundant getCart() call or flashing the spinner over an already-visible cart.
-  function handleMessage(e: MessageEvent) {
-    let d: Record<string, unknown>;
-    try { d = typeof e.data === 'string' ? JSON.parse(e.data) : e.data; }
-    catch { return; }
-    if (d?.type === 'cart:updated' && 'cart' in d) cart = d.cart as CheckoutCartDetailDto | null;
-  }
-
-  $effect(() => {
-    window.addEventListener('message', handleMessage);
-    return () => window.removeEventListener('message', handleMessage);
-  });
+  $effect(() => onWidgetMessage((d) => {
+    if (d.type === 'cart:updated' && 'cart' in d) cart = d.cart as CheckoutCartDetailDto | null;
+  }));
 </script>
 
 <div class="bw-widget">
@@ -69,6 +64,10 @@
           value: total,
           currency,
         });
+        // The cart is paid and confirmed, so its token has done its job. Nothing used to clear it, so it sat
+        // in localStorage on the merchant's origin until absoluteExpiresAt - readable by every third-party
+        // script they load, and picked up by the next person to use a shared or kiosk browser.
+        cartManager?.reset();
       }}
     />
   {:else}

package/src/lib/CheckoutModal.svelte

@@ -35,7 +35,11 @@
   let editingItem = $state<CheckoutCartItemDetailDto | null>(null);
   let paymentResult = $state<CheckoutCartPaymentInitiationDto | null>(null);
   let confirmResult = $state<CheckoutCartConfirmResultDto | null>(null);
-  let confirmFailed = $state(false);
+  // What the confirm attempt actually produced, once it's settled - not a plain success/failure boolean,
+  // because "payment succeeded but this gateway couldn't confirm it in time" and "payment itself never went
+  // through" need different copy and different actions (see the ResultView status computed below and
+  // runConfirmLoop's own remarks). null while still in flight.
+  let confirmOutcome = $state<'success' | 'pending' | 'partial' | 'notCharged' | null>(null);
   let isLoading = $state(true);
   let isConfirming = $state(false);
   let privacyAccepted = $state(false);
@@ -171,6 +175,16 @@
     hasAttemptedSubmit = true;
     if (!contactForm?.isValid() || !privacyAccepted) return;
 
+    // A cart only ever gets one Peach checkout - RecordPaymentInitiatedAsync's own concurrency lock rejects
+    // a second payCart call on the same cart with a 409 ("already has a payment initiated"), even though
+    // nothing has actually been charged yet. Cancelling out of PaymentPage (onPaymentComplete's 'cancelled'
+    // case below) never clears paymentResult, so re-entering here just resumes that same still-open attempt
+    // instead of re-initiating.
+    if (paymentResult) {
+      currentView = 'payment';
+      return;
+    }
+
     const contact = contactForm.getContact();
 
     isPaying = true;
@@ -199,41 +213,115 @@
       return;
     }
 
-    if (result.status === 'expired') {
-      confirmFailed = true;
+    // Neither of these ever reached a real charge - Peach's own SDK is reporting that the checkout itself
+    // didn't go through (session timeout, a declined card, a 3DS failure, a client-side error), not that a
+    // successful charge's confirmation is in question. That distinction matters: every path below this point
+    // is only reachable once onCompleted has already fired, meaning the card WAS charged, so "try again"
+    // there would risk a second charge rather than retrying a payment that never happened. Here, nothing was
+    // charged, so re-opening the card form is exactly correct.
+    if (result.status === 'expired' || result.status === 'error') {
+      confirmOutcome = 'notCharged';
       isConfirming = false;
       currentView = 'result';
       return;
     }
 
-    isConfirming = true;
     currentView = 'result';
+    await runConfirmLoop();
+  }
+
+  // One confirm attempt, interpreted: records the result and reports whether it settled (success or a
+  // supplier-side partial failure - either way, nothing left to retry) versus still needs another attempt
+  // (the two webhook races below). Shared by the automatic loop and the manual on-demand recheck so there is
+  // exactly one place that decides what a given confirmCart() outcome means.
+  async function attemptConfirm(): Promise<'settled' | 'awaitingWebhook'> {
+    try {
+      confirmResult = await api.confirmCart();
+      const allOk = confirmResult.items.every((i) => i.statusCode >= 200 && i.statusCode < 300);
+      confirmOutcome = allOk ? 'success' : 'partial';
+      // Notifies the host (order value/currency for analytics, clearing the stored cart token) without
+      // closing the modal - the shopper still needs to see the success screen below, and only dismisses it
+      // themselves via ResultView's Done button, which is the one thing that posts modal:close.
+      if (allOk) {
+        onOrderConfirmed();
+      }
+      return 'settled';
+    } catch (e) {
+      // Two different races with the same webhook, neither a real failure:
+      //   402 - the charge succeeded (that's why PaymentPage's onCompleted fired) but the webhook hasn't
+      //         reached PeachWebhookEndpoints yet to move the cart to Paid.
+      //   409 - the webhook got there first and is confirming the cart right now, so there is no outcome to
+      //         read yet. Only one caller is allowed to run confirmation, and the loser is told to retry
+      //         rather than being handed a second, independently-produced answer.
+      // Both resolve on their own within a second or two, so both are worth retrying. Any other error settles
+      // as 'pending' rather than a failure state - the charge already succeeded by the time this can run at
+      // all, so there is no "payment failed" to report, only "not confirmed yet".
+      if (e instanceof ApiError && (e.status === 402 || e.status === 409)) {
+        return 'awaitingWebhook';
+      }
+      confirmOutcome = 'pending';
+      return 'settled';
+    }
+  }
+
+  async function runConfirmLoop() {
+    isConfirming = true;
+    confirmOutcome = null;
 
     for (let attempt = 1; attempt <= ConfirmMaxAttempts; attempt++) {
-      try {
-        confirmResult = await api.confirmCart();
-        const allOk = confirmResult.items.every((i) => i.statusCode >= 200 && i.statusCode < 300);
-        confirmFailed = !allOk;
+      if (await attemptConfirm() === 'settled') {
+        isConfirming = false;
+        return;
+      }
+
+      if (attempt === ConfirmMaxAttempts) {
+        confirmOutcome = 'pending';
         isConfirming = false;
-        if (allOk) {
-          postMessage({ type: 'modal:close' });
-          onOrderConfirmed();
-        }
         return;
-      } catch (e) {
-        // 402 means the card charge already succeeded (that's why PaymentPage's onCompleted fired at all) but
-        // Peach's own webhook hasn't reached PeachWebhookEndpoints yet to move the cart to Paid server-side -
-        // a race with the webhook, not a real failure, so it's worth a few retries rather than failing outright.
-        const isAwaitingWebhook = e instanceof ApiError && e.status === 402;
-        if (!isAwaitingWebhook || attempt === ConfirmMaxAttempts) {
-          confirmFailed = true;
-          isConfirming = false;
-          return;
-        }
-        await new Promise((resolve) => setTimeout(resolve, ConfirmRetryDelayMs));
       }
+
+      await new Promise((resolve) => setTimeout(resolve, ConfirmRetryDelayMs));
     }
   }
+
+  // A single on-demand recheck for the 'pending' screen's "Check Again" button - deliberately not another
+  // full runConfirmLoop, which would re-impose its own ~15s auto-retry wait on someone who is already
+  // actively engaged and can just click again. Confirming is idempotent (CheckoutCartConfirmer), so this
+  // costs nothing to repeat; still 'pending' either way if the webhook still hasn't landed.
+  async function checkConfirmationAgain() {
+    isConfirming = true;
+    if (await attemptConfirm() === 'awaitingWebhook') {
+      confirmOutcome = 'pending';
+    }
+    isConfirming = false;
+  }
+
+  // The one ResultView prop that isn't a straight readout of confirmOutcome: 'partial' means the payment
+  // succeeded but this gateway could not confirm every item, which is a real problem worth surfacing
+  // distinctly from 'pending' (which resolves on its own) - but from ResultView's own outcome union, that is
+  // still a kind of 'failed', just one retryPayment must gate off since the charge already happened.
+  let resultStatus = $derived(
+    isConfirming
+      ? null
+      : confirmOutcome === 'success'
+        ? { outcome: 'successful' as const }
+        : confirmOutcome === 'pending'
+          ? { outcome: 'pending' as const }
+          : confirmOutcome === 'partial'
+            ? {
+                outcome: 'failed' as const,
+                resultDescription:
+                  "Your payment succeeded, but we couldn't confirm every item in your booking. Please contact us with your order details.",
+                retryPayment: false,
+              }
+            : confirmOutcome === 'notCharged'
+              ? {
+                  outcome: 'failed' as const,
+                  resultDescription: 'Your payment could not be completed. Please try again.',
+                  retryPayment: true,
+                }
+              : null,
+  );
 </script>
 
 <div class="modal">
@@ -245,20 +333,23 @@
   {:else if currentView === 'payment' && paymentResult}
     <PaymentPage
       checkoutId={paymentResult.checkoutId}
-      totalFormatted={formattedTotal()}
-      onBack={() => { currentView = 'contact'; }}
-      onClose={close}
+      entityId={paymentResult.entityId}
       {onPaymentComplete}
     />
 
   {:else if currentView === 'result'}
     <ResultView
-      status={isConfirming ? null : confirmFailed
-        ? { outcome: 'failed', resultDescription: 'Something went wrong confirming your order. Please try again.' }
-        : { outcome: 'successful' }}
+      status={resultStatus}
       verifying={isConfirming}
-      onDone={() => { postMessage({ type: 'modal:close' }); onOrderConfirmed(); }}
+      onDone={() => {
+        // onOrderConfirmed only for the outcome that actually earns it - a 'pending'/'partial' Close is
+        // just dismissing the dialog on an order this gateway cannot yet (or fully) vouch for, not
+        // reporting it complete. The 'success' case already fired onOrderConfirmed the moment it was
+        // known, inside runConfirmLoop/checkConfirmationAgain - this simply closes what's still open.
+        postMessage({ type: 'modal:close' });
+      }}
       onRetry={() => { currentView = 'payment'; }}
+      onCheckAgain={confirmOutcome === 'pending' ? checkConfirmationAgain : undefined}
     />
 
   {:else if currentView === 'edit' && editingItem && productsById.get(editingItem.productId)}
@@ -272,6 +363,7 @@
       onBack={() => { currentView = 'cart'; }}
       onClose={close}
       onUpdated={onItemUpdated}
+      onPriceChanged={loadProducts}
     />
 
   {:else if currentView === 'contact'}

package/src/lib/EditBookingView.svelte

@@ -1,7 +1,7 @@
 <script lang="ts">
   import type { CartItem, CheckoutCartItemDetailDto, CheckoutProductDto } from './client-types';
   import type { BookingApi } from './api';
-  import { ApiError } from './api';
+  import { ApiError, isPriceMismatch } from './api';
   import type { WizardPages } from './config';
   import { DEFAULT_WIZARD_PAGES } from './config';
   import { expandUnitItems } from './utils';
@@ -17,8 +17,11 @@
     onBack: () => void;
     onClose: () => void;
     onUpdated: () => void;
+    /// Re-fetches the products this view is handed, so a price that moved under the customer can be shown to
+    /// them. Owned by the parent because `product` is a prop here - this view cannot refresh it itself.
+    onPriceChanged?: () => Promise<void>;
   }
-  let { cartItem, product, api, wizardPages, editPages, autoSelectSingleTimeSlot = false, onBack, onClose, onUpdated }: Props = $props();
+  let { cartItem, product, api, wizardPages, editPages, autoSelectSingleTimeSlot = false, onBack, onClose, onUpdated, onPriceChanged }: Props = $props();
 
   let isSaving = $state(false);
   let errorMessage = $state<string | null>(null);
@@ -34,12 +37,20 @@
         availabilityId: item.availabilityId,
         localDate: item.localDate,
         pickupPointId: item.pickupPointId,
+        // Currency and precision are resolved server-side - see the same call in TicketConfigurator.
         amount: item.totalPrice,
-        currencyCode: item.currency,
-        currencyPrecision: item.currencyPrecision,
       });
       onUpdated();
     } catch (e) {
+      // The supplier moved the price mid-edit, so the amount being submitted is no longer one the server will
+      // accept. Retrying resubmits the same stale figure and fails identically, so the prices this view is
+      // showing have to be refreshed before the customer can do anything useful.
+      if (isPriceMismatch(e)) {
+        errorMessage = "This item's price has changed. Please check the updated price and save again.";
+        await onPriceChanged?.();
+        return;
+      }
+
       // 424 means the cart item itself was rolled back server-side (see CheckoutCartEndpoints.UpdateItemAsync) -
       // the supplier rejected the change, so nothing was saved. Surface that instead of letting it vanish
       // silently: WizardPage stays mounted (not swapped for a spinner) specifically so the user's in-progress

package/src/lib/PaymentPage.svelte

@@ -4,12 +4,10 @@
 
   interface Props {
     checkoutId: string;
-    totalFormatted: string;
-    onBack: () => void;
-    onClose: () => void;
+    entityId: string;
     onPaymentComplete: (result: { status: string }) => void;
   }
-  let { checkoutId, totalFormatted, onBack, onClose, onPaymentComplete }: Props = $props();
+  let { checkoutId, entityId, onPaymentComplete }: Props = $props();
 
   let failed = $state(false);
   let errorMessage = $state('');
@@ -30,9 +28,16 @@
 
         peachInstance = Checkout.initiate({
           checkoutId,
+          // Peach's own "key" field, not our checkoutKey/entityId naming - without it Checkout.initiate()
+          // throws (Cannot read properties of undefined (reading 'trim')) before ever rendering anything,
+          // since the embedded widget authenticates to Peach directly with this rather than through us.
+          key: entityId,
           customisations: {
             card: { submitButtonText: 'Pay Now' },
             theme: { brand: { primary: '#E30613' } },
+            // Peach's own Cancel (method-selection screen) and Back (card-entry screen) are the only
+            // back/exit controls in this dialog - we don't render one of our own alongside them, so there's
+            // exactly one way out per screen instead of ours and Peach's competing for the same job.
           },
           eventHandlers: {
             onCompleted: () => { cleanup(); onPaymentComplete({ status: 'completed' }); },
@@ -60,77 +65,70 @@
   onDestroy(cleanup);
 </script>
 
-<div class="payment-page">
-  <div class="page-header">
-    <button class="icon-btn" onclick={onBack} aria-label="Back">&larr;</button>
-    <h2>Payment</h2>
-    <span class="spacer"></span>
-    <button class="icon-btn" onclick={onClose} aria-label="Close">&times;</button>
-  </div>
-
-  <div class="body">
-    <div class="amount-bar">
-      <span>Amount to pay</span>
-      <span class="amount">{totalFormatted}</span>
+<!-- Peach's own card form renders inside a cross-origin iframe with its own Cancel/Back controls we have no
+     way to hide or reach (no SDK option, no CSS/JS access across origins) - see Checkout.initiate()'s
+     customisations doc comment above. Presenting it as its own nested dialog over the checkout modal, rather
+     than as just another view swapped into that modal's own body, means Peach's own Cancel/Back read as
+     belonging to Peach's own layer instead of visually competing with a second, separate Back of ours - so
+     this dialog has no back/exit control of its own at all; onCancelled below routes back to contact. -->
+<div class="payment-overlay">
+  <!-- svelte-ignore a11y_click_events_have_key_events a11y_no_static_element_interactions -->
+  <div class="payment-dialog" onclick={(e) => e.stopPropagation()}>
+    <div class="page-header">
+      <h2>Payment</h2>
     </div>
 
-    {#if failed}
-      <div class="error-state">
-        <div class="error-icon">!</div>
-        <p class="error-title">Unable to load payment form</p>
-        <p class="error-msg">{errorMessage || 'The checkout session may have expired.'}</p>
-      </div>
-    {:else}
-      <div class="brands">
-        <span class="brand">VISA</span>
-        <span class="brand">MC</span>
-        <span class="brand">AMEX</span>
-      </div>
-      <div id="peach-container"></div>
-    {/if}
+    <div class="body">
+      {#if failed}
+        <div class="error-state">
+          <div class="error-icon">!</div>
+          <p class="error-title">Unable to load payment form</p>
+          <p class="error-msg">{errorMessage || 'The checkout session may have expired.'}</p>
+        </div>
+      {:else}
+        <div id="peach-container"></div>
+      {/if}
+    </div>
   </div>
 </div>
 
 <style>
-  .payment-page {
+  .payment-overlay {
+    position: fixed;
+    inset: 0;
+    /* Above bw-checkout's own .bw-modal-overlay (z-index 10000) so this reads as a second dialog opening
+       on top of the checkout modal, not content living inside it. */
+    z-index: 10001;
+    background: rgba(0, 0, 0, 0.5);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    padding: 16px;
+  }
+  .payment-dialog {
     display: flex;
     flex-direction: column;
-    height: 100%;
+    width: 100%;
+    max-width: 480px;
+    height: min(700px, 90vh);
+    background: var(--bw-color-bg);
+    border-radius: var(--bw-radius-lg);
+    box-shadow: var(--bw-shadow-3);
+    overflow: hidden;
   }
   .body {
     flex: 1;
+    /* A definite height (not just flex:1 alone) so #peach-container's own height:100% below has something
+       real to resolve against, and so this scrolls as a single region if content overflows - Peach's own
+       root is `height: inherit`, so without that it collapses to its 360px fallback regardless of how tall
+       the card form actually gets (e.g. once billing address fields are showing), and its submit button
+       ends up overlapping the fields above it. */
+    min-height: 0;
     overflow-y: auto;
     padding: 16px;
   }
-  .amount-bar {
-    display: flex;
-    justify-content: space-between;
-    align-items: center;
-    padding: 16px;
-    background: var(--bw-color-surface);
-    border-radius: var(--bw-radius-lg);
-    margin-bottom: 20px;
-    font-weight: 600;
-    font-size: 15px;
-  }
-  .amount {
-    color: var(--bw-color-primary);
-    font-size: 18px;
-    font-weight: 700;
-  }
-  .brands {
-    display: flex;
-    gap: 8px;
-    margin-bottom: 16px;
-  }
-  .brand {
-    padding: 4px 10px;
-    border: 1px solid var(--bw-color-border);
-    border-radius: var(--bw-radius-sm);
-    font-size: 11px;
-    font-weight: 700;
-    color: var(--bw-color-text-secondary);
-    letter-spacing: 0.02em;
+  #peach-container {
+    height: 100%;
   }
   .error-state {
     text-align: center;

package/src/lib/ResultView.svelte

@@ -6,19 +6,43 @@
     verifying: boolean;
     onDone: () => void;
     onRetry: () => void;
+    // Re-checks confirmation on demand without touching payment - only meaningful (and only rendered) for
+    // a 'pending' outcome. Optional so callers that predate this state need not pass it.
+    onCheckAgain?: () => void;
   }
-  let { status, verifying, onDone, onRetry }: Props = $props();
+  let { status, verifying, onDone, onRetry, onCheckAgain }: Props = $props();
 
   let success = $derived(status?.outcome === 'successful');
+  let pending = $derived(status?.outcome === 'pending');
+  // A 'failed' outcome covers two genuinely different situations - see CheckoutModal's own remarks on
+  // confirmOutcome. Only one of them is safe to offer "Try Again" for: the payment itself never went
+  // through (declined, expired, SDK error), so re-opening the card form charges the shopper once, not
+  // twice. The other - payment succeeded but this gateway could not confirm every item - already has the
+  // shopper's money against a real charge; offering to pay again there would risk a second charge for
+  // nothing this screen can fix, so status.retryPayment gates the button rather than the outcome alone.
+  let retryable = $derived(status?.outcome === 'failed' && status.retryPayment !== false);
 </script>
 
 <div class="result">
   {#if verifying}
     <div class="spinner"></div>
     <p class="hint">Verifying payment...</p>
+  {:else if pending}
+    <div class="icon pending">&hellip;</div>
+    <h2>Payment Received</h2>
+    <p class="desc">
+      {status?.resultDescription ??
+        "We're still confirming your booking - this can take a minute. Please don't try to pay again; we'll email your confirmation as soon as it's ready."}
+    </p>
+    <div class="actions">
+      {#if onCheckAgain}
+        <button class="btn btn-primary" onclick={onCheckAgain}>Check Again</button>
+      {/if}
+      <button class="btn btn-outline" onclick={onDone}>Close</button>
+    </div>
   {:else}
     <div class="icon" class:success class:failure={!success}>
-      {success ? '\u2713' : '!'}
+      {success ? '✓' : '!'}
     </div>
     <h2>{success ? 'Payment Successful' : 'Payment Failed'}</h2>
     <p class="desc">
@@ -28,8 +52,10 @@
     </p>
     {#if success}
       <button class="btn btn-primary" onclick={onDone}>Done</button>
-    {:else}
+    {:else if retryable}
       <button class="btn btn-outline" onclick={onRetry}>Try Again</button>
+    {:else}
+      <button class="btn btn-outline" onclick={onDone}>Close</button>
     {/if}
   {/if}
 </div>
@@ -69,6 +95,13 @@
     color: var(--bw-color-error);
     background: var(--bw-color-primary-light);
   }
+  /* Deliberately its own amber, not success green or failure red - payment succeeded (so red reads as an
+     alarming false alarm) but nothing is confirmed yet (so green would be premature). */
+  .icon.pending {
+    border: 2px solid #B8860B;
+    color: #B8860B;
+    background: rgba(184, 134, 11, 0.08);
+  }
   h2 {
     font-size: 20px;
     font-weight: 700;
@@ -81,4 +114,11 @@
     max-width: 280px;
     line-height: 1.5;
   }
+  .actions {
+    display: flex;
+    flex-direction: column;
+    gap: 8px;
+    width: 100%;
+    max-width: 220px;
+  }
 </style>

package/src/lib/TicketConfigurator.svelte

@@ -1,6 +1,6 @@
 <script lang="ts">
   import type { BookingApi } from './api';
-  import { ApiError } from './api';
+  import { ApiError, isPriceMismatch } from './api';
   import type { WizardPages } from './config';
   import { DEFAULT_WIZARD_PAGES } from './config';
   import type { CartItem, CheckoutProductDto } from './client-types';
@@ -43,9 +43,11 @@
       availabilityId: item.availabilityId,
       localDate: item.localDate,
       pickupPointId: item.pickupPointId,
+      // Currency and precision are the supplier's to state, not ours - the API resolves both server-side and
+      // ignores anything sent here. Amount stays, but only as a claim about the price the customer was shown:
+      // the server accepts it solely when it matches what the supplier is asking or a price the server itself
+      // published, and returns PRICE_MISMATCH otherwise.
       amount: item.totalPrice,
-      currencyCode: item.currency,
-      currencyPrecision: item.currencyPrecision,
     });
 
     const total = formatCurrency(item.totalPrice, item.currency, item.currencyPrecision, 2);
@@ -72,6 +74,15 @@
     try {
       await addItemToCart(item);
     } catch (e) {
+      // The supplier moved the price while the customer was configuring, and the amount they agreed to is no
+      // longer one the server accepts. Retrying is useless - the wizard still holds the old prices, so it
+      // would resubmit exactly the same amount and fail identically. The only way out is to re-fetch and let
+      // the customer see the new price, which is what the message asks them to do.
+      if (isPriceMismatch(e)) {
+        await reloadAfterPriceChange();
+        return;
+      }
+
       // CartManager only knows a cart is expired from timestamps it saw at creation - it can't see the
       // server's idle window sliding forward, so a cart that looks valid locally can still be rejected
       // server-side. A 401/404 here means exactly that: drop the stale cart and retry once with a fresh one
@@ -91,6 +102,17 @@
       isAddingToCart = false;
     }
   }
+
+  async function reloadAfterPriceChange() {
+    addToCartError = "This ticket's price has changed since you started. Please check the updated price and try again.";
+    try {
+      await load();
+    } catch {
+      // The reload is what makes the message actionable; if even that fails the customer needs to start over
+      // rather than be left looking at prices we already know are wrong.
+      addToCartError = "This ticket's price has changed and we could not load the new one. Please reload the page.";
+    }
+  }
 </script>
 
 <div class="bw-widget">

package/src/lib/api.ts

@@ -18,9 +18,27 @@ import { dateKey } from './utils';
 // Lets a caller distinguish "the server said no, and specifically why" (e.g. 402 - not paid yet, retryable
 // while Peach's webhook is still in flight) from any other failure, without parsing the message string.
 export class ApiError extends Error {
-  constructor(public readonly status: number) {
+  constructor(
+    public readonly status: number,
+    public readonly body?: unknown,
+  ) {
     super(`API error ${status}`);
   }
+
+  // The server's own machine-readable reason, where it sends one. Several distinct failures share a status -
+  // a price that moved and a malformed request are both 400 - and only this tells them apart.
+  get code(): string | undefined {
+    return typeof this.body === 'object' && this.body !== null && 'error' in this.body
+      ? String((this.body as { error: unknown }).error)
+      : undefined;
+  }
+}
+
+// The price of an item changed between the widget displaying it and the item being added, and the amount the
+// customer agreed to is no longer one the server will accept. Recoverable, but only by showing the customer
+// the new price - see PRICE_MISMATCH handling in TicketConfigurator/EditBookingView.
+export function isPriceMismatch(e: unknown): e is ApiError {
+  return e instanceof ApiError && e.status === 400 && e.code === 'PRICE_MISMATCH';
 }
 
 export interface BookingApi {
@@ -78,7 +96,7 @@ export class ApiClient implements BookingApi {
 
   private unwrap<T>(result: { data?: T; error?: unknown; response: Response }): T {
     if (result.data === undefined) {
-      throw new ApiError(result.response.status);
+      throw new ApiError(result.response.status, result.error);
     }
     return result.data;
   }