stack-auth · N2D4 · Oct 4, 2025 · Sep 23, 2025 · Sep 23, 2025 · Sep 23, 2025
diff --git a/.claude/CLAUDE-KNOWLEDGE.md b/.claude/CLAUDE-KNOWLEDGE.md
@@ -366,3 +366,6 @@ A: This happens when packages haven't been built yet. Run these commands in orde
 pnpm clean && pnpm i && pnpm codegen && pnpm build:packages
 ```
 Then restart the dev server. This rebuilds all packages and generates the necessary TypeScript declarations.
+
+## Q: How is backwards compatibility for the offer→product rename handled in the payments purchase APIs?
+A: API v1 requests are routed through the `v2beta1` migration. The migration wraps the latest handlers, accepts legacy `offer_id`/`offer_inline` request fields, translates product-related errors back to the old offer error codes/messages, and augments responses (like `validate-code`) with `offer`/`conflicting_group_offers` aliases alongside the new `product` fields. Newer API versions keep the product-only contract.
diff --git a/apps/backend/prisma/migrations/20250923191615_rename_offers_to_products/migration.sql b/apps/backend/prisma/migrations/20250923191615_rename_offers_to_products/migration.sql
@@ -0,0 +1,15 @@
+-- AlterTable
+ALTER TABLE "OneTimePurchase" 
+RENAME COLUMN "offer" TO "product";
+
+-- AlterTable
+ALTER TABLE "OneTimePurchase" 
+RENAME COLUMN "offerId" TO "productId";
+
+-- AlterTable
+ALTER TABLE "Subscription" 
+RENAME COLUMN "offer" TO "product";
+
+-- AlterTable
+ALTER TABLE "Subscription" 
+RENAME COLUMN "offerId" TO "productId";
diff --git a/apps/backend/prisma/schema.prisma b/apps/backend/prisma/schema.prisma
@@ -763,9 +763,9 @@ model Subscription {
   tenancyId    String       @db.Uuid
   customerId   String
   customerType CustomerType
-  offerId      String?
+  productId    String?
   priceId      String?
-  offer        Json
+  product      Json
   quantity     Int          @default(1)
 
   stripeSubscriptionId String?
@@ -802,9 +802,9 @@ model OneTimePurchase {
   tenancyId             String                 @db.Uuid
   customerId            String
   customerType          CustomerType
-  offerId               String?
+  productId             String?
   priceId               String?
-  offer                 Json
+  product               Json
   quantity              Int
   stripePaymentIntentId String?
   createdAt             DateTime               @default(now())

diff --git a/apps/backend/prisma/seed.ts b/apps/backend/prisma/seed.ts
@@ -98,14 +98,14 @@ async function seed() {
         }
       },
       payments: {
-        groups: {
+        catalogs: {
           plans: {
             displayName: "Plans",
           }
         },
-        offers: {
+        products: {
           team: {
-            groupId: "plans",
+            catalogId: "plans",
             displayName: "Team",
             customerType: "team",
             serverOnly: false,
@@ -126,7 +126,7 @@ async function seed() {
             }
           },
           growth: {
-            groupId: "plans",
+            catalogId: "plans",
             displayName: "Growth",
             customerType: "team",
             serverOnly: false,
@@ -147,7 +147,7 @@ async function seed() {
             }
           },
           free: {
-            groupId: "plans",
+            catalogId: "plans",
             displayName: "Free",
             customerType: "team",
             serverOnly: false,
@@ -162,7 +162,7 @@ async function seed() {
             }
           },
           "extra-admins": {
-            groupId: "plans",
+            catalogId: "plans",
             displayName: "Extra Admins",
             customerType: "team",
             serverOnly: false,

diff --git a/apps/backend/scripts/verify-data-integrity.ts b/apps/backend/scripts/verify-data-integrity.ts
@@ -76,6 +76,7 @@ async function main() {
   const shouldSaveOutput = flags.includes("--save-output");
   const shouldVerifyOutput = flags.includes("--verify-output");
   const shouldSkipNeon = flags.includes("--skip-neon");
+  const recentFirst = flags.includes("--recent-first");
 
 
   if (shouldSaveOutput) {
@@ -117,7 +118,9 @@ async function main() {
       displayName: true,
       description: true,
     },
-    orderBy: {
+    orderBy: recentFirst ? {
+      updatedAt: "desc",
+    } : {
       id: "asc",
     },
   });
@@ -126,7 +129,7 @@ async function main() {
     console.log(`Starting at project ${startAt}.`);
   }
 
-  const maxUsersPerProject = 10000;
+  const maxUsersPerProject = 100;
 
   const endAt = Math.min(startAt + count, projects.length);
   for (let i = startAt; i < endAt; i++) {
@@ -264,6 +267,7 @@ async function main() {
   console.log();
   console.log();
 }
+// eslint-disable-next-line no-restricted-syntax
 main().catch((...args) => {
   console.error();
   console.error();

diff --git a/apps/backend/src/app/api/latest/integrations/stripe/webhooks/route.tsx b/apps/backend/src/app/api/latest/integrations/stripe/webhooks/route.tsx
@@ -53,7 +53,7 @@ async function processStripeWebhookEvent(event: Stripe.Event): Promise<void> {
       throw new StackAssertionError("Tenancy not found", { event });
     }
     const prisma = await getPrismaClientForTenancy(tenancy);
-    const offer = JSON.parse(metadata.offer || "{}");
+    const product = JSON.parse(metadata.product || "{}");
     const qty = Math.max(1, Number(metadata.purchaseQuantity || 1));
     const stripePaymentIntentId = event.data.object.id;
-    const product = JSON.parse(metadata.product || "{}");
-    const qty = Math.max(1, Number(metadata.purchaseQuantity || 1));
-    const stripePaymentIntentId = event.data.object.id;
+    const product = (() => {
+      try {
+        return metadata.product ? JSON.parse(metadata.product) : null;
+      } catch {
+        return null;
+      }
+    })();
+    const qty = (() => {
+      const n = Number(metadata.purchaseQuantity);
+      return Number.isFinite(n) && n >= 1 ? Math.floor(n) : 1;
+    })();
+    const stripePaymentIntentId = event.data.object.id;
-    const product = JSON.parse(metadata.product || "{}");
-    const qty = Math.max(1, Number(metadata.purchaseQuantity || 1));
-    const stripePaymentIntentId = event.data.object.id;
+    const product = (() => {
+      try {
+        return metadata.product ? JSON.parse(metadata.product) : null;
+      } catch {
+        return null;
+      }
+    })();
+    const qty = (() => {
+      const n = Number(metadata.purchaseQuantity);
+      return Number.isFinite(n) && n >= 1 ? Math.floor(n) : 1;
+    })();
+    const stripePaymentIntentId = event.data.object.id;
     if (!metadata.customerId || !metadata.customerType) {
@@ -73,17 +73,17 @@ async function processStripeWebhookEvent(event: Stripe.Event): Promise<void> {
         tenancyId: tenancy.id,
         customerId: metadata.customerId,
         customerType: typedToUppercase(metadata.customerType),
-        offerId: metadata.offerId || null,
+        productId: metadata.productId || null,
         priceId: metadata.priceId || null,
         stripePaymentIntentId,
-        offer,
+        product,
         quantity: qty,
         creationSource: "PURCHASE_PAGE",
       },
       update: {
-        offerId: metadata.offerId || null,
+        productId: metadata.productId || null,
         priceId: metadata.priceId || null,
-        offer,
+        product,
         quantity: qty,
-        productId: metadata.productId || null,
-        priceId: metadata.priceId || null,
-        stripePaymentIntentId,
-        offer,
-        product,
-        quantity: qty,
-        creationSource: "PURCHASE_PAGE",
-      },
-      update: {
-        offerId: metadata.offerId || null,
-        productId: metadata.productId || null,
-        priceId: metadata.priceId || null,
-        offer,
-        product,
-        quantity: qty,
+        productId: metadata.productId ?? null,
+        priceId: metadata.priceId || null,
+        stripePaymentIntentId,
+        product,
+        quantity: qty,
+        creationSource: "PURCHASE_PAGE",
+      },
+      update: {
+        productId: metadata.productId ?? null,
+        priceId: metadata.priceId || null,
+        product,
+        quantity: qty,
-        productId: metadata.productId || null,
-        priceId: metadata.priceId || null,
-        stripePaymentIntentId,
-        offer,
-        product,
-        quantity: qty,
-        creationSource: "PURCHASE_PAGE",
-      },
-      update: {
-        offerId: metadata.offerId || null,
-        productId: metadata.productId || null,
-        priceId: metadata.priceId || null,
-        offer,
-        product,
-        quantity: qty,
+        productId: metadata.productId ?? null,
+        priceId: metadata.priceId || null,
+        stripePaymentIntentId,
+        product,
+        quantity: qty,
+        creationSource: "PURCHASE_PAGE",
+      },
+      update: {
+        productId: metadata.productId ?? null,
+        priceId: metadata.priceId || null,
+        product,
+        quantity: qty,
       }
     });

diff --git a/apps/backend/src/app/api/latest/internal/config/override/crud.tsx b/apps/backend/src/app/api/latest/internal/config/override/crud.tsx
@@ -1,6 +1,7 @@
-import { getRenderedEnvironmentConfigQuery, overrideEnvironmentConfigOverride, validateEnvironmentConfigOverride } from "@/lib/config";
+import { getRenderedEnvironmentConfigQuery, overrideEnvironmentConfigOverride } from "@/lib/config";
 import { globalPrismaClient, rawQuery } from "@/prisma-client";
 import { createCrudHandlers } from "@/route-handlers/crud-handler";
+import { environmentConfigSchema, getConfigOverrideErrors, migrateConfigOverride } from "@stackframe/stack-shared/dist/config/schema";
 import { configOverrideCrud } from "@stackframe/stack-shared/dist/interface/crud/config";
 import { yupObject } from "@stackframe/stack-shared/dist/schema-fields";
 import { StatusError } from "@stackframe/stack-shared/dist/utils/errors";
@@ -20,14 +21,10 @@ export const configOverridesCrudHandlers = createLazyProxy(() => createCrudHandl
         throw e;
       }
 
-      const validationResult = await validateEnvironmentConfigOverride({
-        environmentConfigOverride: parsedConfig,
-        branchId: auth.tenancy.branchId,
-        projectId: auth.tenancy.project.id,
-      });
-
-      if (validationResult.status === "error") {
-        throw new StatusError(StatusError.BadRequest, validationResult.error);
+      // TODO instead of doing this check here, we should change overrideEnvironmentConfigOverride to return the errors from its ensureNoConfigOverrideErrors call
+      const overrideError = await getConfigOverrideErrors(environmentConfigSchema, migrateConfigOverride("environment", parsedConfig));
+      if (overrideError.status === "error") {
+        throw new StatusError(StatusError.BadRequest, overrideError.error);
       }
 
       await overrideEnvironmentConfigOverride({

diff --git a/apps/backend/src/app/api/latest/internal/payments/test-mode-purchase-session/route.tsx b/apps/backend/src/app/api/latest/internal/payments/test-mode-purchase-session/route.tsx
@@ -37,7 +37,7 @@ export const POST = createSmartRouteHandler({
     }
     const prisma = await getPrismaClientForTenancy(auth.tenancy);
 
-    const { selectedPrice, conflictingGroupSubscriptions } = await validatePurchaseSession({
+    const { selectedPrice, conflictingCatalogSubscriptions } = await validatePurchaseSession({
       prisma,
       tenancy: auth.tenancy,
       codeData: data,
@@ -53,18 +53,18 @@ export const POST = createSmartRouteHandler({
         data: {
           tenancyId: auth.tenancy.id,
           customerId: data.customerId,
-          customerType: typedToUppercase(data.offer.customerType),
-          offerId: data.offerId,
+          customerType: typedToUppercase(data.product.customerType),
+          productId: data.productId,
           priceId: price_id,
-          offer: data.offer,
+          product: data.product,
           quantity,
           creationSource: "TEST_MODE",
         },
       });
     } else {
       // Cancel conflicting subscriptions for TEST_MODE as well, then create new TEST_MODE subscription
-      if (conflictingGroupSubscriptions.length > 0) {
-        const conflicting = conflictingGroupSubscriptions[0];
+      if (conflictingCatalogSubscriptions.length > 0) {
+        const conflicting = conflictingCatalogSubscriptions[0];
         if (conflicting.stripeSubscriptionId) {
           const stripe = await getStripeForAccount({ tenancy: auth.tenancy });
           await stripe.subscriptions.cancel(conflicting.stripeSubscriptionId);
@@ -85,11 +85,11 @@ export const POST = createSmartRouteHandler({
         data: {
           tenancyId: auth.tenancy.id,
           customerId: data.customerId,
-          customerType: typedToUppercase(data.offer.customerType),
+          customerType: typedToUppercase(data.product.customerType),
           status: "active",
-          offerId: data.offerId,
+          productId: data.productId,
           priceId: price_id,
-          offer: data.offer,
+          product: data.product,
           quantity,
           currentPeriodStart: new Date(),
           currentPeriodEnd: addInterval(new Date(), selectedPrice.interval!),

diff --git a/apps/backend/src/app/api/latest/internal/payments/transactions/route.tsx b/apps/backend/src/app/api/latest/internal/payments/transactions/route.tsx
@@ -8,24 +8,24 @@ import { typedToLowercase, typedToUppercase } from "@stackframe/stack-shared/dis
 
 
 type SelectedPrice = NonNullable<AdminTransaction['price']>;
-type OfferWithPrices = {
+type ProductWithPrices = {
   displayName?: string,
   prices?: Record<string, SelectedPrice & { serverOnly?: unknown, freeTrial?: unknown }> | "include-by-default",
 } | null | undefined;
 
-function resolveSelectedPriceFromOffer(offer: OfferWithPrices, priceId?: string | null): SelectedPrice | null {
-  if (!offer) return null;
+function resolveSelectedPriceFromProduct(product: ProductWithPrices, priceId?: string | null): SelectedPrice | null {
+  if (!product) return null;
   if (!priceId) return null;
-  const prices = offer.prices;
+  const prices = product.prices;
   if (!prices || prices === "include-by-default") return null;
   const selected = prices[priceId as keyof typeof prices] as (SelectedPrice & { serverOnly?: unknown, freeTrial?: unknown }) | undefined;
   if (!selected) return null;
   const { serverOnly: _serverOnly, freeTrial: _freeTrial, ...rest } = selected as any;
   return rest as SelectedPrice;
 }
 
-function getOfferDisplayName(offer: OfferWithPrices): string | null {
-  return offer?.displayName ?? null;
+function getProductDisplayName(product: ProductWithPrices): string | null {
+  return product?.displayName ?? null;
 }
 
 
@@ -137,8 +137,8 @@ export const GET = createSmartRouteHandler({
       customer_id: s.customerId,
       quantity: s.quantity,
       test_mode: s.creationSource === 'TEST_MODE',
-      offer_display_name: getOfferDisplayName(s.offer as OfferWithPrices),
-      price: resolveSelectedPriceFromOffer(s.offer as OfferWithPrices, s.priceId ?? null),
+      product_display_name: getProductDisplayName(s.product as ProductWithPrices),
+      price: resolveSelectedPriceFromProduct(s.product as ProductWithPrices, s.priceId ?? null),
       status: s.status,
     }));
 
@@ -153,7 +153,7 @@ export const GET = createSmartRouteHandler({
         customer_id: i.customerId,
         quantity: i.quantity,
         test_mode: false,
-        offer_display_name: null,
+        product_display_name: null,
         price: null,
         status: null,
         item_id: i.itemId,
@@ -170,8 +170,8 @@ export const GET = createSmartRouteHandler({
       customer_id: o.customerId,
       quantity: o.quantity,
       test_mode: o.creationSource === 'TEST_MODE',
-      offer_display_name: getOfferDisplayName(o.offer as OfferWithPrices),
-      price: resolveSelectedPriceFromOffer(o.offer as OfferWithPrices, o.priceId ?? null),
+      product_display_name: getProductDisplayName(o.product as ProductWithPrices),
+      price: resolveSelectedPriceFromProduct(o.product as ProductWithPrices, o.priceId ?? null),
       status: null,
     }));
 

diff --git a/apps/backend/src/app/api/latest/payments/purchases/create-purchase-url/route.ts b/apps/backend/src/app/api/latest/payments/purchases/create-purchase-url/route.ts
@@ -1,10 +1,10 @@
-import { ensureOfferIdOrInlineOffer } from "@/lib/payments";
+import { ensureProductIdOrInlineProduct } from "@/lib/payments";
 import { getStripeForAccount } from "@/lib/stripe";
 import { globalPrismaClient } from "@/prisma-client";
 import { createSmartRouteHandler } from "@/route-handlers/smart-route-handler";
 import { CustomerType } from "@prisma/client";
 import { KnownErrors } from "@stackframe/stack-shared/dist/known-errors";
-import { adaptSchema, clientOrHigherAuthTypeSchema, inlineOfferSchema, yupNumber, yupObject, yupString } from "@stackframe/stack-shared/dist/schema-fields";
+import { adaptSchema, clientOrHigherAuthTypeSchema, inlineProductSchema, yupNumber, yupObject, yupString } from "@stackframe/stack-shared/dist/schema-fields";
 import { getEnvVariable } from "@stackframe/stack-shared/dist/utils/env";
 import { throwErr } from "@stackframe/stack-shared/dist/utils/errors";
 import { purchaseUrlVerificationCodeHandler } from "../verification-code-handler";
@@ -22,8 +22,8 @@ export const POST = createSmartRouteHandler({
     body: yupObject({
       customer_type: yupString().oneOf(["user", "team", "custom"]).defined(),
       customer_id: yupString().defined(),
-      offer_id: yupString().optional(),
-      offer_inline: inlineOfferSchema.optional(),
+      product_id: yupString().optional(),
+      product_inline: inlineProductSchema.optional(),
     }),
   }),
   response: yupObject({
@@ -36,10 +36,10 @@ export const POST = createSmartRouteHandler({
   handler: async (req) => {
     const { tenancy } = req.auth;
     const stripe = await getStripeForAccount({ tenancy });
-    const offerConfig = await ensureOfferIdOrInlineOffer(tenancy, req.auth.type, req.body.offer_id, req.body.offer_inline);
-    const customerType = offerConfig.customerType;
+    const productConfig = await ensureProductIdOrInlineProduct(tenancy, req.auth.type, req.body.product_id, req.body.product_inline);
+    const customerType = productConfig.customerType;
     if (req.body.customer_type !== customerType) {
-      throw new KnownErrors.OfferCustomerTypeDoesNotMatch(req.body.offer_id, req.body.customer_id, customerType, req.body.customer_type);
+      throw new KnownErrors.ProductCustomerTypeDoesNotMatch(req.body.product_id, req.body.customer_id, customerType, req.body.customer_type);
     }
 
     const stripeCustomerSearch = await stripe.customers.search({
@@ -66,8 +66,8 @@ export const POST = createSmartRouteHandler({
       data: {
         tenancyId: tenancy.id,
         customerId: req.body.customer_id,
-        offerId: req.body.offer_id,
-        offer: offerConfig,
+        productId: req.body.product_id,
+        product: productConfig,
         stripeCustomerId: stripeCustomer.id,
         stripeAccountId: project?.stripeAccountId ?? throwErr("Stripe account not configured"),
       },