@tribe-nest/forge 3.2.0 → 3.4.0

package/src/ui/headless/checkout/_tests/bundleCoupon.spec.ts

@@ -0,0 +1,169 @@
+import { describe, it, expect } from "vitest";
+import { bundleCouponSummary, bundleCouponRequestBody, bundleReturnUrl } from "../bundleCoupon";
+import type { ApplyCheckoutCouponResult } from "../../../../data/queries/useCheckouts";
+
+/**
+ * A bundle's discount code, as `useCheckout` handles it.
+ *
+ * These are the two decisions that used to be impossible to make at all: before
+ * `/public/checkouts/apply-coupon` existed, a bundle's code was consumed by the
+ * call that CREATED the checkout, so for a signed-in buyer with a digital-only
+ * cart — who enters the payment stage on mount — the field froze before it could
+ * be typed into.
+ *
+ * They live outside the hook so they can be asserted without a provider tree,
+ * the same reason `couponFailureMessage` does.
+ */
+
+/** The endpoint's answer, defaulted to "APPLYME20 took $2 off a $60 bundle". */
+const answer = (overrides: Partial<ApplyCheckoutCouponResult> = {}): ApplyCheckoutCouponResult => ({
+  checkoutId: "checkout-1",
+  currency: "USD",
+  subtotalCents: 6000,
+  discountCents: 200,
+  couponId: "coupon-1",
+  totalCents: 5800,
+  appliedCoupons: [{ code: "APPLYME20", discountKind: "simple", discountAmount: 2 }],
+  paymentSecret: "pi_2_secret",
+  paymentId: "pi_2",
+  chargedAmount: 58,
+  chargedCurrency: "USD",
+  isFreeCheckout: false,
+  ...overrides,
+});
+
+describe("bundleCouponSummary — applying", () => {
+  it("converts the minor-unit discount and names the coupon", () => {
+    const next = bundleCouponSummary(answer());
+
+    expect(next.discountAmount).toBe(2);
+    expect(next.appliedCoupon).toEqual({ code: "APPLYME20", discountAmount: 2 });
+    expect(next.settledCheckoutId).toBeNull();
+  });
+
+  it("labels an AUTOMATIC discount the buyer never typed", () => {
+    // The whole point of the response carrying `appliedCoupons`: without it a
+    // no-code discount could only be drawn as an unexplained amount, because
+    // there is no public `couponId` → code lookup.
+    const next = bundleCouponSummary(
+      answer({ appliedCoupons: [{ code: "SUMMER10", discountKind: "simple", discountAmount: 6 }], discountCents: 600 }),
+    );
+
+    expect(next.appliedCoupon).toEqual({ code: "SUMMER10", discountAmount: 6 });
+  });
+
+  it("moves the payment element onto the re-minted intent", () => {
+    // Applying re-prices AND re-mints. Leaving the old secret in place would
+    // have the buyer confirm a payment quoting the PRE-coupon amount.
+    const next = bundleCouponSummary(answer());
+
+    expect(next.paymentUpdate).toEqual({
+      paymentSecret: "pi_2_secret",
+      paymentId: "pi_2",
+      chargedAmount: 58,
+      chargedCurrency: "USD",
+    });
+    expect(next.chargedTotal).toEqual({ amount: 58, currency: "USD" });
+  });
+
+  it("claims no payment when the bundle had no intent to replace", () => {
+    // A bundle that has not reached start-payment yet: the client's own
+    // start-payment will pick the new figure up, so nothing may supersede it.
+    const next = bundleCouponSummary(answer({ paymentSecret: "", paymentId: "", chargedAmount: 0, chargedCurrency: "" }));
+
+    expect(next.paymentUpdate).toBeNull();
+    expect(next.chargedTotal).toBeNull();
+    // The discount is still real and still shown.
+    expect(next.discountAmount).toBe(2);
+    expect(next.appliedCoupon).toEqual({ code: "APPLYME20", discountAmount: 2 });
+  });
+
+  it("does not claim a coupon it cannot name", () => {
+    // A reduction with no coupon behind it is reported as an amount and nothing
+    // more — inventing a label is how a buyer ends up chasing a code that
+    // does not exist.
+    const next = bundleCouponSummary(answer({ appliedCoupons: [] }));
+
+    expect(next.discountAmount).toBe(2);
+    expect(next.appliedCoupon).toBeNull();
+  });
+});
+
+describe("bundleCouponSummary — removing", () => {
+  it("restores the undiscounted figure and drops the applied coupon", () => {
+    const next = bundleCouponSummary(
+      answer({
+        discountCents: 0,
+        couponId: null,
+        totalCents: 6000,
+        appliedCoupons: [],
+        paymentSecret: "pi_3_secret",
+        paymentId: "pi_3",
+        chargedAmount: 60,
+      }),
+    );
+
+    expect(next.discountAmount).toBe(0);
+    expect(next.appliedCoupon).toBeNull();
+    // The full price is what the buyer is now charged, on a fresh intent.
+    expect(next.chargedTotal).toEqual({ amount: 60, currency: "USD" });
+    expect(next.paymentUpdate?.paymentId).toBe("pi_3");
+    expect(next.settledCheckoutId).toBeNull();
+  });
+});
+
+describe("bundleCouponSummary — a bundle taken to zero", () => {
+  it("reports the settled checkout so the buyer is sent to finalise", () => {
+    // There is no intent to confirm: the server settled and fulfilled it. Left
+    // unhandled, the buyer waits in front of a payment form that will never be
+    // asked to do anything.
+    const next = bundleCouponSummary(
+      answer({
+        discountCents: 6000,
+        totalCents: 0,
+        appliedCoupons: [{ code: "ALLOFIT", discountKind: "simple", discountAmount: 60 }],
+        paymentSecret: "",
+        paymentId: "",
+        chargedAmount: 0,
+        chargedCurrency: "",
+        isFreeCheckout: true,
+      }),
+    );
+
+    expect(next.settledCheckoutId).toBe("checkout-1");
+    expect(next.paymentUpdate).toBeNull();
+    expect(next.chargedTotal).toBeNull();
+    expect(next.discountAmount).toBe(60);
+    expect(next.appliedCoupon).toEqual({ code: "ALLOFIT", discountAmount: 60 });
+  });
+});
+
+describe("bundleCouponRequestBody", () => {
+  const base = { profileId: "p1", checkoutId: "c1", returnUrl: "https://x.test/finalise?checkoutId=c1" };
+
+  it("sends the trimmed code when applying", () => {
+    expect(bundleCouponRequestBody({ ...base, couponCode: "  applyme20 " })).toEqual({
+      ...base,
+      couponCode: "applyme20",
+    });
+  });
+
+  it("omits the field entirely when removing", () => {
+    // The endpoint validates `couponCode` as `min(1)`, so an empty string is a
+    // 400 — "take my code off" would fail and the discount would stay on.
+    expect(bundleCouponRequestBody(base)).toEqual(base);
+    expect(bundleCouponRequestBody({ ...base, couponCode: "" })).toEqual(base);
+    expect(bundleCouponRequestBody({ ...base, couponCode: "   " })).toEqual(base);
+    expect("couponCode" in bundleCouponRequestBody(base)).toBe(false);
+  });
+});
+
+describe("bundleReturnUrl", () => {
+  it("returns the buyer to the bundle's own finalise page", () => {
+    // `?checkoutId=` and not `?orderId=`: the finalise page resolves a bundle
+    // through the checkout, and a bundle's children are several orders.
+    expect(bundleReturnUrl("https://artist.test", "/checkout/finalise", "c1")).toBe(
+      "https://artist.test/checkout/finalise?checkoutId=c1",
+    );
+  });
+});

package/src/ui/headless/checkout/bundleCoupon.ts

@@ -0,0 +1,96 @@
+import type { ApplyCheckoutCouponResult, AppliedBundleCoupon } from "../../../data/queries/useCheckouts";
+
+/**
+ * The two decisions a bundle's discount code turns on, kept out of the hook so
+ * they can be asserted without a provider tree.
+ *
+ * Both exist because a bundle is the odd one out: it is the only checkout that
+ * answers in MINOR units, the only one whose "remove" is expressed by the
+ * ABSENCE of a field rather than an empty one, and the only one that can settle
+ * itself — a code that takes it to zero leaves nothing to pay for.
+ */
+
+/** What the summary and the payment element read after an apply or a remove. */
+export type BundleCouponSummary = {
+  /** MAJOR units, converted from the endpoint's minor-unit answer. */
+  discountAmount: number;
+  /**
+   * The discount as the buyer sees it, or null when nothing came off.
+   *
+   * Named from the server's `appliedCoupons`, so an AUTOMATIC discount the buyer
+   * never typed is labelled with its real code instead of appearing as an
+   * unexplained reduction.
+   */
+  appliedCoupon: { code: string; discountAmount: number } | null;
+  /**
+   * The re-minted intent. Applying re-prices AND re-mints, so the payment
+   * element must move onto this secret — the previous one still quotes the
+   * pre-coupon amount. Null when there was no intent to replace (the bundle had
+   * not started payment) or when the bundle settled for free.
+   */
+  paymentUpdate: {
+    paymentSecret: string;
+    paymentId: string;
+    chargedAmount: number;
+    chargedCurrency: string;
+  } | null;
+  /** The charged total for the summary, or null when there is nothing to charge. */
+  chargedTotal: { amount: number; currency: string } | null;
+  /**
+   * Set when the re-price took the bundle to zero. The server has already
+   * settled and fulfilled it, so the buyer belongs on the finalise page rather
+   * than in front of a payment form that will never be asked to do anything.
+   */
+  settledCheckoutId: string | null;
+};
+
+export function bundleCouponSummary(data: ApplyCheckoutCouponResult): BundleCouponSummary {
+  const discountAmount = (data.discountCents ?? 0) / 100;
+  const named: AppliedBundleCoupon | undefined = data.appliedCoupons?.[0];
+
+  return {
+    discountAmount,
+    // A discount with no coupon behind it cannot be labelled honestly, so it is
+    // not claimed as one — `discountAmount` still reports the reduction.
+    appliedCoupon: discountAmount > 0 && named ? { code: named.code, discountAmount } : null,
+    paymentUpdate:
+      data.paymentSecret && data.paymentId
+        ? {
+            paymentSecret: data.paymentSecret,
+            paymentId: data.paymentId,
+            chargedAmount: data.chargedAmount,
+            chargedCurrency: data.chargedCurrency,
+          }
+        : null,
+    chargedTotal: data.chargedAmount > 0 ? { amount: data.chargedAmount, currency: data.chargedCurrency } : null,
+    settledCheckoutId: data.isFreeCheckout ? data.checkoutId : null,
+  };
+}
+
+/**
+ * The body for `POST /public/checkouts/apply-coupon`.
+ *
+ * Removing sends NO `couponCode` at all. An empty string is a validation error
+ * on that endpoint (`min(1)`), so sending one would turn "take my code off" into
+ * a 400 and leave the discount in place.
+ */
+export function bundleCouponRequestBody(input: {
+  /** Optional only because `useForge()` types it so before the provider resolves. */
+  profileId?: string;
+  checkoutId: string;
+  returnUrl: string;
+  couponCode?: string;
+}): Record<string, unknown> {
+  const code = input.couponCode?.trim();
+  return {
+    profileId: input.profileId,
+    checkoutId: input.checkoutId,
+    returnUrl: input.returnUrl,
+    ...(code ? { couponCode: code } : {}),
+  };
+}
+
+/** The return URL a bundle's re-minted intent comes back to. */
+export function bundleReturnUrl(origin: string, finalisePath: string, checkoutId: string): string {
+  return `${origin}${finalisePath}?checkoutId=${checkoutId}`;
+}

package/src/ui/headless/checkout/useCheckout.ts

@@ -11,7 +11,13 @@ import {
   type ShippingCountry,
 } from "../../../data/queries/useShipping";
 import { usePaymentFlow } from "../../../data/queries/usePaymentFlow";
-import { useCreateCheckout, cartToCheckoutLines } from "../../../data/queries/useCheckouts";
+import {
+  useCreateCheckout,
+  useApplyCheckoutCoupon,
+  cartToCheckoutLines,
+  type ApplyCheckoutCouponResult,
+} from "../../../data/queries/useCheckouts";
+import { bundleCouponSummary, bundleReturnUrl } from "./bundleCoupon";
 import { readAttributionRef } from "../../../utils/attribution";
 import { readLanding } from "../../../utils/landing";
 import { ProductDeliveryType, PaymentProviderName, type ApiError, type PublicTaxQuote } from "../../../types/models";
@@ -52,6 +58,12 @@ interface AppliedCoupon {
   code: string;
   discountType: string | null;
   discountValue: number | null;
+  /**
+   * MAJOR units. Set for the BUNDLE path only, where the endpoint reports what
+   * came off (`discountCents`) but not the coupon's type or rate — so "10% off"
+   * cannot be rendered and the cash figure is the honest thing to show.
+   */
+  discountAmount?: number;
 }
 
 interface CouponPaymentUpdate {
@@ -96,6 +108,7 @@ export function useCheckout(opts: UseCheckoutOptions = {}) {
   const createOrder = useCreateOrder();
   const createCheckout = useCreateCheckout();
   const applyCouponMutation = useApplyCoupon();
+  const applyCheckoutCouponMutation = useApplyCheckoutCoupon();
 
   const hasPhysicalProduct = useMemo(
     () => cartItems.some((item) => item.deliveryType === ProductDeliveryType.Physical),
@@ -153,6 +166,12 @@ export function useCheckout(opts: UseCheckoutOptions = {}) {
   const [created, setCreated] = useState<CreateOrderResult | null>(null);
   /** Set instead of `created` when the cart is a bundle. */
   const [checkoutId, setCheckoutId] = useState<string | null>(null);
+  /**
+   * A bundle a discount took to zero. Applying such a code settles it on the
+   * server (there is no intent to mint), so there is nothing left to pay and the
+   * caller has to move the buyer straight to the finalise page.
+   */
+  const [settledCheckoutId, setSettledCheckoutId] = useState<string | null>(null);
   const [startError, setStartError] = useState("");
   const startedRef = useRef(false);
 
@@ -184,6 +203,7 @@ export function useCheckout(opts: UseCheckoutOptions = {}) {
     // both settle on one payment. Every single-surface cart keeps the flow it
     // has always had, below.
     if (isBundle) {
+      const enteredCode = couponCode.trim() || undefined;
       createCheckout
         .mutateAsync({
           firstName: guestUserData?.firstName || user?.firstName || "",
@@ -194,10 +214,41 @@ export function useCheckout(opts: UseCheckoutOptions = {}) {
           selectedShippingRates: selectedShippingRates.length ? selectedShippingRates : undefined,
           attributionRefId: readAttributionRef() ?? undefined,
           ...(readLanding() ?? {}),
+          // A code typed BEFORE this call still travels with it — that is the
+          // cheapest path and the only one available to a guest, whose bundle
+          // does not exist yet. A code typed AFTERWARDS goes through
+          // `/public/checkouts/apply-coupon`, which is what stops the field
+          // freezing for a signed-in buyer whose digital-only cart enters the
+          // payment stage on mount.
+          couponCode: enteredCode,
           lines: cartToCheckoutLines(cartItems, ticketItems),
         })
-        .then((r) => setCheckoutId(r.checkoutId))
-        .catch((e) => setStartError(messageOf(e) || "An error occurred"));
+        .then((r) => {
+          setCheckoutId(r.checkoutId);
+          // Minor → major. The bundle is the only endpoint answering in minor units.
+          const off = (r.discountCents ?? 0) / 100;
+          setDiscountAmount(off);
+          // `appliedCoupons` names what came off, so an AUTOMATIC discount the
+          // buyer never typed is labelled rather than being an unexplained
+          // amount. The typed code is the fallback for an older API.
+          const named = r.appliedCoupons?.[0];
+          setAppliedCoupon(
+            off > 0
+              ? {
+                  code: named?.code ?? enteredCode ?? "Discount applied",
+                  discountType: null,
+                  discountValue: null,
+                  discountAmount: off,
+                }
+              : null,
+          );
+        })
+        .catch((e) => {
+          // A refused code fails the whole bundle, so with one entered the
+          // reason belongs at the field the buyer used — verbatim from the API.
+          if (enteredCode) setCouponError(messageOf(e) || "This code could not be applied.");
+          else setStartError(messageOf(e) || "An error occurred");
+        });
       return;
     }
 
@@ -243,7 +294,10 @@ export function useCheckout(opts: UseCheckoutOptions = {}) {
   // and start-payment have resolved.
   const effectivePayment = useMemo<CouponPaymentUpdate | null>(() => {
     if (couponPaymentUpdate) return couponPaymentUpdate;
-    if (created && flow.result?.paymentSecret && flow.result?.paymentId) {
+    // `checkoutId` as well as `created`: a BUNDLE has no `created` order, and
+    // gating on that alone left a bundle buyer with no payment element at all
+    // unless a coupon happened to re-mint one.
+    if ((created || checkoutId) && flow.result?.paymentSecret && flow.result?.paymentId) {
       return {
         paymentSecret: flow.result.paymentSecret,
         paymentId: flow.result.paymentId,
@@ -252,7 +306,7 @@ export function useCheckout(opts: UseCheckoutOptions = {}) {
       };
     }
     return null;
-  }, [created, flow.result, couponPaymentUpdate]);
+  }, [created, checkoutId, flow.result, couponPaymentUpdate]);
 
   // Surface the charged total (for the summary) as soon as a payment resolves.
   useEffect(() => {
@@ -317,8 +371,66 @@ export function useCheckout(opts: UseCheckoutOptions = {}) {
     setCurrentStage("payment");
   }, [shippingGroups, selections]);
 
-  // ── Coupon (applied against the created order) ──────────────────────────────
+  // ── Coupon (applied against the created order / bundle) ─────────────────────
+  /**
+   * Whether the code field can still be changed.
+   *
+   * Both shapes are now re-priceable in place: a single-surface order through
+   * `/public/orders/apply-coupon`, a bundle through
+   * `/public/checkouts/apply-coupon`. A bundle's field used to freeze the moment
+   * the checkout was created — which for a signed-in buyer with a digital-only
+   * cart was on mount, so the code could never be typed at all.
+   */
+  const isCouponEditable = isBundle ? !settledCheckoutId : !!orderId;
+
+  /** Fold an apply/remove answer for a bundle back into the summary + payment. */
+  const absorbBundleCoupon = useCallback((data: ApplyCheckoutCouponResult) => {
+    const next = bundleCouponSummary(data);
+    setDiscountAmount(next.discountAmount);
+    setAppliedCoupon(
+      next.appliedCoupon
+        ? {
+            code: next.appliedCoupon.code,
+            discountType: null,
+            discountValue: null,
+            discountAmount: next.appliedCoupon.discountAmount,
+          }
+        : null,
+    );
+    setCouponPaymentUpdate(next.paymentUpdate);
+    if (next.chargedTotal) setChargedTotal(next.chargedTotal);
+    if (next.settledCheckoutId) setSettledCheckoutId(next.settledCheckoutId);
+  }, []);
+
   const applyCoupon = useCallback(async () => {
+    if (isBundle) {
+      if (!couponCode.trim()) return;
+      setCouponError("");
+      // Not created yet (a guest, or a cart with a shipping stage still ahead):
+      // the code travels with `createCheckout`, which is the one call that can
+      // price it without leaving an abandoned bundle behind.
+      if (!checkoutId) {
+        setAppliedCoupon({ code: couponCode.trim(), discountType: null, discountValue: null });
+        return;
+      }
+      setIsApplyingCoupon(true);
+      try {
+        const data = await applyCheckoutCouponMutation.mutateAsync({
+          checkoutId,
+          returnUrl: bundleReturnUrl(window.location.origin, finalisePath, checkoutId),
+          couponCode: couponCode.trim(),
+        });
+        absorbBundleCoupon(data);
+      } catch (e) {
+        // The API answers a refused code with the real reason, already
+        // translated. Collapsing it into "invalid code" throws away the only
+        // thing that tells the buyer what to do next.
+        setCouponError(messageOf(e) || "Invalid coupon code");
+      } finally {
+        setIsApplyingCoupon(false);
+      }
+      return;
+    }
     if (!couponCode.trim() || !orderId) return;
     setCouponError("");
     setIsApplyingCoupon(true);
@@ -344,9 +456,37 @@ export function useCheckout(opts: UseCheckoutOptions = {}) {
     } finally {
       setIsApplyingCoupon(false);
     }
-  }, [couponCode, orderId, finalisePath, applyCouponMutation]);
+  }, [couponCode, orderId, checkoutId, finalisePath, applyCouponMutation, applyCheckoutCouponMutation, absorbBundleCoupon, isBundle]);
 
   const removeCoupon = useCallback(async () => {
+    if (isBundle) {
+      setCouponError("");
+      // Nothing created yet — the staged code simply never travels.
+      if (!checkoutId) {
+        setAppliedCoupon(null);
+        setCouponCode("");
+        setShowCouponInput(false);
+        setDiscountAmount(0);
+        return;
+      }
+      setIsApplyingCoupon(true);
+      try {
+        // No code sent: the bundle is re-priced with none, which restores the
+        // original total rather than freezing the last discounted one.
+        const data = await applyCheckoutCouponMutation.mutateAsync({
+          checkoutId,
+          returnUrl: bundleReturnUrl(window.location.origin, finalisePath, checkoutId),
+        });
+        absorbBundleCoupon(data);
+        setCouponCode("");
+        setShowCouponInput(false);
+      } catch (e) {
+        setCouponError(messageOf(e) || "Failed to remove coupon");
+      } finally {
+        setIsApplyingCoupon(false);
+      }
+      return;
+    }
     if (!orderId) return;
     setCouponError("");
     setIsApplyingCoupon(true);
@@ -372,7 +512,7 @@ export function useCheckout(opts: UseCheckoutOptions = {}) {
     } finally {
       setIsApplyingCoupon(false);
     }
-  }, [orderId, finalisePath, applyCouponMutation]);
+  }, [orderId, checkoutId, finalisePath, applyCouponMutation, applyCheckoutCouponMutation, absorbBundleCoupon, isBundle]);
 
   // ── Free checkout (nothing to charge) ───────────────────────────────────────
   /** Create the (free) order and return its id so the caller can navigate to the
@@ -439,6 +579,12 @@ export function useCheckout(opts: UseCheckoutOptions = {}) {
     orderId,
     /** Set instead of `orderId` when the cart spans surfaces. */
     checkoutId,
+    /**
+     * Set when a discount took the bundle to zero: it is already paid and
+     * fulfilled server-side, so the caller must send the buyer to the finalise
+     * page instead of waiting for a payment that will never be asked for.
+     */
+    settledCheckoutId,
     isBundle,
     ticketItems,
     isCreatingOrder: createOrder.isPending || flow.isStarting,
@@ -463,6 +609,8 @@ export function useCheckout(opts: UseCheckoutOptions = {}) {
     isApplyingCoupon,
     applyCoupon,
     removeCoupon,
+    /** False once the code can no longer be changed (a created bundle). */
+    isCouponEditable,
     // ── Errors ─────────────────────────────────────────────────────────────────
     pageError,
     setPageError,

package/src/ui/headless/coaching/useCoachingBooking.ts

@@ -8,6 +8,7 @@ import {
   useUnreserveCoachingBooking,
 } from "../../../data/queries/useCoachingAvailability";
 import { usePaymentFlow } from "../../../data/queries/usePaymentFlow";
+import { useCouponField, type CouponQuoteFn } from "../coupon/useCouponField";
 import { readAttributionRef } from "../../../utils/attribution";
 import { readLanding } from "../../../utils/landing";
 
@@ -93,6 +94,37 @@ export function useCoachingBooking(slug?: string, opts: UseCoachingBookingOption
   const finalisePath =
     opts.finalisePath ?? ((s, bId) => `/i/coaching/${s}/finalise?orderId=${bId}`);
 
+  /**
+   * Discount code — genuinely quoted, because `booking/update` re-derives the
+   * gross price from the PRODUCT on every call. Applying re-prices the held
+   * booking and removing (no code) puts the original total back rather than
+   * netting a second time off an already-netted figure.
+   *
+   * `confirmIfFree` is deliberately false here: pricing a code must never be
+   * able to complete the booking. Only "Continue" confirms.
+   */
+  const quoteCoupon: CouponQuoteFn = useCallback(
+    async (code) => {
+      if (!bookingId) throw new Error("Reserve a time slot before entering a code.");
+      if (!firstName.trim() || !lastName.trim() || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
+        throw new Error("Enter your name and a valid email before applying a code.");
+      }
+      return update.mutateAsync({
+        bookingId,
+        email,
+        firstName,
+        lastName,
+        confirmIfFree: false,
+        questionnaire,
+        couponCode: code ?? undefined,
+      });
+    },
+    // `update` is a stable react-query mutation object.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [bookingId, firstName, lastName, email, questionnaire],
+  );
+  const coupon = useCouponField(quoteCoupon);
+
   // Highlight a slot (no server hold yet — the slot is reserved on "Continue").
   const selectSlot = (slotId: string) => {
     setError(null);
@@ -139,8 +171,12 @@ export function useCoachingBooking(slug?: string, opts: UseCoachingBookingOption
     setBookingId(null);
     setSelectedSlotId(null);
     setReservationExpiresAt(null);
+    // The quote belonged to a booking that no longer exists — keeping it would
+    // show a discount against a price nothing has agreed to.
+    coupon.reset();
     setStep("slot");
-  }, [bookingId, unreserve]);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [bookingId, unreserve, coupon.reset]);
 
   /** Release the hold and surface a notice — call when the reservation timer runs out. */
   const expireReservation = useCallback(async () => {
@@ -163,9 +199,12 @@ export function useCoachingBooking(slug?: string, opts: UseCoachingBookingOption
         lastName,
         confirmIfFree: true,
         questionnaire,
+        // Re-sent so the booking is confirmed at the price the buyer was shown.
+        couponCode: coupon.submittedCode,
         attributionRefId: readAttributionRef() ?? undefined,
         ...(readLanding() ?? {}),
       });
+      coupon.record(updated);
       const origin = typeof window !== "undefined" ? window.location.origin : "";
       const ru = `${origin}${finalisePath(slug, bookingId)}`;
       setReturnUrl(ru);
@@ -180,7 +219,10 @@ export function useCoachingBooking(slug?: string, opts: UseCoachingBookingOption
       if (result.provider && result.provider !== "stripe") return;
       setStep("payment");
     } catch (e) {
-      setError(errMessage(e));
+      // With a code entered, the API's rejection reason belongs at the field the
+      // buyer used, not in the generic error slot.
+      if (coupon.submittedCode) coupon.fail(e);
+      else setError(errMessage(e));
     }
   };
 
@@ -213,7 +255,15 @@ export function useCoachingBooking(slug?: string, opts: UseCoachingBookingOption
     setQuestionnaire,
     continueToPayment,
     clientSecret: flow.clientSecret,
-    totalAmount: flow.result?.totalAmount,
+    // The booking quote WINS over start-payment: every `continueToPayment`
+    // re-quotes before starting the payment, and applying or removing a code
+    // re-quotes again — so the quote is never staler, and preferring the
+    // payment result would leave a removed discount on screen.
+    totalAmount: coupon.quote?.totalAmount ?? flow.result?.totalAmount,
+    /** GROSS session price, before any discount. Undefined until quoted. */
+    subTotal: coupon.quote?.subTotal,
+    /** Discount code state + the server's quote. See `useCouponField`. */
+    coupon,
     /** Authoritative sales-tax quote from start-payment (display only). */
     taxQuote: flow.result?.taxQuote ?? null,
     returnUrl,