@carrierllc/mcp 0.13.41 → 0.13.47

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carrierllc/mcp",
-  "version": "0.13.41",
+  "version": "0.13.47",
   "description": "Carrier MCP \u2014 natural-language control of MVNO/eSIM fleets via eSIMVault OCS. Stdio mode for direct integration with Claude Desktop, Cursor, Windsurf, and MCP-compatible clients. Ships the `carrier` CLI (plugin install + white-label eSIM storefront scaffold).",
   "license": "MIT",
   "author": "Carrier (Lifecycle Innovations Limited)",

package/templates/storefront/CLERK.md

@@ -0,0 +1,23 @@
+# Clerk instance switch
+
+This template does not create or configure a Clerk application. Dev is the default. Production is a config switch for a later approval.
+
+Set the switch with `NEXT_PUBLIC_CLERK_INSTANCE`.
+
+| `NEXT_PUBLIC_CLERK_INSTANCE` | Publishable key | Secret key |
+| --- | --- | --- |
+| unset, or `dev` | `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` | `CLERK_SECRET_KEY` |
+| `production` | `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY_PRODUCTION` | `CLERK_SECRET_KEY_PRODUCTION` |
+
+Dev mode ignores the production key names even when they are present. Production mode does not fall back to the dev key names. Leave the production names empty until that instance exists.
+
+`NEXT_PUBLIC_PASSWORD_RESET_ENABLED` controls the buyer reset path. Leave it unset to show Forgot password. Set it to `false` to hide that path on a storefront.
+
+The sign-in title is `Sign in to` plus `NEXT_PUBLIC_BRAND_NAME`. Buyers are not shown an organization chooser: a session whose only pending task is `choose-organization` continues to `/dashboard`.
+
+Buyers sign in and sign up on this shop. Set both of these so Clerk does not send them to its hosted pages:
+
+- `NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in`
+- `NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up`
+
+`ClerkProvider` sets the same paths. A return path stays on this origin: a same-origin absolute URL is kept as its path, and that path is carried into Create account.

package/templates/storefront/src/app/activate/[orderId]/ActivateClient.tsx

@@ -19,12 +19,15 @@
  *   Phone is NEVER required — user can skip.
  */
 import { useCallback, useEffect, useRef, useState, FormEvent } from "react";
+import brand from "@/brand.config";
+import { buyerFacingError } from "@/lib/buyer-error";
 import {
   ANDROID_INSTALL_STEPS,
   IPHONE_INSTALL_STEPS,
   directInstallUrl,
   manualActivationCode,
 } from "@/lib/esim-install";
+import { shortOrderReference, supportOrderHref } from "@/lib/order-reference";
 import type { EsimOrder } from "@/vendor/carrier/types";
 
 interface Props {
@@ -94,11 +97,9 @@ export function ActivateClient({ orderId }: Props) {
         setState({
           phase: "error",
           terminal,
-          message:
-            payload.error ??
-            (terminal
-              ? "We can't find this order on your account."
-              : "We could not load your eSIM details right now."),
+          message: terminal
+            ? "We can't find this order on your account."
+            : "We could not load your eSIM details right now.",
         });
         return null;
       }
@@ -194,13 +195,16 @@ export function ActivateClient({ orderId }: Props) {
         body: JSON.stringify({ phone }),
       });
       if (!res.ok) {
-        const err = (await res.json()) as { error?: string };
-        throw new Error(err.error ?? "Failed to save phone number");
+        try {
+          await res.json();
+        } catch {
+          // The body is not buyer copy.
+        }
+        throw new Error("phone");
       }
       setSubmitted(true);
     } catch (err) {
-      const msg = err instanceof Error ? err.message : "Failed to save. Please try again.";
-      setSaveError(msg);
+      setSaveError(buyerFacingError("phone", err));
     } finally {
       setSaving(false);
     }
@@ -231,7 +235,7 @@ export function ActivateClient({ orderId }: Props) {
         <h1 className="text-2xl font-bold text-sand-900 dark:text-sand-50">
           {ready ? "Your eSIM is ready" : "Setting up your eSIM"}
         </h1>
-        <p className="mt-2 text-sm text-sand-500">Order: {orderId}</p>
+        <p className="mt-2 text-sm text-sand-700 dark:text-sand-200">Reference {shortOrderReference(orderId)}</p>
       </div>
 
       <div className="rounded-2xl border border-sand-200 dark:border-sand-800 bg-white dark:bg-sand-900 p-8 text-center mb-8">
@@ -248,8 +252,11 @@ export function ActivateClient({ orderId }: Props) {
               {state.terminal ? "We can't show this eSIM" : "We couldn't load your eSIM"}
             </p>
             <p className="text-sand-600 dark:text-sand-400 text-sm mb-4">{state.message}</p>
-            <p className="text-sand-400 text-xs mb-4">
-              Your payment is safe and your order number is above. Quote it if you contact us.
+            <p className="text-sand-700 dark:text-sand-200 text-sm mb-4">
+              Your payment is safe.{" "}
+              <a className="inline-flex min-h-11 items-center font-medium text-[var(--brand-accent-text)]" href={supportOrderHref(brand.supportEmail, orderId)}>
+                Email {brand.supportEmail}
+              </a>
             </p>
             <div className="flex items-center justify-center gap-3">
               {/* No "Try again" on a terminal answer: the same request would
@@ -263,7 +270,7 @@ export function ActivateClient({ orderId }: Props) {
                     setState({ phase: "loading" });
                     void loadOrder();
                   }}
-                  className="rounded-full bg-[var(--brand-accent)] px-5 py-2 text-sm font-semibold text-white transition-opacity hover:opacity-90"
+                  className="rounded-full bg-[var(--brand-accent)] px-5 min-h-11 text-base font-semibold text-[var(--brand-on-accent)] transition-opacity hover:opacity-90"
                 >
                   Try again
                 </button>
@@ -272,8 +279,8 @@ export function ActivateClient({ orderId }: Props) {
                 href="/contact"
                 className={
                   state.terminal
-                    ? "rounded-full bg-[var(--brand-accent)] px-5 py-2 text-sm font-semibold text-white transition-opacity hover:opacity-90"
-                    : "rounded-full border border-sand-300 dark:border-sand-700 px-5 py-2 text-sm text-sand-900 dark:text-sand-50 hover:bg-white/10 transition-colors"
+                    ? "rounded-full bg-[var(--brand-accent)] px-5 min-h-11 text-base font-semibold text-[var(--brand-on-accent)] transition-opacity hover:opacity-90"
+                    : "rounded-full border border-sand-300 dark:border-sand-700 px-5 min-h-11 text-base text-sand-900 dark:text-sand-50 hover:bg-white/10 transition-colors"
                 }
               >
                 Contact support
@@ -300,13 +307,13 @@ export function ActivateClient({ orderId }: Props) {
                   setState({ phase: "loading" });
                   setPollCycle((n) => n + 1);
                 }}
-                className="rounded-full border border-sand-300 dark:border-sand-700 px-5 py-2 text-sm text-sand-900 dark:text-sand-50 hover:bg-white/10 transition-colors"
+                className="rounded-full border border-sand-300 dark:border-sand-700 px-5 min-h-11 text-base text-sand-900 dark:text-sand-50 hover:bg-white/10 transition-colors"
               >
                 Check again
               </button>
               <a
                 href="/contact"
-                className="rounded-full bg-[var(--brand-accent)] px-5 py-2 text-sm font-semibold text-white transition-opacity hover:opacity-90"
+                className="rounded-full bg-[var(--brand-accent)] px-5 min-h-11 text-base font-semibold text-[var(--brand-on-accent)] transition-opacity hover:opacity-90"
               >
                 Contact support
               </a>
@@ -337,7 +344,7 @@ export function ActivateClient({ orderId }: Props) {
             </p>
             <a
               href="/contact"
-              className="inline-block rounded-full bg-[var(--brand-accent)] px-5 py-2 text-sm font-semibold text-white transition-opacity hover:opacity-90"
+              className="inline-block rounded-full bg-[var(--brand-accent)] px-5 min-h-11 text-base font-semibold text-[var(--brand-on-accent)] transition-opacity hover:opacity-90"
             >
               Contact support
             </a>
@@ -390,7 +397,7 @@ export function ActivateClient({ orderId }: Props) {
       {ready && manualCode && (
         <a
           href={directInstallUrl(manualCode)}
-          className="mb-4 block w-full rounded-full bg-[var(--brand-accent)] px-6 py-3 text-center text-sm font-semibold text-white transition-opacity hover:opacity-90"
+          className="mb-4 block w-full rounded-full bg-[var(--brand-accent)] px-6 py-3 text-center text-sm font-semibold text-[var(--brand-on-accent)] transition-opacity hover:opacity-90"
         >
           Install this eSIM on this iPhone
         </a>
@@ -433,7 +440,7 @@ export function ActivateClient({ orderId }: Props) {
             <button
               type="button"
               onClick={() => void copyActivationCode(manualCode)}
-              className="mt-4 w-full rounded-lg border border-sand-300 dark:border-sand-700 px-4 py-2 text-sm text-sand-900 dark:text-sand-50 hover:bg-white/10 transition-colors"
+              className="mt-4 w-full rounded-lg border border-sand-300 dark:border-sand-700 px-4 min-h-11 text-base text-sand-900 dark:text-sand-50 hover:bg-white/10 transition-colors"
             >
               {copied ? "Copied" : "Copy activation string"}
             </button>
@@ -499,12 +506,12 @@ export function ActivateClient({ orderId }: Props) {
                 value={phone}
                 onChange={(e) => setPhone(e.target.value)}
                 placeholder="+1 555 000 0000"
-                className="flex-1 rounded-lg border border-sand-200 dark:border-sand-800 bg-sand-50 dark:bg-sand-950 px-3 py-2 text-sm text-sand-900 dark:text-sand-50 placeholder:text-sand-400 focus:border-[var(--brand-accent)] focus:outline-none"
+                className="flex-1 rounded-lg border border-sand-200 dark:border-sand-800 bg-sand-50 dark:bg-sand-950 px-3 min-h-11 text-base text-sand-900 dark:text-sand-50 placeholder:text-sand-400 focus:border-[var(--brand-accent)]"
               />
               <button
                 type="submit"
                 disabled={saving || !phone.trim()}
-                className="rounded-lg bg-[var(--brand-accent)] px-4 py-2 text-sm font-semibold text-white transition-opacity hover:opacity-90 disabled:opacity-50 whitespace-nowrap"
+                className="rounded-lg bg-[var(--brand-accent)] px-4 min-h-11 text-base font-semibold text-[var(--brand-on-accent)] transition-opacity hover:opacity-90 disabled:opacity-50 whitespace-nowrap"
               >
                 {saving ? "Saving…" : "Save"}
               </button>

package/templates/storefront/src/app/activate/[orderId]/page.tsx

@@ -9,8 +9,8 @@ export const dynamic = "force-dynamic";
  *
  * The orderId is the Stripe Checkout session_id (or templateId in dev/mock mode).
  */
-import { auth } from "@clerk/nextjs/server";
 import { redirect } from "next/navigation";
+import { buyerUserId } from "@/lib/buyer-session";
 import { userOwnsOrder } from "@/lib/checkout-order-claim";
 import { ActivateClient } from "./ActivateClient";
 
@@ -21,7 +21,7 @@ interface Props {
 }
 
 export default async function ActivatePage({ params }: Props) {
-  const { userId } = await auth();
+  const userId = await buyerUserId();
   if (!userId) redirect("/sign-in");
 
   const { orderId } = await params;

package/templates/storefront/src/app/api/checkout/claim/route.ts

@@ -1,29 +1,30 @@
-import { auth } from "@clerk/nextjs/server";
 import { NextRequest, NextResponse } from "next/server";
+import { buyerFacingError } from "@/lib/checkout-copy";
+import { buyerUserId } from "@/lib/buyer-session";
 import { claimCheckoutOrder } from "@/lib/checkout-order-claim";
 
 export async function POST(req: NextRequest): Promise<NextResponse> {
-  const { userId } = await auth();
+  const userId = await buyerUserId();
   if (!userId) {
-    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+    return NextResponse.json({ error: buyerFacingError(401) }, { status: 401 });
   }
 
   let body: { sessionId?: string; templateId?: string };
   try {
     body = (await req.json()) as { sessionId?: string; templateId?: string };
   } catch {
-    return NextResponse.json({ error: "Invalid request body" }, { status: 400 });
+    return NextResponse.json({ error: buyerFacingError(400) }, { status: 400 });
   }
 
   const sessionId = body.sessionId ?? "";
   const templateId = body.templateId ?? "";
   if (!sessionId || !templateId) {
-    return NextResponse.json({ error: "sessionId and templateId are required" }, { status: 400 });
+    return NextResponse.json({ error: buyerFacingError(400) }, { status: 400 });
   }
 
   const result = await claimCheckoutOrder(userId, sessionId, templateId);
   if (!result.ok) {
-    return NextResponse.json({ error: result.error }, { status: result.status });
+    return NextResponse.json({ error: buyerFacingError(result.status) }, { status: result.status });
   }
 
   return NextResponse.json({ ok: true, orderId: result.orderId });

package/templates/storefront/src/app/api/checkout/guest/route.ts

@@ -20,18 +20,20 @@
  * The success / return URL encodes the templateId so the /checkout/success
  * page can display the correct plan and prompt sign-up / sign-in.
  *
- * The line item is built inline from the plan's own price (`price_data`, no
- * Stripe price id), which means Stripe accepts whatever number we send. So the
- * plan has to be real before we get here: with a live Stripe key, a catalog
- * that fell back to sample plans is refused outright. Charging for
- * "Visit — Calm" at EUR 4.99 when no such product exists is a real payment
- * against nothing, and no webhook downstream can fulfil it.
+ * The line item is a Stripe Price id. The session charges that Price's
+ * current `unit_amount`, which is also what the page renders. A catalog that
+ * fell back to sample plans is refused when Stripe is configured: those plans
+ * have no Price id, and charging one would take money for a product that
+ * cannot be fulfilled. A live secret is refused as well — this template
+ * charges in Stripe test mode only.
  */
 import { auth, clerkClient } from "@clerk/nextjs/server";
 import { NextRequest, NextResponse } from "next/server";
 import { orderPurchaserEmail, userOwnsOrder } from "@/lib/checkout-order-claim";
 import { fetchOrder, fetchTopUpOptions, fetchTemplateCatalog } from "@/vendor/carrier/client";
 import { decideGuestCheckout, normalizeChannel } from "@/vendor/carrier/catalog-guard";
+import { checkoutPriceFields, isLiveStripeKey, isStripePriceId, overlayStripePrices } from "@/vendor/carrier/stripe-price";
+import type { SkuTemplate } from "@/vendor/carrier/types";
 
 interface GuestCheckoutBody {
   templateId?: string;
@@ -45,6 +47,26 @@ interface GuestCheckoutBody {
   topUpForOrderId?: string;
 }
 
+/**
+ * The catalog only carries `stripe_price_id` for a caller whose bearer equals
+ * the worker's CARRIER_STOREFRONT_API_KEY. With a different or unset key the
+ * catalog still answers 200 and every plan arrives without a Price id, so the
+ * guard refuses each sale. The refusal stays: there is no inline-amount
+ * fallback. This line makes the cause visible in the server log, with no
+ * secret in it.
+ */
+function logPlanNotSellable(plan: SkuTemplate | undefined): void {
+  if (plan && !isStripePriceId(plan.stripe_price_id)) {
+    console.error(
+      `[checkout] plan ${plan.id} has no Stripe Price id, so it cannot be sold. ` +
+        "The catalog omits it unless CARRIER_API_KEY on this storefront equals " +
+        "CARRIER_STOREFRONT_API_KEY on the Carrier worker; check both match.",
+    );
+  } else {
+    console.error("[checkout] plan is not sellable: the catalog row is incomplete");
+  }
+}
+
 export async function POST(req: NextRequest): Promise<NextResponse> {
   // Resolve server identity for every request, independent of client input.
   // First purchases may remain anonymous; only top-ups require this identity.
@@ -113,7 +135,11 @@ export async function POST(req: NextRequest): Promise<NextResponse> {
       if (!base || !/^[a-z0-9](?:[a-z0-9-]{0,38}[a-z0-9])?$/.test(slug)) {
         return NextResponse.json({ error: "Storefront unavailable" }, { status: 503 });
       }
-      const response = await fetch(`${base}/api/hosted/${encodeURIComponent(slug)}`, { cache: "no-store" });
+      const catalogKey = process.env.CARRIER_API_KEY;
+      const response = await fetch(`${base}/api/hosted/${encodeURIComponent(slug)}`, {
+        cache: "no-store",
+        headers: catalogKey ? { Authorization: `Bearer ${catalogKey}` } : {},
+      });
       if (!response.ok) return NextResponse.json({ error: "Storefront unavailable" }, { status: 503 });
       const shop = await response.json();
       if (!shop || typeof shop !== "object" || Array.isArray(shop) ||
@@ -124,6 +150,16 @@ export async function POST(req: NextRequest): Promise<NextResponse> {
         return NextResponse.json({ error: "Storefront unavailable" }, { status: 503 });
       }
       storefrontId = shop.id;
+      // A shop with its own connected Stripe account sells under that
+      // account. This template creates sessions on the platform account only,
+      // so a connected shop is refused until account-scoped checkout exists.
+      if (typeof shop.stripe_account_id === "string" && shop.stripe_account_id) {
+        console.error("[checkout] storefront has a connected Stripe account; platform-scoped checkout refused");
+        return NextResponse.json(
+          { error: "That plan cannot be purchased right now. Please try again in a few minutes.", code: "plan_not_sellable" },
+          { status: 503 },
+        );
+      }
       catalog = { source: "live" as const, templates: shop.plans };
     } else {
       catalog = await fetchTemplateCatalog();
@@ -143,6 +179,9 @@ export async function POST(req: NextRequest): Promise<NextResponse> {
             "NEXT_PUBLIC_CARRIER_API_URL is unset or the catalog request failed",
         );
       }
+      if (decision.code === "plan_not_sellable") {
+        logPlanNotSellable(catalog.templates.find((p: SkuTemplate) => p.id === templateId));
+      }
       return NextResponse.json({ error: decision.error, code: decision.code }, { status: decision.status });
     }
 
@@ -155,12 +194,19 @@ export async function POST(req: NextRequest): Promise<NextResponse> {
       }
     }
 
+    if (isLiveStripeKey(stripeKey)) {
+      console.error("[checkout] refusing a live Stripe key; test mode only");
+      return NextResponse.json(
+        { error: "Checkout is unavailable right now. Please try again in a moment.", code: "stripe_live_refused" },
+        { status: 503 },
+      );
+    }
+
     if (!stripeKey) {
-      // No Stripe configured — return a mock URL so the storefront still builds
-      // and renders without credentials. No money moves on this path.
-      const appUrl = process.env.NEXT_PUBLIC_APP_URL ?? "";
-      const successUrl = `${appUrl}/checkout/success?templateId=${encodeURIComponent(templateId)}&session_id=mock`;
-      return NextResponse.json({ url: successUrl });
+      return NextResponse.json(
+        { error: "Checkout is unavailable right now.", code: "stripe_unconfigured" },
+        { status: 503 },
+      );
     }
 
     const appUrl = process.env.NEXT_PUBLIC_APP_URL ?? "";
@@ -180,14 +226,23 @@ export async function POST(req: NextRequest): Promise<NextResponse> {
         return NextResponse.json({ error: "This order cannot be topped up" }, { status: 409 });
       }
     }
+    const [priced] = await overlayStripePrices([plan]);
+    const priceFields = checkoutPriceFields(priced ?? plan);
+    if (!priceFields) {
+      logPlanNotSellable(priced ?? plan);
+      return NextResponse.json(
+        {
+          error: "That plan cannot be purchased right now. Please try again in a few minutes.",
+          code: "plan_not_sellable",
+        },
+        { status: 503 },
+      );
+    }
+
     const formBody = new URLSearchParams({
       mode: "payment",
       ...(buyerEmail ? { customer_email: buyerEmail } : {}),
-      "line_items[0][price_data][currency]": plan.currency.toLowerCase(),
-      "line_items[0][price_data][unit_amount]": String(plan.price_cents),
-      "line_items[0][price_data][product_data][name]": plan.name,
-      "line_items[0][price_data][product_data][description]": plan.description,
-      "line_items[0][quantity]": "1",
+      ...priceFields,
       // Embedded sessions take `return_url` and reject `success_url` /
       // `cancel_url`: there is no hosted page to come back from, and cancelling
       // is just closing the form.

package/templates/storefront/src/app/api/orders/[orderId]/route.ts

@@ -9,8 +9,8 @@
  * an order must say so; the one thing it must never do is draw a reassuring
  * placeholder while the eSIM behind it does not exist.
  */
-import { auth } from "@clerk/nextjs/server";
 import { NextResponse } from "next/server";
+import { buyerUserId } from "@/lib/buyer-session";
 import { userOwnsOrder } from "@/lib/checkout-order-claim";
 import { fetchOrder } from "@/vendor/carrier/client";
 
@@ -21,7 +21,7 @@ interface Context {
 }
 
 export async function GET(_req: Request, ctx: Context): Promise<NextResponse> {
-  const { userId } = await auth();
+  const userId = await buyerUserId();
   if (!userId) {
     return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
   }

package/templates/storefront/src/app/checkout/[templateId]/CheckoutClient.tsx

@@ -14,9 +14,10 @@
  * publishable key the browser goes to Stripe's hosted page and comes back.
  * Both take money; the embedded one loses fewer people on the way.
  *
- * After payment the user lands on /checkout/success, where they create an
- * account (email + password, no phone) or sign in, and are then sent to
- * /activate/[orderId].
+ * After payment the user lands on /checkout/success. That page confirms the
+ * payment on its own. Saving the eSIM to an account is an inline step on the
+ * same page, and it does not start another charge. A mock session id is an
+ * error, not a confirmation.
  *
  * Every string on this page is read by a customer. It names no environment
  * variable and gives no configuration instructions — an operator's deployment
@@ -30,6 +31,12 @@ import {
   EmbeddedStripeCheckout,
   canEmbedStripeCheckout,
 } from "@/components/checkout/EmbeddedStripeCheckout";
+import {
+  BuyerCopyError,
+  checkoutErrorCopy,
+  GENERIC_CHECKOUT_ERROR,
+  readCheckoutJson,
+} from "@/lib/checkout-client-error";
 import { conversionEvents } from "@/lib/conversion-events";
 import { normalizeChannel } from "@/vendor/carrier/catalog-guard";
 import type { SkuTemplate } from "@/vendor/carrier/types";
@@ -40,8 +47,6 @@ interface Props {
   session: { url: string } | null;
 }
 
-const GENERIC_CHECKOUT_ERROR = "Checkout is unavailable right now. Please try again in a moment.";
-
 /**
  * Where this visit came from, read off the landing URL.
  *
@@ -94,19 +99,21 @@ export function CheckoutClient({ plan, session }: Props) {
           }),
         })
           .then(async (res) => {
+            let body: { error?: string; code?: string; url?: string; clientSecret?: string; sessionId?: string } | null;
+            try {
+              body = (await readCheckoutJson(res)) as typeof body;
+            } catch {
+              body = null;
+            }
+            if (!body || typeof body !== "object") {
+              throw new BuyerCopyError(GENERIC_CHECKOUT_ERROR);
+            }
             if (!res.ok) {
-              // The route returns customer-safe copy for every refusal it knows
-              // about. Anything else (a proxy error page, say) gets the generic
-              // line rather than whatever text happened to come back.
-              const err = (await res.json().catch(() => ({}))) as { error?: string; code?: string };
-              if (embed && err.code === "embed_unavailable") throw new EmbedUnavailable();
-              throw new Error(err.code && err.error ? err.error : GENERIC_CHECKOUT_ERROR);
+              if (embed && body.code === "embed_unavailable") throw new EmbedUnavailable();
+              if (body.code && body.error) throw new BuyerCopyError(body.error);
+              throw new BuyerCopyError(GENERIC_CHECKOUT_ERROR);
             }
-            return res.json() as Promise<{
-              url?: string;
-              clientSecret?: string;
-              sessionId?: string;
-            }>;
+            return body;
           })
           .then((data) => {
             if (embed && data.clientSecret && data.sessionId) {
@@ -116,10 +123,13 @@ export function CheckoutClient({ plan, session }: Props) {
               return;
             }
             if (data.url) {
+              if (data.url.includes("session_id=mock")) {
+                throw new BuyerCopyError(GENERIC_CHECKOUT_ERROR);
+              }
               window.location.href = data.url;
               return;
             }
-            throw new Error(GENERIC_CHECKOUT_ERROR);
+            throw new BuyerCopyError(GENERIC_CHECKOUT_ERROR);
           })
           .catch((err: unknown) => {
             if (err instanceof EmbedUnavailable && !embedAbandonedRef.current) {
@@ -130,7 +140,7 @@ export function CheckoutClient({ plan, session }: Props) {
               return;
             }
             guestCheckoutPlanIdRef.current = null;
-            setCheckoutError(err instanceof Error ? err.message : GENERIC_CHECKOUT_ERROR);
+            setCheckoutError(checkoutErrorCopy(err));
             setLoading(false);
           });
       };
@@ -140,7 +150,7 @@ export function CheckoutClient({ plan, session }: Props) {
   );
 
   useEffect(() => {
-    if (!isLoaded) return;
+    if (!isLoaded || plan.price_unavailable === true) return;
 
     conversionEvents.beginCheckout(plan.name, plan.price_cents / 100);
 
@@ -189,14 +199,30 @@ export function CheckoutClient({ plan, session }: Props) {
     startGuestCheckout(false);
   }, [startGuestCheckout]);
 
+  if (plan.price_unavailable === true) {
+    return (
+      <div className="mx-auto max-w-lg px-4 py-32 text-center">
+        <p className="text-sand-700 dark:text-sand-200">
+          We can&apos;t show a price for this plan right now, so it can&apos;t be bought yet.
+        </p>
+        <a
+          href="/shop"
+          className="mt-6 inline-flex min-h-11 items-center rounded-full border border-sand-300 px-6 text-base text-sand-900 dark:border-sand-700 dark:text-sand-50"
+        >
+          ← Back to shop
+        </a>
+      </div>
+    );
+  }
+
   if (checkoutError) {
     return (
       <div className="mx-auto max-w-lg px-4 py-32 text-center">
-        <p className="text-sand-700 dark:text-sand-200">{checkoutError}</p>
-        <p className="mt-2 text-sm text-sand-400">{plan.name}</p>
+        <p role="alert" className="text-sand-700 dark:text-sand-200">{checkoutError}</p>
+        <p className="mt-2 text-base dark:text-sand-200 text-sand-600">{plan.name}</p>
         <a
           href="/shop"
-          className="mt-6 inline-block rounded-full border border-sand-300 px-6 py-2 text-sm text-sand-900 transition-colors hover:bg-white/10 dark:border-sand-700 dark:text-sand-50"
+          className="mt-6 inline-flex min-h-11 items-center rounded-full border border-sand-300 px-6 text-base text-sand-900 dark:border-sand-700 dark:text-sand-50"
         >
           ← Back to shop
         </a>
@@ -210,7 +236,7 @@ export function CheckoutClient({ plan, session }: Props) {
         <h1 className="text-2xl font-semibold tracking-tight text-sand-900 dark:text-sand-50">
           Almost there.
         </h1>
-        <p className="mt-2 mb-8 text-sm text-sand-500">
+        <p className="mt-2 mb-8 text-base text-sand-700 dark:text-sand-200">
           {plan.name} — your QR code is ready the moment this clears.
         </p>
         <EmbeddedStripeCheckout
@@ -225,10 +251,10 @@ export function CheckoutClient({ plan, session }: Props) {
   return (
     <div className="mx-auto max-w-lg px-4 py-32 text-center">
       <div className="mx-auto mb-4 h-8 w-8 animate-spin rounded-full border-2 border-[var(--brand-accent)] border-t-transparent" />
-      <p className="text-sand-600 dark:text-sand-400">
+      <p className="text-sand-700 dark:text-sand-200">
         {loading ? "Preparing your checkout…" : "Redirecting to payment…"}
       </p>
-      <p className="mt-2 text-sm text-sand-400">{plan.name}</p>
+      <p className="mt-2 text-base dark:text-sand-200 text-sand-600">{plan.name}</p>
     </div>
   );
 }