@blamejs/blamejs-shop 0.4.18 → 0.4.20

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.4.x
 
+- v0.4.20 (2026-06-06) — **Payment integrity: refunds, gift-card balances, and checkout submission are race-proof, and abandoned checkouts return gift-card funds.** A money-path hardening release. Concurrent refund clicks on the same return can no longer reach the payment provider twice. A gift card that part-paid a checkout gets its balance back when the order is cancelled, fails payment, or is reaped as stale. Double-submitting checkout can no longer create two charges and two orders. Return requests are refused server-side on orders that aren't in a returnable state, the refund confirmation screen shows the currency the provider will actually refund, and a buy-online-pickup-in-store order now reaches its delivered state when picked up. **Fixed:** *A return can only be refunded once, even under concurrent requests* — Two simultaneous refund requests for the same approved return could both pass the status check and both reach the payment provider, each with a fresh idempotency key — a double refund. The refund now claims the return atomically before the provider is called (the second request answers 409), the provider call uses a key derived from the return itself so even a retry collapses into the same refund, and a provider failure releases the claim so the refund can be retried. · *Gift-card funds come back when a part-paid checkout dies* — When a gift card partially covered a checkout and the order was then cancelled, failed payment, or sat abandoned until reaped, the card's debit was never returned — the balance was permanently gone. Redemptions are now reversed on those order transitions: the card balance is restored (a fully drained card is reactivated), the reversal is idempotent, and it rides the same order lifecycle that releases inventory holds. · *Double-submitting checkout creates one charge and one order* — Two concurrent checkout submissions could both pass the cart-status read and each create a payment intent and an order. The cart is now claimed atomically as the single gate — the second submission is redirected back to the cart — and the payment-provider idempotency key is derived from the cart, so even a duplicate that slipped through would collapse into one charge on the provider's side. A failure before the order exists releases the claim so the customer can retry. · *Return requests are validated server-side* — The return-request form and its submission are now refused on orders that are not in a returnable state — a refunded, cancelled, or unpaid order answers with a clear message instead of opening a return that could feed a second refund downstream. Previously only the button's visibility enforced this. · *A failed gift-card settlement no longer strands a completed payment* — If recording a gift card's redemption failed after the payment had already succeeded and the order existed, the checkout aborted mid-way — leaving a paid order with a cart that never converted. The settlement step now completes the order regardless and surfaces the failure for follow-up instead of stranding the purchase. · *The refund confirmation shows the currency the provider refunds* — The confirmation screen displayed the return's approved currency, but the provider refunds in the original charge's currency. The screen now reads the same source the refund uses. · *Pickup orders reach their delivered state* — Marking a pickup order as picked up drove an order transition that was only legal for shipped orders, and the failure was silently swallowed — the pickup schedule said picked up while the order stayed in its paid state. The order lifecycle now has a pickup-completion transition, so a picked-up order genuinely lands in delivered and downstream reporting sees it.
+
+- v0.4.19 (2026-06-06) — **Wishlist alerts fire once per event instead of repeating daily, stale digests catch up with a single email, and webhook delivery stops throttling itself.** A set of notification and delivery fixes. Back-in-stock and price-drop wishlist alerts now fire only when something actually changes — a steadily in-stock item no longer re-alerts every day. A wishlist digest whose schedule fell behind sends one catch-up email instead of one per minute until current. Outbound webhook delivery no longer counts its own rate-limit refusals against the limit (which kept the throttle tripped once hit), retrying an exhausted delivery no longer duplicates its dead-letter record, and the blog RSS feed renders correctly when a post title or body contains dollar-sign sequences. **Fixed:** *Back-in-stock and price-drop alerts fire on the change, not the state* — The wishlist alert sweep evaluated the current state of each item, so anything in stock re-alerted every wishlister on every sweep — the daily dedupe window just made the flood daily. Alerts now track the last-observed state per customer and item: back-in-stock fires only on an out-of-stock-to-in-stock transition, price-drop only when the price falls below the level already alerted, and a recovered price re-arms the alert. A steadily in-stock item never re-fires. The weekly cap and dedupe are also enforced atomically, so two overlapping sweeps can't double-send past the cap. · *A stale digest enrollment catches up with one email* — A wishlist digest whose next-send time had fallen far behind advanced one period per scheduler tick and sent an email each time — a subscriber could receive dozens of digests in an hour while the schedule caught up. Catching up now snaps the schedule to the present and sends at most one digest. · *Webhook delivery rate limiting no longer feeds on its own refusals* — The outbound webhook rate-limit gate counted its own refusal records toward the limit, so once an endpoint tripped the throttle it could stay tripped indefinitely, and every suppressed attempt persisted another row. Refusals are no longer counted by the gate and collapse to a single record per endpoint per window. · *Retrying an exhausted webhook delivery is idempotent* — Manually retrying a delivery that had already exhausted its attempts inserted a fresh dead-letter record on every click. Retry of an exhausted or already-delivered delivery now answers as a clean no-op, and the dead-letter table enforces one record per delivery. · *The RSS feed renders posts containing dollar-sign sequences* — The feed assembled items with a plain string replacement, which gives `$` sequences special meaning — a post title or body containing a dollar sign followed by a backtick or ampersand could corrupt the entire feed XML. The feed now uses the same literal splice the page renderers use. The feed's author field also no longer exposes an internal identifier; it carries the shop name, matching the blog pages.
+
 - v0.4.18 (2026-06-06) — **Staff accounts: per-operator credentials with owner, manager, and viewer roles — the shared admin key becomes break-glass.** The admin console gains multi-operator support. Create staff accounts at the new Operators screen, each with its own password and optional API key, and assign a least-privilege role: owner (everything, including operator management), manager (catalog, orders, customers, marketing), or viewer (read-only). Role enforcement happens at the admin write layer on every state-changing request — a viewer is refused the write itself, not just the menu link. The shared ADMIN_API_KEY keeps working as the bootstrap and break-glass owner credential, so upgrading can never lock a store out; once staff accounts exist, treat it like a recovery key. **Added:** *Operators console with per-operator credentials* — `/admin/operators` creates and disables staff accounts. Each operator gets their own password (Argon2id) and optionally a personal API key for the JSON surface, shown once at creation. The screen lists who created each operator and when; disabling one takes effect on their very next request — the signed-in session re-reads the live account row, so there is no revocation lag. · *Owner / manager / viewer roles, enforced on the write itself* — Every admin mutation passes a single permission gate keyed to the action being performed: owner holds every permission including operator management and settings; manager covers catalog, orders, customers, and marketing; viewer holds none — every POST, PUT, and DELETE is refused with a 403, regardless of how the request arrives (browser form or bearer JSON). Read screens remain available to any authenticated operator. Role-denied attempts are recorded in the audit chain alongside every operator-management action. · *Bootstrap and break-glass: the shared key still works* — `ADMIN_API_KEY` resolves to the owner role exactly as before — a store with no operator rows behaves identically to the previous release, and the first staff account is created while signed in with the shared key. Unknown sign-in attempts burn a real password verification against a fixed dummy hash, so response timing does not reveal whether an account exists.
 
 - v0.4.17 (2026-06-06) — **Email campaigns: consent-gated broadcasts to the newsletter list, with one-click unsubscribe and a send ledger that never re-mails.** The admin console gains an Email campaigns screen: author a broadcast, target a mailing audience, preview it, test-send to yourself, and send. Consent is the design center — the recipient set resolves at send time from the newsletter list (the only place a deliverable address exists; customer accounts keep only an email hash), every recipient is re-checked against the unsubscribe flag and the marketing suppression list at the moment their message sends, and every message carries one-click unsubscribe headers plus an in-body link. Sending drains in rate-bounded batches on the scheduled tick, one bad address never aborts a campaign, and a per-recipient ledger makes a resumed send never deliver twice. **Added:** *Campaign console: author, preview, test-send, send* — `/admin/campaigns` lists campaigns with status and delivered / failed / skipped counts, and a campaign editor takes a subject and a Markdown-or-plaintext body. The body renders escape-by-default with an https-only link gate — the same rendering discipline as the blog — so markup or script in a body lands as inert text in the inbox and in the console list. Preview and an operator-addressed test send are available before any real send. · *Consent resolved per recipient, at the send moment* — The reachable-recipient count shown before sending is computed live from the newsletter list, excluding anyone unsubscribed or on the marketing suppression list — and the same two checks run again for each recipient at the moment their message sends, so someone who unsubscribes mid-broadcast is skipped. Customer accounts keep only an email hash by design, so the newsletter list is the only deliverable-address source and the console says exactly how many recipients are reachable. · *One-click unsubscribe on every broadcast* — Every campaign message carries the RFC 8058 `List-Unsubscribe` / `List-Unsubscribe-Post` headers (so mail clients show their native unsubscribe control), an RFC 2919 `List-Id`, and an in-body unsubscribe link through the existing newsletter opt-out flow. · *Rate-bounded, resumable sending* — Sends drain in batches on the scheduled tick with a reserved hourly budget, so a large campaign spreads out rather than bursting. Each recipient's outcome lands in a send ledger keyed uniquely per campaign and recipient — a send interrupted by the rate budget or a restart resumes where it left off and never mails anyone twice. A failing address is counted and shown, never fatal to the rest of the campaign.

package/lib/admin.js

@@ -4622,26 +4622,60 @@ function mount(router, deps) {
       function (id, body) { return returns.markReceived(id, { operator_notes: body.operator_notes || undefined }); },
     ));
 
-    // Issue the provider refund for an RMA (when a captured intent exists),
-    // then record the RMA refund. The provider call runs FIRST — only if it
-    // succeeds does the RMA move to refunded — so the queue never marks a
-    // return refunded with the customer never paid back. The refund amount
-    // is the RMA's approved refund_amount_minor (set at approve time);
-    // absent one, the provider issues a full refund of the intent.
+    // Issue the provider refund for an RMA (when a captured intent exists).
+    //
+    // Two guards stop a concurrent double-click / two-operator race from
+    // refunding the customer twice:
+    //
+    //   1. The RMA is CLAIMED atomically (received → refunded) BEFORE the
+    //      provider call. returns.refund's conditional UPDATE matches the
+    //      row for exactly one racer; the loser gets RMA_TRANSITION_REFUSED
+    //      (mapped to 409) and never reaches the provider. The claim runs
+    //      first so a winner holds the row while money moves.
+    //   2. The Stripe idempotency key is DETERMINISTIC in the return id
+    //      ("rma-refund:<rma.id>") — no per-request uuid. Even if a logic
+    //      regression let two calls reach the provider, Stripe collapses
+    //      them onto one Refund (same key → same result), so the customer is
+    //      never paid back twice. The deterministic key is also stable
+    //      across an operator retry of the SAME refund.
+    //
+    // On a provider failure the claim is RELEASED (refunded → received) so a
+    // retry can run — the RMA never strands in `refunded` with no money
+    // moved. The refund amount is the RMA's approved refund_amount_minor
+    // (set at approve time); absent one, the provider issues a full refund
+    // of the intent IN THE ORDER'S CHARGE CURRENCY (a Stripe refund against a
+    // PaymentIntent has no currency of its own — it always returns the
+    // charge currency, which is order2.currency).
     async function _rmaProviderRefund(rma, order2, body) {
-      var idem = "rma-refund:" + rma.id + ":" + (body.idempotency_suffix || b.uuid.v7());
-      var refund = await payment.refund({
-        payment_intent: order2.payment_intent_id,
-        amount_minor:   (rma.refund_amount_minor != null && rma.refund_amount_minor > 0) ? rma.refund_amount_minor : undefined,
-        reason:         "requested_by_customer",
-        metadata:       { order_id: order2.id, rma_id: rma.id, rma_code: rma.rma_code || "" },
-      }, idem);
-      var updated = await returns.refund(rma.id, {
+      // Claim the RMA first. A lost claim (RMA_TRANSITION_REFUSED) bubbles
+      // to the route, which maps it to 409 via _returnsClientError — the
+      // loser of a concurrent refund never touches the provider. The note
+      // stamped at claim time is the operator's own text when supplied, else
+      // a stable marker; the live provider refund id is on the audit row +
+      // the JSON response, so it stays reconcilable without a second write.
+      var claimed = await returns.refund(rma.id, {
         operator_notes: (body.operator_notes && body.operator_notes.length)
           ? body.operator_notes
-          : ("provider refund " + refund.id),
+          : "provider refund issued",
       });
-      return { refund: refund, rma: updated };
+      var idem = "rma-refund:" + rma.id;
+      var refund;
+      try {
+        refund = await payment.refund({
+          payment_intent: order2.payment_intent_id,
+          amount_minor:   (rma.refund_amount_minor != null && rma.refund_amount_minor > 0) ? rma.refund_amount_minor : undefined,
+          reason:         "requested_by_customer",
+          metadata:       { order_id: order2.id, rma_id: rma.id, rma_code: rma.rma_code || "" },
+        }, idem);
+      } catch (e) {
+        // Provider call failed — release the claim so the operator can retry
+        // a transient failure. A release failure can't be recovered here, so
+        // surface the original provider error (the operator-actionable one).
+        try { await returns.releaseRefundClaim(rma.id); }
+        catch (_releaseErr) { /* drop-silent — the original provider error below is the actionable one */ }
+        throw e;
+      }
+      return { refund: refund, rma: claimed };
     }
 
     // Browser confirmation interstitial for a provider-backed RMA refund —
@@ -4665,9 +4699,17 @@ function mount(router, deps) {
           // record-only form handles it.
           return _redirect(res, "/admin/returns/" + enc + "?err=1");
         }
+        // Format the confirm amount in the ORDER'S CHARGE CURRENCY, not the
+        // RMA's approved refund_currency. A Stripe refund against a captured
+        // PaymentIntent carries no currency of its own — it always settles in
+        // the charge currency. The two differ on a multi-currency shop (an
+        // RMA approved with the default USD currency against a EUR order), and
+        // showing the RMA currency would promise the operator a different
+        // figure than the provider actually refunds.
+        var refundCcy = rmaCtx.order.currency;
         var amount = (rma.refund_amount_minor != null && rma.refund_amount_minor > 0)
-          ? pricing.format(rma.refund_amount_minor, rma.refund_currency || "USD")
-          : pricing.format(rmaCtx.order.grand_total_minor, rmaCtx.order.currency);
+          ? pricing.format(rma.refund_amount_minor, refundCcy)
+          : pricing.format(rmaCtx.order.grand_total_minor, refundCcy);
         _sendHtml(res, 200, renderAdminConfirm({
           shop_name: deps.shop_name, nav_available: navAvailable, active: "returns",
           heading: "Refund return " + _htmlEscape(rma.rma_code || rma.id.slice(0, 8)) + "?",

package/lib/asset-manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.4.18",
+  "version": "0.4.20",
   "assets": {
     "css/admin.css": {
       "integrity": "sha384-6k53cvkRrxMgmeStLIoLjVXZQHqIJgTmv1Izd8TYhh1HOC4POgE6GCvx1bsalyEP",

package/lib/cart.js

@@ -354,6 +354,50 @@ function create(opts) {
       return (await query("SELECT * FROM carts WHERE id = ?1", [cartId])).rows[0];
     },
 
+    // Atomically claim an ACTIVE cart for checkout. The `AND status =
+    // 'active'` predicate is the serialization point: on D1 a single UPDATE
+    // is atomic, so when two concurrent POST /checkout requests race the same
+    // cart (a double-click, two tabs) exactly ONE flips it to 'converted' and
+    // matches the row; the other matches zero rows and loses. The winner runs
+    // the (single) charge + order; the loser is told the checkout is already
+    // in progress and never creates a second PaymentIntent or order.
+    //
+    // Returns `{ claimed: true, cart }` for the winner, `{ claimed: false,
+    // cart }` for the loser (cart is the post-claim row so the caller can
+    // redirect to its order), or `{ claimed: false, cart: null }` when the
+    // cart id doesn't exist at all. A non-active cart (already converted /
+    // abandoned) loses the claim — the existing checkout owns it.
+    claimForCheckout: async function (cartId) {
+      _uuid(cartId, "cart_id");
+      var ts = _now();
+      var r = await query(
+        "UPDATE carts SET status = 'converted', updated_at = ?1 WHERE id = ?2 AND status = 'active'",
+        [ts, cartId],
+      );
+      var cart = (await query("SELECT * FROM carts WHERE id = ?1", [cartId])).rows[0] || null;
+      return { claimed: Number(r.rowCount || 0) === 1, cart: cart };
+    },
+
+    // Release a checkout claim back to 'active' so the buyer can retry. The
+    // checkout flow claims the cart (claimForCheckout) BEFORE the charge so a
+    // concurrent racer is locked out; if the charge / order creation then
+    // throws BEFORE the order exists, the claimer releases the cart so the
+    // shopper isn't stranded on a permanently-'converted' cart with no order
+    // to show. Atomic + self-targeting: `AND status = 'converted'` makes a
+    // double-release a no-op, and only the claimer (which set 'converted')
+    // ever calls this, so it can't resurrect a cart a DIFFERENT completed
+    // checkout legitimately converted. Returns true when the cart was
+    // released, false when there was nothing to release.
+    releaseCheckoutClaim: async function (cartId) {
+      _uuid(cartId, "cart_id");
+      var ts = _now();
+      var r = await query(
+        "UPDATE carts SET status = 'active', updated_at = ?1 WHERE id = ?2 AND status = 'converted'",
+        [ts, cartId],
+      );
+      return Number(r.rowCount || 0) === 1;
+    },
+
     // ---- abandoned-cart visibility (operator dashboard) ---------------
     //
     // A cart is "abandoned" for dashboard purposes when it is still

package/lib/checkout.js

@@ -413,6 +413,15 @@ function create(deps) {
   // the order id. Called once per order, immediately after the order
   // row exists, so a card is never burned for an order that failed to
   // create.
+  //
+  // The ledger debit is BEST-EFFORT: the card row's balance (decremented by
+  // redeem above) is the authoritative spendable balance, and the ledger is
+  // the audit trail. A ledger write failure (e.g. an unmigrated ledger table,
+  // or a ledger view that lags the card row) must not throw out of the
+  // post-create redeem path and strand the already-created order + its live
+  // PaymentIntent. The card-row debit already happened; the ledger row is
+  // reconcilable from the redemption record. Same posture the admin issue
+  // route takes when seeding the opening credit.
   async function _redeemGiftCard(resolved, orderId) {
     var redemption = await giftcards.redeem({
       code:         resolved.code_plain,
@@ -420,15 +429,58 @@ function create(deps) {
       amount_minor: resolved.applied_minor,
     });
     if (giftCardLedger) {
-      await giftCardLedger.debit({
-        gift_card_id: resolved.card.id,
-        order_id:     orderId,
-        amount_minor: resolved.applied_minor,
-      });
+      try {
+        await giftCardLedger.debit({
+          gift_card_id: resolved.card.id,
+          order_id:     orderId,
+          amount_minor: resolved.applied_minor,
+        });
+      } catch (ledgerErr) {
+        // Surface for reconciliation, but never let the audit-row write undo
+        // a card debit that already landed or strand the placed order.
+        try {
+          b.audit.safeEmit({
+            action:   "checkout.giftcard.ledger_debit.error",
+            outcome:  "failure",
+            metadata: {
+              gift_card_id: resolved.card.id,
+              order_id:     orderId,
+              amount_minor: resolved.applied_minor,
+              message:      (ledgerErr && ledgerErr.message) || String(ledgerErr),
+            },
+          });
+        } catch (_auditErr) { /* drop-silent — the redemption record is the durable trail */ }
+      }
     }
     return redemption;
   }
 
+  // Run a post-create credit redemption (gift-card / loyalty burn) so a
+  // failure can NEVER strand the already-created order + its live
+  // PaymentIntent. The order row and the PaymentIntent exist by the time
+  // this runs, and the buyer will pay the credit-reduced amount — so a
+  // throw out of the redeem (a card that raced to zero, a transient DB
+  // error) must not bubble up and leave the cart un-converted with an
+  // orphaned charge. The failure is captured to the audit sink for operator
+  // reconciliation (the credit reduced the charge but the debit didn't
+  // land, so the operator settles the card / points by hand) and the flow
+  // continues. `fn` returns the redeem promise (or null when there's no
+  // credit of that kind to burn).
+  async function _settleCreditPostCreate(kind, orderId, fn) {
+    try {
+      return await fn();
+    } catch (e) {
+      try {
+        b.audit.safeEmit({
+          action:   "checkout." + kind + ".redeem.error",
+          outcome:  "failure",
+          metadata: { order_id: orderId, message: (e && e.message) || String(e) },
+        });
+      } catch (_auditErr) { /* drop-silent — never let the audit write mask the original failure */ }
+      return null;
+    }
+  }
+
   // Resolve an optional loyalty points credit against a priced quote.
   // `points` is the number of points the customer asked to spend;
   // `customerId` is the signed-in customer's UUID (a guest cart has
@@ -693,14 +745,23 @@ function create(deps) {
 
   // Compose a quote from a cart + ship-to + (optional) selected
   // shipping service. Pure read — no DB writes.
-  async function _buildQuote(input) {
+  async function _buildQuote(input, qOpts) {
     if (!input || typeof input !== "object") throw new TypeError("checkout.quote: input required");
     _uuid(input.cart_id, "cart_id");
     _shipTo(input.ship_to);
+    qOpts = qOpts || {};
 
     var c = await cart.get(input.cart_id);
     if (!c)                       throw new TypeError("checkout: cart " + input.cart_id + " not found");
-    if (c.status !== "active")    throw new TypeError("checkout: cart status is " + c.status + ", cannot quote");
+    // A live preview (quote) requires the cart to be active. confirm() claims
+    // the cart to 'converted' BEFORE building the quote (the single-charge
+    // gate against a double-submit), so on that path the claimed status is
+    // permitted via qOpts.allowClaimed — the cart confirm is settling IS
+    // 'converted', and rejecting it here would break the very flow that owns
+    // the conversion.
+    if (c.status !== "active" && !(qOpts.allowClaimed && c.status === "converted")) {
+      throw new TypeError("checkout: cart status is " + c.status + ", cannot quote");
+    }
     var rawLines = await cart.listLines(c.id);
     if (rawLines.length === 0)    throw new TypeError("checkout: cart is empty");
     // Reapply the active quantity-break for each line at confirm time —
@@ -816,43 +877,84 @@ function create(deps) {
         throw new TypeError("checkout: customer.name — Enter a name of 120 characters or fewer.");
       }
       if (!input.selected_shipping_id) throw new TypeError("checkout.confirm: selected_shipping_id required");
-      var idempotencyKey = input.idempotency_key;
-      if (typeof idempotencyKey !== "string" || idempotencyKey.length < 8) {
-        throw new TypeError("checkout.confirm: idempotency_key (≥8 chars) required");
-      }
 
-      var quote = await _buildQuote(input);
-      if (!quote.selected_shipping) {
-        // _buildQuote already threw above, but defense in depth.
-        throw new TypeError("checkout.confirm: selected_shipping resolution returned null");
-      }
-      if (quote.totals.grand_total_minor <= 0) {
-        throw new TypeError("checkout.confirm: grand_total_minor must be > 0 (zero-total orders use a separate freebie flow)");
+      // Atomic single-charge gate against a double-submit. Two concurrent
+      // POST /checkout requests for the same cart (a double-click, two tabs,
+      // a retried form post) must NOT each create a PaymentIntent + order.
+      // claimForCheckout flips the cart 'active' → 'converted' in one atomic
+      // UPDATE; exactly one racer matches the row and proceeds, the other
+      // loses the claim and is told the checkout is already in progress —
+      // never a second charge. A non-active cart (already converting /
+      // converted / abandoned) loses for the same reason. The claim runs
+      // BEFORE the PaymentIntent so the loser can't slip a charge in.
+      var claim = await cart.claimForCheckout(input.cart_id);
+      if (!claim.cart) throw new TypeError("checkout: cart " + input.cart_id + " not found");
+      if (!claim.claimed) {
+        // Lost the claim — another checkout for this cart is in flight or
+        // already completed. Surface a typed signal so the storefront can
+        // redirect to the in-progress order rather than starting a second.
+        var inProgress = new Error("checkout: a checkout is already in progress for this cart");
+        inProgress.code = "CHECKOUT_IN_PROGRESS";
+        throw inProgress;
       }
 
-      // Reserve stock for every shippable, non-exempt line BEFORE any
-      // charge. Insufficient stock throws a coded INSUFFICIENT_STOCK error
-      // here (no PaymentIntent, no order) which the storefront re-renders
-      // inline. The holds placed here ride into the pending order and are
-      // converted to a real shelf debit on the paid transition (or released
-      // when the order is cancelled / expires). Everything AFTER this point
-      // runs inside a guard that releases the holds if a later step throws
-      // before the order is committed, so a refused gift-card / payment
-      // error never strands held stock.
-      var stockHolds = await _placeStockHolds(quote.lines);
-      // Conditional rollback: the catch releases the placed holds ONLY when
-      // no pending order was created. Once createFromCart succeeds, the
-      // order row OWNS those holds — releasing them here would double-free
-      // (the paid decrement / cancel release, or the stale-pending reaper,
-      // settles them once the order exists), and a floored blanket release
-      // could even eat a CONCURRENT shopper's hold on the same SKU. The
-      // context object is mutated inside _confirmAfterHolds the instant the
-      // order is created.
+      // The cart is claimed ('converted'); from here a throw BEFORE the order
+      // is created must RELEASE the claim ('converted' → 'active') so the
+      // shopper can retry. Once the order exists the claim is permanent (the
+      // order owns the conversion) — the reaper / cancel edge handles an
+      // abandoned pending order, not a re-openable cart. rollbackCtx, shared
+      // with _confirmAfterHolds, flips orderCreated true the instant the order
+      // row exists so neither the stock-hold release nor the claim release
+      // fires once the order owns them.
       var rollbackCtx = { orderCreated: false };
       try {
-        return await this._confirmAfterHolds(input, quote, email, stockHolds, rollbackCtx);
+        // Deterministic Stripe idempotency key, derived from the claimed
+        // cart. One cart = one checkout (the claim guarantees it), so even if
+        // a double-fire reached the provider, Stripe collapses both onto the
+        // same PaymentIntent (same key → same intent). The caller-supplied
+        // idempotency_key is ignored for the provider call — the cart claim
+        // is the authoritative single-charge identity — but still accepted on
+        // the input for backward compatibility / the record-only paths.
+        var idempotencyKey = "checkout:" + input.cart_id;
+
+        var quote = await _buildQuote(input, { allowClaimed: true });
+        if (!quote.selected_shipping) {
+          // _buildQuote already threw above, but defense in depth.
+          throw new TypeError("checkout.confirm: selected_shipping resolution returned null");
+        }
+        if (quote.totals.grand_total_minor <= 0) {
+          throw new TypeError("checkout.confirm: grand_total_minor must be > 0 (zero-total orders use a separate freebie flow)");
+        }
+
+        // Reserve stock for every shippable, non-exempt line BEFORE any
+        // charge. Insufficient stock throws a coded INSUFFICIENT_STOCK error
+        // here (no PaymentIntent, no order) which the storefront re-renders
+        // inline. The holds placed here ride into the pending order and are
+        // converted to a real shelf debit on the paid transition (or released
+        // when the order is cancelled / expires).
+        var stockHolds = await _placeStockHolds(quote.lines);
+        // Stash the placed holds on rollbackCtx so the single catch below can
+        // release them when a later step throws before the order is created.
+        rollbackCtx.stockHolds = stockHolds;
+        return await this._confirmAfterHolds(input, quote, email, stockHolds, rollbackCtx, idempotencyKey);
       } catch (e) {
-        if (!rollbackCtx.orderCreated) await _releaseStockHolds(stockHolds);
+        // Only roll back when no pending order was created. Once
+        // createFromCart succeeds the order OWNS the holds + the conversion —
+        // releasing the holds would double-free (the paid decrement / cancel
+        // release, or the stale-pending reaper, settles them) and could eat a
+        // concurrent shopper's hold on the same SKU, and re-opening the cart
+        // would orphan the order. A throw before the order exists releases
+        // both the placed holds AND the checkout claim so the shopper can
+        // retry on the same cart. Both releases are atomic + self-targeting,
+        // so neither can disturb a genuinely completed checkout.
+        if (!rollbackCtx.orderCreated) {
+          if (rollbackCtx.stockHolds) {
+            try { await _releaseStockHolds(rollbackCtx.stockHolds); }
+            catch (_holdErr) { /* drop-silent — claim release below + original error are the actionable parts */ }
+          }
+          try { await cart.releaseCheckoutClaim(input.cart_id); }
+          catch (_releaseErr) { /* drop-silent — the original error below is the actionable one */ }
+        }
         throw e;
       }
     },
@@ -867,10 +969,16 @@ function create(deps) {
     // mutable flag the catch reads: set `orderCreated` true the moment a
     // pending order exists so a LATER throw doesn't release holds the order
     // now owns.
-    _confirmAfterHolds: async function (input, quote, email, stockHolds, rollbackCtx) {
-      // Already validated in confirm() above; re-read here since the PI
-      // creation moved into this split-out body.
-      var idempotencyKey = input.idempotency_key;
+    _confirmAfterHolds: async function (input, quote, email, stockHolds, rollbackCtx, idempotencyKey) {
+      // The Stripe idempotency key is derived deterministically from the
+      // claimed cart by confirm() (one cart = one checkout), so a double-fire
+      // collapses onto a single PaymentIntent on Stripe's side. Defended for
+      // a direct call: fall back to the input key.
+      if (typeof idempotencyKey !== "string" || idempotencyKey.length < 8) {
+        idempotencyKey = (typeof input.idempotency_key === "string" && input.idempotency_key.length >= 8)
+          ? input.idempotency_key
+          : ("checkout:" + input.cart_id);
+      }
       // Resolve an optional gift-card credit BEFORE any charge so a bad
       // code fails the checkout without touching Stripe. The credit
       // reduces the amount due; the order still records the full grand
@@ -940,8 +1048,16 @@ function create(deps) {
         // The pending order now owns the holds — a throw from here on must
         // NOT blanket-release them (see the conditional rollback in confirm).
         if (rollbackCtx) rollbackCtx.orderCreated = true;
-        if (gc) await _redeemGiftCard(gc, paidOrder.id);
-        if (loy) await _redeemLoyalty(loy, loyaltyCustomerId, paidOrder.id);
+        // Same settlement posture as the PaymentIntent branch below: the
+        // order exists and the credits priced it, so a redeem failure here
+        // must not strand the cart un-converted — it is captured and
+        // reconciled, never propagated.
+        await _settleCreditPostCreate("giftcard", paidOrder.id, function () {
+          return gc ? _redeemGiftCard(gc, paidOrder.id) : null;
+        });
+        await _settleCreditPostCreate("loyalty", paidOrder.id, function () {
+          return loy ? _redeemLoyalty(loy, loyaltyCustomerId, paidOrder.id) : null;
+        });
         // Best-effort: record the auto-discount redemptions against the
         // placed order. Runs post-commit so a recording failure can't
         // reverse an order that's already paid.
@@ -1003,11 +1119,20 @@ function create(deps) {
       if (rollbackCtx) rollbackCtx.orderCreated = true;
 
       // Burn the gift-card + loyalty credits against the created order.
-      // Runs after the order row exists so a failed order never spends
-      // either credit; each redeem decrement is its own double-spend
-      // guard.
-      if (gc) await _redeemGiftCard(gc, createdOrder.id);
-      if (loy) await _redeemLoyalty(loy, loyaltyCustomerId, createdOrder.id);
+      // POST-COMMIT: the order row + its PaymentIntent already exist, so a
+      // redeem failure must NOT throw out of confirm — that would leave the
+      // cart un-converted (still `active`) while a live, charge-able
+      // PaymentIntent and order sit orphaned, and the conditional rollback
+      // above no longer fires (orderCreated is set). Each redeem is captured
+      // and reconciled instead (see _settleCreditPostCreate): the order is
+      // valid and the buyer pays the credit-reduced amount; a failed debit is
+      // surfaced for the operator to reconcile, never a stranded cart.
+      await _settleCreditPostCreate("giftcard", createdOrder.id, function () {
+        return gc ? _redeemGiftCard(gc, createdOrder.id) : null;
+      });
+      await _settleCreditPostCreate("loyalty", createdOrder.id, function () {
+        return loy ? _redeemLoyalty(loy, loyaltyCustomerId, createdOrder.id) : null;
+      });
       // Best-effort: record the auto-discount redemptions against the
       // placed order. Runs post-commit so a recording failure can't
       // reverse or fail an order whose PaymentIntent already exists.
@@ -1256,7 +1381,12 @@ function create(deps) {
           lines:               ppLines,
         });
         ppOrderCreated = true;
-        await _redeemGiftCard(gc, paidOrder.id);
+        // Same settlement posture as the Stripe branches: the order exists,
+        // so a redeem failure is captured and reconciled, never allowed to
+        // strand the cart un-converted.
+        await _settleCreditPostCreate("giftcard", paidOrder.id, function () {
+          return _redeemGiftCard(gc, paidOrder.id);
+        });
         await cart.setStatus(quote.cart_id, "converted");
         var settled = await order.transition(paidOrder.id, "mark_paid", { reason: "gift_card:full" });
         return { order: settled, paypal_order_id: null, status: "PAID_BY_GIFT_CARD", gift_card: { applied_minor: gc.applied_minor, amount_due_minor: 0 } };
@@ -1285,7 +1415,14 @@ function create(deps) {
         lines:               ppLines,
       });
       ppOrderCreated = true;
-      if (gc) await _redeemGiftCard(gc, createdOrder.id);
+      // Post-commit gift-card burn — captured, never stranding. The order row
+      // + the PayPal order already exist; a redeem throw must not bubble to
+      // the outer catch (which re-throws and would leave the cart active with
+      // an orphaned PayPal order). The buyer pays the credit-reduced PayPal
+      // amount; a failed debit is surfaced for reconciliation.
+      await _settleCreditPostCreate("giftcard", createdOrder.id, function () {
+        return gc ? _redeemGiftCard(gc, createdOrder.id) : null;
+      });
       await cart.setStatus(quote.cart_id, "converted");
       return { order: createdOrder, paypal_order_id: ppOrder.id, status: ppOrder.status, gift_card: gc ? { applied_minor: gc.applied_minor, amount_due_minor: amountDue } : null };
       } catch (e) {

package/lib/click-and-collect.js

@@ -574,24 +574,39 @@ function create(opts) {
         [input.picked_up_at, sigHash, proofKind, now, orderId],
       );
 
-      // Drive the parent order FSM to delivered. The transition is
-      // guarded — an already-delivered order surfaces as
-      // `fsm/illegal-transition` and we swallow it so a double
-      // markPickedUp (idempotent at the schedule layer) doesn't
-      // spuriously fail at the order layer. Other refusal codes
-      // surface to the caller.
+      // Drive the parent order FSM to `delivered` so the order really
+      // reaches its terminal state when the goods leave the store.
+      //
+      // A pickup order is normally `paid` (or `fulfilling`, if the picker
+      // started staging) when the customer collects — for which the order
+      // FSM's BOPIS edge `mark_picked_up` goes straight to `delivered` (an
+      // in-store collection has no carrier ship leg). If the operator
+      // already shipped the order through the standard flow, `mark_picked_up`
+      // is illegal from `shipped`, so we fall back to the standard
+      // `mark_delivered` edge. If BOTH are illegal the order is already
+      // `delivered` (or otherwise terminal) — a double markPickedUp is
+      // idempotent at the schedule layer, so the order-layer no-op is
+      // expected and swallowed. Any non-FSM-refusal error still surfaces.
+      var pickupMeta = {
+        reason:   "click_and_collect_picked_up",
+        metadata: {
+          location_code: schedule.location_code,
+          picked_up_at:  input.picked_up_at,
+        },
+      };
       if (orderPrim) {
         try {
-          await orderPrim.transition(orderId, "mark_delivered", {
-            reason:   "click_and_collect_picked_up",
-            metadata: {
-              location_code: schedule.location_code,
-              picked_up_at:  input.picked_up_at,
-            },
-          });
+          await orderPrim.transition(orderId, "mark_picked_up", pickupMeta);
         } catch (e) {
-          var code = e && e.code;
-          if (code !== "fsm/illegal-transition") throw e;
+          if ((e && e.code) !== "fsm/illegal-transition") throw e;
+          // Not legal from the order's current state — try the standard
+          // ship→deliver edge (operator already shipped it), then treat an
+          // already-terminal order as the idempotent no-op it is.
+          try {
+            await orderPrim.transition(orderId, "mark_delivered", pickupMeta);
+          } catch (e2) {
+            if ((e2 && e2.code) !== "fsm/illegal-transition") throw e2;
+          }
         }
       }
       return await _getScheduleByOrder(orderId);