payment-kit 1.24.3 → 1.25.0

package/api/src/routes/checkout-sessions.ts

@@ -2,7 +2,7 @@
 import { isValid } from '@arcblock/did';
 import { getUrl } from '@blocklet/sdk/lib/component';
 import { sessionMiddleware } from '@blocklet/sdk/lib/middlewares/session';
-import { BN, fromUnitToToken } from '@ocap/util';
+import { BN, fromTokenToUnit, fromUnitToToken } from '@ocap/util';
 import { NextFunction, Request, Response, Router } from 'express';
 import Joi from 'joi';
 import cloneDeep from 'lodash/cloneDeep';
@@ -12,6 +12,7 @@ import pick from 'lodash/pick';
 import sortBy from 'lodash/sortBy';
 import uniq from 'lodash/uniq';
 import type { WhereOptions } from 'sequelize';
+import { Op } from 'sequelize';
 
 import { CustomError, formatError, getStatusFromError } from '@blocklet/error';
 import pAll from 'p-all';
@@ -20,7 +21,14 @@ import { MetadataSchema } from '../libs/api';
 import { checkPassportForPaymentLink } from '../integrations/blocklet/passport';
 import dayjs from '../libs/dayjs';
 import logger from '../libs/logger';
+import { trimDecimals } from '../libs/math-utils';
 import { authenticate } from '../libs/security';
+import {
+  buildSlippageSnapshot,
+  DEFAULT_SLIPPAGE_PERCENT,
+  isRateBelowMinAcceptableRate,
+  normalizeSlippageConfigFromMetadata,
+} from '../libs/slippage';
 import {
   canPayWithDelegation,
   canUpsell,
@@ -45,6 +53,7 @@ import {
   validatePaymentAmounts,
   processCheckoutSessionDiscounts,
   getCheckoutSessionAmounts,
+  enrichCheckoutSessionWithQuotes,
 } from '../libs/session';
 import { getDaysUntilCancel, getDaysUntilDue, getSubscriptionTrialSetup } from '../libs/subscription';
 import {
@@ -71,6 +80,7 @@ import {
   Coupon,
   PromotionCode,
 } from '../store/models';
+import type { ChainType } from '../store/models/types';
 import { CheckoutSession } from '../store/models/checkout-session';
 import { Customer } from '../store/models/customer';
 import { PaymentCurrency } from '../store/models/payment-currency';
@@ -78,6 +88,7 @@ import { PaymentIntent } from '../store/models/payment-intent';
 import { PaymentLink } from '../store/models/payment-link';
 import { PaymentMethod } from '../store/models/payment-method';
 import { Price } from '../store/models/price';
+import { PriceQuote } from '../store/models/price-quote';
 import { Product } from '../store/models/product';
 import {
   ensureStripePaymentIntent,
@@ -110,6 +121,10 @@ import { rollbackDiscountUsageForCheckoutSession, applyDiscountsToLineItems } fr
 import { formatToShortUrl } from '../libs/url';
 import { destroyExistingInvoice } from '../libs/invoice';
 import { getApproveFunction } from '../integrations/ethereum/contract';
+import { getQuoteService } from '../libs/quote-service';
+import { getExchangeRateService } from '../libs/exchange-rate/service';
+import { getExchangeRateSymbol } from '../libs/exchange-rate/token-address-mapping';
+import { sequelize } from '../store/sequelize';
 
 const router = Router();
 
@@ -117,6 +132,16 @@ const user = sessionMiddleware({ accessKey: true });
 const auth = authenticate<CheckoutSession>({ component: true, roles: ['owner', 'admin'] });
 
 const authLogin = authenticate<CheckoutSession>({ component: true, roles: ['owner', 'admin'], ensureLogin: true });
+const exchangeRateService = getExchangeRateService();
+const DEFAULT_RATE_VOLATILITY_THRESHOLD = 0.1;
+
+const getRateVolatilityThreshold = () => {
+  const raw = Number(process.env.PAYMENT_RATE_VOLATILITY_THRESHOLD || DEFAULT_RATE_VOLATILITY_THRESHOLD);
+  if (!Number.isFinite(raw) || raw <= 0) {
+    return DEFAULT_RATE_VOLATILITY_THRESHOLD;
+  }
+  return raw > 1 ? raw / 100 : raw;
+};
 
 const getPaymentMethods = async (doc: CheckoutSession) => {
   const paymentMethods = await PaymentMethod.expand(doc.livemode, { type: doc.payment_method_types });
@@ -328,10 +353,12 @@ async function validatePromotionCodesOnSubmit(
 export async function calculateAndUpdateAmount(
   checkoutSession: CheckoutSession,
   paymentCurrencyId: string,
-  useTrialSetting: boolean = false
+  useTrialSetting: boolean = false,
+  options: { lineItemsOverride?: TLineItemExpanded[] } = {}
 ) {
   const now = dayjs().unix();
-  const lineItems = await Price.expand(checkoutSession.line_items, { product: true, upsell: true });
+  const lineItems =
+    options.lineItemsOverride || (await Price.expand(checkoutSession.line_items, { product: true, upsell: true }));
 
   let trialInDays = 0;
   let trialEnd = 0;
@@ -376,7 +403,8 @@ export async function calculateAndUpdateAmount(
     discountConfig
   );
 
-  await checkoutSession.update({
+  // Build update payload
+  const updatePayload: any = {
     amount_subtotal: amount.subtotal,
     amount_total: amount.total,
     total_details: {
@@ -384,7 +412,44 @@ export async function calculateAndUpdateAmount(
       amount_shipping: amount.shipping,
       amount_tax: amount.tax,
     },
-  });
+  };
+
+  // Update discounts[0].discount_amount with recalculated value at submit time
+  // recalculate-promotion intentionally removes discount_amount (frontend calculates dynamically)
+  // but we need to persist the final calculated value at submit for createDiscountRecordsForCheckout
+  if (checkoutSession.discounts && checkoutSession.discounts.length > 0 && amount.discount) {
+    updatePayload.discounts = checkoutSession.discounts.map((discount: any, index: number) =>
+      index === 0 ? { ...discount, discount_amount: amount.discount } : discount
+    );
+  }
+
+  // Update line_items with recalculated discount_amounts at submit time
+  // recalculate-promotion clears discount_amounts (frontend calculates dynamically)
+  // but we need to persist the final calculated values at submit for invoice display
+  if (amount.processedItems?.length > 0) {
+    const discountAmountsMap = new Map(
+      amount.processedItems
+        .filter((item: any) => item.discount_amounts?.length > 0)
+        .map((item: any) => [item.price_id, item.discount_amounts])
+    );
+
+    if (discountAmountsMap.size > 0) {
+      updatePayload.line_items = checkoutSession.line_items.map((item: any) => {
+        const discountAmounts = discountAmountsMap.get(item.price_id);
+        return discountAmounts ? { ...item, discount_amounts: discountAmounts } : item;
+      });
+    }
+  }
+
+  await checkoutSession.update(updatePayload);
+
+  // Sync in-memory instance with persisted values
+  if (updatePayload.discounts) {
+    checkoutSession.discounts = updatePayload.discounts;
+  }
+  if (updatePayload.line_items) {
+    checkoutSession.line_items = updatePayload.line_items;
+  }
 
   logger.info('Amount calculated', {
     checkoutSessionId: checkoutSession.id,
@@ -395,6 +460,8 @@ export async function calculateAndUpdateAmount(
       shipping: amount.shipping,
       tax: amount.tax,
     },
+    discountsUpdated: !!updatePayload.discounts,
+    lineItemsDiscountsUpdated: !!updatePayload.line_items,
   });
 
   if (checkoutSession.mode === 'payment' && new BN(amount.total || '0').lt(new BN('0'))) {
@@ -410,6 +477,16 @@ export async function calculateAndUpdateAmount(
   };
 }
 
+const QUOTE_LOCK_DURATION_SECONDS = 180;
+const QUOTE_LOCK_DURATION_MS = QUOTE_LOCK_DURATION_SECONDS * 1000;
+
+// Removed unused functions getQuoteLockStart and isQuoteLockActive
+
+const fetchCurrentExchangeRate = (paymentCurrency: PaymentCurrency, paymentMethod: PaymentMethod) => {
+  const rateSymbol = getExchangeRateSymbol(paymentCurrency.symbol, paymentMethod.type as ChainType);
+  return exchangeRateService.getRate(rateSymbol);
+};
+
 /**
  * 创建或更新支付意向
  */
@@ -420,7 +497,8 @@ async function createOrUpdatePaymentIntent(
   lineItems: any[],
   customerId?: string,
   customerEmail?: string,
-  formData?: any
+  formData?: any,
+  options: { quoteIds?: string[] } = {}
 ) {
   let paymentIntent: PaymentIntent | null = null;
 
@@ -434,6 +512,9 @@ async function createOrUpdatePaymentIntent(
 
   const beneficiaries =
     paymentLink?.payment_intent_data?.beneficiaries || paymentLink?.donation_settings?.beneficiaries || [];
+  const quoteIds = options.quoteIds || [];
+  const shouldLockQuotes = quoteIds.length > 0;
+  const nowMs = Date.now();
 
   if (checkoutSession.payment_intent_id) {
     paymentIntent = await PaymentIntent.findByPk(checkoutSession.payment_intent_id);
@@ -459,8 +540,27 @@ async function createOrUpdatePaymentIntent(
       payment_method_id: paymentMethod.id,
       last_payment_error: null,
       beneficiaries: createPaymentBeneficiaries(checkoutSession.amount_total, beneficiaries),
+      metadata: {
+        ...(paymentIntent.metadata || {}),
+        ...(checkoutSession.payment_intent_data?.metadata || {}),
+        ...(quoteIds.length ? { quote_ids: quoteIds } : {}),
+      },
     };
 
+    if (shouldLockQuotes) {
+      const lockedAtMs = paymentIntent.quote_locked_at ? new Date(paymentIntent.quote_locked_at).getTime() : null;
+      if (lockedAtMs && nowMs - lockedAtMs > QUOTE_LOCK_DURATION_MS) {
+        await paymentIntent.update({ quote_locked_at: undefined });
+        await checkoutSession.update({
+          metadata: { ...checkoutSession.metadata, quote_locked_at: undefined },
+        });
+        throw new CustomError(409, 'QUOTE_LOCK_EXPIRED', 'Quote lock expired, please refresh and retry');
+      }
+      if (!lockedAtMs) {
+        updateData.quote_locked_at = new Date(nowMs);
+      }
+    }
+
     if (customerId) {
       updateData.customer_id = customerId;
     }
@@ -470,6 +570,11 @@ async function createOrUpdatePaymentIntent(
     }
 
     paymentIntent = await paymentIntent.update(updateData);
+    if (updateData.quote_locked_at) {
+      await checkoutSession.update({
+        metadata: { ...checkoutSession.metadata, quote_locked_at: Math.floor(nowMs / 1000) },
+      });
+    }
     logger.info('payment intent for checkout session reset', {
       session: checkoutSession.id,
       intent: paymentIntent.id,
@@ -493,9 +598,16 @@ async function createOrUpdatePaymentIntent(
       statement_descriptor_suffix: '',
       setup_future_usage: 'on_session',
       beneficiaries: createPaymentBeneficiaries(checkoutSession.amount_total, beneficiaries),
-      metadata: checkoutSession.payment_intent_data?.metadata || checkoutSession.metadata,
+      metadata: {
+        ...(checkoutSession.payment_intent_data?.metadata || checkoutSession.metadata),
+        ...(quoteIds.length ? { quote_ids: quoteIds } : {}),
+      },
     };
 
+    if (shouldLockQuotes) {
+      createData.quote_locked_at = new Date(nowMs);
+    }
+
     if (customerId) {
       createData.customer_id = customerId;
     }
@@ -527,6 +639,12 @@ async function createOrUpdatePaymentIntent(
       updateData.metadata = {
         ...checkoutSession.metadata,
         is_donation: true,
+        ...(shouldLockQuotes ? { quote_locked_at: Math.floor(nowMs / 1000) } : {}),
+      };
+    } else if (shouldLockQuotes) {
+      updateData.metadata = {
+        ...checkoutSession.metadata,
+        quote_locked_at: Math.floor(nowMs / 1000),
       };
     }
 
@@ -1033,6 +1151,12 @@ router.post('/', authLogin, async (req, res) => {
 
     const doc = await CheckoutSession.create(raw as any);
 
+    try {
+      await prefetchQuotesForCheckoutSession(doc as CheckoutSession);
+    } catch (error: any) {
+      return res.status(400).json({ error: error.message });
+    }
+
     let url = getUrl(`/checkout/${doc.submit_type}/${doc.id}`);
     if (createMine && currentUserDid) {
       url = withQuery(url, getConnectQueryParam({ userDid: currentUserDid }));
@@ -1205,6 +1329,34 @@ export async function startCheckoutSessionFromPaymentLink(id: string, req: Reque
       doc.line_items = await Price.expand(updatedItems, { upsell: true });
     }
 
+    // Final Freeze: Don't create Quotes during Preview
+    // Quotes are created ONLY at Submit time via createUsedQuoteWithValidation
+    // Frontend uses /exchange-rate endpoint for live rate display
+    // @see Intent: blocklets/core/ai/intent/20260112-dynamic-price.md
+    let quotes = {};
+    let rateUnavailable = false;
+    let rateError: string | undefined;
+    try {
+      const quoteResult = await enrichCheckoutSessionWithQuotes(
+        doc,
+        doc.line_items as TLineItemExpanded[],
+        doc.currency_id,
+        { skipGeneration: true } // Final Freeze: Don't create quotes during Preview
+      );
+      doc.line_items = quoteResult.lineItems;
+      quotes = quoteResult.quotes;
+      rateUnavailable = quoteResult.rateUnavailable || false;
+      rateError = quoteResult.rateError;
+    } catch (error: any) {
+      logger.warn('Failed to enrich checkout session with quote info', {
+        checkoutSessionId: doc.id,
+        error: error.message,
+      });
+      // Set error flags so frontend can display warning
+      rateUnavailable = true;
+      rateError = error.message || 'Failed to get price quote info';
+    }
+
     let paymentUrl = getUrl(`/checkout/pay/${doc.id}`);
     if (needShortUrl) {
       const validUntil = dayjs().add(20, 'minutes').format('YYYY-MM-DDTHH:mm:ss+00:00');
@@ -1215,6 +1367,9 @@ export async function startCheckoutSessionFromPaymentLink(id: string, req: Reque
     res.json({
       paymentUrl,
       checkoutSession: doc.toJSON(),
+      quotes, // Include quotes information for frontend
+      rateUnavailable, // Warning flag for frontend
+      rateError, // Error message for frontend
       paymentMethods: await getPaymentMethods(doc),
       paymentLink: link,
       paymentIntent: null,
@@ -1306,7 +1461,7 @@ router.post('/:id/abort-stripe', user, ensureCheckoutSessionOpen, async (req, re
     // remove related invoice if created
     try {
       const existInvoice = await Invoice.findOne({ where: { checkout_session_id: checkoutSession.id } });
-      if (existInvoice && existInvoice.status === 'paid') {
+      if (existInvoice) {
         await destroyExistingInvoice(existInvoice);
       }
     } catch (error: any) {
@@ -1354,8 +1509,9 @@ router.get('/retrieve/:id', user, async (req, res) => {
     });
   }
 
+  const rawLineItems = doc.line_items;
   // @ts-ignore
-  doc.line_items = await Price.expand(doc.line_items, { upsell: true });
+  doc.line_items = await Price.expand(rawLineItems, { upsell: true });
 
   // Enhance line items with coupon information if discounts are applied
   if (doc.discounts?.length) {
@@ -1369,14 +1525,103 @@ router.get('/retrieve/:id', user, async (req, res) => {
   // Expand discounts with complete details
   const enhancedDiscounts = await expandDiscountsWithDetails(doc.discounts);
 
+  // Handle dynamic pricing: create or reuse quotes
+  // Skip quote generation when checkout session is confirmed and should not change:
+  // 1. Payment completed (payment_status === 'paid')
+  // 2. Subscription created (has subscription_id) - includes free trial scenarios
+  // 3. Status is 'complete'
+  const isCheckoutConfirmed = doc.payment_status === 'paid' || doc.status === 'complete' || !!doc.subscription_id;
+  const forceRefresh = req.query.forceRefresh === '1' || req.query.forceRefresh === 'true';
+
+  let quotes = {};
+  let rateUnavailable = false;
+  let rateError: string | undefined;
+  let quotesRefreshed = false;
+
+  try {
+    const quoteResult = await enrichCheckoutSessionWithQuotes(
+      doc,
+      doc.line_items as TLineItemExpanded[],
+      doc.currency_id,
+      { skipGeneration: isCheckoutConfirmed, forceRefresh } // Skip for confirmed checkouts
+    );
+    doc.line_items = quoteResult.lineItems;
+    quotes = quoteResult.quotes;
+    rateUnavailable = quoteResult.rateUnavailable || false;
+    rateError = quoteResult.rateError;
+    quotesRefreshed = quoteResult.refreshed || false;
+
+    if (quoteResult.regenerated && Array.isArray(rawLineItems)) {
+      const quoteIdByPriceId = new Map<string, string>();
+      quoteResult.lineItems.forEach((item) => {
+        const priceId = item.price_id || item.price?.id;
+        const quoteId = (item as any).quote_id;
+        if (priceId && quoteId) {
+          quoteIdByPriceId.set(priceId, quoteId);
+        }
+      });
+
+      if (quoteIdByPriceId.size > 0) {
+        const updatedLineItems = rawLineItems.map((item: any) => ({
+          ...item,
+          quote_id: quoteIdByPriceId.get(item.price_id) || item.quote_id,
+        }));
+
+        await doc.update({ line_items: updatedLineItems });
+        // @ts-ignore
+        doc.line_items = await Price.expand(updatedLineItems, { upsell: true });
+        logger.info('Updated checkout session line_items with refreshed quote_ids', {
+          checkoutSessionId: doc.id,
+          updatedQuotes: quoteIdByPriceId.size,
+        });
+      }
+    }
+
+    if (isCheckoutConfirmed && Object.keys(quotes).length > 0) {
+      logger.info('Retrieved locked quotes for confirmed checkout', {
+        checkoutSessionId: doc.id,
+        paymentStatus: doc.payment_status,
+        status: doc.status,
+        hasSubscription: !!doc.subscription_id,
+        quotesCount: Object.keys(quotes).length,
+      });
+    }
+  } catch (error: any) {
+    logger.warn('Failed to process quotes for checkout session', {
+      checkoutSessionId: doc.id,
+      paymentStatus: doc.payment_status,
+      status: doc.status,
+      hasSubscription: !!doc.subscription_id,
+      isCheckoutConfirmed,
+      error: error.message,
+    });
+    // Set error flags so frontend can display warning
+    rateUnavailable = true;
+    rateError = error.message || 'Failed to process price quotes';
+  }
+
   // check payment intent
   const paymentIntent = doc.payment_intent_id ? await PaymentIntent.findByPk(doc.payment_intent_id) : null;
+  if ((forceRefresh || quotesRefreshed) && !isCheckoutConfirmed) {
+    if (doc.metadata?.quote_locked_at) {
+      await doc.update({
+        metadata: { ...doc.metadata, quote_locked_at: null },
+      });
+    }
+    if (paymentIntent?.quote_locked_at) {
+      await paymentIntent.update({ quote_locked_at: undefined });
+    }
+  }
+
   res.json({
     checkoutSession: {
       ...doc.toJSON(),
       discounts: enhancedDiscounts,
       subscriptions,
     },
+    quotes, // Include quotes information for frontend
+    rateUnavailable, // Warning flag for frontend
+    rateError, // Error message for frontend
     paymentMethods: await getPaymentMethods(doc),
     paymentLink: doc.payment_link_id ? await PaymentLink.findByPk(doc.payment_link_id) : null,
     paymentIntent,
@@ -1384,6 +1629,73 @@ router.get('/retrieve/:id', user, async (req, res) => {
   });
 });
 
+// Fetch latest exchange rate for checkout session (for UI display/monitoring only)
+// Also renews active Quote's expires_at if it's about to expire
+/**
+ * Exchange Rate Endpoint (Final Freeze Architecture)
+ *
+ * Returns rate snapshot ONLY for display purposes.
+ * Does NOT create or modify Quotes (Quotes are created at Submit time only).
+ *
+ * @see Intent: blocklets/core/ai/intent/20260112-dynamic-price.md
+ */
+router.get('/:id/exchange-rate', user, async (req, res) => {
+  const doc = await CheckoutSession.findByPk(req.params.id);
+  if (!doc) {
+    return res.status(404).json({ error: 'Checkout session not found, you may have incorrectly copied the link.' });
+  }
+
+  const currencyId = (req.query.currency_id as string) || doc.currency_id;
+  const paymentCurrency = (await PaymentCurrency.findByPk(currencyId, {
+    include: [{ model: PaymentMethod, as: 'payment_method' }],
+  })) as (PaymentCurrency & { payment_method: PaymentMethod }) | null;
+
+  if (!paymentCurrency) {
+    return res.status(400).json({ error: 'Payment currency not found' });
+  }
+
+  if (paymentCurrency.payment_method?.type === 'stripe') {
+    return res.status(400).json({ error: 'Exchange rate is not supported for stripe payments' });
+  }
+
+  const serverNow = Math.floor(Date.now() / 1000);
+
+  try {
+    const rateResult = await fetchCurrentExchangeRate(paymentCurrency, paymentCurrency.payment_method);
+
+    // Final Freeze: Only return rate snapshot, no quote data
+    return res.json({
+      server_now: serverNow,
+      rate: rateResult.rate,
+      timestamp_ms: rateResult.timestamp_ms,
+      fetched_at: rateResult.fetched_at, // When we fetched (updates every 30s)
+      provider_id: rateResult.provider_id,
+      provider_name: rateResult.provider_name,
+      provider_display: rateResult.provider_display, // Human-readable: "CoinGecko" or "CoinGecko (2 sources)"
+      providers: rateResult.providers,
+      consensus_method: rateResult.consensus_method,
+      degraded: rateResult.degraded,
+      degraded_reason: rateResult.degraded_reason,
+      currency: paymentCurrency.symbol,
+      base_currency: 'USD',
+      volatility_threshold: getRateVolatilityThreshold(),
+      // quote_snapshot removed - Quotes are created at Submit time only
+    });
+  } catch (error: any) {
+    logger.error('Exchange rate fetch failed', {
+      sessionId: doc.id,
+      currencyId,
+      error: error?.message,
+    });
+
+    // Return 503 with RATE_UNAVAILABLE code
+    return res.status(503).json({
+      code: 'RATE_UNAVAILABLE',
+      error: error?.message || 'Exchange rate unavailable',
+    });
+  }
+});
+
 // for checkout page
 router.get('/broker-status/:id', user, async (req, res) => {
   const { needShortUrl = false } = req.query;
@@ -1422,6 +1734,7 @@ router.get('/broker-status/:id', user, async (req, res) => {
   res.json({
     checkoutSession: {
       ...doc.toJSON(),
+      line_items: doc.line_items, // Override with expanded line_items (includes price object)
     },
     paymentLink,
   });
@@ -1432,13 +1745,762 @@ async function checkVendorConfig(items: TLineItemExpanded[]) {
   return lineItems?.some((item: TLineItemExpanded) => !!item?.price?.product?.vendor_config?.length);
 }
 
+type QuoteInput = {
+  price_id: string;
+  quote_id: string;
+};
+
+function getQuoteErrorCode(error: any): string {
+  if (!error) {
+    return '';
+  }
+  if (typeof error.code === 'string') {
+    return error.code;
+  }
+  if (typeof error.message === 'string' && error.message.startsWith('QUOTE_')) {
+    return error.message;
+  }
+  return '';
+}
+
+/**
+ * Calculate total base amount for quote validation
+ * Uses same precision logic as quote creation
+ */
+function calculateTotalBaseAmount(baseAmount: string, quantity: number): string {
+  const USD_DECIMALS = 8;
+  const baseAmountBN = fromTokenToUnit(trimDecimals(baseAmount, USD_DECIMALS), USD_DECIMALS);
+  const quantityBN = new BN(quantity);
+  const totalBaseAmountBN = baseAmountBN.mul(quantityBN);
+  return fromUnitToToken(totalBaseAmountBN.toString(), USD_DECIMALS);
+}
+
+function isSqliteBusyError(error: any): boolean {
+  const message = String(error?.message || '').toUpperCase();
+  const code = error?.original?.code || error?.code;
+  return code === 'SQLITE_BUSY' || message.includes('SQLITE_BUSY');
+}
+
+async function updateQuoteWithRetry(
+  quote: PriceQuote,
+  payload: Record<string, any>,
+  transaction: any,
+  maxRetries = 3
+): Promise<PriceQuote> {
+  // Retry loop with exponential backoff for SQLite busy errors
+  // eslint-disable-next-line no-await-in-loop
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      // eslint-disable-next-line no-await-in-loop
+      return await quote.update(payload, { transaction });
+    } catch (err: any) {
+      const isBusy = isSqliteBusyError(err);
+      const isLastAttempt = attempt === maxRetries;
+
+      if (!isBusy || isLastAttempt) {
+        throw err;
+      }
+
+      // Exponential backoff: 50ms, 100ms, 200ms
+      const delay = 50 * 2 ** (attempt - 1);
+      console.warn(`[Quote] SQLITE_BUSY, retry ${attempt}/${maxRetries} after ${delay}ms`);
+      // eslint-disable-next-line no-await-in-loop, no-promise-executor-return
+      await new Promise((resolve) => setTimeout(resolve, delay));
+    }
+  }
+
+  // TypeScript 需要这个（虽然逻辑上不会到达）
+  throw new Error('Unexpected: exceeded max retries');
+}
+
+/**
+ * Create Quotes at Submit time (Final Freeze Architecture)
+ *
+ * This function creates quotes directly as 'used' with dual-layer validation.
+ * It replaces the old flow where quotes were pre-created during Preview.
+ *
+ * @see Intent: blocklets/core/ai/intent/20260112-dynamic-price.md
+ */
+async function createQuotesAtSubmit(options: {
+  checkoutSession: CheckoutSession;
+  lineItems: TLineItemExpanded[];
+  paymentCurrencyId: string;
+  idempotencyKey: string;
+  previewRate?: string;
+  priceConfirmed?: boolean;
+  trialing?: boolean;
+}): Promise<{
+  lineItems: TLineItemExpanded[];
+  consumedQuotes: PriceQuote[];
+  validationError?: {
+    code: 'PRICE_UNAVAILABLE' | 'PRICE_UNSTABLE' | 'PRICE_CHANGED' | 'RATE_BELOW_SLIPPAGE_LIMIT';
+    message: string;
+    changePercent?: number;
+    currentRate?: string;
+    minAcceptableRate?: string;
+  };
+}> {
+  const {
+    checkoutSession,
+    lineItems,
+    paymentCurrencyId,
+    idempotencyKey,
+    previewRate,
+    priceConfirmed = false,
+    trialing = false,
+  } = options;
+
+  // Filter dynamic items, but exclude items that don't require payment (trialing recurring or metered)
+  // This matches the logic in getCheckoutAmount (session.ts) to ensure quote creation
+  // is consistent with actual payment amount calculation
+  const dynamicItems = lineItems.filter((item) => {
+    const price = item.upsell_price || item.price;
+    if (price.pricing_type !== 'dynamic') {
+      return false;
+    }
+    // Skip recurring items during trial period (they don't need payment during trial)
+    if (price.type === 'recurring' && trialing) {
+      return false;
+    }
+    // Skip metered items (usage-based billing, no upfront payment)
+    if (price.type === 'recurring' && price.recurring?.usage_type === 'metered') {
+      return false;
+    }
+    return true;
+  });
+
+  if (!dynamicItems.length) {
+    return { lineItems, consumedQuotes: [] };
+  }
+
+  // Skip quote creation for Stripe payments - they use base_amount (USD) directly
+  // No exchange rate conversion needed
+  const paymentCurrency = (await PaymentCurrency.findByPk(paymentCurrencyId, {
+    include: [{ model: PaymentMethod, as: 'payment_method' }],
+  })) as (PaymentCurrency & { payment_method: PaymentMethod }) | null;
+  if (paymentCurrency?.payment_method?.type === 'stripe') {
+    logger.info('Skipping quote creation for Stripe payment (base_amount is already USD)', {
+      sessionId: checkoutSession.id,
+      currencyId: paymentCurrencyId,
+      dynamicItemCount: dynamicItems.length,
+    });
+    return { lineItems, consumedQuotes: [] };
+  }
+
+  const quoteService = getQuoteService();
+  const slippageConfig = normalizeSlippageConfigFromMetadata(checkoutSession.metadata, DEFAULT_SLIPPAGE_PERCENT);
+  const slippagePercent = slippageConfig?.percent ?? DEFAULT_SLIPPAGE_PERCENT;
+  const minAcceptableRate = slippageConfig?.min_acceptable_rate;
+
+  // Early check: if user has set min_acceptable_rate, verify current rate is above it
+  // This prevents users from submitting when the rate has already dropped below their limit
+  if (minAcceptableRate) {
+    try {
+      const rateResult = await fetchCurrentExchangeRate(
+        paymentCurrency as PaymentCurrency,
+        paymentCurrency?.payment_method as PaymentMethod
+      );
+
+      if (isRateBelowMinAcceptableRate(rateResult.rate, minAcceptableRate)) {
+        logger.info('Current rate below user slippage limit', {
+          sessionId: checkoutSession.id,
+          currentRate: rateResult.rate,
+          minAcceptableRate,
+          slippagePercent,
+        });
+
+        return {
+          lineItems,
+          consumedQuotes: [],
+          validationError: {
+            code: 'RATE_BELOW_SLIPPAGE_LIMIT',
+            message: `Current exchange rate (${rateResult.rate}) is below your minimum acceptable rate (${minAcceptableRate}). Please update your slippage settings.`,
+            currentRate: rateResult.rate,
+            minAcceptableRate,
+          },
+        };
+      }
+    } catch (error: any) {
+      logger.warn('Failed to fetch rate for slippage limit check', {
+        sessionId: checkoutSession.id,
+        error: error.message,
+      });
+      // Continue with normal flow if rate fetch fails - will be caught later
+    }
+  }
+
+  const consumedQuotes: PriceQuote[] = [];
+  const updatedLineItems = [...lineItems];
+
+  // Create quotes for each dynamic item using the new validation flow
+  // Sequential processing is required: fail fast on first validation error
+  // eslint-disable-next-line no-await-in-loop
+  for (const item of dynamicItems) {
+    // Use upsell_price_id if available, otherwise use price_id
+    // This ensures quote is created with the correct base_amount (upsell price may have different base_amount)
+    const priceId = item.upsell_price_id || item.price_id;
+    const quantity = item.quantity || 1;
+
+    // Generate unique idempotency key per price
+    const itemIdempotencyKey = `${idempotencyKey}:${priceId}`;
+
+    // eslint-disable-next-line no-await-in-loop
+    const result = await quoteService.createUsedQuoteWithValidation({
+      price_id: priceId,
+      session_id: checkoutSession.id,
+      idempotency_key: itemIdempotencyKey,
+      target_currency_id: paymentCurrencyId,
+      quantity,
+      preview_rate: previewRate,
+      slippage_percent: slippagePercent,
+      price_confirmed: priceConfirmed,
+    });
+
+    // Check for validation errors
+    if (!result.validation_passed) {
+      logger.info('Quote creation validation failed', {
+        sessionId: checkoutSession.id,
+        priceId,
+        errorCode: result.error_code,
+        errorMessage: result.error_message,
+      });
+
+      return {
+        lineItems,
+        consumedQuotes: [],
+        validationError: {
+          code: result.error_code!,
+          message: result.error_message!,
+          changePercent: result.change_percent,
+        },
+      };
+    }
+
+    consumedQuotes.push(result.quote);
+
+    // Update line item with quote reference
+    // NOTE: Must use item.price_id (original) to find the line item, not priceId (which may be upsell_price_id)
+    // Line items are always keyed by original price_id, even when upsell pricing is used
+    const itemIndex = updatedLineItems.findIndex((li) => li.price_id === item.price_id);
+    if (itemIndex >= 0) {
+      (updatedLineItems[itemIndex] as any).quote_id = result.quote.id;
+      (updatedLineItems[itemIndex] as any).quoted_amount = result.quote.quoted_amount;
+      (updatedLineItems[itemIndex] as any).custom_amount = result.quote.quoted_amount;
+      (updatedLineItems[itemIndex] as any).exchange_rate = result.quote.exchange_rate;
+      (updatedLineItems[itemIndex] as any).rate_timestamp_ms = result.quote.rate_timestamp_ms;
+      // Store the currency ID this quote was created for - essential for frontend validation
+      (updatedLineItems[itemIndex] as any).quote_currency_id = result.quote.target_currency_id;
+    }
+  }
+
+  logger.info('Created quotes at submit (Final Freeze)', {
+    sessionId: checkoutSession.id,
+    quoteCount: consumedQuotes.length,
+    quoteIds: consumedQuotes.map((q) => q.id),
+  });
+
+  return { lineItems: updatedLineItems, consumedQuotes };
+}
+
+async function attachQuotesToLineItems(options: {
+  checkoutSession: CheckoutSession;
+  lineItems: TLineItemExpanded[];
+  paymentCurrencyId: string;
+  quotesInput?: QuoteInput[];
+  strict?: boolean;
+}) {
+  const { checkoutSession, lineItems, paymentCurrencyId, quotesInput = [], strict = false } = options;
+  const dynamicItems = lineItems.filter((item) => (item.upsell_price || item.price).pricing_type === 'dynamic');
+  const now = Math.floor(Date.now() / 1000);
+  const quoteLockedAt = checkoutSession.metadata?.quote_locked_at;
+  let lockStart = null;
+  if (typeof quoteLockedAt === 'number') {
+    lockStart = quoteLockedAt;
+  } else if (typeof quoteLockedAt === 'string') {
+    lockStart = Number(quoteLockedAt);
+  }
+  const lockActive = Number.isFinite(lockStart) && now - (lockStart as number) < QUOTE_LOCK_DURATION_SECONDS;
+  // Final Freeze: Quotes only have 'used', 'paid', 'payment_failed' statuses
+  // 'used' quotes are valid for payment (created at submit, immutable)
+  const isQuoteUsable = (quote: PriceQuote | null) => {
+    if (!quote) {
+      return false;
+    }
+    // 'used' status means quote was created at submit and is ready for payment
+    if (quote.status === 'used') {
+      return true;
+    }
+    // 'payment_failed' quotes can be retried
+    if (quote.status === 'payment_failed') {
+      return true;
+    }
+    return false;
+  };
+
+  if (!dynamicItems.length) {
+    return { lineItems, consumedQuotes: [] as PriceQuote[] };
+  }
+
+  let quotes: PriceQuote[] = [];
+
+  // ✅ Auto-find quotes if not provided by frontend
+  if (quotesInput.length === 0) {
+    if (strict) {
+      const quoteMap = new Map<string, string>();
+      dynamicItems.forEach((item) => {
+        const quoteId = (item as any).quote_id;
+        if (quoteId) {
+          quoteMap.set(item.price_id, quoteId);
+        }
+      });
+
+      if (quoteMap.size < dynamicItems.length) {
+        throw new CustomError(400, 'QUOTE_REQUIRED');
+      }
+
+      const quoteIds = Array.from(new Set(Array.from(quoteMap.values())));
+      quotes = await PriceQuote.findAll({ where: { id: quoteIds } });
+      const quotesById = new Map(quotes.map((q) => [q.id, q]));
+
+      // ✅ Pre-fetch payment currency and rate once (optimization: avoid repeated fetches in loop)
+      let paymentCurrency: (PaymentCurrency & { payment_method: PaymentMethod }) | null = null;
+      let rateResult: any = null;
+      let slippagePercent = 0.5;
+
+      // Final Freeze: Quotes are immutable after creation
+      // No refresh logic needed - quotes are created at submit with final price
+      // Just verify all quotes are in usable state
+      const unusableQuotes = dynamicItems
+        .map((item) => {
+          const quoteId = quoteMap.get(item.price_id);
+          const quoteRecord = quoteId ? quotesById.get(quoteId) : null;
+          return quoteRecord && !isQuoteUsable(quoteRecord) ? { item, quoteRecord } : null;
+        })
+        .filter(Boolean) as Array<{ item: any; quoteRecord: PriceQuote }>;
+
+      if (unusableQuotes.length > 0) {
+        logger.warn('Found unusable quotes - payment may fail', {
+          count: unusableQuotes.length,
+          quoteIds: unusableQuotes.map((q) => q.quoteRecord.id),
+          statuses: unusableQuotes.map((q) => q.quoteRecord.status),
+        });
+      }
+
+      // Legacy code below kept for backward compatibility but should not execute
+      // in Final Freeze architecture since quotes are never refreshed
+      const quotesNeedingRefresh: Array<{ item: any; quoteRecord: PriceQuote }> = [];
+
+      if (quotesNeedingRefresh.length > 0) {
+        logger.info('Detected quotes needing refresh, fetching rate once', {
+          count: quotesNeedingRefresh.length,
+          quoteIds: quotesNeedingRefresh.map((q) => q.quoteRecord.id),
+        });
+
+        // Fetch payment currency and rate once for all quotes
+        paymentCurrency = (await PaymentCurrency.findByPk(paymentCurrencyId, {
+          include: [{ model: PaymentMethod, as: 'payment_method' }],
+        })) as PaymentCurrency & { payment_method: PaymentMethod };
+
+        if (!paymentCurrency) {
+          throw new Error(`Currency ${paymentCurrencyId} not found`);
+        }
+
+        const rateSymbol = getExchangeRateSymbol(
+          paymentCurrency.symbol,
+          paymentCurrency.payment_method?.type as ChainType
+        );
+        rateResult = await exchangeRateService.getRate(rateSymbol);
+
+        slippagePercent =
+          normalizeSlippageConfigFromMetadata(checkoutSession.metadata, DEFAULT_SLIPPAGE_PERCENT)?.percent ??
+          DEFAULT_SLIPPAGE_PERCENT;
+
+        // ✅ Refresh quotes sequentially to avoid SQLite BUSY errors
+        // Using pAll with concurrency 1 ensures no concurrent writes to the database
+        const quoteService = getQuoteService();
+        try {
+          const refreshTasks = quotesNeedingRefresh.map(({ item, quoteRecord }) => {
+            return async () => {
+              logger.info('Auto-refreshing quote on backend', {
+                quoteId: quoteRecord.id,
+                status: quoteRecord.status,
+                lockActive,
+              });
+
+              const result = await quoteService.refreshQuoteWithRate({
+                quote_id: quoteRecord.id,
+                price_id: item.price_id,
+                session_id: checkoutSession.id,
+                invoice_id: undefined,
+                target_currency_id: paymentCurrencyId,
+                quantity: item.quantity || 1,
+                rateResult,
+                slippage_percent: slippagePercent,
+              });
+
+              return { quoteRecord, result };
+            };
+          });
+
+          // Use concurrency 1 to avoid SQLite BUSY errors
+          const refreshResults = await pAll(refreshTasks, { concurrency: 1 });
+
+          // Update quoteRecord references with refreshed data
+          refreshResults.forEach(({ quoteRecord, result }) => {
+            const refreshedQuote = result.quote;
+            logger.info('Quote auto-refreshed successfully on backend', {
+              quoteId: refreshedQuote.id,
+              newExpiresAt: refreshedQuote.expires_at,
+              newStatus: refreshedQuote.status,
+            });
+            Object.assign(quoteRecord, refreshedQuote.toJSON());
+          });
+        } catch (refreshError: any) {
+          logger.error('Failed to auto-refresh quotes on backend', {
+            error: refreshError.message,
+            quoteIds: quotesNeedingRefresh.map((q) => q.quoteRecord.id),
+          });
+          throw new CustomError(400, 'QUOTE_REFRESH_FAILED', 'Failed to refresh quote automatically');
+        }
+      }
+
+      // ✅ Validate all quotes (synchronous loop is fine for validation)
+      for (const item of dynamicItems) {
+        const quoteId = quoteMap.get(item.price_id);
+        if (!quoteId) {
+          throw new CustomError(400, 'QUOTE_REQUIRED');
+        }
+        const quoteRecord = quotesById.get(quoteId);
+        if (!quoteRecord) {
+          throw new CustomError(400, 'QUOTE_NOT_FOUND');
+        }
+        // Use effective price_id: upsell_price_id takes precedence (quote was created with upsell price)
+        const effectivePriceId = item.upsell_price_id || item.price_id;
+        if (quoteRecord.price_id !== effectivePriceId) {
+          throw new CustomError(400, 'QUOTE_PRICE_MISMATCH');
+        }
+        if (quoteRecord.target_currency_id !== paymentCurrencyId) {
+          throw new CustomError(400, 'QUOTE_CURRENCY_MISMATCH');
+        }
+        const price = (item.upsell_price || item.price) as any;
+        if (quoteRecord.base_currency !== price.base_currency) {
+          throw new CustomError(400, 'QUOTE_BASE_CURRENCY_MISMATCH');
+        }
+        if (quoteRecord.session_id && quoteRecord.session_id !== checkoutSession.id) {
+          throw new CustomError(400, 'QUOTE_SESSION_MISMATCH');
+        }
+
+        const expectedBaseAmount = calculateTotalBaseAmount(price.base_amount || '0', Number(item.quantity || 0));
+        const USD_DECIMALS = 8;
+        const expectedBaseAmountTrimmed = trimDecimals(expectedBaseAmount, USD_DECIMALS);
+        const quoteBaseAmountTrimmed = trimDecimals(quoteRecord.base_amount, USD_DECIMALS);
+        if (quoteBaseAmountTrimmed !== expectedBaseAmountTrimmed) {
+          throw new CustomError(
+            400,
+            'QUOTE_AMOUNT_MISMATCH',
+            `Quote amount mismatch for price ${item.price_id}. Expected ${expectedBaseAmountTrimmed} but got ${quoteBaseAmountTrimmed}. Please refresh the page.`
+          );
+        }
+
+        if (!isQuoteUsable(quoteRecord)) {
+          throw new CustomError(400, 'QUOTE_EXPIRED_OR_USED', 'Quote not usable');
+        }
+      }
+    } else {
+      logger.info('Auto-finding quotes for checkout session', { sessionId: checkoutSession.id });
+
+      // Find all active quotes for this session
+      // Use effective price_id: upsell_price_id takes precedence (quote was created with upsell price)
+      const priceIds = dynamicItems.map((item) => item.upsell_price_id || item.price_id);
+      quotes = await PriceQuote.findAll({
+        where: {
+          session_id: checkoutSession.id,
+          target_currency_id: paymentCurrencyId,
+          status: 'active',
+          expires_at: { [Op.gt]: Math.floor(Date.now() / 1000) },
+          price_id: { [Op.in]: priceIds },
+        },
+        order: [['created_at', 'DESC']], // Use latest quote if multiple exist
+      });
+
+      // Validate: each dynamic item must have a corresponding quote
+      // Pick the latest quote per price_id (query is ordered by created_at DESC)
+      const quotesByPriceId = new Map<string, PriceQuote>();
+      for (const quote of quotes) {
+        if (!quotesByPriceId.has(quote.price_id)) {
+          quotesByPriceId.set(quote.price_id, quote);
+        }
+      }
+      quotes = Array.from(quotesByPriceId.values());
+
+      for (const item of dynamicItems) {
+        const effectivePriceId = item.upsell_price_id || item.price_id;
+        const quote = quotesByPriceId.get(effectivePriceId);
+        if (!quote) {
+          throw new CustomError(
+            400,
+            'QUOTE_NOT_FOUND',
+            `No active quote found for price ${effectivePriceId}. Please refresh the page to generate a new quote.`
+          );
+        }
+
+        // Validate base_amount matches (quantity * unit_price)
+        // Use same precision calculation as quote creation
+        const price = (item.upsell_price || item.price) as any;
+        const expectedBaseAmount = calculateTotalBaseAmount(price.base_amount || '0', Number(item.quantity || 0));
+        const USD_DECIMALS = 8;
+        const expectedBaseAmountTrimmed = trimDecimals(expectedBaseAmount, USD_DECIMALS);
+        const quoteBaseAmountTrimmed = trimDecimals(quote.base_amount, USD_DECIMALS);
+        if (quoteBaseAmountTrimmed !== expectedBaseAmountTrimmed) {
+          throw new CustomError(
+            400,
+            'QUOTE_AMOUNT_MISMATCH',
+            `Quote amount mismatch for price ${item.price_id}. Expected ${expectedBaseAmountTrimmed} but got ${quoteBaseAmountTrimmed}. Please refresh the page.`
+          );
+        }
+      }
+
+      logger.info('Auto-found quotes successfully', {
+        sessionId: checkoutSession.id,
+        quoteCount: quotes.length,
+        quoteIds: quotes.map((q) => q.id),
+      });
+    }
+  } else {
+    // Legacy: use quotes provided by frontend (for backward compatibility)
+    logger.info('Using frontend-provided quotes', {
+      sessionId: checkoutSession.id,
+      quotesInput,
+    });
+
+    const quoteMap = new Map<string, string>();
+    quotesInput.forEach((x) => {
+      if (x.price_id && x.quote_id) {
+        quoteMap.set(x.price_id, x.quote_id);
+      }
+    });
+
+    if (quoteMap.size < dynamicItems.length) {
+      throw new CustomError(400, 'QUOTE_REQUIRED');
+    }
+
+    const quoteIds = Array.from(quoteMap.values());
+
+    // Step 1: Pre-validation outside transaction (fast fail)
+    quotes = await PriceQuote.findAll({
+      where: { id: quoteIds },
+    });
+    const quotesById = new Map(quotes.map((q) => [q.id, q]));
+
+    // Validate all quotes before starting transaction
+    for (const item of dynamicItems) {
+      const quoteId = quoteMap.get(item.price_id);
+      if (!quoteId) {
+        throw new CustomError(400, 'QUOTE_REQUIRED');
+      }
+
+      const quoteRecord = quotesById.get(quoteId);
+      if (!quoteRecord) {
+        throw new CustomError(400, 'QUOTE_NOT_FOUND');
+      }
+      // Use effective price_id: upsell_price_id takes precedence (quote was created with upsell price)
+      const effectivePriceId = item.upsell_price_id || item.price_id;
+      if (quoteRecord.price_id !== effectivePriceId) {
+        throw new CustomError(400, 'QUOTE_PRICE_MISMATCH');
+      }
+      if (quoteRecord.target_currency_id !== paymentCurrencyId) {
+        throw new CustomError(400, 'QUOTE_CURRENCY_MISMATCH');
+      }
+      const price = (item.upsell_price || item.price) as any;
+      if (quoteRecord.base_currency !== price.base_currency) {
+        throw new CustomError(400, 'QUOTE_BASE_CURRENCY_MISMATCH');
+      }
+      if (quoteRecord.session_id && quoteRecord.session_id !== checkoutSession.id) {
+        throw new CustomError(400, 'QUOTE_SESSION_MISMATCH');
+      }
+
+      if (quoteRecord.status === 'used' && !lockActive) {
+        throw new CustomError(409, 'QUOTE_LOCK_EXPIRED', 'Quote lock expired, please refresh and retry');
+      }
+
+      const expectedBaseAmount = calculateTotalBaseAmount(price.base_amount || '0', Number(item.quantity || 0));
+      const USD_DECIMALS = 8;
+      const expectedBaseAmountTrimmed = trimDecimals(expectedBaseAmount, USD_DECIMALS);
+      const quoteBaseAmountTrimmed = trimDecimals(quoteRecord.base_amount, USD_DECIMALS);
+      if (quoteBaseAmountTrimmed !== expectedBaseAmountTrimmed) {
+        throw new CustomError(
+          400,
+          'QUOTE_AMOUNT_MISMATCH',
+          `Quote amount mismatch for price ${item.price_id}. Expected ${expectedBaseAmountTrimmed} but got ${quoteBaseAmountTrimmed}. Please refresh the page.`
+        );
+      }
+
+      // Check if active
+      if (!isQuoteUsable(quoteRecord)) {
+        throw new CustomError(400, 'QUOTE_EXPIRED_OR_USED');
+      }
+    }
+  }
+
+  // Get quote IDs for locking
+  const quoteIds = quotes.map((q) => q.id);
+
+  // Step 2: Minimal transaction - batch update status only
+  const transaction = await sequelize.transaction();
+  const consumedQuotes: PriceQuote[] = [];
+
+  try {
+    // Re-fetch with lock and verify status didn't change
+    const lockedQuotes = await PriceQuote.findAll({
+      where: { id: quoteIds },
+      transaction,
+      lock: transaction.LOCK.UPDATE,
+    });
+    const lockedQuotesById = new Map(lockedQuotes.map((q) => [q.id, q]));
+
+    // Double-check all quotes are still active under lock
+    for (const quoteId of quoteIds) {
+      const quote = lockedQuotesById.get(quoteId) || null;
+      if (!isQuoteUsable(quote)) {
+        if (quote?.status === 'used' && !lockActive) {
+          throw new CustomError(409, 'QUOTE_LOCK_EXPIRED', 'Quote lock expired, please refresh and retry');
+        }
+        throw new CustomError(400, 'QUOTE_EXPIRED_OR_USED');
+      }
+    }
+
+    // Update quotes to 'used' with slippage snapshot
+    const updatedQuotes: PriceQuote[] = [];
+    // Sequential updates needed for transaction consistency
+    for (const quoteId of quoteIds) {
+      const quote = lockedQuotesById.get(quoteId);
+      if (quote) {
+        if (quote.status === 'used') {
+          updatedQuotes.push(quote);
+        } else {
+          const slippageSnapshot = buildSlippageSnapshot({ quote, checkoutSession });
+          const updatePayload: Record<string, any> = { status: 'used' };
+          if (slippageSnapshot) {
+            updatePayload.slippage_percent = slippageSnapshot.percent;
+            updatePayload.max_payable_token = slippageSnapshot.max_payable_token;
+            updatePayload.min_acceptable_rate = slippageSnapshot.min_acceptable_rate;
+            updatePayload.slippage_derived_at_ms = slippageSnapshot.derived_at_ms;
+            updatePayload.metadata = {
+              ...(quote.metadata || {}),
+              slippage: {
+                ...((quote.metadata as any)?.slippage || {}),
+                ...slippageSnapshot,
+              },
+            };
+          }
+          // eslint-disable-next-line no-await-in-loop
+          const updatedQuote = await updateQuoteWithRetry(quote, updatePayload, transaction);
+          updatedQuotes.push(updatedQuote);
+        }
+      }
+    }
+    consumedQuotes.push(...updatedQuotes);
+
+    await transaction.commit();
+
+    const quotesByPriceId = new Map(consumedQuotes.map((q) => [q.price_id, q]));
+    const enrichedLineItems = lineItems.map((item) => {
+      // Use effective price_id: upsell_price takes precedence (quote was created with upsell price)
+      const effectivePriceId = item.upsell_price?.id || item.price.id;
+      const quote = quotesByPriceId.get(effectivePriceId);
+      if (!quote) {
+        return item;
+      }
+      return {
+        ...item,
+        quote_id: quote.id,
+        quoted_amount: quote.quoted_amount,
+        expires_at: quote.expires_at,
+        exchange_rate: quote.exchange_rate,
+        rate_provider_name: quote.rate_provider_name,
+        rate_provider_id: quote.rate_provider_id,
+        custom_amount: quote.quoted_amount,
+        // Store the currency ID this quote was created for - essential for frontend validation
+        quote_currency_id: quote.target_currency_id,
+      };
+    });
+
+    return { lineItems: enrichedLineItems, consumedQuotes };
+  } catch (err) {
+    await transaction.rollback();
+    throw err;
+  }
+}
+
+async function lockCheckoutSessionQuotes(checkoutSession: CheckoutSession) {
+  const lockedAt = Math.floor(Date.now() / 1000);
+  const metadata = {
+    ...(checkoutSession.metadata || {}),
+    quote_locked_at: lockedAt,
+  };
+  await checkoutSession.update({ metadata });
+  checkoutSession.metadata = metadata;
+  return lockedAt;
+}
+
+/**
+ * @deprecated Final Freeze: Quotes are NO longer prefetched during session creation.
+ * Quotes are created ONLY at Submit time via createUsedQuoteWithValidation.
+ * This function is kept for backward compatibility but does nothing.
+ * @see Intent: blocklets/core/ai/intent/20260112-dynamic-price.md
+ */
+async function prefetchQuotesForCheckoutSession(checkoutSession: CheckoutSession) {
+  const expandedLineItems = await Price.expand(checkoutSession.line_items, { product: true, upsell: true });
+  const hasDynamic = expandedLineItems.some((item) => (item.upsell_price || item.price).pricing_type === 'dynamic');
+  if (!hasDynamic) {
+    return;
+  }
+
+  // Final Freeze: Don't prefetch/create Quotes during session creation
+  // Quotes are created ONLY at Submit time
+  logger.info('Skipping quote prefetch for checkout session (Final Freeze)', {
+    checkoutSessionId: checkoutSession.id,
+    hasDynamicPricing: true,
+  });
+}
+
 // submit order
 router.put('/:id/submit', user, ensureCheckoutSessionOpen, async (req, res) => {
+  let consumedQuotes: PriceQuote[] = [];
+  const checkoutSession = req.doc as CheckoutSession;
+
   try {
     if (!req.user) {
       return res.status(403).json({ code: 'REQUIRE_LOGIN', error: 'Please login to continue' });
     }
 
+    // Idempotency check: If already complete/paid, return existing state
+    if (checkoutSession.status === 'complete' || checkoutSession.payment_status === 'paid') {
+      await checkoutSession.reload();
+      const existingPaymentIntent = checkoutSession.payment_intent_id
+        ? await PaymentIntent.findByPk(checkoutSession.payment_intent_id)
+        : null;
+      const existingInvoice = checkoutSession.invoice_id
+        ? await Invoice.findOne({ where: { checkout_session_id: checkoutSession.id } })
+        : null;
+
+      const quoteIds = (existingPaymentIntent?.metadata as any)?.quoteIds || [];
+      const quotes = quoteIds.length > 0 ? await PriceQuote.findAll({ where: { id: quoteIds } }) : [];
+
+      return res.status(200).json({
+        checkoutSession,
+        paymentIntent: existingPaymentIntent,
+        invoice: existingInvoice,
+        quotes: quotes.map((q) => ({
+          id: q.id,
+          status: q.status,
+          quoted_amount: q.quoted_amount,
+          expires_at: q.expires_at,
+        })),
+        message: 'Checkout session already completed',
+      });
+    }
+
     const hasVendorConfig = await checkVendorConfig(req.doc.line_items);
     if (hasVendorConfig) {
       const { user: userDetail } = await blocklet.getUser(req.user.did, { enableConnectedAccount: true });
@@ -1450,7 +2512,6 @@ router.put('/:id/submit', user, ensureCheckoutSessionOpen, async (req, res) => {
       }
     }
 
-    const checkoutSession = req.doc as CheckoutSession;
     if (checkoutSession.line_items) {
       try {
         await validateInventory(checkoutSession.line_items);
@@ -1485,6 +2546,198 @@ router.put('/:id/submit', user, ensureCheckoutSessionOpen, async (req, res) => {
       metadata: { ...checkoutSession.metadata, preferred_locale: req.locale },
     });
 
+    const expandedLineItems = await Price.expand(checkoutSession.line_items, { product: true, upsell: true });
+    let lineItemsWithQuotes = expandedLineItems;
+
+    // Get trial status for subscription mode - needed to skip quote creation for trialing items
+    const submitNow = dayjs().unix();
+    const trialSetup = getSubscriptionTrialSetup(checkoutSession.subscription_data as any, paymentCurrency.id);
+    const isTrialing = trialSetup.trialInDays > 0 || trialSetup.trialEnd > submitNow;
+
+    // Check if using Final Freeze flow (idempotency_key provided)
+    const useFinalFreezeFlow = !!req.body.idempotency_key;
+
+    if (useFinalFreezeFlow) {
+      // Final Freeze: Create quotes at submit time with dual-layer validation
+      logger.info('Using Final Freeze quote creation flow', {
+        sessionId: checkoutSession.id,
+        idempotencyKey: req.body.idempotency_key,
+        isTrialing,
+      });
+
+      const quoteResult = await createQuotesAtSubmit({
+        checkoutSession,
+        lineItems: expandedLineItems,
+        paymentCurrencyId: paymentCurrency.id,
+        idempotencyKey: req.body.idempotency_key,
+        previewRate: req.body.preview_rate,
+        priceConfirmed: req.body.price_confirmed === true,
+        trialing: isTrialing,
+      });
+
+      // Handle validation errors (PRICE_UNAVAILABLE, PRICE_UNSTABLE, PRICE_CHANGED, RATE_BELOW_SLIPPAGE_LIMIT)
+      if (quoteResult.validationError) {
+        const { code, message, changePercent, currentRate, minAcceptableRate } = quoteResult.validationError;
+        // RATE_BELOW_SLIPPAGE_LIMIT: 400 - user needs to update slippage settings
+        // PRICE_CHANGED: 409 - price changed, needs confirmation
+        // PRICE_UNAVAILABLE/PRICE_UNSTABLE: 503 - service temporarily unavailable
+        let statusCode = 503;
+        if (code === 'RATE_BELOW_SLIPPAGE_LIMIT') {
+          statusCode = 400;
+        } else if (code === 'PRICE_CHANGED') {
+          statusCode = 409;
+        }
+        return res.status(statusCode).json({
+          code,
+          error: message,
+          change_percent: changePercent,
+          // Include extra data for PRICE_CHANGED to help frontend display confirmation dialog
+          ...(code === 'PRICE_CHANGED' && {
+            requires_confirmation: true,
+          }),
+          // Include rate info for RATE_BELOW_SLIPPAGE_LIMIT to help frontend display update dialog
+          ...(code === 'RATE_BELOW_SLIPPAGE_LIMIT' && {
+            current_rate: currentRate,
+            min_acceptable_rate: minAcceptableRate,
+          }),
+        });
+      }
+
+      consumedQuotes = quoteResult.consumedQuotes;
+      lineItemsWithQuotes = quoteResult.lineItems;
+
+      if (consumedQuotes.length) {
+        await lockCheckoutSessionQuotes(checkoutSession);
+      }
+    } else {
+      // Legacy flow: Use pre-created quotes
+      try {
+        const quoteResult = await attachQuotesToLineItems({
+          checkoutSession,
+          lineItems: expandedLineItems,
+          paymentCurrencyId: paymentCurrency.id,
+          quotesInput: req.body.quotes,
+          strict: true,
+        });
+        consumedQuotes = quoteResult.consumedQuotes;
+        lineItemsWithQuotes = quoteResult.lineItems;
+        if (consumedQuotes.length) {
+          await lockCheckoutSessionQuotes(checkoutSession);
+        }
+      } catch (err) {
+        if (err instanceof CustomError) {
+          const errCode = getQuoteErrorCode(err) || err.code || 'QUOTE_INVALID';
+          if (
+            [
+              'QUOTE_AMOUNT_MISMATCH',
+              'QUOTE_EXPIRED_OR_USED',
+              'QUOTE_NOT_FOUND',
+              'QUOTE_REQUIRED',
+              'QUOTE_LOCK_EXPIRED',
+            ].includes(String(errCode))
+          ) {
+            return res.status(409).json({ code: String(errCode), error: err.message });
+          }
+          return res.status(400).json({ code: String(errCode), error: err.message });
+        }
+        throw err;
+      }
+    }
+
+    // Save quote_id and quote_currency_id to CheckoutSession.line_items for future reference
+    // Preserve all existing fields in line_items, but update quote-related fields
+    // Quote data is the single source of truth in PriceQuote table
+    // Also update metadata.slippage with min_acceptable_rate for subscription creation
+    const quoteWithMinRate = consumedQuotes.find((q) => q.min_acceptable_rate);
+    let updatedMetadata = checkoutSession.metadata;
+
+    if (quoteWithMinRate) {
+      // Use min_acceptable_rate from quote
+      updatedMetadata = {
+        ...(checkoutSession.metadata || {}),
+        slippage: {
+          ...((checkoutSession.metadata as any)?.slippage || {}),
+          mode: 'rate', // Use 'rate' mode so buildSlippageConfig will include min_acceptable_rate
+          min_acceptable_rate: quoteWithMinRate.min_acceptable_rate,
+          percent: quoteWithMinRate.slippage_percent ?? 0.5,
+          updated_at_ms: Date.now(),
+        },
+      };
+    } else {
+      // No quote (e.g., trial period) - calculate min_acceptable_rate from current rate if needed
+      const existingSlippage = (checkoutSession.metadata as any)?.slippage;
+      const hasDynamicPricing = expandedLineItems.some(
+        (item) => ((item.upsell_price || item.price) as any)?.pricing_type === 'dynamic'
+      );
+
+      // If dynamic pricing and no min_acceptable_rate yet, calculate from current rate
+      if (hasDynamicPricing && existingSlippage && !existingSlippage.min_acceptable_rate) {
+        try {
+          const rateResult = await fetchCurrentExchangeRate(paymentCurrency, paymentMethod);
+          if (rateResult?.rate) {
+            const rate = Number(rateResult.rate);
+            const percent = existingSlippage.percent ?? DEFAULT_SLIPPAGE_PERCENT;
+            if (Number.isFinite(rate) && rate > 0) {
+              // min_rate = rate / (1 + percent/100)
+              const minRate = rate / (1 + percent / 100);
+              updatedMetadata = {
+                ...(checkoutSession.metadata || {}),
+                slippage: {
+                  ...existingSlippage,
+                  min_acceptable_rate: minRate.toFixed(8).replace(/\.?0+$/, ''),
+                  base_currency: 'USD', // Exchange rates are always USD-based
+                  updated_at_ms: Date.now(),
+                },
+              };
+              logger.info('Calculated min_acceptable_rate for trial subscription', {
+                sessionId: checkoutSession.id,
+                currentRate: rateResult.rate,
+                percent,
+                minAcceptableRate: (updatedMetadata as any).slippage.min_acceptable_rate,
+              });
+            }
+          }
+        } catch (error: any) {
+          logger.warn('Failed to fetch rate for min_acceptable_rate calculation', {
+            sessionId: checkoutSession.id,
+            error: error.message,
+          });
+          // Continue without min_acceptable_rate - not a fatal error
+        }
+      }
+    }
+
+    await checkoutSession.update({
+      metadata: updatedMetadata,
+      line_items: lineItemsWithQuotes.map((item) => {
+        const baseItem = checkoutSession.line_items.find((li: any) => li.price_id === item.price_id);
+        const quoteId = (item as any).quote_id || (baseItem as any)?.quote_id;
+        const quoteCurrencyId = (item as any).quote_currency_id || (baseItem as any)?.quote_currency_id;
+        const result: any = {
+          ...baseItem, // Preserve all original fields
+        };
+        if (quoteId) {
+          result.quote_id = String(quoteId); // Ensure quote_id is string
+          // Also save quote_currency_id so backend can validate custom_amount against currency
+          if (quoteCurrencyId) {
+            result.quote_currency_id = quoteCurrencyId;
+          }
+          // Update custom_amount from the new quote if available
+          if ((item as any).custom_amount) {
+            result.custom_amount = (item as any).custom_amount;
+          }
+        }
+        return result as LineItem;
+      }) as LineItem[],
+    });
+
+    logger.info('Saved quote_id references to checkout session line_items', {
+      checkoutSessionId: checkoutSession.id,
+      lineItemsCount: lineItemsWithQuotes.length,
+      quoteIds: consumedQuotes.map((q) => q.id),
+      savedMinAcceptableRate: quoteWithMinRate?.min_acceptable_rate,
+    });
+
     let customer = await Customer.findOne({ where: { did: req.user.did } });
     if (!customer) {
       const { user: userInfo } = await blocklet.getUser(req.user.did);
@@ -1605,7 +2858,10 @@ router.put('/:id/submit', user, ensureCheckoutSessionOpen, async (req, res) => {
     const { lineItems, trialInDays, trialEnd, now } = await calculateAndUpdateAmount(
       checkoutSession,
       paymentCurrency.id,
-      true
+      true,
+      {
+        lineItemsOverride: lineItemsWithQuotes,
+      }
     );
 
     // Validate payment amounts meet minimum requirements
@@ -1656,7 +2912,9 @@ router.put('/:id/submit', user, ensureCheckoutSessionOpen, async (req, res) => {
         paymentCurrency,
         lineItems,
         customer.id,
-        customer.email
+        customer.email,
+        undefined,
+        { quoteIds: consumedQuotes.map((q) => q.id) }
       );
       paymentIntent = result.paymentIntent;
 
@@ -1683,6 +2941,11 @@ router.put('/:id/submit', user, ensureCheckoutSessionOpen, async (req, res) => {
           });
         }
       }
+
+      if (paymentIntent?.status === 'succeeded' && paymentIntent.invoice_id) {
+        const quoteService = getQuoteService();
+        await quoteService.markQuotesAsPaidByInvoice(paymentIntent.invoice_id);
+      }
     }
 
     // SetupIntent processing
@@ -1836,11 +3099,21 @@ router.put('/:id/submit', user, ensureCheckoutSessionOpen, async (req, res) => {
       }
     }
 
+    // Calculate actual current payment amount (excludes future renewals)
+    const trialing = trialInDays > 0 || trialEnd > now;
+    const { total: currentPaymentTotal } = await getCheckoutAmount(
+      lineItems,
+      paymentCurrency.id,
+      trialing,
+      discountConfig
+    );
+    const noPaymentRequired = currentPaymentTotal === '0';
+
     const fastCheckoutAmount = await getFastCheckoutAmount({
       items: lineItems,
       mode: checkoutSession.mode,
       currencyId: paymentCurrency.id,
-      trialing: trialInDays > 0 || trialEnd > now,
+      trialing,
       minimumCycle: 1,
       discountConfig,
     });
@@ -2052,8 +3325,31 @@ router.put('/:id/submit', user, ensureCheckoutSessionOpen, async (req, res) => {
       balance: canFastPay ? balance : null,
       fastPayInfo,
       creditSufficient,
+      noPaymentRequired,
     });
   } catch (err) {
+    if (consumedQuotes.length) {
+      const quoteService = getQuoteService();
+      await Promise.all(
+        consumedQuotes.map((q) =>
+          quoteService.markAsPaymentFailed(q.id).catch((error) =>
+            logger.error('Failed to mark quote as payment failed', {
+              quoteId: q.id,
+              sessionId: req.params.id,
+              error: error.message,
+            })
+          )
+        )
+      );
+    }
+    if (err instanceof CustomError) {
+      if (err.code === 'RATE_UNAVAILABLE') {
+        return res.status(503).json({ code: err.code, error: err.message });
+      }
+      if (['QUOTE_LOCK_EXPIRED'].includes(String(err.code))) {
+        return res.status(409).json({ code: String(err.code), error: err.message });
+      }
+    }
     logger.error('Error submitting checkout session', {
       sessionId: req.params.id,
       error: err,
@@ -2065,6 +3361,7 @@ router.put('/:id/submit', user, ensureCheckoutSessionOpen, async (req, res) => {
 
 // 打赏（不强制登录）
 router.put('/:id/donate-submit', ensureCheckoutSessionOpen, async (req, res) => {
+  let consumedQuotes: PriceQuote[] = [];
   try {
     const checkoutSession = req.doc as CheckoutSession;
     if (!isDonationCheckoutSession(checkoutSession)) {
@@ -2102,16 +3399,60 @@ router.put('/:id/donate-submit', ensureCheckoutSessionOpen, async (req, res) =>
     );
     await checkoutSession.update({ currency_id: paymentCurrency.id });
 
+    const expandedLineItems = await Price.expand(checkoutSession.line_items, { product: true, upsell: true });
+    let lineItemsWithQuotes = expandedLineItems;
+    try {
+      const quoteResult = await attachQuotesToLineItems({
+        checkoutSession,
+        lineItems: expandedLineItems,
+        paymentCurrencyId: paymentCurrency.id,
+        quotesInput: req.body.quotes,
+        strict: true,
+      });
+      consumedQuotes = quoteResult.consumedQuotes;
+      lineItemsWithQuotes = quoteResult.lineItems;
+      if (consumedQuotes.length) {
+        await lockCheckoutSessionQuotes(checkoutSession);
+      }
+    } catch (err) {
+      if (err instanceof CustomError) {
+        const errCode = String(getQuoteErrorCode(err) || err.code || 'QUOTE_INVALID');
+        if (
+          [
+            'QUOTE_AMOUNT_MISMATCH',
+            'QUOTE_EXPIRED_OR_USED',
+            'QUOTE_NOT_FOUND',
+            'QUOTE_REQUIRED',
+            'QUOTE_LOCK_EXPIRED',
+          ].includes(errCode)
+        ) {
+          return res.status(409).json({ code: errCode, error: err.message });
+        }
+        return res.status(400).json({ code: errCode, error: err.message });
+      }
+      throw err;
+    }
+
     // calculate amount and update checkout session
-    const { lineItems } = await calculateAndUpdateAmount(checkoutSession, paymentCurrency.id, false);
+    const { lineItems } = await calculateAndUpdateAmount(checkoutSession, paymentCurrency.id, false, {
+      lineItemsOverride: lineItemsWithQuotes,
+    });
 
     const { paymentIntent } = await createOrUpdatePaymentIntent(
       checkoutSession,
       paymentMethod,
       paymentCurrency,
-      lineItems
+      lineItems,
+      undefined,
+      undefined,
+      { quoteIds: consumedQuotes.map((q) => q.id) }
     );
 
+    if (paymentIntent?.status === 'succeeded' && paymentIntent.invoice_id) {
+      const quoteService = getQuoteService();
+      await quoteService.markQuotesAsPaidByInvoice(paymentIntent.invoice_id);
+    }
+
     return res.json({
       paymentIntent,
       checkoutSession,
@@ -2120,6 +3461,28 @@ router.put('/:id/donate-submit', ensureCheckoutSessionOpen, async (req, res) =>
       formData: req.body,
     });
   } catch (err) {
+    if (consumedQuotes.length) {
+      const quoteService = getQuoteService();
+      await Promise.all(
+        consumedQuotes.map((q) =>
+          quoteService.markAsPaymentFailed(q.id).catch((error) =>
+            logger.error('Failed to mark quote as payment failed', {
+              quoteId: q.id,
+              sessionId: req.params.id,
+              error: error.message,
+            })
+          )
+        )
+      );
+    }
+    if (err instanceof CustomError) {
+      if (err.code === 'RATE_UNAVAILABLE') {
+        return res.status(503).json({ code: err.code, error: err.message });
+      }
+      if (['QUOTE_LOCK_EXPIRED'].includes(String(err.code))) {
+        return res.status(409).json({ code: String(err.code), error: err.message });
+      }
+    }
     logger.error('Error processing donation submission', {
       sessionId: req.params.id,
       error: err.message,
@@ -2130,6 +3493,7 @@ router.put('/:id/donate-submit', ensureCheckoutSessionOpen, async (req, res) =>
 });
 
 router.post('/:id/fast-checkout-confirm', user, ensureCheckoutSessionOpen, async (req, res) => {
+  let consumedQuotes: PriceQuote[] = [];
   try {
     if (!req.user) {
       return res.status(403).json({ code: 'REQUIRE_LOGIN', error: 'Please login to continue' });
@@ -2197,10 +3561,47 @@ router.post('/:id/fast-checkout-confirm', user, ensureCheckoutSessionOpen, async
       });
     }
 
+    const expandedLineItems = await Price.expand(checkoutSession.line_items, { product: true, upsell: true });
+    let lineItemsWithQuotes = expandedLineItems;
+    try {
+      const quoteResult = await attachQuotesToLineItems({
+        checkoutSession,
+        lineItems: expandedLineItems,
+        paymentCurrencyId: paymentCurrency.id,
+        quotesInput: req.body.quotes,
+        strict: true,
+      });
+      consumedQuotes = quoteResult.consumedQuotes;
+      lineItemsWithQuotes = quoteResult.lineItems;
+      if (consumedQuotes.length) {
+        await lockCheckoutSessionQuotes(checkoutSession);
+      }
+    } catch (err) {
+      if (err instanceof CustomError) {
+        const errCode = String(getQuoteErrorCode(err) || err.code || 'QUOTE_INVALID');
+        if (
+          [
+            'QUOTE_AMOUNT_MISMATCH',
+            'QUOTE_EXPIRED_OR_USED',
+            'QUOTE_NOT_FOUND',
+            'QUOTE_REQUIRED',
+            'QUOTE_LOCK_EXPIRED',
+          ].includes(errCode)
+        ) {
+          return res.status(409).json({ code: errCode, error: err.message });
+        }
+        return res.status(400).json({ code: errCode, error: err.message });
+      }
+      throw err;
+    }
+
     const { lineItems, trialInDays, trialEnd, now } = await calculateAndUpdateAmount(
       checkoutSession,
       paymentCurrency.id,
-      true
+      true,
+      {
+        lineItemsOverride: lineItemsWithQuotes,
+      }
     );
 
     let paymentIntent: PaymentIntent | null = null;
@@ -2211,7 +3612,9 @@ router.post('/:id/fast-checkout-confirm', user, ensureCheckoutSessionOpen, async
         paymentCurrency,
         lineItems,
         customer.id,
-        customer.email
+        customer.email,
+        undefined,
+        { quoteIds: consumedQuotes.map((q) => q.id) }
       );
       paymentIntent = result.paymentIntent;
     }
@@ -2378,6 +3781,11 @@ router.post('/:id/fast-checkout-confirm', user, ensureCheckoutSessionOpen, async
       return res.status(400).json({ error: 'Payment method not supported for fast checkout' });
     }
 
+    if (paymentIntent?.status === 'succeeded' && paymentIntent?.invoice_id) {
+      const quoteService = getQuoteService();
+      await quoteService.markQuotesAsPaidByInvoice(paymentIntent.invoice_id);
+    }
+
     logger.info('Checkout session submitted successfully', {
       sessionId: req.params.id,
       paymentIntentId: paymentIntent?.id,
@@ -2391,6 +3799,28 @@ router.post('/:id/fast-checkout-confirm', user, ensureCheckoutSessionOpen, async
       fastPaid,
     });
   } catch (err) {
+    if (consumedQuotes.length) {
+      const quoteService = getQuoteService();
+      await Promise.all(
+        consumedQuotes.map((q) =>
+          quoteService.markAsPaymentFailed(q.id).catch((error) =>
+            logger.error('Failed to mark quote as payment failed', {
+              quoteId: q.id,
+              sessionId: req.params.id,
+              error: error.message,
+            })
+          )
+        )
+      );
+    }
+    if (err instanceof CustomError) {
+      if (err.code === 'RATE_UNAVAILABLE') {
+        return res.status(503).json({ code: err.code, error: err.message });
+      }
+      if (['QUOTE_LOCK_EXPIRED'].includes(String(err.code))) {
+        return res.status(409).json({ code: String(err.code), error: err.message });
+      }
+    }
     logger.error('Error confirming fast checkout', {
       sessionId: req.params.id,
       error: err.message,
@@ -2494,7 +3924,7 @@ router.put('/:id/downsell', user, ensureCheckoutSessionOpen, async (req, res) =>
 router.put('/:id/adjust-quantity', user, ensureCheckoutSessionOpen, async (req, res) => {
   try {
     const checkoutSession = req.doc as CheckoutSession;
-    const { itemId, quantity } = req.body;
+    const { itemId, quantity, currency_id: currencyIdInput } = req.body;
     if (!checkoutSession.line_items) {
       return res.status(400).json({ error: 'Line items not found' });
     }
@@ -2503,15 +3933,59 @@ router.put('/:id/adjust-quantity', user, ensureCheckoutSessionOpen, async (req,
     if (!item) {
       return res.status(400).json({ error: 'Item not found' });
     }
-    const items = cloneDeep(checkoutSession.line_items);
-    const targetItem = items.find((x) => x.price_id === itemId);
+
+    // Final Freeze: When adjusting quantity, clear all quote-related fields
+    // Quote will be created only at Submit time
+    const items = cloneDeep(checkoutSession.line_items).map((lineItem: any) => {
+      const cleaned = { ...lineItem };
+      // Clear quote-related fields - price will be calculated by frontend using live rate
+      delete cleaned.quote_id;
+      delete cleaned.quoted_amount;
+      delete cleaned.custom_amount;
+      delete cleaned.exchange_rate;
+      delete cleaned.rate_provider_name;
+      delete cleaned.rate_provider_id;
+      delete cleaned.rate_timestamp_ms;
+      delete cleaned.expires_at;
+      delete cleaned.quote_currency_id;
+      return cleaned;
+    });
+
+    const targetItem = items.find((x: any) => x.price_id === itemId);
     if (targetItem) {
       targetItem.quantity = quantity;
     }
     await validateInventory(items, true);
-    await checkoutSession.update({ line_items: items });
-    const lineItems = await Price.expand(checkoutSession.line_items);
-    res.json({ ...checkoutSession.toJSON(), line_items: lineItems });
+
+    // Build update payload - clear quote_locked_at since we're in preview mode
+    const updatePayload: { line_items: any; currency_id?: string; metadata?: any } = { line_items: items };
+    if (currencyIdInput && currencyIdInput !== checkoutSession.currency_id) {
+      updatePayload.currency_id = currencyIdInput;
+    }
+    // Clear quote lock since quantity changed
+    if (checkoutSession.metadata?.quote_locked_at) {
+      updatePayload.metadata = { ...checkoutSession.metadata, quote_locked_at: undefined };
+    }
+    await checkoutSession.update(updatePayload);
+
+    // Also clear quote_locked_at on payment intent if exists
+    if (checkoutSession.payment_intent_id) {
+      const paymentIntent = await PaymentIntent.findByPk(checkoutSession.payment_intent_id);
+      if (paymentIntent?.quote_locked_at) {
+        await paymentIntent.update({ quote_locked_at: undefined });
+      }
+    }
+
+    // Expand line items for response (no quote enrichment needed - frontend uses live rate)
+    const lineItems = await Price.expand(checkoutSession.line_items, { upsell: true });
+
+    logger.info('Adjusted quantity and cleared quote data', {
+      checkoutSessionId: checkoutSession.id,
+      itemId,
+      quantity,
+    });
+
+    res.json({ ...checkoutSession.toJSON(), line_items: lineItems, quotes: {}, rateUnavailable: false });
   } catch (err) {
     logger.error(err);
     res.status(400).json({ error: err.message });
@@ -2687,9 +4161,19 @@ router.post('/:id/apply-promotion', user, ensureCheckoutSessionOpen, async (req,
     }
 
     const checkoutItems = checkoutSession.line_items || [];
-    // Get line items
+    // Get line items with quote data for accurate discount calculation
     const expandedItems = await Price.expand(checkoutSession.line_items || [], { product: true, upsell: true });
 
+    // Enrich line items with quote data for dynamic pricing
+    // This ensures discount calculation uses the same amounts as the actual payment
+    const quoteResult = await enrichCheckoutSessionWithQuotes(
+      checkoutSession,
+      expandedItems,
+      curCurrencyId,
+      { skipGeneration: true } // Don't generate new quotes, just use existing ones
+    );
+    const itemsWithQuotes = quoteResult.lineItems;
+
     // Calculate trial status for discount application (same logic as in calculateAndUpdateAmount)
     const now = dayjs().unix();
     const trialSetup = getSubscriptionTrialSetup(checkoutSession.subscription_data as any, currency.id);
@@ -2697,7 +4181,7 @@ router.post('/:id/apply-promotion', user, ensureCheckoutSessionOpen, async (req,
 
     // Apply discount using our new function
     const discountResult = await applyDiscountsToLineItems({
-      lineItems: expandedItems,
+      lineItems: itemsWithQuotes,
       promotionCodeId: foundPromotionCode.id,
       couponId: foundPromotionCode.coupon_id,
       customerId: customer.id,
@@ -2818,7 +4302,7 @@ router.post('/:id/recalculate-promotion', user, ensureCheckoutSessionOpen, async
     }
 
     const checkoutItems = checkoutSession.line_items || [];
-    // Get line items
+    // Get line items - no need for quote data since frontend calculates discount amounts
     const expandedItems = await Price.expand(checkoutSession.line_items || [], { product: true, upsell: true });
 
     // Get the first discount (assuming only one promotion code at a time)
@@ -2848,27 +4332,13 @@ router.post('/:id/recalculate-promotion', user, ensureCheckoutSessionOpen, async
       return res.status(400).json({ error: 'Coupon no longer valid' });
     }
 
-    const now = dayjs().unix();
-    const trialSetup = getSubscriptionTrialSetup(checkoutSession.subscription_data as any, currency.id);
-    const isTrialing = trialSetup.trialInDays > 0 || trialSetup.trialEnd > now;
-
-    // Apply discount with new currency
-    const discountResult = await applyDiscountsToLineItems({
-      lineItems: expandedItems,
-      promotionCodeId,
-      couponId,
-      customerId: customer.id,
-      currency,
-      billingContext: {
-        trialing: isTrialing,
-      },
-    });
-
-    // Check if discount can still be applied with the new currency
-    if (!discountResult.discountSummary.appliedCoupon) {
-      // Calculate original total without discount (finalTotal when no discount is applied)
-      const originalTotal = discountResult.discountSummary.finalTotal;
+    // Check if coupon can be applied with the new currency (for fixed amount coupons)
+    const canApplyWithCurrency =
+      coupon.percent_off > 0 || // Percentage discounts always work
+      coupon.currency_id === currency.id || // Same currency
+      coupon.currency_options?.[currency.id]?.amount_off; // Has currency option
 
+    if (!canApplyWithCurrency) {
       // Remove discount if it can't be applied with new currency
       await checkoutSession.update({
         discounts: [],
@@ -2876,15 +4346,11 @@ router.post('/:id/recalculate-promotion', user, ensureCheckoutSessionOpen, async
           const cur = checkoutItems.find((x) => x.price_id === item.price_id) as LineItem;
           return {
             ...cur,
+            discountable: false,
+            discount_amounts: [],
           };
         }),
         currency_id: newCurrencyId,
-        amount_subtotal: originalTotal,
-        amount_total: originalTotal,
-        total_details: {
-          ...checkoutSession.total_details,
-          amount_discount: '0',
-        },
         metadata: {
           ...omit(checkoutSession.metadata, ['promotion_code']),
         },
@@ -2906,57 +4372,52 @@ router.post('/:id/recalculate-promotion', user, ensureCheckoutSessionOpen, async
       });
     }
 
-    // Create updated discount configuration
+    // Mark which items are discountable based on coupon product restrictions
+    const enhancedLineItems = expandedItems.map((item) => {
+      const isDiscountable =
+        !coupon.applies_to?.products?.length ||
+        coupon.applies_to.products.some((productId: string) => item.price?.product_id === productId);
+
+      const cur = checkoutItems.find((x) => x.price_id === item.price_id) as LineItem;
+      return {
+        ...cur,
+        discountable: isDiscountable,
+        discount_amounts: [], // Frontend will calculate actual amounts
+      };
+    });
+
+    // Create updated discount configuration - NO discount_amount, frontend calculates it
     const discountConfig = {
       promotion_code: promotionCodeId,
       coupon: couponId,
-      discount_amount: discountResult.discountSummary.totalDiscountAmount,
+      // discount_amount removed - frontend calculates based on live exchange rate
       verification_method: existingDiscount.verification_method,
       verification_data: existingDiscount.verification_data,
     };
 
-    // Update checkout session with recalculated discount
+    // Update checkout session with discountable flags only
     await checkoutSession.update({
       discounts: [discountConfig],
-      line_items: discountResult.enhancedLineItems.map((item: TLineItemExpanded) => {
-        const cur = checkoutItems.find((x) => x.price_id === item.price_id) as LineItem;
-        return {
-          ...cur,
-          discountable: item.discountable,
-          discount_amounts: item.discount_amounts,
-        };
-      }),
+      line_items: enhancedLineItems,
       currency_id: newCurrencyId,
-      amount_subtotal: checkoutSession.amount_total, // Original amount
-      amount_total: discountResult.discountSummary.finalTotal, // Discounted amount
-      total_details: {
-        ...checkoutSession.total_details,
-        amount_discount: discountResult.discountSummary.totalDiscountAmount,
-      },
     });
 
-    // Create enhanced line items with complete coupon information for response
-    const enhancedLineItemsWithCoupon = await expandLineItemsWithCouponInfo(
-      discountResult.enhancedLineItems,
-      [discountConfig],
-      currency.id
-    );
-
-    logger.info('Promotion code recalculated for new currency', {
+    logger.info('Promotion code validated for new currency (frontend calculates amount)', {
       sessionId: checkoutSession.id,
       oldCurrencyId: checkoutSession.currency_id,
       newCurrencyId,
       promotionCode: foundPromotionCode.code,
-      oldDiscountAmount: existingDiscount?.discount_amount || '0',
-      newDiscountAmount: discountResult.discountSummary.totalDiscountAmount,
     });
 
-    // Expand discounts with complete details for response
+    // Expand discounts with complete details for response (coupon_details for frontend calculation)
     const enhancedDiscounts = await expandDiscountsWithDetails([discountConfig]);
 
+    // Expand line items for response
+    const responseItems = await Price.expand(enhancedLineItems, { product: true, upsell: true });
+
     res.json({
       ...checkoutSession.toJSON(),
-      line_items: enhancedLineItemsWithCoupon,
+      line_items: responseItems,
       discounts: enhancedDiscounts,
       discount_applied: true,
       discount_recalculated: true,
@@ -3288,4 +4749,192 @@ router.put('/:id', auth, async (req, res) => {
   res.json(doc);
 });
 
+router.put('/:id/slippage', user, ensureCheckoutSessionOpen, async (req, res) => {
+  try {
+    const checkoutSession = req.doc as CheckoutSession;
+    const { slippage_percent: slippagePercent } = req.body;
+    const rawConfig = req.body?.slippage_config || req.body?.slippage || null;
+
+    const normalizePercent = (value: any) => {
+      const normalized = typeof value === 'string' ? Number(value) : value;
+      // Only validate that it's a non-negative finite number, no upper limit
+      if (!Number.isFinite(normalized) || normalized < 0) {
+        return null;
+      }
+      return normalized;
+    };
+
+    let config: any = null;
+    if (rawConfig && typeof rawConfig === 'object') {
+      const mode = rawConfig.mode === 'rate' ? 'rate' : 'percent';
+      const minRate = rawConfig.min_acceptable_rate ?? rawConfig.minAcceptableRate;
+
+      // For rate mode, min_acceptable_rate is required; percent is derived
+      if (mode === 'rate') {
+        if (minRate === undefined || minRate === null || minRate === '') {
+          return res.status(400).json({ error: 'min_acceptable_rate is required for rate mode' });
+        }
+        // Accept any non-negative percent value for rate mode (calculated from rate)
+        const percent = normalizePercent(rawConfig.percent);
+        const baseCurrency = rawConfig.base_currency ?? rawConfig.baseCurrency;
+        config = {
+          mode,
+          percent: percent ?? 0,
+          min_acceptable_rate: String(minRate),
+          ...(baseCurrency ? { base_currency: String(baseCurrency) } : {}),
+          updated_at_ms: Date.now(),
+        };
+      } else {
+        // Percent mode: validate percent
+        const percent = normalizePercent(rawConfig.percent);
+        if (percent === null) {
+          return res.status(400).json({ error: 'slippage_percent must be a non-negative number' });
+        }
+        const baseCurrency = rawConfig.base_currency ?? rawConfig.baseCurrency;
+        config = {
+          mode,
+          percent,
+          // Also save min_acceptable_rate if provided (calculated by frontend from current rate)
+          ...(minRate ? { min_acceptable_rate: String(minRate) } : {}),
+          ...(baseCurrency ? { base_currency: String(baseCurrency) } : {}),
+          updated_at_ms: Date.now(),
+        };
+      }
+    } else if (slippagePercent !== undefined && slippagePercent !== null) {
+      const slippageValue = normalizePercent(slippagePercent);
+      if (slippageValue === null) {
+        return res.status(400).json({ error: 'slippage_percent must be a non-negative number' });
+      }
+      config = {
+        mode: 'percent',
+        percent: slippageValue,
+        updated_at_ms: Date.now(),
+      };
+    } else {
+      return res.status(400).json({ error: 'slippage config is required' });
+    }
+
+    const nextMetadata = {
+      ...(checkoutSession.metadata || {}),
+      slippage: config,
+    };
+    await checkoutSession.update({ metadata: nextMetadata });
+    logger.info('Checkout session slippage updated', {
+      sessionId: checkoutSession.id,
+      slippageConfig: config,
+    });
+
+    // Final Freeze: Don't create Quotes during Preview (slippage change)
+    // Slippage is applied at Submit time when Quote is created
+    const items = await Price.expand(checkoutSession.line_items, { upsell: true });
+    const enriched = await enrichCheckoutSessionWithQuotes(checkoutSession, items, checkoutSession.currency_id, {
+      skipGeneration: true, // Final Freeze: Don't create quotes during Preview
+    });
+
+    res.json({
+      ...checkoutSession.toJSON(),
+      line_items: enriched.lineItems,
+      quotes: enriched.quotes,
+      rateUnavailable: enriched.rateUnavailable,
+      rateError: enriched.rateError,
+    });
+  } catch (err) {
+    logger.error('Error updating checkout session slippage', {
+      sessionId: req.params.id,
+      error: err,
+    });
+    if (err instanceof CustomError) {
+      return res.status(getStatusFromError(err)).json({ code: err.code, error: err.message });
+    }
+    res.status(500).json({ error: err.message });
+  }
+});
+
+/**
+ * Switch payment currency for checkout session
+ * This endpoint clears quote-related fields when currency changes
+ * because quotes are currency-specific (e.g., TBA quote amount with 18 decimals
+ * cannot be used for USD with 2 decimals)
+ */
+router.put('/:id/switch-currency', user, ensureCheckoutSessionOpen, async (req, res) => {
+  try {
+    const checkoutSession = req.doc as CheckoutSession;
+    const { currency_id: newCurrencyId } = req.body;
+
+    if (!newCurrencyId) {
+      return res.status(400).json({ error: 'currency_id is required' });
+    }
+
+    // Validate the new currency exists
+    const newCurrency = await PaymentCurrency.findByPk(newCurrencyId);
+    if (!newCurrency) {
+      return res.status(400).json({ error: 'Currency not found' });
+    }
+
+    const oldCurrencyId = checkoutSession.currency_id;
+    const currencyChanged = oldCurrencyId && oldCurrencyId !== newCurrencyId;
+
+    if (currencyChanged) {
+      // Clear quote-related fields from line_items
+      const cleanedLineItems = checkoutSession.line_items.map((item: any) => {
+        const {
+          quote_id: quoteId,
+          quoted_amount: quotedAmount,
+          custom_amount: customAmount,
+          quote_currency_id: quoteCurrencyId,
+          ...rest
+        } = item;
+        return rest;
+      });
+
+      // Clear discount amounts - they will be recalculated by recalculate-promotion
+      // This prevents showing stale values (e.g., ABT units when switching to USD)
+      const cleanedDiscounts = checkoutSession.discounts?.map((discount: any) => ({
+        ...discount,
+        discount_amount: null, // Will be recalculated
+      }));
+
+      await checkoutSession.update({
+        line_items: cleanedLineItems,
+        currency_id: newCurrencyId,
+        discounts: cleanedDiscounts,
+        total_details: {
+          ...checkoutSession.total_details,
+          amount_discount: '0', // Clear until recalculated
+        },
+      });
+
+      logger.info('Cleared quote-related fields due to currency switch', {
+        checkoutSessionId: checkoutSession.id,
+        oldCurrencyId,
+        newCurrencyId,
+      });
+    } else {
+      // Just update the currency_id if it's the same (first time setting)
+      await checkoutSession.update({
+        currency_id: newCurrencyId,
+      });
+    }
+
+    // Reload and expand line items
+    await checkoutSession.reload();
+    const expandedLineItems = await Price.expand(checkoutSession.line_items, { product: true, upsell: true });
+
+    res.json({
+      ...checkoutSession.toJSON(),
+      line_items: expandedLineItems,
+      currency_changed: currencyChanged,
+    });
+  } catch (err) {
+    logger.error('Error switching checkout session currency', {
+      sessionId: req.params.id,
+      error: err,
+    });
+    if (err instanceof CustomError) {
+      return res.status(getStatusFromError(err)).json({ code: err.code, error: err.message });
+    }
+    res.status(500).json({ error: err.message });
+  }
+});
+
 export default router;