@blamejs/blamejs-shop 0.4.19 → 0.4.21

package/lib/store-credit.js

@@ -67,6 +67,14 @@ var C = b.constants;
 var KINDS   = ["credit", "debit", "expire"];
 var SOURCES = ["refund", "goodwill", "promotional", "manual", "loyalty_redemption"];
 
+// Reserved source_ref stamped on every expire row the scheduled sweep
+// writes. `cleanupExpired` keys its "already swept" idempotency on this
+// marker SO THAT operator-initiated `expire()` rows (which carry the
+// operator's own reason) don't masquerade as prior sweep output and
+// suppress a legitimate expiry. The marker is short + control-byte-free
+// so it passes `_sourceRef` validation when written.
+var SWEEP_SOURCE_REF = "scheduled-expiry-sweep";
+
 var MAX_SOURCE_REF_LEN = 128;
 // source_ref / reason are short correlation handles. Refuse all
 // control bytes (including CR/LF and tab) — log-injection cover has
@@ -488,20 +496,25 @@ function create(opts) {
       var now = _epochMs(input.now, "now");
       if (now == null) now = _now();
 
-      // Walk every credit row whose deadline has passed. For each,
-      // check whether a later `expire` row has already offset it —
-      // if so, skip (idempotent re-run produces no duplicates).
-      // Otherwise write an offsetting expire row capped at the
-      // wallet's current balance.
+      // Walk every credit row whose deadline has passed. For each
+      // customer, expire the still-unburned portion of their expired
+      // credit, capped at the wallet's current balance.
       //
-      // The "already offset" check is per-customer rather than
-      // per-credit-row because expire rows have no parent pointer
-      // at the schema level. We sum the customer's expired-credit
-      // amounts (kind=credit AND expires_at <= now) and the
-      // customer's burn-expire amounts (kind=expire) — the delta
-      // is the still-unburned expiring credit for that customer.
-      // When the delta is zero, the sweep is a no-op for that
-      // customer.
+      // The "already swept" check is per-customer rather than
+      // per-credit-row because expire rows have no parent pointer at
+      // the schema level. The idempotency key is the SWEEP's OWN prior
+      // output — expire rows stamped with `SWEEP_SOURCE_REF` — NOT
+      // every expire row. Counting all expire rows here was the bug:
+      // an operator-initiated `expire()` (a clawback, a goodwill burn)
+      // or any non-sweep expire would be subtracted from the expired-
+      // credit total, shrinking `pendingBurn` and leaving genuinely
+      // expired credit un-swept. Operator expires + debits already
+      // reduced the BALANCE; the `min(pendingBurn, balance)` cap below
+      // is what keeps the sweep from over-burning when the wallet was
+      // partly drained — so they must not also be netted out of the
+      // expired pool, or the reduction is double-counted. When the
+      // unburned remainder is zero, the sweep is a no-op for that
+      // customer (idempotent re-run produces no duplicates).
       var expiredByCustomer = (await query(
         "SELECT customer_id, SUM(amount_minor) AS total " +
         "FROM store_credit_ledger " +
@@ -519,16 +532,15 @@ function create(opts) {
         var burnRow = (await query(
           "SELECT COALESCE(SUM(amount_minor), 0) AS total " +
           "FROM store_credit_ledger " +
-          "WHERE customer_id = ?1 AND kind = 'expire'",
-          [customerId],
+          "WHERE customer_id = ?1 AND kind = 'expire' AND source_ref = ?2",
+          [customerId, SWEEP_SOURCE_REF],
         )).rows[0];
         var alreadyBurned = burnRow ? burnRow.total : 0;
         var pendingBurn   = expiredTotal - alreadyBurned;
 
         if (pendingBurn <= 0) {
-          // Already fully offset by prior expire rows (or by
-          // debits that drained the wallet below the expired
-          // amount — see cap below). Idempotent skip.
+          // The sweep already burned this customer's expired credit on
+          // a prior run. Idempotent skip.
           continue;
         }
 
@@ -548,7 +560,7 @@ function create(opts) {
         }
         var ts    = _resolveOccurredAt(now, latest.occurred_at);
         var after = latest.balance - toBurn;
-        var id    = await _writeRow(customerId, "expire", toBurn, null, "scheduled-expiry-sweep", null, after, null, ts);
+        var id    = await _writeRow(customerId, "expire", toBurn, null, SWEEP_SOURCE_REF, null, after, null, ts);
         processed.push({
           id:                  id,
           customer_id:         customerId,

package/lib/storefront.js

@@ -5795,6 +5795,21 @@ function _subscriptionControlState(sub) {
   return "active";
 }
 
+// Stripe statuses that wind a subscription down for good. A subscription
+// the customer cancelled at Stripe (or that lapsed unpaid) syncs to one
+// of these via the `customer.subscription.*` webhook, which writes
+// `status` but NOT the local `cancelled_at`. Without checking the synced
+// status, a Stripe-cancelled subscription whose local control-state is
+// still "active" would render live pause / skip / quantity / frequency
+// controls that mutate a row Stripe no longer bills — a customer would
+// "pause" or "change the quantity" of a subscription that's already
+// dead. So the self-manage controls are gated on the synced status: a
+// terminally-wound-down subscription shows its state, not live controls.
+var TERMINAL_SUB_STATUSES = ["canceled", "incomplete_expired", "unpaid"];
+function _subscriptionSelfManageable(sub) {
+  return TERMINAL_SUB_STATUSES.indexOf(sub.status) === -1;
+}
+
 // The 90-day reactivation grace mirrors subscriptionControls.REACTIVATE_
 // GRACE_MS. A cancelled row is reactivatable from the storefront while
 // the cancellation is inside that window; past it, the primitive refuses
@@ -5841,6 +5856,13 @@ var SUBSCRIPTION_ERR = {
   frequency:   "Choose a valid delivery frequency.",
   state:       "That change isn't available for this subscription right now.",
   grace:       "This subscription was cancelled too long ago to reactivate. Start a new one instead.",
+  // Stripe doesn't let an active subscription's billing cadence change in
+  // place; the customer cancels + re-subscribes on a plan with the
+  // cadence they want.
+  freq_locked: "Delivery frequency can't be changed on this subscription. Cancel it and start a new one on the cadence you want.",
+  // A Stripe-side quantity push failed; the local quantity was NOT
+  // changed, so the customer sees the unchanged value and can retry.
+  processor:   "We couldn't update your subscription with the payment processor. Nothing changed — please try again.",
 };
 function _subscriptionErrorCopy(code) {
   if (code == null) return null;
@@ -5853,14 +5875,23 @@ function _subscriptionErrorCopy(code) {
 // payment handle wired — the list renders read-only with a note, since
 // cancel composes Stripe. `opts.self_manage` adds the pause / resume /
 // skip / change-quantity / change-frequency / reactivate controls (wired
-// only when the subscriptionControls primitive is available). Empty state
-// points at the catalog (creation is a separate Stripe-subscription-
-// checkout surface, not built here).
+// only when the subscriptionControls primitive is available).
+// `opts.stripe_backed` is true when those controls can reach Stripe — it
+// suppresses the change-frequency form on a Stripe-backed row (the
+// billing interval is immutable at Stripe) and gates the whole control
+// block on the synced status so a Stripe-cancelled subscription shows its
+// state, not live controls. Empty state points at the catalog (creation
+// is a separate Stripe-subscription-checkout surface, not built here).
 function renderAccountSubscriptions(opts) {
   var esc = b.template.escapeHtml;
   var subs = opts.subscriptions || [];
   var canCancel = opts.can_cancel !== false;
   var selfManage = opts.self_manage === true;
+  // True when the controls can actually reach Stripe (retrieve+update
+  // wired). Only then is a row's billing cadence processor-locked and the
+  // frequency control suppressed; a local-only controls instance keeps
+  // offering it even on a Stripe-shaped row.
+  var stripeAware = opts.stripe_backed === true;
   var rowsHtml = "";
   for (var i = 0; i < subs.length; i += 1) {
     var s = subs[i];
@@ -5920,11 +5951,22 @@ function renderAccountSubscriptions(opts) {
     // cancel (a second server-rendered screen, no inline confirm()); the
     // reversible controls post directly. Quantity / frequency take input
     // validated server-side.
+    //
+    // The active + paused control sets are additionally gated on the
+    // SYNCED Stripe status: a subscription Stripe has wound down
+    // (canceled / incomplete_expired / unpaid via webhook) but whose
+    // LOCAL control-state still reads "active"/"paused" must NOT offer
+    // pause / skip / quantity / frequency / resume — those would mutate a
+    // row Stripe no longer bills. The cancelled-within-grace REACTIVATE
+    // path is intentionally NOT gated this way: a Stripe-canceled status
+    // is the normal state of a row the customer is reactivating, and
+    // reactivate is the recovery action for exactly that case.
     var manageControls = "";
+    var liveManageable = _subscriptionSelfManageable(s);
     if (selfManage) {
       var actId = esc(s.id);
       var ctrls = "";
-      if (controlState === "active") {
+      if (controlState === "active" && liveManageable) {
         ctrls +=
           "<a class=\"btn-ghost btn-ghost--sm\" href=\"/account/subscriptions/" + actId + "/pause\">Pause</a>";
         ctrls +=
@@ -5939,15 +5981,26 @@ function renderAccountSubscriptions(opts) {
             "</label>" +
             "<button type=\"submit\" class=\"btn-ghost btn-ghost--sm\">Update quantity</button>" +
           "</form>";
-        ctrls +=
-          "<form class=\"subscription-card__control subscription-card__control--freq\" method=\"post\" action=\"/account/subscriptions/" + actId + "/frequency\">" +
-            "<label class=\"form-field form-field--inline\">" +
-              "<span class=\"form-field__label\">Frequency</span>" +
-              "<select name=\"frequency\" required>" + _frequencyOptions(s.frequency || null) + "</select>" +
-            "</label>" +
-            "<button type=\"submit\" class=\"btn-ghost btn-ghost--sm\">Update frequency</button>" +
-          "</form>";
-      } else if (controlState === "paused") {
+        // The frequency control only renders for a shop-local (non-
+        // Stripe) subscription. A Stripe-backed subscription's billing
+        // cadence is fixed by its Stripe Price (interval is immutable),
+        // so there's nothing for this form to change — offering it would
+        // be a button that always errors. `stripeAware` is set only when
+        // the controls can reach Stripe; combined with the row's
+        // `stripe_subscription_id` it identifies a genuinely Stripe-
+        // backed row.
+        var stripeBacked = stripeAware && s.stripe_subscription_id != null && String(s.stripe_subscription_id).length > 0;
+        if (!stripeBacked) {
+          ctrls +=
+            "<form class=\"subscription-card__control subscription-card__control--freq\" method=\"post\" action=\"/account/subscriptions/" + actId + "/frequency\">" +
+              "<label class=\"form-field form-field--inline\">" +
+                "<span class=\"form-field__label\">Frequency</span>" +
+                "<select name=\"frequency\" required>" + _frequencyOptions(s.frequency || null) + "</select>" +
+              "</label>" +
+              "<button type=\"submit\" class=\"btn-ghost btn-ghost--sm\">Update frequency</button>" +
+            "</form>";
+        }
+      } else if (controlState === "paused" && liveManageable) {
         ctrls +=
           "<form class=\"subscription-card__control\" method=\"post\" action=\"/account/subscriptions/" + actId + "/resume\">" +
             "<button type=\"submit\" class=\"btn-primary btn-primary--sm\">Resume</button>" +
@@ -13999,6 +14052,16 @@ function mount(router, deps) {
         // fat-fingered value re-prompts rather than 500-ing checkout.
         var code = (e && typeof e.code === "string") ? e.code : "";
         var msg = (e && e.message) || "checkout failed";
+        // Lost the single-charge claim: another POST for this cart (a double-
+        // click / second tab) is already converting it. The winner created
+        // (or is creating) the one order; bounce this loser to the cart so it
+        // can't start a second checkout. The winner's redirect carries the
+        // shopper to /pay or /orders — this branch just refuses the duplicate.
+        if (code === "CHECKOUT_IN_PROGRESS") {
+          res.status(303);
+          res.setHeader && res.setHeader("location", "/cart");
+          return res.end ? res.end() : res.send("");
+        }
         // A coded gift-card / loyalty / out-of-stock error is something the
         // shopper can fix in place — re-render the checkout form with the
         // message inline (preserving the cart + their prefilled fields where
@@ -17477,6 +17540,11 @@ function mount(router, deps) {
           subscriptions: rows,
           can_cancel:    subsCanCancel,
           self_manage:   !!subControls,
+          // The frequency control is suppressed for Stripe-backed rows
+          // ONLY when the controls can actually reach Stripe (a payment
+          // handle with retrieve + update was wired) — otherwise the
+          // controls are local-only and the cadence is still editable.
+          stripe_backed: !!(subControls && subControls.stripeBacked),
           notice:        notice,
           error:         _subscriptionErrorCopy(errKind),
           shop_name:     shopName,
@@ -17503,6 +17571,7 @@ function mount(router, deps) {
           if (e && e.code === "SUBSCRIPTION_REACTIVATE_GRACE_EXPIRED") return "grace";
           if (e && e.code === "SUBSCRIPTION_STATE_REFUSED")            return "state";
           if (e && e.code === "SUBSCRIPTION_NOT_FOUND")                return "state";
+          if (e && e.code === "SUBSCRIPTION_FREQUENCY_IMMUTABLE")      return "freq_locked";
           if (e instanceof TypeError)                                   return "state";
           return null;
         }
@@ -17512,13 +17581,32 @@ function mount(router, deps) {
           return res.end ? res.end() : res.send("");
         }
 
+        // Resolve an owned subscription AND refuse the self-manage action
+        // when the synced Stripe status is terminal (canceled /
+        // incomplete_expired / unpaid). The display gates the controls on
+        // the same status, but the backend validates independently — a
+        // forged POST to a wound-down subscription's pause / skip /
+        // quantity / frequency endpoint bounces to the list with the
+        // generic state error rather than mutating a row Stripe no longer
+        // bills. Returns null (after redirecting) when ownership fails or
+        // the status is terminal; the caller bails on null.
+        async function _ownedManageableSubscription(req, res, auth) {
+          var sub = await _ownedSubscription(req, res, auth);
+          if (!sub) return null;
+          if (!_subscriptionSelfManageable(sub)) {
+            _redirect(res, "?error=state");
+            return null;
+          }
+          return sub;
+        }
+
         // Pause is confirm-gated (GET → POST), mirroring cancel — a
         // deliberate, reversible hold. The confirm page only renders for a
         // currently-active subscription; a paused/cancelled row bounces
         // back to the list.
         router.get("/account/subscriptions/:id/pause", async function (req, res) {
           var auth = _subsAuth(req, res); if (!auth) return;
-          var sub = await _ownedSubscription(req, res, auth); if (!sub) return;
+          var sub = await _ownedManageableSubscription(req, res, auth); if (!sub) return;
           if (_subscriptionControlState(sub) !== "active") return _redirect(res, "");
           if (sub.plan_id != null) {
             try { sub.plan = await subscriptions.plans.get(sub.plan_id); }
@@ -17534,7 +17622,7 @@ function mount(router, deps) {
 
         router.post("/account/subscriptions/:id/pause", async function (req, res) {
           var auth = _subsAuth(req, res); if (!auth) return;
-          var sub = await _ownedSubscription(req, res, auth); if (!sub) return;
+          var sub = await _ownedManageableSubscription(req, res, auth); if (!sub) return;
           try {
             await subControls.pause({ subscription_id: sub.id, reason: "customer self-service pause", actor: SELF_ACTOR });
           } catch (e) {
@@ -17546,7 +17634,7 @@ function mount(router, deps) {
 
         router.post("/account/subscriptions/:id/resume", async function (req, res) {
           var auth = _subsAuth(req, res); if (!auth) return;
-          var sub = await _ownedSubscription(req, res, auth); if (!sub) return;
+          var sub = await _ownedManageableSubscription(req, res, auth); if (!sub) return;
           try {
             await subControls.resume({ subscription_id: sub.id, reason: "customer self-service resume", actor: SELF_ACTOR });
           } catch (e) {
@@ -17558,7 +17646,7 @@ function mount(router, deps) {
 
         router.post("/account/subscriptions/:id/skip", async function (req, res) {
           var auth = _subsAuth(req, res); if (!auth) return;
-          var sub = await _ownedSubscription(req, res, auth); if (!sub) return;
+          var sub = await _ownedManageableSubscription(req, res, auth); if (!sub) return;
           try {
             await subControls.skipNext({ subscription_id: sub.id, count: 1, reason: "customer self-service skip", actor: SELF_ACTOR });
           } catch (e) {
@@ -17570,7 +17658,7 @@ function mount(router, deps) {
 
         router.post("/account/subscriptions/:id/quantity", async function (req, res) {
           var auth = _subsAuth(req, res); if (!auth) return;
-          var sub = await _ownedSubscription(req, res, auth); if (!sub) return;
+          var sub = await _ownedManageableSubscription(req, res, auth); if (!sub) return;
           // Backend validates: a non-positive / non-integer / missing value
           // is a client error → bounce with the quantity error code rather
           // than handing garbage to the primitive (which would throw a
@@ -17581,6 +17669,14 @@ function mount(router, deps) {
             await subControls.changeQuantity({ subscription_id: sub.id, new_quantity: qty, reason: "customer self-service quantity change", actor: SELF_ACTOR });
           } catch (e) {
             if (e instanceof TypeError) return _redirect(res, "?error=quantity");
+            // A Stripe-side push failure (no billable item, or the
+            // processor rejected/timed out the update) left the local
+            // quantity unchanged. Surface a clean "nothing changed, retry"
+            // notice instead of 500-ing — the customer's row still shows
+            // the old quantity, which is the truth.
+            if (e && (e.code === "SUBSCRIPTION_STRIPE_NO_ITEM" || e.code === "SUBSCRIPTION_STRIPE_PUSH_FAILED")) {
+              return _redirect(res, "?error=processor");
+            }
             var code = _controlError(e); if (code == null) throw e;
             return _redirect(res, "?error=" + code);
           }
@@ -17589,7 +17685,7 @@ function mount(router, deps) {
 
         router.post("/account/subscriptions/:id/frequency", async function (req, res) {
           var auth = _subsAuth(req, res); if (!auth) return;
-          var sub = await _ownedSubscription(req, res, auth); if (!sub) return;
+          var sub = await _ownedManageableSubscription(req, res, auth); if (!sub) return;
           // Backend validates: reject anything outside the allowed cadence
           // enum before composing the primitive.
           var freq = String((req.body || {}).frequency || "");
@@ -17606,6 +17702,11 @@ function mount(router, deps) {
 
         router.post("/account/subscriptions/:id/reactivate", async function (req, res) {
           var auth = _subsAuth(req, res); if (!auth) return;
+          // Reactivate is the recovery path for a cancelled subscription,
+          // so it is NOT gated on the terminal-status guard (a Stripe-
+          // canceled status is the normal state of a row being
+          // reactivated). The primitive enforces the cancelled-state +
+          // grace-window FSM.
           var sub = await _ownedSubscription(req, res, auth); if (!sub) return;
           try {
             await subControls.reactivate({ subscription_id: sub.id, reason: "customer self-service reactivate", actor: SELF_ACTOR });
@@ -17968,6 +18069,18 @@ function mount(router, deps) {
         var auth = _returnsAuth(req, res); if (!auth) return;
         var order = await _ownedOrder(req, res, auth); if (!order) return;
         var cartCount = await _cartCountForReq(req);
+        // An ineligible order (unpaid, cancelled, or already refunded) never
+        // gets the open-return form — the same window the return button is
+        // gated on. Without this the form renders on, say, a refunded order
+        // and the POST below would mint an RMA the operator could then refund
+        // a SECOND time through the provider.
+        if (!_orderEligibleForReturn(order.status)) {
+          return _send(res, 400, renderReturnForm({
+            order: order, lines: order.lines || [],
+            notice: "This order isn't eligible for a return.",
+            shop_name: shopName, cart_count: cartCount,
+          }));
+        }
         _send(res, 200, renderReturnForm({ order: order, lines: order.lines || [], shop_name: shopName, cart_count: cartCount }));
       });
 
@@ -17976,6 +18089,21 @@ function mount(router, deps) {
         var order = await _ownedOrder(req, res, auth); if (!order) return;
         var body = req.body || {};
         var cartCount = await _cartCountForReq(req);
+        // Server-side eligibility gate — the load-bearing check. A return is
+        // only openable while the goods are in the customer's hands and paid
+        // for (paid / fulfilling / shipped / delivered); an unpaid pending
+        // order, a cancelled one, or an already-refunded one is refused. The
+        // form/button gate on the same predicate, but a forged direct POST —
+        // or an order that changed state between the GET and this POST — must
+        // not slip an RMA onto an ineligible order (which would enable a
+        // second provider refund downstream).
+        if (!_orderEligibleForReturn(order.status)) {
+          return _send(res, 400, renderReturnForm({
+            order: order, lines: order.lines || [],
+            notice: "This order isn't eligible for a return.",
+            shop_name: shopName, cart_count: cartCount,
+          }));
+        }
         // Build the return lines from the order's own lines (authoritative
         // sku/qty), keyed by the checkboxes the customer ticked — never
         // trust a client-supplied sku.

package/lib/subscription-controls.js

@@ -242,6 +242,77 @@ function create(opts) {
   if (!subscriptionsHandle || typeof subscriptionsHandle.get !== "function") {
     throw new TypeError("subscriptionControls.create: opts.subscriptions handle required");
   }
+  // Optional payment handle (the shared Stripe adapter). When wired,
+  // quantity changes on a Stripe-backed subscription are pushed to
+  // Stripe BEFORE the local row is touched, so the row the shop shows
+  // and the quantity Stripe actually bills never diverge. Without it
+  // (a deploy with no payment processor, or a non-Stripe row), the
+  // controls stay local-only. The handle must expose
+  // `subscriptions.retrieve(id)` + `subscriptions.update(id, body)`.
+  var payment = opts.payment || null;
+  var hasStripe = !!(payment && payment.subscriptions &&
+    typeof payment.subscriptions.update === "function" &&
+    typeof payment.subscriptions.retrieve === "function");
+
+  // A row is Stripe-backed when the processor adapter is wired AND the
+  // row carries the upstream subscription id the webhook + billing
+  // mirror key on. Rows without one are shop-local (e.g. a manually
+  // seeded subscription on a deploy that never reached Stripe) and the
+  // controls mutate only local columns for them.
+  function _isStripeBacked(row) {
+    return hasStripe && row && typeof row.stripe_subscription_id === "string" && row.stripe_subscription_id.length > 0;
+  }
+
+  // Push a new line quantity to Stripe for a Stripe-backed subscription.
+  // Stripe models quantity on the subscription ITEM, not the
+  // subscription, so we retrieve the live subscription to find its
+  // (single) item id, then update that item's quantity. Every
+  // subscription this shop creates binds exactly one price
+  // (`items: [{ price }]`), so the first item is authoritative; if a
+  // subscription somehow carries no item we surface a structured error
+  // rather than silently writing a local-only change that diverges from
+  // Stripe. The idempotency key folds in the subscription id + target
+  // quantity so a retried call is a safe no-op at Stripe.
+  async function _pushQuantityToStripe(stripeSubscriptionId, newQuantity) {
+    var live;
+    try {
+      live = await payment.subscriptions.retrieve(stripeSubscriptionId);
+    } catch (e) {
+      var rErr = new Error(
+        "subscriptionControls.changeQuantity: could not reach Stripe to update the subscription — " + (e && e.message || e),
+      );
+      rErr.code = "SUBSCRIPTION_STRIPE_PUSH_FAILED";
+      rErr.cause = e;
+      throw rErr;
+    }
+    var items = live && live.items && Array.isArray(live.items.data) ? live.items.data : [];
+    if (!items.length || !items[0] || !items[0].id) {
+      var noItem = new Error(
+        "subscriptionControls.changeQuantity: Stripe subscription " + stripeSubscriptionId + " has no billable item to update",
+      );
+      noItem.code = "SUBSCRIPTION_STRIPE_NO_ITEM";
+      throw noItem;
+    }
+    var idemKey = "subctl:qty:" + stripeSubscriptionId + ":" + newQuantity;
+    try {
+      return await payment.subscriptions.update(
+        stripeSubscriptionId,
+        { items: [{ id: items[0].id, quantity: newQuantity }] },
+        idemKey,
+      );
+    } catch (e2) {
+      // The processor rejected or failed the quantity update. Wrap it in
+      // a stable code so the route can surface a "nothing changed, retry"
+      // notice; the local row is still untouched (this runs before the
+      // local write).
+      var uErr = new Error(
+        "subscriptionControls.changeQuantity: Stripe rejected the quantity update — " + (e2 && e2.message || e2),
+      );
+      uErr.code = "SUBSCRIPTION_STRIPE_PUSH_FAILED";
+      uErr.cause = e2;
+      throw uErr;
+    }
+  }
 
   // Fetch the raw subscription row + bound plan in one round-trip,
   // returning `null` if either is absent. The plan lookup feeds the
@@ -317,6 +388,14 @@ function create(opts) {
     MAX_SKIP_COUNT:     MAX_SKIP_COUNT,
     MAX_QUANTITY:       MAX_QUANTITY,
     REACTIVATE_GRACE_MS: REACTIVATE_GRACE_MS,
+    // True when this instance can push changes to Stripe (a payment
+    // handle with retrieve + update was wired). Callers use it to decide
+    // whether a row with a stripe_subscription_id is genuinely Stripe-
+    // backed — a frequency change is refused (immutable interval) and a
+    // quantity change round-trips Stripe. Without it, the controls are
+    // local-only even for a Stripe-shaped row, so the storefront keeps
+    // offering the frequency control.
+    stripeBacked:       hasStripe,
 
     pause: async function (input) {
       if (!input || typeof input !== "object") {
@@ -462,6 +541,18 @@ function create(opts) {
         throw cErr;
       }
 
+      // Stripe-backed: push the new quantity to Stripe BEFORE the local
+      // write. If the processor rejects the update, we throw and leave
+      // the local row untouched — the customer sees an honest error and
+      // the shop's `quantity` column never diverges from what Stripe
+      // actually bills (the divergence this control surface previously
+      // produced, writing a local "Quantity updated." while Stripe kept
+      // charging the old quantity). The local write only lands after the
+      // Stripe update succeeds.
+      if (_isStripeBacked(row)) {
+        await _pushQuantityToStripe(row.stripe_subscription_id, newQuantity);
+      }
+
       var before = _snapshot(row);
       var ts = _now();
       await query(
@@ -495,6 +586,28 @@ function create(opts) {
         throw cErr;
       }
 
+      // Stripe-backed: refuse. A Stripe Price's `recurring.interval` is
+      // IMMUTABLE — you cannot re-cadence an existing price, only swap
+      // the subscription item to a DIFFERENT price with the desired
+      // interval. This shop binds each subscription to a single
+      // `stripe_price_id` from its plan and carries no catalog of
+      // per-frequency prices to swap between, so the billing interval
+      // simply isn't expressible here. Writing the local `frequency`
+      // column anyway would tell the customer "Delivery frequency
+      // updated" while Stripe kept invoicing on the original cadence —
+      // exactly the divergence this surface must not create. Refuse with
+      // honest copy; the customer cancels + re-subscribes on a plan with
+      // the cadence they want. (A non-Stripe row falls through to the
+      // local-only recompute below — the shop's own cadence view.)
+      if (_isStripeBacked(row)) {
+        var fErr = new Error(
+          "subscriptionControls.changeFrequency: delivery frequency can't be changed on this subscription — " +
+          "cancel and start a new subscription on a plan with the cadence you want",
+        );
+        fErr.code = "SUBSCRIPTION_FREQUENCY_IMMUTABLE";
+        throw fErr;
+      }
+
       // next_billing_at is recomputed off the row's current cycle
       // anchor — `current_period_start` (Stripe-mirrored) if present,
       // otherwise the current next_billing_at, otherwise now. One

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/blamejs-shop",
-  "version": "0.4.19",
+  "version": "0.4.21",
   "description": "Open-source framework built on blamejs. Vendored stack, zero npm runtime deps, PQC-first crypto, security-on by default.",
   "main": "lib/index.js",
   "scripts": {