@homie-rocks/studio 0.33.1 → 0.35.0

package/worker/shop.mjs

@@ -5,11 +5,11 @@
  *   GET  /api/shop               the items, each with how THIS player may get it (shop-rules.mjs wayFor); on a kids
  *                                server or studio, the studio policy applies; until set up, { open: false, missing: [...] }
  *   POST /api/shop/age           the neutral age question, once per account: a year of birth, kept only as a band
- *   POST /api/shop/buy           a permitted buyer buys one item: an order row, then Stripe's own hosted Checkout page
+ *   POST /api/shop/buy           a buyer checks out a cart: an order and its lines, then Stripe's own hosted Checkout page
  *   POST /api/shop/parent        studio parent policy: a one-time link a parent opens on their own device (/shop/parent/<token>)
  *   POST /api/shop/hook          Stripe's webhook, signature checked; verified Stripe events record paid, refunded, disputed
- *   POST /api/shop/used          the game says an item was used (equipped, played): it leaves the self-serve refund
- *   POST /api/shop/refund        the player's own refund of an unused item within the studio's refund days
+ *   POST /api/shop/used          the game says an item was used (equipped, played): the optional used-item policy applies
+ *   POST /api/shop/refund        the player's own refund of an item line within the studio's refund days
  *   GET  /api/player/owns        what the signed-in player owns (the keys the game reads; a beginner or kids server
  *                                follows the studio advantage settings)
  *   GET  /api/shop/mine          the player's orders and what they own (the account page)
@@ -21,8 +21,9 @@
  * owner's AI (an office key) can only ASK for one, which the owner confirms with one tap. A dispute never touches the
  * player's account: it changes nothing until it is decided, and a lost one is a refund of that one item.
  *
- * SECRETS (Worker secrets, put there by `homie-studio shop connect` from a page on the owner's own computer):
- * STRIPE_KEY (a restricted key: Checkout Sessions write, Charges write for refunds, PaymentIntents and Disputes read;
+ * SECRETS (Worker secrets, put there by `homie-studio shop connect` on the owner's own computer):
+ * Default: STRIPE_SHOP_LINKS and STRIPE_WEBHOOK_SECRET; no API key or API requests at purchase time.
+ * Optional fuller checkout: STRIPE_KEY (a secret key or a restricted key: Checkout Sessions write, Charges write for refunds, PaymentIntents and Disputes read;
  * from 0.24.3 also Webhook Endpoints write, which only the connect page on the owner's computer uses) and
  * STRIPE_WEBHOOK_SECRET. Never in a file, a chat, a log or a page.
  *
@@ -31,14 +32,15 @@
  * by product. The price is always shop.json's (the rules checked it), never one read from Stripe. A Product missing
  * in this mode falls back to the item described inline, so a sale never fails over the catalog.
  */
+import { hasStripeKey, linkConfig, linkSettings, shopMode, fullerReason, paymentLinkURL, rememberMoneyEvent, rememberedMoney } from './shop-links.mjs';
 import { players } from './players.mjs';
 import { serversOf } from './servers.mjs';
-import { ENTITLEMENT_KEY, checkoutMessage, amountError, amountStep, parseAmount, currencyScale, audienceOf, bandOf, checkShop, defaultTaxCode, money, wayFor } from './shop-rules.mjs';
+import { ENTITLEMENT_KEY, referralShare, checkoutMessage, amountError, amountStep, parseAmount, currencyScale, audienceOf, bandOf, checkShop, defaultTaxCode, money, wayFor } from './shop-rules.mjs';
 import {
-  bandOfPlayer, forgetPlayerShop, grantStatements, migrationNeeded, migrated, newOrderId, orderById, orderByPayment, orderBySession, orderView, playerOrderStatus, ownsOf, restoreStatement, revokeStatement,
+  orderLines, lineView, bandOfPlayer, forgetPlayerShop, grantStatements, migrationNeeded, migrated, newOrderId, orderById, orderByPayment, orderBySession, orderView, playerOrderStatus, ownsOf, restoreStatement, revokeStatement,
   setBand, shopDataOf, spentThisMonth,
 } from './shop-store.mjs';
-import { KEY_SHAPE, stripeCall, StripeError, WEBHOOK_SECRET_SHAPE, createCheckoutSession, createRefund, expireCheckoutSession, dashboardLink, isApprovalRequired, isMissingProduct, modeOf, productIdOf, verifyWebhook } from './stripe.mjs';
+import { redactStripe, WEBHOOK_SECRET_SHAPE, KEY_SHAPE, stripeCall, StripeError, createCheckoutSession, createRefund, expireCheckoutSession, dashboardLink, isApprovalRequired, isMissingProduct, productIdOf, verifyWebhook } from './stripe.mjs';
 import { pendingStatementPeriod, statementFailures, arrivalOf, booksOf, linesOf, statementPage, lineFor, receiveStatement, receivedPages, referrerOk, sendStatements, settle, statementsIn, voidLineStatements } from './referrals.mjs';
 import { SHOP_JS, officeShopPage, parentPage, refundsPage, shopPage, thanksPage } from './shop-page.mjs';
 import { notFoundPage } from './site.mjs';
@@ -83,10 +85,24 @@ function sameOrigin(request, url) {
   if (origin && origin !== 'null') return origin === url.origin;
   return request.headers.get('sec-fetch-site') === 'same-origin';
 }
+async function boundedText(request, max) {
+  const reader = request.body?.getReader();
+  if (!reader) return '';
+  const decoder = new TextDecoder();
+  let text = '', bytes = 0;
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    bytes += value.byteLength;
+    if (bytes > max) { await reader.cancel(); return null; }
+    text += decoder.decode(value, { stream: true });
+  }
+  return text + decoder.decode();
+}
 async function bodyOf(request, max = 4096) {
   if (!/^application\/json\b/i.test(request.headers.get('content-type') ?? '')) return { error: fail(415, 'json', 'send JSON (content-type: application/json)') };
-  const text = await request.text();
-  if (text.length > max) return { error: fail(413, 'too-large', 'that request is too large') };
+  const text = await boundedText(request, max);
+  if (text === null) return { error: fail(413, 'too-large', 'that request is too large') };
   try { const b = text ? JSON.parse(text) : {}; return b && typeof b === 'object' && !Array.isArray(b) ? { body: b } : { error: fail(400, 'json', 'send a JSON object') }; } catch { return { error: fail(400, 'json', 'that is not JSON') }; }
 }
 
@@ -94,8 +110,9 @@ async function bodyOf(request, max = 4096) {
 
 const sizes = new WeakMap();
 function requestSize(shop) {
+  if (shop.requestBytes !== null) return shop.requestBytes;
   if (sizes.has(shop)) return sizes.get(shop);
-  const size = (shop?.items ?? []).reduce((size, item) => (item.gives ?? []).reduce((n, key) => Math.max(n, JSON.stringify(key).length), Math.max(size, JSON.stringify(item.id).length)), 0) * 6 + 4096;
+  const size = (shop?.items ?? []).reduce((size, item) => (item.gives ?? []).reduce((n, key) => Math.max(n, JSON.stringify(key).length), Math.max(size, JSON.stringify(item.id).length)), 0) * 600 + 4096;
   sizes.set(shop, size);
   return size;
 }
@@ -121,14 +138,19 @@ export async function readiness(env, shop) {
   else if (shop.broken) missing.push('shop.json-refused');
   else if (shop.till === 'off') missing.push('till-off');
   else if (!shop.items.length) missing.push('items');
-  const key = String(env?.STRIPE_KEY ?? '');
-  if (/^sk_live_/.test(key)) missing.push('restricted-key');
-  else if (!KEY_SHAPE.test(key)) missing.push('stripe-key');
-  if (!WEBHOOK_SECRET_SHAPE.test(String(env?.STRIPE_WEBHOOK_SECRET ?? ''))) missing.push('webhook-secret');
+  const paidItems = shop?.items.some((i) => i.price !== 0);
+  const links = linkConfig(env);
+  if (paidItems && !hasStripeKey(env)) {
+    if (fullerReason(shop)) missing.push('fuller-checkout');
+    else if (!links || links.settings !== linkSettings(shop) || shop.items.some((i) => i.price !== 0 && !links.items.some((l) => l.item === i.id && paymentLinkURL(l.url)))) missing.push('payment-links');
+  }
+  // Reliable fulfillment requires the webhook as well as the redirect.
+  // https://docs.stripe.com/checkout/fulfillment
+  if (paidItems && !WEBHOOK_SECRET_SHAPE.test(String(env?.STRIPE_WEBHOOK_SECRET ?? ''))) missing.push('webhook-secret');
   let migration = null;
-  if (!env?.DB || env.HOMIE_PREVIEW === '1') missing.push('database');
+  if (!env?.DB) missing.push('database');
   else if ((migration = await migrationNeeded(env))) missing.push('migration');
-  return { ready: missing.length === 0, missing, migration, mode: KEY_SHAPE.test(key) ? modeOf(key) : null };
+  return { ready: missing.length === 0, missing, next: missing.length ? MISSING_WORDS[missing[0]] : null, migration, mode: paidItems ? shopMode(env) : null };
 }
 
 export const MISSING_WORDS = Object.freeze({
@@ -137,11 +159,12 @@ export const MISSING_WORDS = Object.freeze({
   'shop.json-refused': 'shop.json conflicts with the studio settings or payment requirements (homie-studio shop check says which), so nothing is sold.',
   'till-off': 'shop.json says "till": "off".',
   items: 'shop.json has no items.',
-  'restricted-key': 'The Worker has a full secret key: the shop takes only a restricted key (homie-studio shop connect).',
-  'stripe-key': 'The Worker has no Stripe key yet (homie-studio shop connect: the owner pastes a restricted key into a page on their own computer).',
-  'webhook-secret': 'The Worker has no webhook signing secret yet (the same page takes it).',
-  database: 'This Worker has no database (a Preview never sells).',
-  migration: 'The shop\'s tables are not in the studio\'s D1 yet: npm run deploy applies migrations 0008_studio_shop.sql, 0010_shop_reservations.sql and 0011_shop_statements.sql.',
+  'payment-links': 'Run homie-studio shop connect to sync your items and connect Stripe; approve its browser page if asked.',
+  'fuller-checkout': 'Your spending allowance or checkout expiry needs the fuller checkout connection. Ask your AI to connect it.',
+  'stripe-key': 'The Worker has no Stripe key yet (homie-studio shop connect: approve Stripe in your browser; the command names any remaining Worker credential step).',
+  'webhook-secret': 'The Worker has no webhook signing secret yet (run homie-studio shop connect to create and store it automatically).',
+  database: 'This Worker has no database.',
+  migration: 'The shop\'s tables are not in the studio\'s D1 yet: npm run deploy applies migrations 0008_studio_shop.sql, 0010_shop_reservations.sql and 0011_shop_statements.sql and 0012_shop_lines.sql.',
 });
 
 /** The server a request names (the play shell says which), with its kids and beginner flags. */
@@ -176,8 +199,8 @@ async function itemsView(env, shop, { game, kids, beginner, player, open, cursor
   const page = item ? selected : selected.slice(cursor, cursor + 100);
   const items = page.map((it) => {
     const owned = it.gives.length > 0 && it.gives.every((k) => owns.some((o) => o.key === k && o.item === it.id));
-    const way = wayFor(it, { open, kids, beginner, player, band, owned, spent, cap: purchasing ? null : shop.capPerPlayerMonth, policy: shop.policy });
-    return { id: it.id, kind: it.kind, name: it.name, blurb: it.blurb ?? null, price: it.price, ...(it.kind === 'tip' ? { min: it.min, max: it.max } : {}), shown: it.kind === 'tip' ? `${money(it.min, shop.currency)} or more` : money(it.price, shop.currency), gives: it.gives, ...(it.badge ? { badge: it.badge } : {}), ...(it.days ? { days: it.days } : {}), ...(it.ends ? { ends: it.ends } : {}), ...(it.game ? { game: it.game } : {}), way, ...(way === 'cap' ? { retryWay: wayFor(it, { open, kids, beginner, player, band, owned, cap: null, policy: shop.policy }) } : {}) };
+    const way = wayFor(it, { open: open || it.price === 0 && !shop.broken && shop.till !== 'off', kids, beginner, player, band, owned, spent, cap: purchasing ? null : shop.capPerPlayerMonth, policy: shop.policy });
+    return { id: it.id, kind: it.kind, name: it.name, blurb: it.blurb ?? null, price: it.price, ...(it.price === 'choose' ? { min: it.min, max: it.max } : {}), shown: it.price === 'choose' ? `${money(it.min, shop.currency)} or more` : money(it.price, shop.currency), gives: it.gives, ...(it.badge ? { badge: it.badge } : {}), ...(it.days ? { days: it.days } : {}), ...(it.ends ? { ends: it.ends } : {}), ...(it.game ? { game: it.game } : {}), way, ...(way === 'cap' ? { retryWay: wayFor(it, { open, kids, beginner, player, band, owned, cap: null, policy: shop.policy }) } : {}) };
   }).filter((i) => i.way !== 'beginner' && i.way !== 'kids');
   return { band, owns, spent, items, nextCursor: !item && cursor + 100 < selected.length ? String(cursor + 100) : null };
 }
@@ -186,6 +209,7 @@ async function itemsView(env, shop, { game, kids, beginner, player, open, cursor
 
 /** The shop's paths, or null for any other. */
 export async function shopRoutes(request, env, ctx, url, { catalogueOf }) {
+  const requestAt = Date.now();
   const path = url.pathname;
   const read = request.method === 'GET' || request.method === 'HEAD';
   if (path === '/api/referrals/statement') return receiveStatement(request, env, url);
@@ -195,7 +219,8 @@ export async function shopRoutes(request, env, ctx, url, { catalogueOf }) {
   if (path === '/shop') return Response.redirect(`${url.origin}/shop/${url.search}`, 301);
   const cat = await catalogueOf();
   const shop = shopOf(cat);
-  // The studio's protective policy closes kids studios.
+  if (path === '/api/shop/hook') return hook(request, env, cat, shop ?? checkShop({}).shop);
+  // Only the studio's chosen policy closes a kids studio.
   if (!shop || shop.audience === 'kids') {
     if (path === '/api/player/owns') return json({ ok: true, owns: [], open: false });
     if (path.startsWith('/api/')) return json({ ok: true, open: false, items: [], missing: [shop ? 'kids-studio' : 'shop.json'] });
@@ -203,15 +228,25 @@ export async function shopRoutes(request, env, ctx, url, { catalogueOf }) {
     return shop ? notFoundPage('This studio sells nothing.', cat) : null;
   }
   const ready = await readiness(env, shop);
+  if (read && url.searchParams.get('cancelled') !== '1' && ctx?.waitUntil && !ready.migration && KEY_SHAPE.test(String(env.STRIPE_KEY ?? ''))) {
+    ctx.waitUntil((async () => {
+      const player = await players.of(request, env);
+      if (player) await reconcileOrders(env, shop, player.id);
+    })().catch((error) => logOrderError(env, null, error)));
+  }
   try {
+    if (path === '/shop/' && read && url.searchParams.get('cancelled') === '1' && /^ord_[A-Za-z0-9]{20}$/.test(url.searchParams.get('order') ?? '') && !ready.migration) {
+      const player = await players.of(request, env);
+      if (player) await reconcileOrders(env, shop, player.id, { expireOpen: true, order: url.searchParams.get('order') });
+    }
     if (path === '/api/shop/hook') return await hook(request, env, cat, shop, ready);
     if (!read && !sameOrigin(request, url)) return fail(403, 'origin', 'only this site\'s own pages may do that');
     if (path === '/api/shop' && read) return await listRoute(request, env, url, cat, shop, ready);
     if (path === '/api/player/owns' && read) return await ownsRoute(request, env, url, cat, shop);
     if (path === '/api/shop/mine' && read) return await mineRoute(request, env, shop);
-    if (path === '/api/shop/order' && read) return await orderRoute(request, env, url);
+    if (path === '/api/shop/order' && read) return await orderRoute(request, env, url, shop);
     if (path === '/api/shop/age' && request.method === 'POST') return await ageRoute(request, env, shop);
-    if (path === '/api/shop/buy' && request.method === 'POST') return await buyRoute(request, env, url, cat, shop, ready, ctx);
+    if (path === '/api/shop/buy' && request.method === 'POST') return await buyRoute(request, env, url, cat, shop, ready, ctx, requestAt);
     if (path === '/api/shop/parent' && request.method === 'POST') return await parentLinkRoute(request, env, url, cat, shop, ready);
     if (path === '/api/shop/used' && request.method === 'POST') return await usedRoute(request, env, shop);
     if (path === '/api/shop/refund' && request.method === 'POST') return await selfRefundRoute(request, env, shop, ready);
@@ -236,7 +271,7 @@ async function listRoute(request, env, url, cat, shop, ready) {
   // The studio decides which known age bands see no shop.
   if ((v.band === 'child' && shop.policy.children === 'deny') || (v.band === 'teen' && shop.policy.teens === 'deny')) return json({ ok: true, open: false, kids: true, items: [] });
   return json({
-    ok: true, open: ready.ready, ...(ready.ready ? {} : { missing: ready.missing, migration: ready.migration }), mode: ready.mode,
+    ok: true, keyless: !hasStripeKey(env), open: ready.ready || !ready.migration && ready.missing.every((m) => ['payment-links', 'webhook-secret', 'fuller-checkout'].includes(m)) && shop.items.some((i) => i.price === 0), ...(ready.ready ? {} : { missing: ready.missing, migration: ready.migration }), mode: ready.mode,
     currency: shop.currency, currencyScale: currencyScale(shop.currency), amountStep: amountStep(shop.currency), policy: shop.policy, till: shop.till, refundDays: shop.refundDays, cap: shop.capPerPlayerMonth, spent: v.spent,
     player: player ? { signedIn: !player.guest, guest: player.guest, name: player.name, band: v.band } : null,
     owns: v.owns.map((o) => o.key), items: v.items, nextCursor: v.nextCursor,
@@ -251,7 +286,7 @@ async function ownsRoute(request, env, url, cat, shop) {
   const facts = await serverFacts(env, cat, game, url.searchParams.get('server'));
   const advantage = new Set((shop.items ?? []).filter((i) => i.advantage).map((i) => i.id));
   const owns = (await ownsOf(env, p.id)).filter((o) => !(((facts.kids && !shop.policy.kidsAdvantages) || (facts.beginner && !shop.policy.beginnerAdvantages)) && advantage.has(o.item)));
-  return json({ ok: true, open: Boolean(shop.open), owns: owns.map((o) => o.key), detail: owns.map((o) => ({ key: o.key, item: o.item, until: o.until })) });
+  return json({ ok: true, open: Boolean(shop.open), owns: owns.map((o) => o.key), detail: owns.map((o) => ({ key: o.key, item: o.item, until: o.until, quantity: o.quantity })) });
 }
 
 async function mineRoute(request, env, shop) {
@@ -259,16 +294,35 @@ async function mineRoute(request, env, shop) {
   if (!p) return json({ ok: true, player: null, orders: [], owns: [] });
   const data = await shopDataOf(env, p.id);
   const names = new Map((shop.items ?? []).map((i) => [i.id, i.name]));
-  return json({ ok: true, currency: shop.currency, refundDays: shop.refundDays, refundUsedItems: shop.policy.refundUsedItems, ageBand: data?.ageBand ?? null, orders: (data?.orders ?? []).map((o) => ({ ...o, name: names.get(o.item) ?? o.item, shown: money(o.amount, o.currency), refundable: refundableNow(o, data?.owns ?? [], shop) })).reverse(), owns: (data?.owns ?? []).map((o) => ({ key: o.key, item: o.item, until: o.until, used: o.used })), badges: (data?.owns ?? []).filter((o) => o.key.startsWith('badge:')).map((o) => (shop.items ?? []).find((i) => i.id === o.item)?.badge ?? o.key.slice(6)) });
+  const orders = [];
+  for (const o of data?.orders ?? []) {
+    for (const line of o.lines) {
+      if (line.kind === null) { const item = shop.items.find((i) => i.id === line.item); line.name = item?.name ?? line.name; line.kind = item?.kind ?? null; }
+      const used = await lineWasUsed(env, o.id, line);
+      line.refundable = (o.amount === 0 || hasStripeKey(env)) && refundableNow({ ...line, paidAt: o.paidAt }, used ? [{ item: line.item, used: true }] : [], shop);
+      line.shown = money(line.amount, o.currency);
+    }
+    orders.push({ ...o, name: o.lines.map((l) => `${l.name} × ${l.quantity}`).join(', '), shown: money(o.amount, o.currency), refundable: o.lines.length > 0 && o.lines.every((l) => l.refundable) });
+  }
+  return json({ ok: true, currency: shop.currency, refundDays: shop.refundDays, refundUsedItems: shop.policy.refundUsedItems, ageBand: data?.ageBand ?? null, orders: orders.reverse(), owns: data?.owns ?? [], badges: (data?.owns ?? []).filter((o) => o.key.startsWith('badge:')).map((o) => names.get(o.item) ?? o.key.slice(6)) });
 }
 
 /** The thanks page asks: is my order (of this session) paid yet? Only the buyer's own account sees it. */
-async function orderRoute(request, env, url) {
+async function orderRoute(request, env, url, shop) {
   const p = await players.of(request, env);
   const session = url.searchParams.get('session') ?? '';
   if (!p || !/^cs_[A-Za-z0-9_]{1,200}$/.test(session)) return json({ ok: true, status: null });
   const o = await orderBySession(env, session);
   if (!o || o.player !== p.id) return json({ ok: true, status: null });
+  if (o.paid_at === null && KEY_SHAPE.test(String(env.STRIPE_KEY ?? '')) && !purchaseLimited(request, shop, p.id, 'verify')) {
+    try {
+      const session = await stripeCall(env, 'GET', `/v1/checkout/sessions/${encodeURIComponent(o.session)}`, { expand: ['payment_intent.latest_charge'] }, { timeout: 2000 });
+      if (session.id === o.session && (session.livemode === undefined || session.livemode === (o.mode === 'live')) && ['paid', 'no_payment_required'].includes(session.payment_status)) {
+        await paid(env, shop, session, (session.payment_intent?.latest_charge?.created ?? session.created ?? Math.floor(Date.now() / 1000)) * 1000);
+        Object.assign(o, await orderById(env, o.id));
+      }
+    } catch (error) { logOrderError(env, o.id, error); }
+  }
   return json({ ok: true, status: playerOrderStatus(o), item: o.item, game: o.game ?? null });
 }
 
@@ -295,41 +349,45 @@ async function ageRoute(request, env, shop) {
   return response;
 }
 
-export function sessionParams(shop, item, order, { origin, amount, player, game, parent = false, studio, product = null }) {
+export function sessionParams(shop, item, order, { origin, amount, player, game, parent = false, studio, product = null, lines = null }) {
   const managed = shop.till === 'stripe-managed';
   // Managed Payments needs an eligible digital-goods tax code on every product (video games, downloaded).
-  const taxCode = item.taxCode ?? (managed ? defaultTaxCode(item) : undefined);
+  const cart = lines ?? [{ item, amount, quantity: 1, product }];
   const back = game ? `&game=${encodeURIComponent(game)}` : '';
   return {
     mode: 'payment',
-    line_items: [{
-      quantity: 1,
-      price_data: {
-        currency: shop.currency, unit_amount: amount, tax_behavior: 'exclusive',
-        // The catalog's Product (its name and tax code are Stripe's copy of shop.json's), or the item described inline.
-        ...(product ? { product } : { product_data: { name: item.name, ...(item.blurb ? { description: item.blurb } : {}), ...(taxCode ? { tax_code: taxCode } : {}), metadata: { item: item.id.length <= 500 ? item.id : undefined } } }),
+    // Stripe payment Checkout allows up to 100 lines, each with a quantity:
+    // https://docs.stripe.com/api/checkout/sessions/create#create_checkout_session-line_items
+    line_items: cart.map((line) => ({
+      quantity: line.quantity,
+      price_data: { currency: shop.currency, unit_amount: line.amount, tax_behavior: 'exclusive',
+        ...(line.product ? { product: line.product } : { product_data: {
+          name: line.item.name, ...(line.item.blurb ? { description: line.item.blurb } : {}),
+          ...(line.item.taxCode || managed ? { tax_code: line.item.taxCode ?? defaultTaxCode(line.item) } : {}),
+          metadata: { item: line.item.id.length <= 500 ? line.item.id : undefined, line: line.id },
+        } }),
       },
-    }],
+    })),
     client_reference_id: player,
     // Stripe metadata values allow 500 characters; the order holds the complete item id.
     // https://docs.stripe.com/metadata (fetched 2026-10-08).
-    metadata: { homie: 'shop-v1', studio: String(studio ?? '').length <= 500 ? String(studio ?? '') : undefined, order: order.id, item: item.id.length <= 500 ? item.id : undefined, ...(game ? { game } : {}), ...(order.via ? { via: order.via } : {}), ...(parent ? { parent: '1' } : {}) },
-    payment_intent_data: { metadata: { order: order.id, item: item.id.length <= 500 ? item.id : undefined } },
+    metadata: { homie: 'shop-v1', origin, studio: String(studio ?? '').length <= 500 ? String(studio ?? '') : undefined, order: order.id, item: item.id.length <= 500 ? item.id : undefined, ...(game ? { game } : {}), ...(order.via ? { via: order.via } : {}), ...(parent ? { parent: '1' } : {}) },
+    payment_intent_data: { metadata: { homie: 'shop-v1', origin, order: order.id, item: item.id.length <= 500 ? item.id : undefined } },
     success_url: `${origin}/shop/thanks?session_id={CHECKOUT_SESSION_ID}${back}`,
-    cancel_url: `${origin}/shop/?cancelled=1${back}`,
-    // Stripe permits 30 minutes to 24 hours: https://docs.stripe.com/api/checkout/sessions/create#create_checkout_session-expires_at
-    expires_at: order.expiresAt ?? Math.floor((order.createdAt ?? Date.now()) / 1000) + 31 * 60,
-    // The EU and UK immediate-delivery acknowledgement (Consumer Rights Directive Art 16(m)), beside the pay button.
+    cancel_url: `${origin}/shop/?cancelled=1&order=${order.id}${back}`,
+    // Keep Stripe’s default 24-hour Checkout lifetime: https://docs.stripe.com/api/checkout/sessions/create#create_checkout_session-expires_at
+    expires_at: order.expiresAt ?? Math.floor((order.createdAt ?? Date.now()) / 1000) + Math.max(31, shop.checkoutMinutes ?? 1440) * 60,
+    // The studio can opt into immediate-delivery acknowledgement beside the pay button.
     custom_text: { submit: { message: checkoutMessage(shop, String(studio ?? 'this studio'), parent) } },
-    // The kit's own tills: Stripe Tax on (the studio is the seller), or Managed Payments (Stripe is the seller of record
-    // and computes the tax itself, so automatic_tax and adaptive pricing must not be sent).
-    ...(managed ? { managed_payments: { enabled: true } } : { automatic_tax: { enabled: true }, adaptive_pricing: { enabled: false } }),
+    // The studio can enable Stripe Tax, or choose Managed Payments (Stripe is the seller of record
+    // and computes tax itself). Disable adaptive pricing to preserve the file price.
+    ...(managed ? { managed_payments: { enabled: true } } : { ...(shop.automaticTax ? { automatic_tax: { enabled: true } } : {}), adaptive_pricing: { enabled: false } }),
   };
 }
 
 function logOrderError(env, order, error) {
-  const reason = String(error?.message ?? error).replaceAll(String(env.STRIPE_KEY || '\0'), '[redacted]');
-  console.warn('Shop reconciliation', { order, reason, status: error?.status ?? null, code: error?.code ?? null });
+  const reason = redactStripe(error?.message ?? error, env);
+  console.warn('Shop reconciliation', { order, reason, status: error?.status ?? null, code: redactStripe(error?.code, env) });
 }
 
 /** At most three reads in parallel, claimed before I/O. Old unresolved rows back off up to an hour.
@@ -337,19 +395,49 @@ function logOrderError(env, order, error) {
  * Missing sessions: https://docs.stripe.com/error-codes#resource-missing
  * Payment time: https://docs.stripe.com/api/charges/object#charge_object-created
  */
-export async function reconcileOrders(env, shop, player) {
+export async function reconcileOrders(env, shop, player = null, { expireOpen = false, order = null, before = Infinity } = {}) {
+  if (!shop || !KEY_SHAPE.test(String(env?.STRIPE_KEY ?? '')) || !(await migrated(env))) return;
   const now = Date.now();
-  const rows = (await env.DB.prepare("SELECT * FROM shop_orders WHERE player = ?1 AND mode = ?2 AND session IS NOT NULL AND status IN ('started', 'processing') AND (expires_at IS NULL OR expires_at <= ?3 OR status = 'processing') AND updated_at <= ?3 - MIN(3600000, MAX(CASE WHEN status = 'processing' THEN 300000 ELSE 60000 END, CAST((?3 - created_at) / 24 AS INTEGER))) ORDER BY updated_at, id LIMIT 3")
-    .bind(player, modeOf(env.STRIPE_KEY), now).all()).results ?? [];
+  // Filter eligibility before LIMIT. Unrecorded payments precede old paid rows needing repair.
+  const params = [shopMode(env), now, Number.isFinite(before) ? before : Number.MAX_SAFE_INTEGER, ...(player ? [player] : []), ...(order ? [order] : [])];
+  const query = (status, limit) => env.DB.prepare(`SELECT * FROM shop_orders ${order ? '' : `INDEXED BY ${player ? 'shop_orders_attention_player' : 'shop_orders_attention'}`} WHERE attention = 1 AND mode = ?1
+    AND status = '${status}'
+    AND (created_at < ?3 ${expireOpen ? 'OR expires_at <= ?2' : ''}) ${player ? 'AND player = ?4' : ''} ${order ? `AND id = ?${player ? 5 : 4}` : ''}
+    ${expireOpen ? '' : "AND (created_at <= ?2 - 60000 OR expires_at <= ?2 OR status = 'processing') AND updated_at <= ?2 - MIN(3600000, MAX(60000, CAST((?2 - created_at) / 24 AS INTEGER)))"}
+    ORDER BY updated_at, id LIMIT ${limit}`).bind(...params).all();
+  let rows = (await query('started', 3)).results ?? [];
+  if (!expireOpen) {
+    rows.push(...((await query('processing', 3)).results ?? []));
+    rows.sort((a, b) => a.updated_at - b.updated_at || a.id.localeCompare(b.id));
+    rows = rows.slice(0, 3);
+    if (rows.length < 3) rows.push(...((await query('paid', 3 - rows.length)).results ?? []));
+  }
   await Promise.all(rows.map(async (row) => {
-    const claim = await env.DB.prepare("UPDATE shop_orders SET updated_at = ?3 WHERE id = ?1 AND updated_at = ?2 AND status IN ('started', 'processing')").bind(row.id, row.updated_at, now).run();
-    if (!claim.meta?.changes) return;
+    if (!row.session) {
+      if (row.status === 'paid' || (row.expires_at ?? row.created_at + 1860000) + 60000 < now) await env.DB.prepare('UPDATE shop_orders SET attention = 0 WHERE id = ?1 AND session IS NULL').bind(row.id).run();
+      return;
+    }
+    if (expireOpen && row.status !== 'started') return;
+    if (row.status === 'paid' && !row.player) { await env.DB.prepare('UPDATE shop_orders SET attention = 0 WHERE id = ?1').bind(row.id).run(); return; }
+    const claimedAt = Math.max(now, Number(row.updated_at) + 1);
+    const claim = await env.DB.prepare("UPDATE shop_orders SET updated_at = ?3 WHERE id = ?1 AND updated_at = ?2 AND status IN ('started', 'processing', 'paid')").bind(row.id, row.updated_at, claimedAt).run();
+    if (!claim.meta?.changes && !(expireOpen && order)) return;
     try {
-      const session = await stripeCall(env, 'GET', `/v1/checkout/sessions/${encodeURIComponent(row.session)}`, { expand: ['payment_intent.latest_charge'] }, { timeout: 2000 });
+      let session;
+      if (expireOpen) {
+        try { session = await expireCheckoutSession(env, row.session, { timeout: 2000 }); }
+        catch (error) {
+          if (!(error instanceof StripeError) || error.status !== 400) throw error;
+          // Already complete or expired: read Stripe's outcome instead of freeing an unconfirmed payment.
+          session = await stripeCall(env, 'GET', `/v1/checkout/sessions/${encodeURIComponent(row.session)}`, { expand: ['payment_intent.latest_charge'] }, { timeout: 2000 });
+        }
+      } else session = await stripeCall(env, 'GET', `/v1/checkout/sessions/${encodeURIComponent(row.session)}`, { expand: ['payment_intent.latest_charge'] }, { timeout: 2000 });
       if (!session || session.id !== row.session || (typeof session.livemode === 'boolean' && session.livemode !== (row.mode === 'live'))) throw new Error('Stripe session identity or mode mismatch');
+      // A buyer abandoning their own open session releases only on Stripe's confirmation.
+      // https://docs.stripe.com/api/checkout/sessions/expire
       const payment = session.payment_intent;
       if (session.payment_status === 'paid' || session.payment_status === 'no_payment_required' || payment?.status === 'succeeded') {
-        const time = session.payment_status === 'no_payment_required' ? session.created : payment?.latest_charge?.created;
+        const time = session.payment_status === 'no_payment_required' ? session.created : payment?.latest_charge?.created ?? session.created;
         // Missing payment time remains unresolved; never charge an old payment to this month's allowance.
         if (Number.isSafeInteger(time) && time > 0 && time * 1000 <= now) await paid(env, shop, session, time * 1000);
       } else if (session.status === 'expired' || payment?.status === 'canceled' || (session.status === 'complete' && payment?.status === 'requires_payment_method' && payment.last_payment_error)) {
@@ -359,26 +447,43 @@ export async function reconcileOrders(env, shop, player) {
       logOrderError(env, row.id, error);
       // This key's account cannot see the session; a later verified payment still grants it.
       if (error instanceof StripeError && error.status === 404 && error.code === 'resource_missing') {
-        await env.DB.prepare("UPDATE shop_orders SET status = 'missing', note = 'Stripe account has no such session; previous status: ' || status, updated_at = ?2 WHERE id = ?1 AND status IN ('started', 'processing')").bind(row.id, now).run();
+        await env.DB.prepare("UPDATE shop_orders SET attention = 0, status = CASE WHEN status = 'paid' THEN status ELSE 'missing' END, note = 'Stripe account has no such session; previous status: ' || status, updated_at = ?2 WHERE id = ?1 AND status IN ('started', 'processing', 'paid')").bind(row.id, now).run();
       } else {
         // Keep the atomic claim, but retry failures after roughly a minute, regardless of row age.
         const interval = Math.min(3600000, Math.max(row.status === 'processing' ? 300000 : 60000, Math.trunc((now - row.created_at) / 24)));
-        await env.DB.prepare("UPDATE shop_orders SET updated_at = ?3 WHERE id = ?1 AND updated_at = ?2 AND status IN ('started', 'processing')").bind(row.id, now, now - interval + 60000).run();
+        await env.DB.prepare("UPDATE shop_orders SET updated_at = ?3 WHERE id = ?1 AND updated_at = ?2 AND status IN ('started', 'processing', 'paid')").bind(row.id, claimedAt, now - interval + 60000).run();
       }
     }
   }).map((work, i) => work.catch((error) => logOrderError(env, rows[i].id, error))));
 }
 
 /** Make the order row, then Stripe's Checkout Session. Returns { order, url } or a refusal Response. */
-async function startCheckout(env, url, cat, shop, item, { player, game, via, amount, parent = false }) {
-  if (via && !Number.isSafeInteger(Math.round(amount * shop.referrals.rate))) return { error: fail(400, 'arithmetic', 'The referral share exceeds safe integer arithmetic; change the studio rate or amount.') };
+async function startCheckout(env, url, cat, shop, item, { player, game, via, amount, parent = false, lines = null, requestAt = Date.now() }) {
+  lines ??= [{ item, amount, quantity: 1 }];
+  const keyless = amount > 0 && !hasStripeKey(env);
+  if (keyless && (lines.length !== 1 || fullerReason(shop))) return { error: fail(409, 'one-item', fullerReason(shop) ?? 'Buy one item at a time. A combined cart needs the fuller checkout connection.') };
+  const link = keyless ? linkConfig(env)?.items.find((l) => l.item === item.id) : null;
+  if (keyless && (!link || !paymentLinkURL(link.url))) return { error: fail(503, 'payment-links', MISSING_WORDS['payment-links']) };
+  if (keyless && item.price === 'choose' && lines[0].quantity !== 1) return { error: fail(400, 'quantity', 'A tip is one chosen amount; choose it on Stripe.') };
+  if (keyless) lines = lines.map((l) => ({ ...l, item: { ...l.item, paymentLink: link } }));
+  try { if (via) referralShare(amount, shop.referrals.rate); } catch { return { error: fail(400, 'arithmetic', 'The referral share exceeds safe integer arithmetic.') }; }
   const order = { id: newOrderId(), player: player.id, via: via ?? null, amount, currency: shop.currency };
   const now = Date.now();
   order.createdAt = now;
-  order.expiresAt = Math.floor(now / 1000) + 31 * 60;
+  order.expiresAt = Math.floor(now / 1000) + Math.max(31, shop.checkoutMinutes ?? 1440) * 60;
   // One SQL statement reserves the amount: concurrent requests cannot both spend the remaining cap.
-  const reserve = () => env.DB.prepare("INSERT INTO shop_orders (id, player, item, game, amount, currency, till, mode, status, parent, via, created_at, updated_at, expires_at) SELECT ?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, 'started', ?9, ?10, ?11, ?11, ?14 WHERE ?5 = 0 OR ?12 IS NULL OR ?5 <= ?12 - (SELECT COALESCE(SUM(amount), 0) FROM shop_orders WHERE player = ?2 AND mode = ?8 AND ((status IN ('paid', 'disputed') AND paid_at >= ?13) OR (status IN ('started', 'processing') AND (session IS NOT NULL OR COALESCE(expires_at, created_at + 1860000) + 60000 > ?11))))")
-    .bind(order.id, player.id, item.id, game ?? item.game ?? null, amount, shop.currency, shop.till, modeOf(env.STRIPE_KEY), parent ? 1 : 0, order.via, now, shop.capPerPlayerMonth, Date.UTC(new Date(now).getUTCFullYear(), new Date(now).getUTCMonth(), 1), order.expiresAt * 1000).run();
+  const reservation = () => env.DB.prepare("INSERT INTO shop_orders (id, player, item, game, amount, currency, till, mode, status, parent, via, created_at, updated_at, expires_at) SELECT ?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, 'started', ?9, ?10, ?11, ?11, ?14 WHERE ?5 = 0 OR ?12 IS NULL OR ?5 <= ?12 - (SELECT COALESCE(SUM(amount - refunded_net), 0) FROM shop_orders WHERE player = ?2 AND mode = ?8 AND ((status IN ('paid', 'disputed') AND paid_at >= ?13) OR (status IN ('started', 'processing') AND (session IS NOT NULL OR COALESCE(expires_at, created_at + 1860000) + 60000 > ?11))))")
+    .bind(order.id, player.id, item.id, game ?? item.game ?? null, amount, shop.currency, shop.till, shopMode(env), parent ? 1 : 0, order.via, now, shop.capPerPlayerMonth, Date.UTC(new Date(now).getUTCFullYear(), new Date(now).getUTCMonth(), 1), order.expiresAt * 1000);
+  lines = lines.map((line, i) => ({ ...line, id: `${order.id}_${i}` }));
+  const reserve = async () => {
+    const results = await env.DB.batch([reservation(),
+      ...lines.map((line, i) => env.DB.prepare("INSERT INTO shop_order_lines (id, order_id, position, item, quantity, unit_amount, amount, snapshot) SELECT ?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8 WHERE EXISTS (SELECT 1 FROM shop_orders WHERE id = ?2)")
+        .bind(line.id, order.id, i, line.item.id, line.quantity, line.amount, line.amount * line.quantity, JSON.stringify(line.item))),
+      env.DB.prepare('UPDATE shop_orders SET referral_terms = ?2, checkout_player = player WHERE id = ?1').bind(order.id, shop.referrals ? JSON.stringify(shop.referrals) : null),
+    ]);
+    return results[0];
+  };
+  await reconcileOrders(env, shop, player.id, { expireOpen: true, before: Math.min(requestAt, now - 60000) });
   let reserved = await reserve();
   const reconciled = !reserved.meta?.changes;
   if (!reserved.meta?.changes) {
@@ -386,27 +491,43 @@ async function startCheckout(env, url, cat, shop, item, { player, game, via, amo
     reserved = await reserve();
   }
   if (!reserved.meta?.changes) return { error: fail(403, 'cap', WAY_WORDS.cap, { way: 'cap' }) };
+  if (amount === 0) {
+    const id = `cs_free_${order.id}`;
+    await env.DB.prepare('UPDATE shop_orders SET session = ?2 WHERE id = ?1').bind(order.id, id).run();
+    await paid(env, shop, { id, metadata: { order: order.id }, client_reference_id: player.id, currency: shop.currency, amount_subtotal: 0, amount_total: 0, payment_status: 'no_payment_required' });
+    return { order, url: `${url.origin}/shop/thanks?session_id=${id}`, session: id, reconciled };
+  }
+  if (keyless) {
+    const checkout = new URL(link.url); checkout.searchParams.set('client_reference_id', order.id);
+    return { order, url: checkout.href, reconciled };
+  }
   let session = null;
-  const mode = modeOf(env.STRIPE_KEY);
+  const mode = shopMode(env);
   try {
-    const product = Array.isArray(shop.catalog) && shop.catalog.includes(mode) ? await productIdOf(cat.studio?.slug, item.id) : null;
-    const params = (p) => sessionParams(shop, item, order, { origin: url.origin, amount, player: player.id, game, parent, studio: cat.studio?.name, product: p });
+    const useCatalog = Array.isArray(shop.catalog) && shop.catalog.includes(mode);
+    for (const line of lines) line.product = useCatalog ? await productIdOf(cat.studio?.slug, line.item.id) : null;
+    await env.DB.batch(lines.map((line) => env.DB.prepare('UPDATE shop_order_lines SET snapshot = ?2 WHERE id = ?1').bind(line.id, JSON.stringify({ ...line.item, stripeProduct: line.product }))));
+    // Start the provider lifetime at session creation, after reservation/expiry I/O. At Stripe's
+    // lower bound the timestamp is computed immediately before the HTTP call.
+    const params = () => {
+      order.expiresAt = Math.floor(Date.now() / 1000) + Math.max(31, shop.checkoutMinutes ?? 1440) * 60;
+      return sessionParams(shop, item, order, { origin: url.origin, amount, player: player.id, game, parent, studio: cat.studio?.name, lines });
+    };
     try {
-      session = await createCheckoutSession(env, params(product), { idempotencyKey: `checkout-${order.id}` });
+      session = await createCheckoutSession(env, params(), { idempotencyKey: `checkout-${order.id}` });
     } catch (error) {
-      // shop.json says the catalog is made in this mode, but Stripe has no such Product (made in the sandbox only, or
-      // archived by hand): the item described inline still sells, and `homie-studio shop catalog` says what to make.
-      if (!product || !isMissingProduct(error)) throw error;
-      session = await createCheckoutSession(env, params(null), { idempotencyKey: `checkout-${order.id}-inline` });
+      if (!useCatalog || !isMissingProduct(error)) throw error;
+      for (const line of lines) line.product = null;
+      session = await createCheckoutSession(env, params(), { idempotencyKey: `checkout-${order.id}-inline` });
     }
     if (typeof session?.id !== 'string' || typeof session?.url !== 'string' || !/^https:\/\//.test(session.url) && !/^http:\/\/(127\.0\.0\.1|localhost)/.test(session.url)) {
       await env.DB.prepare("UPDATE shop_orders SET status = 'failed', updated_at = ?2 WHERE id = ?1").bind(order.id, Date.now()).run();
       return { error: fail(502, 'stripe', 'Stripe answered without a checkout page. Nothing was charged.') };
     }
-    await env.DB.prepare('UPDATE shop_orders SET session = ?2, updated_at = ?3 WHERE id = ?1').bind(order.id, session.id, Date.now()).run();
+    await env.DB.prepare('UPDATE shop_orders SET session = ?2, updated_at = ?3, expires_at = ?4 WHERE id = ?1').bind(order.id, session.id, Date.now(), (session.expires_at ?? order.expiresAt) * 1000).run();
   } catch (error) {
-    await env.DB.prepare("UPDATE shop_orders SET status = 'failed', note = ?2, updated_at = ?3 WHERE id = ?1").bind(order.id, String(error?.code ?? 'stripe').slice(0, 60), Date.now()).run();
-    const why = error instanceof StripeError ? error.message : 'Stripe did not answer';
+    await env.DB.prepare("UPDATE shop_orders SET status = 'failed', note = ?2, updated_at = ?3 WHERE id = ?1").bind(order.id, redactStripe(error?.code ?? 'stripe', env).slice(0, 60), Date.now()).run();
+    const why = error instanceof StripeError ? redactStripe(error.message, env) : 'Stripe did not answer';
     return { error: fail(502, 'stripe', `Stripe could not open the checkout (${why}). Nothing was charged.`) };
   }
   return { order, url: session.url, session: session.id, reconciled };
@@ -419,7 +540,7 @@ async function viaFor(request, env, url, shop, player) {
   if (!a || a.via === url.hostname.replace(/^www\./, '')) return null;
   if (shop.referrals.windowDays !== null && Date.now() - a.at > Math.round(shop.referrals.windowDays * DAY)) return null;
   // New players only: an account made before the arrival was already this studio's player.
-  if (player.since !== null && player.since < a.at - 60_000) return null;
+  if (shop.referralNewPlayersOnly && player.since !== null && player.since < a.at - 60_000) return null;
   return (await referrerOk(a.via)) ? a.via : null;
 }
 
@@ -437,26 +558,40 @@ function purchaseLimited(request, shop, player, kind) {
   return account || address;
 }
 
-async function buyRoute(request, env, url, cat, shop, ready, ctx) {
+async function buyRoute(request, env, url, cat, shop, ready, ctx, requestAt) {
   const b = await bodyOf(request, requestSize(shop));
   if (b.error) return b.error;
-  if (!ready.ready) return fail(503, 'closed', 'The shop is not open yet.', { missing: ready.missing, migration: ready.migration });
-  const item = shop.items.find((i) => i.id === b.body.item);
-  if (!item) return fail(404, 'item', 'no such item here');
+  const freeOnly = (b.body.lines ?? [{ item: b.body.item }]).every?.((l) => shop.items.some((i) => i.id === l?.item && i.price === 0));
+  if (!ready.ready && !(freeOnly && ready.missing.every((m) => ['payment-links', 'webhook-secret', 'fuller-checkout'].includes(m)))) return fail(503, 'closed', 'The shop is not open yet.', { missing: ready.missing, migration: ready.migration });
+  const requested = b.body.lines ?? [{ item: b.body.item, quantity: b.body.quantity ?? 1, amount: b.body.amount }];
+  // Stripe's documented limit, not a studio policy: https://docs.stripe.com/api/checkout/sessions/create#line_items
+  if (!Array.isArray(requested) || !requested.length || requested.length > 100) return fail(400, 'stripe-lines', 'Stripe Checkout takes between 1 and 100 lines.');
   const game = GAME_ID.test(String(b.body.game ?? '')) ? String(b.body.game) : null;
-  if (item.game && game && item.game !== game) return fail(400, 'item', 'that item belongs to another game');
   const facts = await serverFacts(env, cat, game, b.body.server);
   let player = await accountOf(request, env);
   if (purchaseLimited(request, shop, player?.id, 'buy')) return fail(429, 'rate', 'The studio purchase attempt rate limit was reached; try again in a minute.');
-  const v = await itemsView(env, shop, { game, ...facts, player, open: true, item, purchasing: true });
-  const row = v.items.find((i) => i.id === item.id);
-  const way = facts.kids && !shop.policy.kidsServer ? 'kids' : row?.way ?? (item.advantage && facts.beginner ? 'beginner' : 'closed');
-  if (way !== 'checkout') return fail(403, way, WAY_WORDS[way] ?? 'Not now.', { way });
-  let amount = item.price;
-  if (item.kind === 'tip') {
-    amount = typeof b.body.amount === 'number' ? b.body.amount : NaN;
-    if (amountError(amount, shop.currency) || !(amount >= item.min && (item.max === null || amount <= item.max))) return fail(400, 'amount', amountError(amount, shop.currency) ?? `The studio tip range starts at ${money(item.min, shop.currency)}${item.max === null ? '' : ` and ends at ${money(item.max, shop.currency)}`}.`);
+  const lines = [];
+  let amount = 0;
+  const seen = new Set();
+  for (const entry of requested) {
+    const item = shop.items.find((i) => i.id === entry?.item);
+    if (!item) return fail(404, 'item', 'no such item here');
+    const quantity = entry.quantity ?? 1;
+    if (!Number.isSafeInteger(quantity) || quantity < 1) return fail(400, 'arithmetic', 'Quantity is a positive safe integer.');
+    if (!shop.policy.repeatPurchases && (quantity > 1 || seen.has(item.id))) return fail(403, 'owned', 'The studio has disabled repeat purchases.');
+    seen.add(item.id);
+    const v = await itemsView(env, shop, { game, ...facts, player, open: true, item, purchasing: true });
+    const way = facts.kids && !shop.policy.kidsServer ? 'kids' : v.items[0]?.way ?? 'beginner';
+    if (way !== 'checkout') return fail(403, way, WAY_WORDS[way] ?? 'Not now.', { way });
+    const unit = item.price === 'choose' ? (entry.amount ?? (!hasStripeKey(env) ? item.min : undefined)) : item.price;
+    if (amountError(unit, shop.currency)) return fail(400, 'amount', amountError(unit, shop.currency));
+    if (item.price === 'choose' && (unit < item.min || (item.max !== null && unit > item.max))) return fail(400, 'amount', 'This amount is outside the studio tip range.');
+    const total = BigInt(unit) * BigInt(quantity) + BigInt(amount);
+    if (total > BigInt(Number.MAX_SAFE_INTEGER)) return fail(400, 'arithmetic', 'The order total exceeds safe integer arithmetic.');
+    amount = Number(total);
+    lines.push({ item, amount: unit, quantity });
   }
+  const item = lines[0].item;
   let cookies = [];
   if (!player) {
     const guest = await players.shopGuest(request, env, url, shop.guestBuyersPerAddressPerHour);
@@ -465,9 +600,9 @@ async function buyRoute(request, env, url, cat, shop, ready, ctx) {
     cookies = guest.session.cookies;
   }
   const via = await viaFor(request, env, url, shop, player);
-  const r = await startCheckout(env, url, cat, shop, item, { player, game, via, amount });
+  const r = await startCheckout(env, url, cat, shop, item, { player, game, via, amount, lines, requestAt });
   const response = r.error ?? json({ ok: true, order: r.order.id, url: r.url });
-  if (!r.error && !r.reconciled && shop.capPerPlayerMonth !== null && ctx?.waitUntil) ctx.waitUntil(reconcileOrders(env, shop, player.id).catch((error) => logOrderError(env, r.order.id, error)));
+  if (!r.error && !r.reconciled && ctx?.waitUntil) ctx.waitUntil(reconcileOrders(env, shop, player.id).catch((error) => logOrderError(env, r.order.id, error)));
   for (const cookie of cookies) response.headers.append('set-cookie', cookie);
   return response;
 }
@@ -477,17 +612,29 @@ async function parentLinkRoute(request, env, url, cat, shop, ready) {
   const b = await bodyOf(request, requestSize(shop));
   if (b.error) return b.error;
   if (!ready.ready) return fail(503, 'closed', 'The shop is not open yet.', { missing: ready.missing, migration: ready.migration });
-  const item = shop.items.find((i) => i.id === b.body.item);
-  if (!item) return fail(404, 'item', 'no such item here');
+  const requested = b.body.lines ?? [{ item: b.body.item, quantity: b.body.quantity ?? 1 }];
+  if (!Array.isArray(requested) || !requested.length || requested.length > 100) return fail(400, 'stripe-lines', 'Stripe Checkout takes between 1 and 100 lines.');
   const game = GAME_ID.test(String(b.body.game ?? '')) ? String(b.body.game) : null;
   const facts = await serverFacts(env, cat, game, b.body.server);
   const player = await accountOf(request, env);
   if (purchaseLimited(request, shop, player?.id, 'parent')) return fail(429, 'rate', 'The studio purchase attempt rate limit was reached; try again in a minute.');
-  const v = await itemsView(env, shop, { game, ...facts, player, open: true, item, purchasing: true });
-  const way = facts.kids && !shop.policy.kidsServer ? 'kids' : v.items.find((i) => i.id === item.id)?.way ?? 'closed';
-  if (way !== 'ask-a-parent') return fail(403, way, WAY_WORDS[way] ?? 'Not now.', { way });
+  const cart = [], seen = new Set();
+  for (const entry of requested) {
+    const item = shop.items.find((i) => i.id === entry?.item);
+    if (!item) return fail(404, 'item', 'no such item here');
+    const quantity = entry.quantity ?? 1;
+    if (!Number.isSafeInteger(quantity) || quantity < 1) return fail(400, 'arithmetic', 'Quantity is a positive safe integer.');
+    if (!shop.policy.repeatPurchases && (quantity > 1 || seen.has(item.id))) return fail(403, 'owned', 'The studio has disabled repeat purchases.');
+    seen.add(item.id);
+    const v = await itemsView(env, shop, { game, ...facts, player, open: true, item, purchasing: true });
+    const way = facts.kids && !shop.policy.kidsServer ? 'kids' : v.items[0]?.way ?? 'closed';
+    if (way !== 'ask-a-parent') return fail(403, way, WAY_WORDS[way] ?? 'Not now.', { way });
+    cart.push({ item: item.id, quantity });
+  }
+  const item = shop.items.find((i) => i.id === cart[0].item);
+  cart[0].via = await viaFor(request, env, url, shop, player);
   const token = randomToken();
-  await env.DB.prepare('INSERT INTO shop_parent_links (hash, player, item, game, order_id, expires_at) VALUES (?1, ?2, ?3, ?4, NULL, ?5)').bind(await sha256Hex(token), player.id, item.id, game, Date.now() + 7 * DAY).run();
+  await env.DB.prepare('INSERT INTO shop_parent_links (hash, player, item, game, order_id, expires_at, cart) VALUES (?1, ?2, ?3, ?4, NULL, ?5, ?6)').bind(await sha256Hex(token), player.id, item.id, game, Date.now() + 7 * DAY, JSON.stringify(cart)).run();
   return json({ ok: true, link: `${url.origin}/shop/parent/${token}`, expiresInDays: 7 });
 }
 
@@ -495,34 +642,44 @@ async function parentLinkRoute(request, env, url, cat, shop, ready) {
 async function parentRoute(request, env, url, cat, shop, ready, token, ctx) {
   if (!TOKEN.test(token)) return notFoundPage('This link does not work.', cat);
   const row = await env.DB.prepare('SELECT * FROM shop_parent_links WHERE hash = ?1').bind(await sha256Hex(token)).first();
-  const item = row ? shop.items.find((i) => i.id === row.item) : null;
+  const cart = row ? row.cart ? JSON.parse(row.cart) : [{ item: row.item, quantity: 1 }] : [];
+  const lines = cart.map((entry) => ({ item: shop.items.find((i) => i.id === entry.item), quantity: entry.quantity }));
+  const item = lines[0]?.item;
+  if (lines.some((line) => !line.item)) return parentPage(cat, shop, { gone: true });
   if (!row || !item || Number(row.expires_at) < Date.now()) return parentPage(cat, shop, { gone: true });
   const kid = await players.get(env, row.player);
   if (!kid) return parentPage(cat, shop, { gone: true });
   const done = row.order_id ? await orderById(env, row.order_id) : null;
-  if (done?.status === 'paid') return parentPage(cat, shop, { item, name: kid.name, paid: true });
-  if (request.method === 'GET' || request.method === 'HEAD') return parentPage(cat, shop, { item, name: kid.name, token, open: ready.ready });
+  if (done?.status === 'paid') return parentPage(cat, shop, { item, lines, name: kid.name, paid: true });
+  if (request.method === 'GET' || request.method === 'HEAD') return parentPage(cat, shop, { item, lines, name: kid.name, token, open: ready.ready });
   if (request.method !== 'POST' || !sameOrigin(request, url)) return new Response('Not allowed', { status: 403 });
   let form = null;
   try { form = await request.formData(); } catch { form = null; }
-  if (String(form?.get('grownup') ?? '') !== 'yes') return parentPage(cat, shop, { item, name: kid.name, token, open: ready.ready, said: 'Tick the box to say you are their parent or guardian and an adult.' });
-  if (!ready.ready) return parentPage(cat, shop, { item, name: kid.name, token, open: false });
-  if (purchaseLimited(request, shop, row.player, 'parentpay')) return parentPage(cat, shop, { item, name: kid.name, token, open: true, said: 'One moment: too many tries.' });
+  if (String(form?.get('grownup') ?? '') !== 'yes') return parentPage(cat, shop, { item, lines, name: kid.name, token, open: ready.ready, said: 'Tick the box to say you are their parent or guardian and an adult.' });
+  if (!ready.ready) return parentPage(cat, shop, { item, lines, name: kid.name, token, open: false });
+  if (purchaseLimited(request, shop, row.player, 'parentpay')) return parentPage(cat, shop, { item, lines, name: kid.name, token, open: true, said: 'One moment: too many tries.' });
   const band = await bandOfPlayer(env, row.player);
   const owns = await ownsOf(env, row.player);
-  const owned = item.gives.length > 0 && item.gives.every((key) => owns.some((o) => o.key === key && o.item === item.id));
-  if (wayFor(item, { player: kid, band, owned, spent: 0, cap: null, policy: shop.policy }) !== 'ask-a-parent') return parentPage(cat, shop, { gone: true });
-  const amount = item.kind === 'tip' ? parseAmount(form?.get('amount'), currencyScale(shop.currency)) : item.price;
-  const invalidAmount = amountError(amount, shop.currency);
-  if (invalidAmount || (item.kind === 'tip' && (amount < item.min || (item.max !== null && amount > item.max)))) return parentPage(cat, shop, { item, name: kid.name, token, said: invalidAmount ?? 'This amount exceeds the studio tip range or monthly cap.' });
-  const r = await startCheckout(env, url, cat, shop, item, { player: { id: row.player }, game: row.game, via: null, amount, parent: true });
-  if (r.error) return parentPage(cat, shop, { item, name: kid.name, token, open: true, said: (await r.error.json()).message });
+  let amount = 0;
+  for (const [index, line] of lines.entries()) {
+    const it = line.item;
+    const owned = it.gives.length > 0 && it.gives.every((key) => owns.some((o) => o.key === key && o.item === it.id));
+    if (wayFor(it, { player: kid, band, owned, spent: 0, cap: null, policy: shop.policy }) !== 'ask-a-parent') return parentPage(cat, shop, { gone: true });
+    line.amount = it.price === 'choose' ? parseAmount(form?.get(lines.length === 1 ? 'amount' : `amount_${index}`), currencyScale(shop.currency)) : it.price;
+    const invalid = amountError(line.amount, shop.currency);
+    if (invalid || it.price === 'choose' && (line.amount < it.min || it.max !== null && line.amount > it.max)) return parentPage(cat, shop, { item, lines, name: kid.name, token, said: invalid ?? 'This amount is outside the studio range.' });
+    const total = BigInt(amount) + BigInt(line.amount) * BigInt(line.quantity);
+    if (total > BigInt(Number.MAX_SAFE_INTEGER)) return parentPage(cat, shop, { item, lines, name: kid.name, token, said: 'The total exceeds safe integer arithmetic.' });
+    amount = Number(total);
+  }
+  const r = await startCheckout(env, url, cat, shop, item, { player: { id: row.player }, game: row.game, via: cart[0]?.via ?? null, amount, parent: true, lines });
+  if (r.error) return parentPage(cat, shop, { item, lines, name: kid.name, token, open: true, said: (await r.error.json()).message });
   await env.DB.prepare('UPDATE shop_parent_links SET order_id = ?2 WHERE hash = ?1').bind(await sha256Hex(token), r.order.id).run();
-  if (!r.reconciled && shop.capPerPlayerMonth !== null && ctx?.waitUntil) ctx.waitUntil(reconcileOrders(env, shop, row.player).catch((error) => logOrderError(env, r.order.id, error)));
+  if (!r.reconciled && ctx?.waitUntil) ctx.waitUntil(reconcileOrders(env, shop, row.player).catch((error) => logOrderError(env, r.order.id, error)));
   return Response.redirect(r.url, 303);
 }
 
-/** The game says the player used something (equipped a skin, played the pass): it is no longer refundable by the player. */
+/** Mark use for studios that choose to exclude used items from player refunds. */
 async function usedRoute(request, env, shop) {
   const b = await bodyOf(request, requestSize(shop));
   if (b.error) return b.error;
@@ -534,13 +691,20 @@ async function usedRoute(request, env, shop) {
   return json({ ok: true, used: Number(r?.meta?.changes ?? 0) });
 }
 
+async function lineWasUsed(env, order, line) {
+  if (await migrated(env)) return env.DB.prepare('SELECT 1 FROM entitlements e WHERE order_id = ?1 AND used_at IS NOT NULL AND (item = ?2 OR key IN (SELECT key FROM shop_entitlement_lines WHERE line_id = ?3)) LIMIT 1').bind(order, line.item, line.id).first();
+  return env.DB.prepare('SELECT 1 FROM entitlements WHERE order_id = ?1 AND item = ?2 AND used_at IS NOT NULL LIMIT 1').bind(order, line.item).first();
+}
+
 function refundableNow(order, owns, shop, now = Date.now()) {
   if (shop.refundDays === null || order.status !== 'paid' || order.paidAt === null) return false;
+  // A tip is a gift, not an item: a player never takes one back by themselves. The studio can still refund any order from its office.
+  if (!(order.kind ?? shop.items.find((it) => it.id === order.item)?.kind) || (order.kind ?? shop.items.find((it) => it.id === order.item)?.kind) === 'tip') return false;
   if (now - order.paidAt > Math.round(shop.refundDays * DAY)) return false;
   return shop.policy.refundUsedItems || !owns.some((o) => o.item === order.item && o.used);
 }
 
-/** A player's own refund: an unused item, within the studio's refund days (fewer disputes, and the respected norm). */
+/** A player's own refund follows the studio window and used-item setting, excluding tips. */
 async function selfRefundRoute(request, env, shop, ready) {
   const b = await bodyOf(request, requestSize(shop));
   if (b.error) return b.error;
@@ -548,11 +712,15 @@ async function selfRefundRoute(request, env, shop, ready) {
   if (!p) return fail(401, 'account', 'sign in first');
   const o = await orderById(env, b.body.order);
   if (!o || o.player !== p.id) return fail(404, 'order', 'no such order on this account');
-  const used = await env.DB.prepare('SELECT COUNT(*) AS n FROM entitlements WHERE order_id = ?1 AND used_at IS NOT NULL').bind(o.id).first();
-  if (!refundableNow(orderView(o), Number(used?.n) ? [{ item: o.item, used: true }] : [], shop)) return fail(403, 'not-refundable', shop.refundDays === null ? 'Ask the studio for a refund; it has not set a self-service refund window.' : `The studio allows self-service refunds for ${shop.policy.refundUsedItems ? 'items' : 'unused items'} within ${shop.refundDays} days. Ask the studio for anything else.`);
-  if (Number(o.amount) !== 0 && !KEY_SHAPE.test(String(env.STRIPE_KEY ?? ''))) return fail(503, 'closed', MISSING_WORDS['stripe-key']);
-  const r = await refundOrder(env, o, { reason: 'requested_by_customer', by: 'player' });
-  if (r.held) return json({ ok: false, held: true, error: 'held', message: 'The studio approves this refund in Stripe first. Your money comes back once they do, and the item leaves your account then.' }, 202);
+  const lines = (await orderLines(env, o.id)).filter((l) => !b.body.line || l.id === b.body.line);
+  if (!lines.length) return fail(404, 'line', 'no such line on this order');
+  for (const line of lines) {
+    const used = await lineWasUsed(env, o.id, line);
+    if (!refundableNow({ ...lineView(line), paidAt: o.paid_at }, used ? [{ item: line.item, used: true }] : [], shop)) return fail(403, 'not-refundable', 'Ask the studio for this refund. Tips are not refundable by the player; items follow the studio refund settings.');
+  }
+  if (Number(o.amount) !== 0 && !hasStripeKey(env)) return fail(409, 'ask-studio', 'Ask the studio to refund this payment in Stripe.');
+  const r = await refundOrder(env, o, { reason: 'requested_by_customer', by: 'player', line: b.body.line });
+  if (r.held) return json({ ...r, error: r.error === 'pending' ? 'pending' : 'held', message: r.error === 'pending' ? r.message : 'The studio approves this refund in Stripe first. Your money comes back once they do, and the item leaves your account then.' }, 202);
   return json(r, r.ok ? 200 : 502);
 }
 
@@ -560,54 +728,131 @@ async function selfRefundRoute(request, env, shop, ready) {
 
 async function hook(request, env, cat, shop, ready) {
   if (request.method !== 'POST') return fail(405, 'method', 'POST only');
-  if (Number(request.headers.get('content-length') ?? 0) > 512 * 1024) return fail(413, 'too-large', 'too large');
-  const payload = await request.text();
+  const maxBytes = Number(env.SHOP_WEBHOOK_BYTES ?? 512 * 1024);
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) return fail(503, 'setting', 'SHOP_WEBHOOK_BYTES is a positive whole number.');
+  const payload = await boundedText(request, maxBytes);
+  if (payload === null) return fail(413, 'too-large', 'The studio webhook byte limit was reached.');
   const v = await verifyWebhook(payload, request.headers.get('stripe-signature'), env.STRIPE_WEBHOOK_SECRET);
   if (!v.ok) return fail(v.why === 'no-secret' ? 503 : 400, v.why, 'not a webhook from this studio\'s Stripe');
-  if (!(await migrated(env))) return fail(503, 'not-migrated', MISSING_WORDS.migration);
   const ev = v.event;
-  // A test event never touches a live shop's books, nor a live one a test shop's.
-  if (typeof ev.livemode === 'boolean' && KEY_SHAPE.test(String(env.STRIPE_KEY ?? '')) && ev.livemode !== (modeOf(env.STRIPE_KEY) === 'live')) return json({ ok: true, ignored: 'mode' });
-  if (await env.DB.prepare('SELECT 1 AS x FROM shop_events WHERE id = ?1').bind(ev.id).first()) return json({ ok: true, duplicate: true });
   const obj = ev.data?.object ?? {};
-  let did = 'ignored';
-  switch (ev.type) {
-    case 'checkout.session.completed':
-    case 'checkout.session.async_payment_succeeded':
-      if (ev.type === 'checkout.session.async_payment_succeeded' || obj.payment_status === 'paid' || obj.payment_status === 'no_payment_required') did = await paid(env, shop, obj);
-      else {
-        await env.DB.prepare("UPDATE shop_orders SET status = 'processing', updated_at = ?2 WHERE session = ?1 AND status = 'started'").bind(String(obj.id ?? ''), Date.now()).run();
-        did = 'waiting';
-      }
-      break;
-    case 'checkout.session.async_payment_failed':
-    case 'checkout.session.expired':
-      await env.DB.prepare('UPDATE shop_orders SET status = ?2, updated_at = ?3 WHERE session = ?1 AND status IN (\'started\', \'processing\', \'missing\', \'released\')').bind(String(obj.id ?? ''), ev.type.endsWith('expired') ? 'expired' : 'failed', Date.now()).run();
-      did = 'closed';
-      break;
-    case 'charge.refunded':
-      if (obj.refunded === true || Number(obj.amount_refunded) >= Number(obj.amount)) did = await refunded(env, String(obj.payment_intent ?? ''), null);
-      break;
-    case 'refund.created':
-    case 'refund.updated':
-      // Individual refunds may be partial. charge.refunded supplies the cumulative full-refund truth.
-      if (obj.status === 'succeeded') {
-        const order = await orderByPayment(env, String(obj.payment_intent ?? ''));
-        if (order && Number(obj.amount) >= Number(order.total ?? order.amount)) did = await refunded(env, String(obj.payment_intent ?? ''), String(obj.id ?? ''));
+  const needed = ['checkout.session.completed', 'checkout.session.async_payment_succeeded', 'checkout.session.async_payment_failed', 'checkout.session.expired', 'charge.refunded', 'refund.created', 'refund.updated', 'refund.failed', 'charge.dispute.created', 'charge.dispute.closed'];
+  if (!needed.includes(ev.type)) return json({ ok: true, did: 'ignored' });
+  if (typeof ev.livemode === 'boolean' && (hasStripeKey(env) || linkConfig(env)) && ev.livemode !== (shopMode(env) === 'live')) return json({ ok: true, ignored: 'mode' });
+  try {
+    const sessionEvent = ev.type.startsWith('checkout.session.');
+    if (!sessionEvent) await rememberMoneyEvent(env, ev);
+    if (sessionEvent && obj.payment_link && !(await bindLinkSession(env, obj, ev.livemode ? 'live' : 'test'))) return json({ ok: true, did: 'mismatch' });
+    let known = sessionEvent ? await orderBySession(env, obj.id) : await orderByPayment(env, String(obj.payment_intent ?? ''));
+    if (!known) {
+      let metadata = obj.metadata;
+      let named = metadata?.order ? await orderById(env, metadata.order) : null;
+      // Charge metadata identifies foreign sales without a provider read. Untagged refunds/disputes
+      // need their PaymentIntent only when this database actually has an unrecorded payment.
+      if (hasStripeKey(env) && !named && !sessionEvent && obj.payment_intent && !metadata?.order &&
+          (!metadata?.homie || metadata.homie === 'shop-v1') && (!metadata?.origin || metadata.origin === new URL(request.url).origin) &&
+          await env.DB.prepare('SELECT 1 FROM shop_orders WHERE payment IS NULL AND paid_at IS NULL AND mode = ?1 LIMIT 1').bind(shopMode(env)).first()) {
+        let payment;
+        try { payment = await stripeCall(env, 'GET', `/v1/payment_intents/${encodeURIComponent(obj.payment_intent)}`); }
+        catch (error) {
+          if (error instanceof StripeError && error.status === 404 && error.code === 'resource_missing') return json({ ok: true, did: 'ignored' });
+          throw error;
+        }
+        metadata = payment.metadata;
+        named = metadata?.order ? await orderById(env, metadata.order) : null;
       }
-      break;
-    case 'charge.dispute.created':
-      did = await disputed(env, String(obj.payment_intent ?? ''), String(obj.id ?? ''));
-      break;
-    case 'charge.dispute.closed':
-      did = await disputeClosed(env, String(obj.payment_intent ?? ''), String(obj.status ?? ''));
-      break;
-    default:
-      break;
+      if (!named) return json({ ok: true, did: !sessionEvent && !hasStripeKey(env) ? 'remembered' : 'ignored' });
+      if (!hasStripeKey(env) && !sessionEvent) return json({ ok: true, did: 'remembered' });
+      if (sessionEvent) return fail(503, 'unknown-order', 'Payment order is not recorded yet; retry this event.');
+      if (!(await migrated(env))) return fail(503, 'not-migrated', MISSING_WORDS.migration);
+      if (named.payment || named.mode !== shopMode(env)) return json({ ok: true, did: 'ignored' });
+      if (!named.session) return fail(503, 'unknown-order', 'Payment order is not recorded yet; retry this event.');
+      const session = await stripeCall(env, 'GET', `/v1/checkout/sessions/${encodeURIComponent(named.session)}`, { expand: ['payment_intent.latest_charge'] });
+      if (session.id !== named.session || !['paid', 'no_payment_required'].includes(session.payment_status)) return fail(503, 'unknown-order', 'Payment order is not recorded yet; retry this event.');
+      if ((session.payment_intent?.id ?? session.payment_intent) !== obj.payment_intent) return json({ ok: true, did: 'ignored' });
+      await paid(env, shop, session, (session.payment_intent?.latest_charge?.created ?? session.created) * 1000);
+      known = await orderByPayment(env, obj.payment_intent);
+      if (!known) return fail(503, 'unknown-order', 'Payment order is not recorded yet; retry this event.');
+    }
+    if (!(await migrated(env))) return fail(503, 'not-migrated', MISSING_WORDS.migration);
+    if (await env.DB.prepare('SELECT 1 AS x FROM shop_events WHERE id = ?1').bind(ev.id).first()) {
+      if (['checkout.session.completed', 'checkout.session.async_payment_succeeded'].includes(ev.type) && ['paid', 'no_payment_required'].includes(ev.data?.object?.payment_status)) await paid(env, shop, ev.data.object);
+      return json({ ok: true, duplicate: true });
+    }
+    let did = 'ignored';
+    switch (ev.type) {
+      case 'checkout.session.completed':
+      case 'checkout.session.async_payment_succeeded':
+        if (ev.type === 'checkout.session.async_payment_succeeded' || obj.payment_status === 'paid' || obj.payment_status === 'no_payment_required') did = await paid(env, shop, obj);
+        else {
+          await env.DB.prepare("UPDATE shop_orders SET status = 'processing', updated_at = ?2 WHERE session = ?1 AND status = 'started'").bind(String(obj.id ?? ''), Date.now()).run();
+          did = 'waiting';
+        }
+        break;
+      case 'checkout.session.async_payment_failed':
+      case 'checkout.session.expired':
+        await env.DB.prepare('UPDATE shop_orders SET status = ?2, updated_at = ?3 WHERE session = ?1 AND status IN (\'started\', \'processing\', \'missing\', \'released\')').bind(String(obj.id ?? ''), ev.type.endsWith('expired') ? 'expired' : 'failed', Date.now()).run();
+        did = 'closed';
+        break;
+      case 'charge.refunded':
+      case 'refund.created':
+      case 'refund.updated':
+      case 'refund.failed':
+        did = await syncRefunds(env, String(obj.payment_intent ?? ''));
+        break;
+      case 'charge.dispute.created':
+        did = await disputed(env, String(obj.payment_intent ?? ''), String(obj.id ?? ''));
+        if (!hasStripeKey(env)) for (const d of await rememberedMoney(env, obj.payment_intent, known.mode)) if (d.id === obj.id && ['lost', 'won', 'warning_closed'].includes(d.status)) did = await disputeClosed(env, obj.payment_intent, d.status);
+        break;
+      case 'charge.dispute.closed':
+        did = await disputeClosed(env, String(obj.payment_intent ?? ''), String(obj.status ?? ''));
+        break;
+      default:
+        break;
+    }
+    if (did === 'needs-keyed-recovery') return fail(503, did, 'This earlier multi-item checkout needs its original connection to recover tax per line. Reconnect it, then resend this event.');
+    if (did === 'missing-item' || did === 'unknown-order') return fail(503, did, did === 'missing-item' ? 'Restore this order item in shop.json to grant it; the office can refund its payment.' : 'Payment order is not recorded yet; retry this event.');
+    await env.DB.prepare('INSERT INTO shop_events (id, type, at) VALUES (?1, ?2, ?3) ON CONFLICT(id) DO NOTHING').bind(ev.id, ev.type, Date.now()).run();
+    if (Math.random() < 0.02) await env.DB.prepare('DELETE FROM shop_events WHERE at < ?1').bind(Date.now() - 60 * DAY).run();
+    return json({ ok: true, did });
+  } catch (error) {
+    logOrderError(env, null, error);
+    return fail(503, 'stripe-retry', 'Payment reconciliation is temporarily unavailable; retry this event.');
   }
-  await env.DB.prepare('INSERT INTO shop_events (id, type, at) VALUES (?1, ?2, ?3) ON CONFLICT(id) DO NOTHING').bind(ev.id, ev.type, Date.now()).run();
-  if (Math.random() < 0.02) await env.DB.prepare('DELETE FROM shop_events WHERE at < ?1').bind(Date.now() - 60 * DAY).run();
-  return json({ ok: true, did });
+}
+
+/** Payment Links can be reopened. Each signed Session becomes its own order; the URL reference
+ * selects a frozen local intent, never an entitlement or a buyer-supplied price. */
+async function bindLinkSession(env, session, mode) {
+  if (!/^ord_[A-Za-z0-9]{20}$/.test(session.client_reference_id ?? '') || !/^cs_[A-Za-z0-9_]+$/.test(session.id ?? '')) return false;
+  const source = await orderById(env, session.client_reference_id);
+  if (!source || source.mode !== mode) return false;
+  const lines = await orderLines(env, source.id);
+  if (lines.length !== 1 || !lines[0].snapshot) return false;
+  const item = JSON.parse(lines[0].snapshot), link = item.paymentLink;
+  if (!link || (session.payment_link?.id ?? session.payment_link) !== link.id || session.metadata?.revision !== link.revision || session.currency !== source.currency) return false;
+  const amount = session.amount_subtotal;
+  if (!Number.isSafeInteger(amount) || amount <= 0) return false;
+  const quantity = item.price === 'choose' ? 1 : amount / item.price;
+  if (!Number.isSafeInteger(quantity) || quantity < 1 || quantity > 999999) return false;
+  if (item.price === 'choose' && (amount < item.min || item.max !== null && amount > item.max)) return false;
+  // Claim the first session atomically. A repeated URL creates a separate paid order, never loses a payment.
+  await env.DB.prepare('UPDATE shop_orders SET session = ?2 WHERE id = ?1 AND session IS NULL').bind(source.id, session.id).run();
+  let order = await orderBySession(env, session.id);
+  if (!order) {
+    const id = `ord_${(await sha256Hex(session.id)).slice(0, 20)}`;
+    await env.DB.batch([
+      env.DB.prepare("INSERT INTO shop_orders (id, player, checkout_player, item, game, amount, currency, till, mode, status, parent, via, created_at, updated_at, session, referral_terms) SELECT ?2, player, checkout_player, item, game, ?4, currency, till, mode, 'started', parent, via, ?5, ?5, ?3, referral_terms FROM shop_orders WHERE id = ?1 ON CONFLICT DO NOTHING").bind(source.id, id, session.id, amount, Date.now()),
+      env.DB.prepare('INSERT INTO shop_order_lines (id, order_id, position, item, quantity, unit_amount, amount, snapshot) VALUES (?1, ?2, 0, ?3, ?4, ?5, ?6, ?7) ON CONFLICT DO NOTHING').bind(`${id}_0`, id, item.id, quantity, amount / quantity, amount, lines[0].snapshot),
+    ]);
+    order = await orderBySession(env, session.id);
+  }
+  if (!order) return false;
+  if (order.paid_at === null) await env.DB.batch([
+    env.DB.prepare('UPDATE shop_orders SET amount = ?2 WHERE id = ?1 AND paid_at IS NULL').bind(order.id, amount),
+    env.DB.prepare('UPDATE shop_order_lines SET quantity = ?2, unit_amount = ?3, amount = ?4 WHERE order_id = ?1 AND EXISTS (SELECT 1 FROM shop_orders WHERE id = ?1 AND paid_at IS NULL)').bind(order.id, quantity, amount / quantity, amount),
+  ]);
+  return true;
 }
 
 /** A paid checkout: the order is paid, its entitlements granted, a referral line written. Idempotent. */
@@ -615,34 +860,159 @@ async function paid(env, shop, session, paidAt = Date.now()) {
   const o = await orderBySession(env, session.id);
   if (!o) return 'unknown-order';
   // The session must be the one this order opened, for this player and this price.
-  if (session.metadata?.order !== o.id || (session.client_reference_id && session.client_reference_id !== o.player)) return 'mismatch';
+  const linkOrder = (await orderLines(env, o.id)).some((l) => l.snapshot && JSON.parse(l.snapshot).paymentLink);
+  if (!linkOrder && (session.metadata?.order !== o.id || ((o.checkout_player ?? o.player) && session.client_reference_id && session.client_reference_id !== (o.checkout_player ?? o.player)))) return 'mismatch';
   if (session.currency !== o.currency || !Number.isSafeInteger(session.amount_subtotal) || session.amount_subtotal !== Number(o.amount)) return 'mismatch';
-  if (o.paid_at !== null) return 'already';
-  const item = shop.items.find((i) => i.id === o.item);
+  if (['refunded', 'lost', 'disputed'].includes(o.status)) {
+    if (o.payment) await syncRefunds(env, o.payment);
+    await env.DB.prepare('UPDATE shop_orders SET attention = 0 WHERE id = ?1').bind(o.id).run();
+    return 'already';
+  }
+  const payment = typeof session.payment_intent === 'string'
+    ? !hasStripeKey(env) ? { id: session.payment_intent } : await stripeCall(env, 'GET', `/v1/payment_intents/${encodeURIComponent(session.payment_intent)}`, { expand: ['latest_charge'] }) : session.payment_intent;
+  let dispute = null;
+  if (hasStripeKey(env) && payment?.latest_charge?.disputed) {
+    const list = await stripeCall(env, 'GET', '/v1/disputes', { payment_intent: payment.id, limit: 100 });
+    if (!Array.isArray(list.data) || !list.data.length || list.has_more) throw new Error('Stripe dispute state is unavailable');
+    dispute = list.data.find((d) => d.status === 'lost') ?? list.data[0];
+  }
+  const lines = await orderLines(env, o.id);
+  if (!lines.length) throw new Error('Order has no lines');
   const now = Date.now();
-  const res = await env.DB.prepare("UPDATE shop_orders SET status = 'paid', payment = ?2, tax = ?3, total = ?4, paid_at = ?5, updated_at = ?6 WHERE id = ?1 AND paid_at IS NULL")
-    .bind(o.id, typeof session.payment_intent === 'string' ? session.payment_intent : session.payment_intent?.id ?? null, Number.isFinite(Number(session.total_details?.amount_tax)) ? Number(session.total_details.amount_tax) : null, Number.isFinite(Number(session.amount_total)) ? Number(session.amount_total) : null, paidAt, now).run();
-  if (!Number(res?.meta?.changes ?? 1)) return 'already';
+  const total = session.amount_total ?? Number(o.amount);
+  const tax = session.total_details?.amount_tax ?? total - Number(o.amount);
+  if (!Number.isSafeInteger(total) || !Number.isSafeInteger(tax) || total < 0 || tax < 0 || total !== Number(o.amount) + tax) return 'mismatch';
+  let stripeLines = null;
+  if (lines.length > 1 && tax) {
+    if (!hasStripeKey(env)) return 'needs-keyed-recovery';
+    // Use Stripe's actual tax per line, never spread tax across products with different tax codes.
+    // https://docs.stripe.com/api/checkout/sessions/line_items
+    const response = await stripeCall(env, 'GET', `/v1/checkout/sessions/${encodeURIComponent(session.id)}/line_items`, { limit: 100, expand: ['data.price.product'] });
+    if (response.has_more || response.data?.length !== lines.length) throw new Error('Stripe line totals are incomplete');
+    stripeLines = [...response.data];
+  }
   const writes = [];
-  if (o.player && item) writes.push(...grantStatements(env, o, item, now));
-  // An item that is no longer in shop.json still reaches its buyer: the keys it gave when it was sold are not known
-  // here, so the order is paid and the office shows it for the owner to settle by hand.
-  if (o.via) writes.push(...(await lineFor(env, o, shop, { now })));
-  if (writes.length) await env.DB.batch(writes);
-  return item ? 'paid' : 'paid-unknown-item';
+  let lineTotal = 0;
+  for (const line of lines) {
+    // The database schema step creates lines for old orders. Only those lack a snapshot.
+    const item = line.snapshot ? JSON.parse(line.snapshot) : shop.items.find((i) => i.id === line.item);
+    if (!item && o.status === 'paid') { await env.DB.prepare('UPDATE shop_orders SET attention = 0 WHERE id = ?1').bind(o.id).run(); return 'already'; }
+    if (!item) {
+      await env.DB.prepare("UPDATE shop_orders SET payment = COALESCE(payment, ?2), total = ?4, tax = ?5, note = 'missing-item: restore the catalog definition to grant this paid order', updated_at = ?3 WHERE id = ?1").bind(o.id, typeof session.payment_intent === 'string' ? session.payment_intent : session.payment_intent?.id ?? null, now, total, tax).run();
+      return 'missing-item';
+    }
+    let gross = lines.length === 1 ? total : Number(line.amount);
+    if (stripeLines) {
+      const index = stripeLines.findIndex((l) => l.quantity === line.quantity && l.amount_subtotal === line.amount &&
+        (l.price?.product?.metadata?.line === line.id || item.stripeProduct && (l.price?.product?.id ?? l.price?.product) === item.stripeProduct || l.price?.product?.metadata?.homie_item === line.item || l.price?.product?.metadata?.item === line.item));
+      if (index < 0) throw new Error('Stripe line identity mismatch');
+      gross = stripeLines.splice(index, 1)[0].amount_total;
+    }
+    if (!Number.isSafeInteger(gross) || gross < line.amount) throw new Error('Invalid Stripe line total');
+    lineTotal += gross;
+    if (o.player && dispute?.status !== 'lost' && line.status !== 'refunded') writes.push(...grantStatements(env, o, item, Number(o.paid_at ?? now), line));
+    writes.push(env.DB.prepare("UPDATE shop_order_lines SET status = 'paid', total = ?2, snapshot = COALESCE(snapshot, ?3) WHERE id = ?1 AND status != 'refunded'").bind(line.id, gross, JSON.stringify(item)));
+  }
+  if (lineTotal !== total) throw new Error('Stripe line totals do not match order');
+  if (o.via && o.paid_at === null) writes.push(...(await lineFor(env, o, o.referral_terms ? { referrals: JSON.parse(o.referral_terms) } : shop, { now })));
+  writes.push(env.DB.prepare("UPDATE referral_lines SET original_share = share WHERE order_id = ?1 AND original_share IS NULL").bind(o.id));
+  writes.push(env.DB.prepare("UPDATE shop_orders SET status = 'paid', payment = ?2, tax = ?3, total = ?4, paid_at = ?5, updated_at = ?6 WHERE id = ?1 AND paid_at IS NULL")
+    .bind(o.id, typeof session.payment_intent === 'string' ? session.payment_intent : session.payment_intent?.id ?? null, tax, total, paidAt, now));
+  // D1 batch is transactional: a failure rolls back payment, every grant and the referral together.
+  // https://developers.cloudflare.com/d1/worker-api/d1-database/#batch
+  const result = await env.DB.batch(writes);
+  const paymentId = payment?.id ?? (typeof session.payment_intent === 'string' ? session.payment_intent : null);
+  if (dispute) {
+    await disputed(env, paymentId, dispute.id);
+    if (['lost', 'won', 'warning_closed'].includes(dispute.status)) await disputeClosed(env, paymentId, dispute.status);
+  }
+  if (paymentId) {
+    await syncRefunds(env, paymentId);
+    if (!hasStripeKey(env)) for (const d of await rememberedMoney(env, paymentId, o.mode)) if (d.id.startsWith('dp_')) {
+      await disputed(env, paymentId, d.id);
+      if (['lost', 'won', 'warning_closed'].includes(d.status)) await disputeClosed(env, paymentId, d.status);
+    }
+  }
+  await env.DB.prepare('UPDATE shop_orders SET attention = 0 WHERE id = ?1').bind(o.id).run();
+  return result.at(-1)?.meta?.changes ? 'paid' : 'already';
 }
 
-async function refunded(env, payment, refundId) {
-  const o = payment ? await orderByPayment(env, payment) : null;
+/** Rebuild the books from Stripe's refund IDs, never event delivery order or Charge.amount_refunded.
+ * Pending/failed refunds do not revoke goods. A failed refund reverses its earlier booking.
+ * https://docs.stripe.com/api/refunds/object#refund_object-status
+ * https://docs.stripe.com/api/refunds/list
+ */
+async function syncRefunds(env, payment, freeOrder = null, freeLines = []) {
+  const o = freeOrder ?? await orderByPayment(env, payment);
   if (!o) return 'unknown-order';
-  if (o.status === 'refunded') return 'already';
-  const now = Date.now();
-  await env.DB.batch([
-    env.DB.prepare("UPDATE shop_orders SET status = 'refunded', refund = COALESCE(?2, refund), refunded_at = ?3, updated_at = ?3 WHERE id = ?1").bind(o.id, refundId, now),
-    revokeStatement(env, o.id),
-    ...voidLineStatements(env, o.id),
-  ]);
-  return 'refunded';
+  const all = await orderLines(env, o.id);
+  const refunds = new Map();
+  let cursor;
+  if (payment && !hasStripeKey(env)) {
+    for (const r of await rememberedMoney(env, payment, o.mode)) if (r.id.startsWith('re_')) {
+      if (r.currency !== o.currency) throw new Error('Refund currency mismatch');
+      refunds.set(r.id, r);
+    }
+  }
+  if (payment && hasStripeKey(env)) do {
+    const page = await stripeCall(env, 'GET', '/v1/refunds', { payment_intent: payment, limit: 100, ...(cursor ? { starting_after: cursor } : {}) });
+    if (!Array.isArray(page.data)) throw new Error('Stripe refund list is unavailable');
+    for (const refund of page.data) refunds.set(refund.id, refund);
+    const next = page.has_more ? page.data.at(-1)?.id : null;
+    if (page.has_more && (!next || next === cursor)) throw new Error('Stripe refund list is incomplete');
+    cursor = next;
+  } while (cursor);
+  const totals = new Map(all.map((line) => [line.id, 0]));
+  let amount = 0;
+  for (const refund of refunds.values()) {
+    if (refund.status !== 'succeeded') continue;
+    if (!Number.isSafeInteger(refund.amount) || refund.amount < 0) throw new Error('Invalid Stripe refund amount');
+    amount += refund.amount;
+    if (refund.metadata?.line && totals.has(refund.metadata.line)) totals.set(refund.metadata.line, totals.get(refund.metadata.line) + refund.amount);
+  }
+  const gross = Number(o.total ?? o.amount);
+  if (!Number.isSafeInteger(amount) || amount > gross) throw new Error('Stripe refund total exceeds payment');
+  const moneyFull = amount === gross && gross > 0;
+  const whole = moneyFull && [...refunds.values()].some((r) => r.status === 'succeeded' && !r.metadata?.line);
+  const taggedGross = [...totals.values()].reduce((n, value) => n + value, 0);
+  const taggedNet = all.reduce((n, line) => n + (Number(line.total ?? line.amount) ? Number(BigInt(line.amount) * BigInt(totals.get(line.id)) / BigInt(line.total ?? line.amount)) : 0), 0);
+  const net = moneyFull ? Number(o.amount) : taggedNet + (gross > taggedGross ? Number(BigInt(Number(o.amount) - taggedNet) * BigInt(amount - taggedGross) / BigInt(gross - taggedGross)) : 0);
+  const revision = Number(o.refund_revision);
+  const guard = `EXISTS (SELECT 1 FROM shop_orders WHERE id = ?1 AND refund_revision = ?2 AND (status != 'lost' OR ${o.status === 'lost' ? 1 : 0}))`;
+  const writes = [];
+  let changed = Number(o.refunded_amount) !== amount || Number(o.refunded_net) !== net;
+  let full = true;
+  for (const line of all) {
+    // A completed whole-order refund (including earlier partial refunds) names every line.
+    // Untagged partial refunds remain solely on the order: no invented item allocation.
+    const target = whole ? Number(line.total ?? line.amount) : totals.get(line.id);
+    if (target > Number(line.total ?? line.amount)) throw new Error('Stripe line refund exceeds line payment');
+    const lineNet = line.total || line.amount ? Number(BigInt(line.amount) * BigInt(target) / BigInt(line.total ?? line.amount)) : 0;
+    const localFree = Number(line.total ?? line.amount) === 0 && (freeLines.includes(line.id) || line.refund === 'local-free');
+    const revoked = whole || localFree || target > 0 && target === Number(line.total ?? line.amount);
+    full &&= revoked;
+    changed ||= Number(line.refunded_amount) !== target || Number(line.refunded_net) !== lineNet || (line.status === 'refunded') !== revoked || localFree && line.refund !== 'local-free';
+    writes.push(env.DB.prepare(`UPDATE shop_order_lines SET refund = CASE WHEN ?8 THEN 'local-free' ELSE refund END, refunded_amount = ?4, refunded_net = ?5, status = CASE WHEN ?6 THEN 'refunded' WHEN status = 'refunded' THEN 'paid' ELSE status END, refunded_at = CASE WHEN ?6 THEN COALESCE(refunded_at, ?7) ELSE NULL END WHERE order_id = ?1 AND id = ?3 AND ${guard}`).bind(o.id, revision, line.id, target, lineNet, revoked ? 1 : 0, Date.now(), localFree ? 1 : 0));
+    writes.push(env.DB.prepare(`UPDATE shop_entitlement_lines SET state = ?4 WHERE order_id = ?1 AND line_id = ?3 AND ${guard}`).bind(o.id, revision, line.id, revoked || o.status === 'lost' ? 'revoked' : 'active'));
+  }
+  writes.push(env.DB.prepare(`UPDATE entitlements SET state = CASE WHEN ?3 OR ?4 OR EXISTS (SELECT 1 FROM shop_entitlement_lines WHERE order_id = ?1 AND key = entitlements.key) AND NOT EXISTS (SELECT 1 FROM shop_entitlement_lines WHERE order_id = ?1 AND key = entitlements.key AND state = 'active') THEN 'revoked' ELSE 'active' END WHERE order_id = ?1 AND ${guard}`).bind(o.id, revision, full ? 1 : 0, o.status === 'lost' ? 1 : 0));
+  writes.push(env.DB.prepare(`UPDATE entitlements SET starts_at = (SELECT MIN(starts_at) FROM shop_entitlement_lines l WHERE l.order_id = ?1 AND l.key = entitlements.key AND l.state = 'active'), ends_at = CASE WHEN EXISTS (SELECT 1 FROM shop_entitlement_lines l WHERE l.order_id = ?1 AND l.key = entitlements.key AND l.state = 'active' AND l.ends_at IS NULL) THEN NULL ELSE (SELECT MAX(ends_at) FROM shop_entitlement_lines l WHERE l.order_id = ?1 AND l.key = entitlements.key AND l.state = 'active') END WHERE order_id = ?1 AND ${guard} AND EXISTS (SELECT 1 FROM shop_entitlement_lines l WHERE l.order_id = ?1 AND l.key = entitlements.key AND l.state = 'active')`).bind(o.id, revision));
+  const referral = await env.DB.prepare('SELECT * FROM referral_lines WHERE order_id = ?1').bind(o.id).first();
+  if (referral && o.status !== 'lost') {
+    const share = Number(referral.original_share ?? referral.share);
+    const remaining = o.amount ? Number((2n * BigInt(share) * BigInt(Number(o.amount) - net) + BigInt(o.amount)) / (2n * BigInt(o.amount))) : 0;
+    changed ||= Number(referral.share) !== remaining || Number(referral.net) !== Number(o.amount) - net || (referral.state === 'void') !== (remaining === 0) && referral.state !== 'settled';
+    const delta = Number(referral.share) - remaining;
+    writes.push(env.DB.prepare(`INSERT INTO referral_lines (order_id, via, net, rate, share, original_share, currency, state, period, hold_until, created_at) SELECT ?3, via, ?4, rate, ?5, ?5, currency, 'clawback', period, hold_until, ?6 FROM referral_lines WHERE order_id = ?1 AND state = 'settled' AND ${guard} AND ?5 != 0 ON CONFLICT DO NOTHING`).bind(o.id, revision, `${o.id}_refund_${revision}`, net - Number(o.refunded_net), delta, Date.now()));
+    writes.push(env.DB.prepare(`UPDATE referral_lines SET share = ?3, net = ?4, state = CASE WHEN state = 'settled' THEN state WHEN ?3 = 0 THEN 'void' WHEN state = 'void' THEN 'pending' ELSE state END WHERE order_id = ?1 AND ${guard}`).bind(o.id, revision, remaining, Number(o.amount) - net));
+  }
+  full &&= o.status !== 'lost';
+  changed ||= (o.status === 'refunded') !== full;
+  if (!changed) return 'already';
+  writes.push(env.DB.prepare(`UPDATE shop_orders SET refunded_amount = ?3, refunded_net = ?4, status = CASE WHEN ?5 THEN 'refunded' WHEN status = 'refunded' THEN 'paid' ELSE status END, refunded_at = CASE WHEN ?5 THEN COALESCE(refunded_at, ?6) ELSE NULL END, refund_revision = refund_revision + 1 WHERE id = ?1 AND ${guard}`).bind(o.id, revision, amount, net, full ? 1 : 0, Date.now()));
+  const result = await env.DB.batch(writes);
+  if (!result.at(-1)?.meta?.changes) return syncRefunds(env, payment, freeOrder ? await orderById(env, o.id) : null, freeLines);
+  return o.refunded_amount === amount && o.status === (full ? 'refunded' : o.status) ? 'already' : 'refunded';
 }
 
 /** A dispute changes nothing until it is decided: the player keeps the item and their account. */
@@ -658,9 +1028,11 @@ async function disputeClosed(env, payment, status) {
   const o = payment ? await orderByPayment(env, payment) : null;
   if (!o) return 'unknown-order';
   const now = Date.now();
+  if (!['paid', 'disputed'].includes(o.status)) return 'already';
   if (status === 'lost') {
     await env.DB.batch([
-      env.DB.prepare("UPDATE shop_orders SET status = 'lost', updated_at = ?2 WHERE id = ?1").bind(o.id, now),
+      env.DB.prepare("UPDATE shop_orders SET status = 'lost', updated_at = ?2 WHERE id = ?1 AND status IN ('paid', 'disputed')").bind(o.id, now),
+      env.DB.prepare("UPDATE shop_order_lines SET status = 'lost' WHERE order_id = ?1 AND status != 'refunded' AND EXISTS (SELECT 1 FROM shop_orders WHERE id = ?1 AND status = 'lost')").bind(o.id),
       revokeStatement(env, o.id),
       ...voidLineStatements(env, o.id),
     ]);
@@ -668,6 +1040,7 @@ async function disputeClosed(env, payment, status) {
   }
   await env.DB.batch([
     env.DB.prepare("UPDATE shop_orders SET status = 'paid', updated_at = ?2 WHERE id = ?1 AND status = 'disputed'").bind(o.id, now),
+    env.DB.prepare("UPDATE shop_order_lines SET status = 'paid' WHERE order_id = ?1 AND status = 'disputed' AND EXISTS (SELECT 1 FROM shop_orders WHERE id = ?1 AND status = 'paid')").bind(o.id),
     restoreStatement(env, o.id),
   ]);
   return 'kept';
@@ -676,31 +1049,53 @@ async function disputeClosed(env, payment, status) {
 /** What the owner reads when Stripe holds a refund for approval (the shop's key is an Agent key). */
 export const REFUND_HELD = 'Stripe is holding this refund until a person approves it in Stripe (Settings, Approvals, Requests): the shop\'s Stripe key is marked as an Agent key, and Stripe asks a person before an agent\'s refund. Approve it there; Stripe then refunds, and the item leaves the player\'s account when Stripe says so. To refund with one tap again, connect the shop with a plain restricted key (homie-studio shop connect), not one made for "Authorizing agent access".';
 
-/** Refund one order in full with Stripe, then take back that one item. The webhook confirms the same (idempotent). */
-export async function refundOrder(env, o, { reason = 'requested_by_customer', by = 'owner' } = {}) {
-  if (o.status !== 'paid') return { ok: false, error: 'state', message: o.status === 'disputed' ? 'This order is disputed: the card network decides it now (answer it in Stripe).' : `This order is ${o.status}, not paid.` };
-  if (Number(o.amount) === 0) {
-    const now = Date.now();
-    await env.DB.batch([env.DB.prepare("UPDATE shop_orders SET status = 'refunded', refunded_at = ?2, updated_at = ?2 WHERE id = ?1 AND status = 'paid'").bind(o.id, now), revokeStatement(env, o.id), ...voidLineStatements(env, o.id)]);
-    return { ok: true, order: o.id, amount: 0, currency: o.currency, status: 'succeeded', refund: null };
-  }
-  if (!o.payment) return { ok: false, error: 'no-payment', message: 'Stripe has not said which payment this was yet; try again in a minute.' };
+/** Refund selected lines through Stripe, revoking each only after success. */
+export async function refundOrder(env, o, { reason = 'requested_by_customer', by = 'owner', line: lineId = null } = {}) {
+  if (o.status !== 'paid' && !(o.payment && ['started', 'processing', 'missing', 'released', 'expired', 'failed'].includes(o.status))) return { ok: false, error: 'state', message: `This order is ${o.status}.` };
+  const lines = (await orderLines(env, o.id)).filter((l) => !lineId || l.id === lineId);
+  if (!lines.length) return { ok: false, error: 'line', message: 'No such order line.' };
+  const legacy = Boolean(await migrationNeeded(env));
+  // One whole-order refund asks Stripe for the charge's remaining balance. Stripe arbitrates concurrent
+  // line/whole refunds; this keeps even 100-line carts within the Worker's subrequest budget.
+  // https://docs.stripe.com/api/refunds/create#create_refund-amount
+  const selected = lines.filter((l) => l.status !== 'refunded');
+  if (!selected.length) return { ok: true, order: o.id, line: lineId, amount: 0, currency: o.currency, status: 'succeeded' };
+  const amount = selected.reduce((sum, l) => sum + Number(l.total ?? l.amount) - Number(l.refunded_amount ?? 0), 0);
   let refund = null;
-  try {
-    refund = await createRefund(env, { payment_intent: o.payment, reason: ['duplicate', 'fraudulent', 'requested_by_customer'].includes(reason) ? reason : 'requested_by_customer', metadata: { order: o.id, by } }, { idempotencyKey: `refund-${o.id}` });
-  } catch (error) {
-    // An Agent-tagged key: Stripe holds an agent's refund for a person's approval. Nothing happened yet; once someone
-    // approves it in Stripe, Stripe refunds and the webhook (refund.created, charge.refunded) takes the item back.
-    if (isApprovalRequired(error)) return { ok: false, error: 'approval', held: true, message: REFUND_HELD };
-    return { ok: false, error: 'stripe', message: `Stripe did not refund it (${error instanceof StripeError ? error.message : 'no answer'}). Nothing changed.` };
+  if (amount) {
+    if (!hasStripeKey(env)) return { ok: false, error: 'stripe-dashboard', message: 'Refund in your Stripe Dashboard or ask your AI connected to Stripe. The signed refund event updates this shop.', url: dashboardLink(o.mode, 'payment', o.payment) };
+    if (!o.payment) return { ok: false, error: 'no-payment', message: 'Stripe has not confirmed the payment yet.' };
+    try {
+      const prior = lineId ? selected[0].refund : legacy ? o.refund : o.whole_refund;
+      refund = prior ? await stripeCall(env, 'GET', `/v1/refunds/${encodeURIComponent(prior)}`) : null;
+      if (!refund || ['failed', 'canceled'].includes(refund.status)) {
+        refund = await createRefund(env, { payment_intent: o.payment, ...(lineId ? { amount } : {}),
+          reason: ['duplicate', 'fraudulent', 'requested_by_customer'].includes(reason) ? reason : 'requested_by_customer',
+          metadata: { order: o.id, ...(lineId ? { line: lineId } : {}), by } },
+          { idempotencyKey: `refund-${lineId ?? o.id}${lineId && selected[0].refunded_amount ? '-' + selected[0].refunded_amount : ''}${refund ? '-' + refund.id : ''}` });
+      }
+      if (typeof refund?.id === 'string') {
+        if (lineId && !legacy) await env.DB.prepare('UPDATE shop_order_lines SET refund = ?2 WHERE id = ?1').bind(lineId, refund.id).run();
+        else await env.DB.prepare(legacy ? 'UPDATE shop_orders SET refund = ?2 WHERE id = ?1' : 'UPDATE shop_orders SET whole_refund = ?2 WHERE id = ?1').bind(o.id, refund.id).run();
+      }
+    } catch (error) {
+      if (isApprovalRequired(error)) return { ok: false, error: 'approval', held: true, message: REFUND_HELD };
+      return { ok: false, error: 'stripe', message: `Stripe did not refund this order (${error instanceof StripeError ? redactStripe(error.message, env) : 'no answer'}).` };
+    }
+    if (!legacy) {
+      try { await syncRefunds(env, o.payment); }
+      catch (error) { logOrderError(env, o.id, error); return { ok: false, error: 'stripe-retry', message: 'Stripe accepted the refund; its books will be reconciled on retry.' }; }
+    }
+    if (refund?.status !== 'succeeded') return { ok: false, held: true, error: 'pending', message: 'Stripe has not completed this refund yet.' };
   }
-  const now = Date.now();
-  await env.DB.batch([
-    env.DB.prepare("UPDATE shop_orders SET status = 'refunded', refund = ?2, refunded_at = ?3, updated_at = ?3 WHERE id = ?1 AND status = 'paid'").bind(o.id, String(refund?.id ?? ''), now),
-    revokeStatement(env, o.id),
-    ...voidLineStatements(env, o.id),
-  ]);
-  return { ok: true, order: o.id, refund: refund?.id ?? null, status: refund?.status ?? null, amount: Number(o.amount), currency: o.currency };
+  if (legacy) {
+    await env.DB.batch([
+      revokeStatement(env, o.id), ...voidLineStatements(env, o.id),
+      env.DB.prepare("UPDATE shop_orders SET status = 'refunded', refund = ?2, refunded_at = ?3, updated_at = ?3 WHERE id = ?1").bind(o.id, refund?.id ?? null, Date.now()),
+    ]);
+  } else if (!amount) await syncRefunds(env, o.payment, o.payment ? null : o, selected.map((line) => line.id));
+
+  return { ok: true, order: o.id, line: lineId, amount: refund?.amount ?? amount, currency: o.currency, status: 'succeeded' };
 }
 
 /* ------------------------------------------------------------------ the office (worker/office.mjs calls these) */
@@ -709,21 +1104,28 @@ export async function refundOrder(env, o, { reason = 'requested_by_customer', by
 export function checkRefund(body) {
   if (!/^ord_[A-Za-z0-9]{20}$/.test(String(body.order ?? ''))) return { ok: false, error: 'bad-request', message: 'order is the order\'s id (ord_…, from the office\'s shop page or `homie-studio shop orders`)' };
   const reason = ['duplicate', 'fraudulent', 'requested_by_customer'].includes(body.reason) ? body.reason : 'requested_by_customer';
-  const note = String(body.note ?? '').replace(/[\u0000-\u001f\u007f-\u009f]+/g, ' ').trim().slice(0, 140) || null;
-  return { ok: true, action: { op: 'refund', order: body.order, reason, note } };
+  const note = String(body.note ?? '').replace(/[\u0000-\u001f\u007f-\u009f]+/g, ' ').trim() || null;
+  return { ok: true, action: { op: 'refund', order: body.order, line: typeof body.line === 'string' ? body.line : null, reason, note } };
 }
 /** Explicit owner override of an unresolved reservation; the existing note records its actor and time. */
 export function checkRelease(body) {
   const checked = checkRefund(body);
   return checked.ok ? { ok: true, action: { op: 'shop-release', order: body.order } } : checked;
 }
-export async function performRelease(env, a) {
+export async function performRelease(env, a, cat) {
+  if (!hasStripeKey(env)) return { ok: false, error: 'stripe-dashboard', message: 'Stripe controls this checkout’s lifetime. Ask your connected AI to expire it in Stripe if needed.' };
   const row = await orderById(env, a.order);
   if (!row || !['started', 'processing'].includes(row.status)) return { ok: false, error: 'state', message: 'Only an unresolved order can be released.' };
   // https://docs.stripe.com/api/checkout/sessions/expire — only open sessions can expire.
   if (row.session) {
     try {
-      const session = await stripeCall(env, 'GET', `/v1/checkout/sessions/${encodeURIComponent(row.session)}`, null, { timeout: 2000 });
+      let session = await stripeCall(env, 'GET', `/v1/checkout/sessions/${encodeURIComponent(row.session)}`, { expand: ['payment_intent.latest_charge'] }, { timeout: 2000 });
+      if (session?.id === row.session && ['paid', 'no_payment_required'].includes(session.payment_status)) {
+        let result;
+        try { result = await paid(env, shopOf(cat), session, (session.payment_intent?.latest_charge?.created ?? session.created ?? Math.floor(Date.now() / 1000)) * 1000); }
+        catch (error) { logOrderError(env, row.id, error); return { ok: false, error: 'stripe-retry', message: 'The paid order could not be granted yet; retry before releasing it.' }; }
+        return ['paid', 'already'].includes(result) ? { ok: true, order: row.id, status: 'paid' } : { ok: false, error: result, message: 'The payment must be reconciled before releasing this order.' };
+      }
       if (session?.id === row.session && session.status === 'open') await expireCheckoutSession(env, row.session, { timeout: 2000 });
     } catch (error) { logOrderError(env, row.id, error); }
   }
@@ -736,7 +1138,7 @@ export async function performRelease(env, a) {
 export function checkSettle(body) {
   if (!/^[a-z0-9.-]{3,253}$/.test(String(body.via ?? ''))) return { ok: false, error: 'bad-request', message: 'via is the referrer\'s host (as the shop page shows it)' };
   if (!/^[a-z]{3}$/.test(body.currency ?? '')) return { ok: false, error: 'currency', message: 'Choose the currency to mark paid.' };
-  return { ok: true, action: { op: 'shop-settle', currency: body.currency, via: String(body.via), ref: String(body.ref ?? '').slice(0, 80) } };
+  return { ok: true, action: { op: 'shop-settle', currency: body.currency, via: String(body.via), ref: String(body.ref ?? '') } };
 }
 
 /** The refund in plain words, for the owner's confirm page and the AI's card. */
@@ -744,14 +1146,23 @@ export function describeRefund(cat, a, order = null) {
   const shop = shopOf(cat);
   const name = shop?.items.find((i) => i.id === order?.item)?.name ?? order?.item ?? 'an item';
   const what = order ? `${name}, ${money(order.amount, order.currency)}` : a.order;
-  return `Refund order ${a.order} (${what}) in full with Stripe: the buyer gets their money back in 5 to 10 days and the item leaves their account. ${a.note ? `Why: "${a.note}".` : ''}`.trim();
+  return `Refund ${a.line ? `line ${a.line} of order` : 'order'} ${a.order} (${what}) with Stripe: the buyer gets their money back in 5 to 10 days and the item leaves their account. ${a.note ? `Why: "${a.note}".` : ''}`.trim();
 }
 
 /** Do the refund (the owner's tap, or the owner's yes to the AI's ask). */
 export async function performRefund(env, cat, a) {
-  const o = await orderById(env, a.order);
+  let o = await orderById(env, a.order);
   if (!o) return { ok: false, error: 'order', message: 'No such order.' };
-  return refundOrder(env, o, { reason: a.reason, by: 'owner' });
+  if (hasStripeKey(env) && !o.payment && o.session && o.paid_at === null && !(await migrationNeeded(env))) {
+    try {
+      const session = await stripeCall(env, 'GET', `/v1/checkout/sessions/${encodeURIComponent(o.session)}`, { expand: ['payment_intent.latest_charge'] }, { timeout: 2000 });
+      if (session?.id === o.session && (session.livemode === undefined || session.livemode === (o.mode === 'live')) && ['paid', 'no_payment_required'].includes(session.payment_status)) {
+        await paid(env, shopOf(cat), session, (session.payment_intent?.latest_charge?.created ?? session.created ?? Math.floor(Date.now() / 1000)) * 1000);
+        o = await orderById(env, a.order);
+      }
+    } catch (error) { return { ok: false, error: 'stripe', message: redactStripe(error.message, env) }; }
+  }
+  return refundOrder(env, o, { reason: a.reason, by: 'owner', line: a.line });
 }
 
 /** Everything the office's shop page shows. Money is read from this studio's D1; Stripe's own pages are linked. */
@@ -761,29 +1172,33 @@ export async function shopOffice(env, cat, origin, cursor = '', itemCursor = 0,
   const mode = ready.mode ?? 'test';
   const out = {
     ok: true, ready: ready.ready, missing: ready.missing.map((m) => ({ id: m, words: m === 'migration' ? `The shop needs ${ready.migration}; npm run deploy applies it.` : MISSING_WORDS[m] ?? m })), mode: ready.mode,
-    shop: shop ? { policy: shop.policy, purchaseAttemptsPerMinute: shop.purchaseAttemptsPerMinute, till: shop.till, currency: shop.currency, refundDays: shop.refundDays, cap: shop.capPerPlayerMonth, nextItemsCursor: itemCursor + 100 < shop.items.length ? String(itemCursor + 100) : null, items: shop.items.slice(itemCursor, itemCursor + 100).map((i) => ({ id: i.id, kind: i.kind, name: i.name, price: i.price, shown: i.kind === 'tip' ? `${money(i.min, shop.currency)}+` : money(i.price, shop.currency), gives: i.gives, game: i.game ?? null })), referrals: shop.referrals, ...(shop.broken ? { broken: shop.broken } : {}) } : null,
+    shop: shop ? { policy: shop.policy, purchaseAttemptsPerMinute: shop.purchaseAttemptsPerMinute, till: shop.till, currency: shop.currency, refundDays: shop.refundDays, cap: shop.capPerPlayerMonth, nextItemsCursor: itemCursor + 100 < shop.items.length ? String(itemCursor + 100) : null, items: shop.items.slice(itemCursor, itemCursor + 100).map((i) => ({ id: i.id, kind: i.kind, name: i.name, price: i.price, shown: i.price === 'choose' ? `${money(i.min, shop.currency)}+` : money(i.price, shop.currency), gives: i.gives, game: i.game ?? null })), referrals: shop.referrals, ...(shop.broken ? { broken: shop.broken } : {}) } : null,
     stripe: {
       payments: dashboardLink(mode, 'payments'), refunds: dashboardLink(mode, 'refunds'), disputes: dashboardLink(mode, 'disputes'), payouts: dashboardLink(mode, 'payouts'),
       balance: dashboardLink(mode, 'balance'), tax: dashboardLink(mode, 'tax'), keys: dashboardLink(mode, 'keys'), webhooks: dashboardLink(mode, 'webhooks'),
       ...(shop?.till === 'stripe-managed' ? { managedPayments: dashboardLink(mode, 'managed-payments') } : {}),
     },
+    keyless: !hasStripeKey(env),
     hook: `${origin}/api/shop/hook`,
     totals: null, orders: [], referrals: { owe: [], owedToUs: [] },
   };
-  if (!(await migrated(env))) return out;
+  if (!(await migrated(env, { complete: false }))) return out;
   const since = Date.now() - 30 * DAY;
   const t = await env.DB.prepare("SELECT SUM(CASE WHEN status IN ('paid', 'disputed') THEN amount ELSE 0 END) AS paid, SUM(CASE WHEN status IN ('paid', 'disputed') THEN 1 ELSE 0 END) AS sales, SUM(CASE WHEN status = 'refunded' THEN amount ELSE 0 END) AS refunded, SUM(CASE WHEN status = 'refunded' THEN 1 ELSE 0 END) AS refunds, SUM(CASE WHEN status = 'disputed' THEN 1 ELSE 0 END) AS disputes, SUM(CASE WHEN status = 'lost' THEN 1 ELSE 0 END) AS lost FROM shop_orders WHERE created_at >= ?1").bind(since).first();
   out.totals = { days: 30, currency: shop?.currency ?? 'usd', paid: Number(t?.paid) || 0, sales: Number(t?.sales) || 0, refunded: Number(t?.refunded) || 0, refunds: Number(t?.refunds) || 0, disputes: Number(t?.disputes) || 0, lost: Number(t?.lost) || 0 };
   const rows = (await env.DB.prepare("SELECT o.*, p.name AS player_name FROM shop_orders o LEFT JOIN players p ON p.id = o.player ORDER BY CASE WHEN o.status IN ('started', 'processing') THEN 0 ELSE 1 END, o.created_at DESC, o.id LIMIT 101 OFFSET ?1").bind(orderCursor).all()).results ?? [];
+  const partial = ready.migration ? null : await env.DB.prepare("SELECT COALESCE(SUM(refunded_net), 0) AS amount, COUNT(*) AS orders FROM shop_orders WHERE created_at >= ?1 AND status IN ('paid', 'disputed') AND refunded_net > 0").bind(since).first();
+  out.totals.paid -= Number(partial?.amount ?? 0); out.totals.refunded += Number(partial?.amount ?? 0); out.totals.refunds += Number(partial?.orders ?? 0);
   out.nextOrdersCursor = rows.length > 100 ? String(orderCursor + 100) : null;
   if (rows.length > 100) rows.pop();
   const names = new Map((shop?.items ?? []).map((i) => [i.id, i.name]));
-  out.orders = rows.map((r) => ({
+  out.orders = await Promise.all(rows.map(async (r) => ({
+    lines: (await orderLines(env, r.id)).map((line) => { const view = lineView(line); return { ...view, name: line.snapshot ? view.name : names.get(line.item) ?? view.name }; }),
     ...orderView(r), note: r.note ?? null, name: names.get(r.item) ?? r.item, shown: money(r.amount, r.currency), player: r.player ? { id: r.player, name: r.player_name ?? null } : null,
     stripe: r.payment ? dashboardLink(r.mode, 'payment', r.payment) : null, dispute: r.dispute ? dashboardLink(r.mode, 'dispute', r.dispute) : null,
-    releasable: ['started', 'processing'].includes(r.status),
-    refundable: r.status === 'paid' && (Number(r.amount) === 0 || Boolean(r.payment)),
-  }));
+    releasable: hasStripeKey(env) && ['started', 'processing'].includes(r.status),
+    refundable: (Number(r.amount) === 0 || hasStripeKey(env)) && ['paid', 'started', 'processing', 'missing', 'released', 'expired', 'failed'].includes(r.status) && (Number(r.amount) === 0 || Boolean(r.payment) || Boolean(r.session)),
+  })));
   const { books, nextCursor } = await booksOf(env, { cursor });
   out.referrals = { nextCursor, owe: books, failures: await statementFailures(env), owedToUs: await statementsIn(env), invoice: dashboardLink(mode, 'invoices') };
   return out;
@@ -793,9 +1208,9 @@ export async function shopOffice(env, cat, origin, cursor = '', itemCursor = 0,
 export async function ordersCsv(env) {
   const rows = (await env.DB.prepare("SELECT * FROM shop_orders WHERE status != 'started' ORDER BY created_at").all()).results ?? [];
   const cell = (v) => { const s = v === null || v === undefined ? '' : String(v); return /[",\n]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s; };
-  const head = ['order', 'created', 'paid', 'refunded', 'status', 'item', 'game', 'amount', 'tax', 'total', 'currency', 'till', 'mode', 'parent', 'via', 'stripe_payment', 'stripe_refund', 'stripe_dispute'];
+  const head = ['order', 'created', 'paid', 'refunded', 'status', 'item', 'game', 'amount', 'tax', 'total', 'currency', 'till', 'mode', 'parent', 'via', 'stripe_payment', 'stripe_refund', 'stripe_dispute', 'lines_json', 'refunded_total', 'refunded_net'];
   const iso = (t) => (t ? new Date(Number(t)).toISOString() : '');
-  const lines = rows.map((r) => [r.id, iso(r.created_at), iso(r.paid_at), iso(r.refunded_at), r.status, r.item, r.game, (Number(r.amount) / currencyScale(r.currency)).toFixed(Math.log10(currencyScale(r.currency))), r.tax === null ? '' : (Number(r.tax) / currencyScale(r.currency)).toFixed(Math.log10(currencyScale(r.currency))), r.total === null ? '' : (Number(r.total) / currencyScale(r.currency)).toFixed(Math.log10(currencyScale(r.currency))), r.currency, r.till, r.mode, Number(r.parent) ? 'yes' : '', r.via, r.payment, r.refund, r.dispute].map(cell).join(','));
+  const lines = await Promise.all(rows.map(async (r) => [r.id, iso(r.created_at), iso(r.paid_at), iso(r.refunded_at), r.status, r.item, r.game, (Number(r.amount) / currencyScale(r.currency)).toFixed(Math.log10(currencyScale(r.currency))), r.tax === null ? '' : (Number(r.tax) / currencyScale(r.currency)).toFixed(Math.log10(currencyScale(r.currency))), r.total === null ? '' : (Number(r.total) / currencyScale(r.currency)).toFixed(Math.log10(currencyScale(r.currency))), r.currency, r.till, r.mode, Number(r.parent) ? 'yes' : '', r.via, r.payment, r.refund, r.dispute, JSON.stringify((await orderLines(env, r.id)).map(lineView)), (Number(r.refunded_amount ?? 0) / currencyScale(r.currency)).toFixed(Math.log10(currencyScale(r.currency))), (Number(r.refunded_net ?? 0) / currencyScale(r.currency)).toFixed(Math.log10(currencyScale(r.currency)))].map(cell).join(',')));
   return `${head.join(',')}\n${lines.join('\n')}${lines.length ? '\n' : ''}`;
 }