@rovela-ai/sdk 0.19.5 → 0.19.7

package/dist/checkout/server/create-checkout-session.js

@@ -5,9 +5,8 @@
  * The payment is processed ON the connected account, not the platform.
  */
 import { getStripe, getConnectedAccountId, calculateApplicationFee, getStoreCurrency, getAllowedShippingCountries, } from '../stripe/client';
-import { findSettings, findActiveShippingZones, findTaxRateForAddress, } from '../../core/db/queries';
-import { repriceItems, resolveShippingSelection, PricingError } from './pricing';
-import { evaluateDiscounts } from './discounts';
+import { findSettings, findActiveShippingZones, } from '../../core/db/queries';
+import { buildQuote, CHECKOUT_PRICING_MODE } from './pricing';
 // =============================================================================
 // Shipping Helpers
 // =============================================================================
@@ -179,98 +178,71 @@ export async function createCheckoutSession(request, options = {}) {
         throw new Error('Success and cancel URLs are required');
     }
     // ==========================================================================
-    // SERVER RE-PRICE (pricing core) — the client's prices are NOT the source
-    // of truth for money. Every line is re-priced from the catalog in 'floor'
-    // mode: a client price ABOVE the catalog price is accepted (configurator /
-    // add-on surcharges priced client-side); a client price BELOW it rejects
-    // the checkout (PricingError → 4xx in the route). The Stripe hosted page
-    // now only DISPLAYS and COLLECTS the amount we computed.
+    // THE QUOTE — one engine, for every payment path
     // ==========================================================================
-    const repriced = await repriceItems(request.items, 'floor');
-    const items = repriced.lines;
-    // Subtotal from SERVER-priced lines; application fee follows it.
-    const subtotal = repriced.subtotalCents;
-    // Server-validate the pre-selected shipping (manual zone rates are
-    // re-derived from the rate id — the server's price wins; Shippo quotes are
-    // sanity-bounded). Replaces the client-claimed price everywhere below.
-    let selectedShipping = request.selectedShipping;
-    const isPickup = selectedShipping?.source === 'pickup';
-    let pickupLocationId = null;
-    if (selectedShipping && isShippingEnabled && collectShippingAddress) {
-        if (selectedShipping.source !== 'shippo' && !request.shippingAddress?.country) {
-            // Manual rates can't be re-derived without a destination country —
-            // bound the claimed price like a Shippo quote instead of trusting it.
-            const claimed = Number(selectedShipping.price);
-            if (!Number.isFinite(claimed) || claimed < 0 || claimed > 1_000_000) {
-                throw new Error('Invalid shipping selection');
-            }
-        }
-        else {
-            const resolved = await resolveShippingSelection({
-                selection: selectedShipping,
-                country: request.shippingAddress?.country ?? '',
-                subtotalCents: subtotal,
-                groupId: request.customerGroupId ?? null,
-            });
-            selectedShipping = {
-                ...selectedShipping,
-                price: resolved.shippingCents,
-                name: selectedShipping.name,
-            };
-            // Click & collect: remember the validated location for the webhook.
-            pickupLocationId = resolved.pickupLocationId ?? null;
-        }
-    }
-    // ==========================================================================
-    // NATIVE DISCOUNTS (pricing core, step 2) — evaluated in OUR infrastructure
-    // before Stripe sees anything. The applied amount reaches the hosted page
-    // as an ephemeral one-off Stripe coupon (display + collection only). An
-    // entered code that fails validation rejects the checkout (the UI
-    // pre-validates via /api/checkout/discount, so this is a stale/tampered
-    // submission).
-    // ==========================================================================
-    const discountEvaluation = await evaluateDiscounts({
-        lines: items,
-        subtotalCents: subtotal,
-        categoryByProductId: repriced.categoryByProductId,
-        code: request.discountCode ?? null,
+    // §55: `buildQuote` is the ONLY money source; processors collect, never
+    // compute. That was not true. This function used to reimplement the whole
+    // pipeline inline — its own repricing, its own discount evaluation, its own
+    // shipping resolution, its own tax — while the manual (wire transfer) path
+    // called `buildQuote`. Two engines, and the drift between them was not
+    // theoretical: click & collect fell through into Stripe's shipping flow and
+    // charged a collecting shopper for delivery; the tax line was taken on a
+    // different base than the tax the order recorded; and the pickup tax base came
+    // from whatever address the client sent rather than from the location.
+    //
+    // From here down, this file is an ADAPTER: Quote → Stripe session. It formats.
+    // It does not compute money. The manual path is the same adapter shape:
+    // Quote → order. One input, one engine, one output, two processors.
+    //
+    // The one honest concession to a processor: if the caller has NOT resolved
+    // shipping, the shopper picks it on Stripe's own page — so Stripe, not us,
+    // determines the final total, and the quote cannot be authoritative over it.
+    // That is inherent (you cannot be payment-agnostic and let the processor choose
+    // shipping), not a second engine: we still quote the goods, the discounts and
+    // the tax through `buildQuote`, and simply don't claim the total.
+    const shippingResolved = !!request.selectedShipping && shouldCollectShipping;
+    const isAuthoritative = shippingResolved || !shouldCollectShipping;
+    const quote = await buildQuote({
+        items: request.items,
+        shippingAddress: request.shippingAddress,
+        selectedShipping: shippingResolved ? request.selectedShipping : null,
+        pricingMode: CHECKOUT_PRICING_MODE,
+        discountCode: request.discountCode ?? null,
         customerId: request.customerId ?? null,
         customerGroupId: request.customerGroupId ?? null,
         customerEmail: request.customerEmail ?? null,
+    }, {
+        // `shouldCollectShipping` folds in the caller's `collectShippingAddress`
+        // option, which the settings row knows nothing about; and when shipping is
+        // still unresolved we tell the quote to skip it rather than demand an
+        // address the shopper has not been asked for yet.
+        settings: storeSettings
+            ? { ...storeSettings, shippingEnabled: shippingResolved }
+            : null,
     });
-    if (request.discountCode && discountEvaluation.codeError) {
-        throw new PricingError(discountEvaluation.codeError.message);
-    }
-    const discountCents = Math.min(discountEvaluation.discountCents, subtotal);
-    const appliedDiscounts = discountEvaluation.applied;
-    // A free-shipping discount zeroes the (already validated) shipping price
-    // while keeping the chosen method — the shipping line renders at 0.
-    if (discountEvaluation.freeShipping && selectedShipping && selectedShipping.price > 0) {
-        selectedShipping = { ...selectedShipping, price: 0 };
-    }
+    // Everything below reads the quote. A PricingError (bad code, stale price,
+    // invalid shipping selection) propagated out of buildQuote and became a 4xx in
+    // the route — never a silent re-price behind the shopper's back.
+    const items = quote.lines;
+    const subtotal = quote.subtotalCents;
+    const discountCents = quote.discountCents;
+    const appliedDiscounts = quote.appliedDiscounts;
+    const taxIncludedInPrices = quote.taxIncludedInPrices;
+    const taxRate = quote.taxRate;
+    const taxZoneId = quote.taxZoneId ?? '';
+    const taxZoneName = quote.taxZoneName ?? '';
+    // The quote's shipping price is the SERVER's: manual rates re-derived from the
+    // rate id, Shippo quotes bounded, free-shipping discounts applied, pickup = 0.
+    // The client's claimed price never survives.
+    const selectedShipping = request.selectedShipping
+        ? { ...request.selectedShipping, price: quote.shippingCents }
+        : undefined;
+    const isPickup = selectedShipping?.source === 'pickup';
+    // Resolved from the LOCATION server-side, not from whatever address the client
+    // happened to send along with the pickup.
+    const pickupLocationId = quote.pickupLocationId;
     // Application fee follows the DISCOUNTED goods value.
     const appFee = applicationFeeAmount ?? calculateApplicationFee(subtotal - discountCents);
-    // ==========================================================================
-    // Zone-Based Tax Calculation
-    // ==========================================================================
-    // Tax is calculated based on the customer's shipping address using tax zones.
-    // The admin configures zones with country/state coverage and tax rates.
-    //
-    // taxIncludedInPrices setting determines how tax is handled:
-    // - true (default): Prices include tax → extract and show separately
-    // - false: Prices exclude tax → add tax on top
-    //
-    // Tax can only be calculated when we have a shipping address (pre-checkout flow).
-    // If no address is provided, tax = 0 (address will be collected in webhook).
-    // Get tax inclusion setting from store settings
-    const taxIncludedInPrices = storeSettings?.taxIncludedInPrices ?? true;
-    // Find matching tax zone from shipping address
-    let taxMatch = null;
-    let taxRate = 0;
-    if (request.shippingAddress) {
-        taxMatch = await findTaxRateForAddress(request.shippingAddress.country, request.shippingAddress.state, request.customerGroupId ?? null);
-        taxRate = taxMatch?.taxRate ?? 0;
-    }
     // Calculate divisor for tax extraction (only when prices include tax)
     const taxDivisor = (taxIncludedInPrices && taxRate > 0) ? (1 + taxRate / 100) : 1;
     // Determine tax handling mode
@@ -293,7 +265,12 @@ export async function createCheckoutSession(request, options = {}) {
                 currency,
                 product_data: {
                     name: item.name,
-                    description: item.description,
+                    // Stripe REJECTS an empty-string description ("cannot be unset") and
+                    // 500s the whole session. A caller that legitimately has nothing to
+                    // say about a line (e.g. a configurator line whose attributes are
+                    // all internal) must be able to send '' / null without breaking
+                    // checkout — so normalize any blank value away entirely.
+                    description: item.description?.trim() ? item.description : undefined,
                     images: safeImage ? [safeImage] : undefined,
                     // Per-item identifiers live on the line item's product metadata —
                     // a per-line 500-char bag that cannot overflow from cart size.
@@ -317,8 +294,11 @@ export async function createCheckoutSession(request, options = {}) {
             quantity: item.quantity,
         };
     });
-    // Track original totals for tax calculation (will include shipping if added)
-    let originalTotal = subtotal; // Will be updated if shipping is added
+    // (There used to be an `originalTotal` accumulator here, feeding a tax
+    // computation taken BEFORE the discount. Tax is now taken once, on the
+    // discounted base — see CANONICAL TAX below — so the accumulator is gone.
+    // Do not reintroduce it: a second tax basis is how the receipt and the
+    // recorded order drifted apart in the first place.)
     // Build session parameters
     const sessionParams = {
         mode: 'payment',
@@ -351,53 +331,69 @@ export async function createCheckoutSession(request, options = {}) {
         sessionParams.customer_email = request.customerEmail;
     }
     // ==========================================================================
-    // Pre-Selected Shipping (from pre-checkout flow)
+    // Pre-Selected Shipping (from pre-checkout flow) — INCLUDING click & collect
     // ==========================================================================
-    // When selectedShipping is provided, we add shipping as a line item
-    // instead of showing shipping_options for customer to choose from.
-    // This ensures the pre-checkout flow selection is locked in.
+    // When selectedShipping is provided, the money is settled server-side: we add
+    // shipping as a fixed line item instead of showing shipping_options for the
+    // customer to choose from, so the pre-checkout selection is locked in.
     // (`selectedShipping` was server-validated above — its price is ours.)
-    if (selectedShipping && shouldCollectShipping && !isPickup) {
-        // Apply same tax extraction logic to shipping (if shipping is tax-inclusive)
-        const shippingDisplayPrice = shouldExtractTax
-            ? Math.round(selectedShipping.price / taxDivisor)
-            : selectedShipping.price;
-        // Track original shipping price for tax calculation
-        originalTotal += selectedShipping.price;
-        // Add shipping as a line item (fixed, not selectable)
-        lineItems.push({
-            price_data: {
-                currency,
-                product_data: {
-                    name: `Shipping - ${selectedShipping.carrierName || 'Standard'} ${selectedShipping.name}`,
-                    description: selectedShipping.description || selectedShipping.estimatedDays || undefined,
-                    metadata: {
-                        shippingOptionId: selectedShipping.id,
-                        shippingSource: selectedShipping.source,
-                        carrierName: selectedShipping.carrierName || '',
-                        carrierCode: selectedShipping.carrierCode || '',
-                        carrierId: selectedShipping.carrierId || '',
+    //
+    // PICKUP BELONGS HERE. It is a pre-selected shipping option at price 0, not a
+    // separate world. The guard used to read `&& !isPickup`, which did two silent
+    // things: it dropped every pickup order into the "let Stripe collect shipping"
+    // branch below — so Stripe was handed shipping_options and auto-charged the
+    // first rate, and a shopper coming to COLLECT their order paid for delivery,
+    // while `rovelaTotals` still stamped shipping = 0 (the webhook then recorded a
+    // different total than Stripe collected) — and it made the `if (isPickup …)`
+    // block inside this branch unreachable by construction, so `rovelaPickup` was
+    // never set and no order was ever flagged as a pickup. Stripe-based click &
+    // collect had therefore never worked on any store.
+    if (selectedShipping && shouldCollectShipping) {
+        if (!isPickup) {
+            // Apply same tax extraction logic to shipping (if shipping is tax-inclusive)
+            const shippingDisplayPrice = shouldExtractTax
+                ? Math.round(selectedShipping.price / taxDivisor)
+                : selectedShipping.price;
+            // Add shipping as a line item (fixed, not selectable)
+            lineItems.push({
+                price_data: {
+                    currency,
+                    product_data: {
+                        name: `Shipping - ${selectedShipping.carrierName || 'Standard'} ${selectedShipping.name}`,
+                        description: selectedShipping.description || selectedShipping.estimatedDays || undefined,
+                        metadata: {
+                            shippingOptionId: selectedShipping.id,
+                            shippingSource: selectedShipping.source,
+                            carrierName: selectedShipping.carrierName || '',
+                            carrierCode: selectedShipping.carrierCode || '',
+                            carrierId: selectedShipping.carrierId || '',
+                        },
                     },
+                    unit_amount: shippingDisplayPrice,
                 },
-                unit_amount: shippingDisplayPrice,
-            },
-            quantity: 1,
-        });
-        // Store selected shipping in session metadata for order creation
-        sessionParams.metadata = {
-            ...sessionParams.metadata,
-            selectedShippingId: selectedShipping.id,
-            selectedShippingName: `${selectedShipping.carrierName || 'Standard'} - ${selectedShipping.name}`,
-            selectedShippingPrice: String(selectedShipping.price),
-            selectedShippingSource: selectedShipping.source,
-            // Store carrier identifier - use carrierId for manual shipping, carrierCode for Shippo
-            ...((selectedShipping.carrierId || selectedShipping.carrierCode) && {
-                selectedShippingCarrierId: selectedShipping.carrierId || selectedShipping.carrierCode || '',
-            }),
-        };
-        // Click & collect: selection metadata for the webhook (the shipping-line
-        // metadata block above is skipped for pickup — price is always 0).
-        if (isPickup && selectedShipping) {
+                quantity: 1,
+            });
+            // Store selected shipping in session metadata for order creation
+            sessionParams.metadata = {
+                ...sessionParams.metadata,
+                selectedShippingId: selectedShipping.id,
+                selectedShippingName: `${selectedShipping.carrierName || 'Standard'} - ${selectedShipping.name}`,
+                selectedShippingPrice: String(selectedShipping.price),
+                selectedShippingSource: selectedShipping.source,
+                // Store carrier identifier - use carrierId for manual shipping, carrierCode for Shippo
+                ...((selectedShipping.carrierId || selectedShipping.carrierCode) && {
+                    selectedShippingCarrierId: selectedShipping.carrierId || selectedShipping.carrierCode || '',
+                }),
+            };
+        }
+        else {
+            // Click & collect. NO shipping line item (the price is always 0) and NO
+            // shipping_options — the shopper is collecting in store. `originalTotal`
+            // is deliberately not incremented: there is nothing to tax as shipping.
+            //
+            // `rovelaPickup` is the load-bearing key: the webhook reads it and stamps
+            // orders.pickup_location_id, which drives the pickup lifecycle labels and
+            // the order-ready-for-pickup email (§59).
             sessionParams.metadata = {
                 ...sessionParams.metadata,
                 selectedShippingId: selectedShipping.id,
@@ -408,7 +404,9 @@ export async function createCheckoutSession(request, options = {}) {
                 ...(request.locale ? { rovelaLocale: String(request.locale).slice(0, 5) } : {}),
             };
         }
-        // If shipping address is pre-collected, store in metadata for webhook order creation
+        // If shipping address is pre-collected, store in metadata for webhook order
+        // creation. For pickup this carries the LOCATION's address, which is the
+        // order's shippingAddress snapshot (§59).
         if (request.shippingAddress) {
             const addr = request.shippingAddress;
             sessionParams.metadata = {
@@ -447,8 +445,10 @@ export async function createCheckoutSession(request, options = {}) {
             };
         }
         // Set shipping_address_collection if no pre-collected address
-        // (need to collect for order fulfillment)
-        if (!request.shippingAddress) {
+        // (need to collect for order fulfillment). NEVER for pickup — asking a
+        // shopper who is collecting in store for a delivery address is nonsense,
+        // and Stripe would then also expect to ship somewhere.
+        if (!request.shippingAddress && !isPickup) {
             const shippingCountries = await getShippingCountriesFromSettings();
             sessionParams.shipping_address_collection = {
                 allowed_countries: shippingCountries,
@@ -534,109 +534,85 @@ export async function createCheckoutSession(request, options = {}) {
         sessionParams.allow_promotion_codes = true;
     }
     // ==========================================================================
-    // Add Tax Line Item (Zone-Based)
+    // CANONICAL TAX — the pricing core's formula, computed ONCE
     // ==========================================================================
-    // Tax handling depends on the taxIncludedInPrices setting:
-    //
-    // TAX-INCLUSIVE (shouldExtractTax):
-    //   - Product prices already include tax
-    //   - Line items sent as pre-tax amounts (divided by taxDivisor)
-    //   - Tax line item = original total - sum of pre-tax line items
+    // These ARE the pricing core's numbers — not a re-derivation of them. The tax
+    // the shopper sees on Stripe, the tax the order records, and the tax a wire
+    // transfer for the same cart records are now literally the same value, because
+    // there is only one place that computes it.
+    const quoteShippingCents = quote.shippingCents;
+    const canonicalTaxCents = quote.taxCents;
+    const quoteTotalCents = quote.totalCents;
+    // The tax LINE. Inclusive stores show goods pre-tax (the line items were
+    // already divided by taxDivisor above) with tax broken out; exclusive stores
+    // show goods as-is with tax added.
     //
-    // TAX-EXCLUSIVE (shouldAddTax):
-    //   - Product prices are pre-tax
-    //   - Line items sent as-is (no division)
-    //   - Tax line item = original total × (taxRate / 100)
-    if (shouldExtractTax) {
-        // TAX-INCLUSIVE: Extract tax from prices
-        const preTaxTotal = lineItems.reduce((sum, item) => sum + (item.price_data?.unit_amount || 0) * (item.quantity || 1), 0);
-        // Tax is the difference between original inclusive total and pre-tax total
-        const extractedTaxAmount = originalTotal - preTaxTotal;
-        if (extractedTaxAmount > 0) {
-            lineItems.push({
-                price_data: {
-                    currency,
-                    product_data: {
-                        name: 'Tax',
-                        description: `${taxRate}% - ${taxMatch?.zoneName || 'Sales Tax'}`,
-                    },
-                    unit_amount: extractedTaxAmount,
-                },
-                quantity: 1,
-            });
-            // Store tax info in session metadata for order creation
-            sessionParams.metadata = {
-                ...sessionParams.metadata,
-                taxZoneId: taxMatch?.zoneId || '',
-                taxZoneName: taxMatch?.zoneName || '',
-                taxRate: String(taxRate),
-                taxAmount: String(extractedTaxAmount),
-                taxIncludedInPrices: 'true',
-            };
-        }
-    }
-    else if (shouldAddTax) {
-        // TAX-EXCLUSIVE: Add tax on top of prices
-        const taxAmount = Math.round(originalTotal * (taxRate / 100));
-        if (taxAmount > 0) {
+    // The amount is the quote's tax — with ONE adjustment. In an inclusive store
+    // each line is divided and rounded to the cent, so the line sum can land a
+    // cent or two off the quote. When there is a discount, the coupon below
+    // absorbs that (it is `lineSum − quoteTotal` by construction). When there is
+    // NOT, there is no coupon to absorb it — and we must not mint one just for a
+    // rounding remainder, because Stripe forbids `discounts` together with
+    // `allow_promotion_codes` and it would silently strip a store's promo-code
+    // field. So the tax line itself takes the remainder: the charged total lands
+    // exactly on the quote, and the displayed tax differs from the recorded tax by
+    // at most a cent. `rovelaTotals` still records the canonical figure, so the
+    // order and the wire-transfer order still agree exactly.
+    if ((shouldExtractTax || shouldAddTax) && canonicalTaxCents > 0) {
+        const preTaxLineSum = lineItems.reduce((sum, li) => sum +
+            ((li.price_data?.unit_amount || 0) *
+                (li.quantity || 1)), 0);
+        const taxLineCents = discountCents === 0 && isAuthoritative
+            ? quoteTotalCents - preTaxLineSum
+            : canonicalTaxCents;
+        if (taxLineCents > 0) {
             lineItems.push({
                 price_data: {
                     currency,
                     product_data: {
                         name: 'Tax',
-                        description: `${taxRate}% - ${taxMatch?.zoneName || 'Sales Tax'}`,
+                        description: `${taxRate}% - ${taxZoneName || 'Sales Tax'}`,
                     },
-                    unit_amount: taxAmount,
+                    unit_amount: taxLineCents,
                 },
                 quantity: 1,
             });
-            // Store tax info in session metadata for order creation
-            sessionParams.metadata = {
-                ...sessionParams.metadata,
-                taxZoneId: taxMatch?.zoneId || '',
-                taxZoneName: taxMatch?.zoneName || '',
-                taxRate: String(taxRate),
-                taxAmount: String(taxAmount),
-                taxIncludedInPrices: 'false',
-            };
         }
+        // Store tax info in session metadata for order creation. This records the
+        // CANONICAL tax, not the rounding-adjusted display line.
+        sessionParams.metadata = {
+            ...sessionParams.metadata,
+            taxZoneId,
+            taxZoneName,
+            taxRate: String(taxRate),
+            taxAmount: String(canonicalTaxCents),
+            taxIncludedInPrices: taxIncludedInPrices ? 'true' : 'false',
+        };
     }
     // ==========================================================================
     // Native discount → ephemeral Stripe coupon + authoritative-totals stamp
     // ==========================================================================
-    // When the session's money is fully deterministic server-side (pre-selected
-    // shipping, or a no-shipping store), stamp OUR computed totals on the
-    // session. The webhook records the order from THESE numbers — Stripe's
-    // amounts become a cross-check, not the source of truth. The standard flow
-    // (shipping chosen on the hosted page) stays on Stripe-derived amounts.
-    const quoteShippingCents = selectedShipping && shouldCollectShipping ? selectedShipping.price : 0;
-    const isDeterministicQuote = (selectedShipping && shouldCollectShipping) || !shouldCollectShipping;
-    if (isDeterministicQuote) {
-        // Canonical (recorded) tax: computed on the DISCOUNTED base — the
-        // session's tax line was computed pre-discount, so re-derive here with
-        // the same rate. Inclusive stores: display-only extraction.
-        const discountedBase = subtotal - discountCents + quoteShippingCents;
-        const canonicalTaxCents = taxRate > 0
-            ? taxIncludedInPrices
-                ? Math.round(discountedBase - discountedBase / (1 + taxRate / 100))
-                : Math.round(discountedBase * (taxRate / 100))
-            : 0;
-        const quoteTotal = taxIncludedInPrices
-            ? discountedBase
-            : discountedBase + canonicalTaxCents;
-        // The hosted page shows our discount as a one-off coupon whose amount is
-        // EXACTLY lineSum − quoteTotal, so the charged total equals the quote by
-        // construction (this also absorbs the tax-on-discount adjustment in
-        // tax-exclusive stores).
-        if (discountCents > 0) {
+    // The discount reaches Stripe as a one-off coupon of EXACTLY
+    // `lineSum − quoteTotal`, so the amount Stripe charges equals our quote BY
+    // CONSTRUCTION (with the tax line taken on the discounted base, this resolves
+    // to the discount itself — an honest "Discount −$X", not a fudge factor).
+    //
+    // The coupon is emitted on BOTH modes. It used to sit inside the
+    // deterministic-only branch, which meant that on the Stripe-collects-shipping
+    // flow a native discount was evaluated, charged to nobody, and silently
+    // dropped: the shopper entered a valid code and paid full price. Nothing
+    // reached that flow, so nobody noticed. It is fixed here rather than left as a
+    // trap for the first store that does.
+    {
+        {
             const lineSum = lineItems.reduce((sum, li) => sum +
                 ((li.price_data?.unit_amount || 0) *
                     (li.quantity || 1)), 0);
-            const couponAmountOff = lineSum - quoteTotal;
+            const couponAmountOff = lineSum - quoteTotalCents;
             if (couponAmountOff > 0) {
                 const couponLabel = appliedDiscounts.find((d) => d.code)?.code ||
                     appliedDiscounts[0]?.title ||
-                    'Discount';
+                    (discountCents > 0 ? 'Discount' : 'Rounding adjustment');
                 const coupon = await stripe.coupons.create({
                     amount_off: couponAmountOff,
                     currency,
@@ -648,6 +624,24 @@ export async function createCheckoutSession(request, options = {}) {
                 delete sessionParams.allow_promotion_codes;
             }
         }
+    }
+    // ==========================================================================
+    // AUTHORITATIVE TOTALS — we claim the total only when we actually know it
+    // ==========================================================================
+    // The quote covers the whole bill (shipping was resolved server-side, or the
+    // store doesn't ship), so stamp it. The webhook records the order from THESE
+    // numbers and Stripe's amounts become a cross-check, not the source of truth —
+    // which is what makes a card order and a wire-transfer order for the same cart
+    // record identical money.
+    //
+    // When shipping is still being chosen on Stripe's page we do NOT stamp them:
+    // Stripe adds the rate, so Stripe determines the total and it is not ours to
+    // claim. The webhook falls back to Stripe's amounts there (and to Stripe's
+    // discount total, since the coupon above was still applied — the shopper does
+    // get their discount now). The one thing that path does not do is increment a
+    // native discount's usage count; no store reaches it, and inventing a
+    // redemption path for a flow nobody uses is not worth the surface area.
+    if (isAuthoritative) {
         sessionParams.metadata = {
             ...sessionParams.metadata,
             rovelaTotals: JSON.stringify({
@@ -656,7 +650,7 @@ export async function createCheckoutSession(request, options = {}) {
                 discount: discountCents,
                 shipping: quoteShippingCents,
                 tax: canonicalTaxCents,
-                total: quoteTotal,
+                total: quoteTotalCents,
             }),
             // Applied-discount snapshot for webhook redemption recording. Compact
             // (id + code + net amount); metadata values cap at 500 chars.