Rename offer to product, offer group to product catalog (#914)

<!--

Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md

-->

<!-- RECURSEML_SUMMARY:START -->
## High-level PR Summary
This PR implements a comprehensive renaming of "offer" to "product" and
"offer group" to "product catalog" throughout the codebase. The changes
include database migrations, schema updates, API compatibility layers,
function renames, and updates to client and server implementations.
Backwards compatibility is maintained through migration layers that
handle requests using the old terminology, translating them to the new
terminology before processing. The PR includes documentation of this
approach in CLAUDE-KNOWLEDGE.md. This rename affects multiple parts of
the system including the database schema, API endpoints, error types,
and SDK interfaces.

⏱️ Estimated Review Time: 1-3 hours

<details>
<summary>💡 Review Order Suggestion</summary>

| Order | File Path |
|-------|-----------|
| 1 |
`apps/backend/prisma/migrations/20250923191615_rename_offers_to_products/migration.sql`
|
| 2 |
`apps/backend/src/app/api/migrations/v2beta1/payments/purchases/offers-compat.ts`
|
| 3 |
`apps/backend/src/app/api/migrations/v2beta1/payments/purchases/create-purchase-url/route.ts`
|
| 4 |
`apps/backend/src/app/api/migrations/v2beta1/payments/purchases/validate-code/route.ts`
|
| 5 | `apps/backend/src/lib/payments.tsx` |
| 6 | `.claude/CLAUDE-KNOWLEDGE.md` |
| 7 | `packages/stack-shared/src/schema-fields.ts` |
| 8 | `packages/stack-shared/src/known-errors.tsx` |
| 9 | `packages/stack-shared/src/config/schema.ts` |
| 10 | `packages/template/src/lib/stack-app/customers/index.ts` |
| 11 |
`packages/template/src/lib/stack-app/apps/implementations/client-app-impl.ts`
|
| 12 |
`packages/template/src/lib/stack-app/apps/implementations/server-app-impl.ts`
|
</details>



[![Need help? Join our
Discord](https://img.shields.io/badge/Need%20help%3F%20Join%20our%20Discord-5865F2?style=plastic&logo=discord&logoColor=white)](https://discord.gg/n3SsVDAW6U)

<!-- RECURSEML_SUMMARY:END -->
<!-- ELLIPSIS_HIDDEN -->


----

> [!IMPORTANT]
> Renames 'offer' to 'product' and 'offer group' to 'product catalog'
across the codebase, updating database schema, API endpoints, and
application logic for consistency and backward compatibility.
> 
>   - **Database**:
> - Rename columns `offer` to `product` and `offerId` to `productId` in
`OneTimePurchase` and `Subscription` tables in `migration.sql`.
>   - **API & Migrations**:
> - Update API endpoints to accept `product_id`/`product_inline` instead
of `offer_id`/`offer_inline`.
> - Add `v2beta5` compatibility layer to map legacy `offer` fields to
`product` equivalents.
>   - **Shared Schemas**:
> - Rename `offerSchema` to `productSchema` and related schemas in
`schema-fields.ts`.
>   - **Server Implementation**:
> - Update `createCheckoutUrl` method in `server-app-impl.ts` to use
`productId`/`InlineProduct`.
>   - **Tests**:
> - Update tests to reflect renaming in `backend-helpers.ts` and other
test files.
>   - **Miscellaneous**:
>     - Remove dummy data related to offers in `dummy-data.tsx`.
> - Update documentation and comments to reflect terminology changes.
> 
> <sup>This description was created by </sup>[<img alt="Ellipsis"
src="https://img.shields.io/badge/Ellipsis-blue?color=175173">](https://www.ellipsis.dev?ref=stack-auth%2Fstack-auth&utm_source=github&utm_medium=referral)<sup>
for e3227bc. You can
[customize](https://app.ellipsis.dev/stack-auth/settings/summaries) this
summary. It will automatically update as commits are pushed.</sup>

----


<!-- ELLIPSIS_HIDDEN -->

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Backwards-compatibility: legacy offer_id/offer_inline requests are
accepted, normalized, and routed to product-based handlers.

* **Refactor**
* Global rename from Offer/Group → Product/Catalog across UI, APIs,
types, client/server interfaces, and error codes.

* **Bug Fixes**
* Responses, webhooks and UI consistently surface product_display_name
and product-related metadata.

* **Documentation**
* Migration notes and docs updated to explain compatibility and
parameter changes.

* **Tests**
  * Unit and E2E suites updated to cover product/catalog flows.

* **Chores**
  * Database schema migration, seed and config updates applied.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> Renames offers→products and groups→catalogs end-to-end (DB, APIs,
schemas, UI, SDK, docs), adding v2beta5 compatibility to accept legacy
offer fields while updating all internals.
> 
> - **Backend/DB**:
> - Prisma migration: rename `offer`/`offerId`→`product`/`productId` in
`OneTimePurchase` and `Subscription`.
> - Update Stripe webhook, purchase-session, and internal test-mode
flows to use `product*` metadata/fields.
> - **API & Migrations**:
>   - Latest endpoints now accept `product_id`/`product_inline`.
> - Add `v2beta5` compat layer mapping legacy `offer_id`/`offer_inline`
to product equivalents; responses alias conflicting products.
> - **Shared Schemas/Errors/Config**:
> - `offerSchema`→`productSchema`,
`inlineOfferSchema`→`inlineProductSchema`, prices/types renamed.
>   - KnownErrors renamed (e.g., `PRODUCT_DOES_NOT_EXIST`).
> - Config: `groups`→`catalogs`, defaults/migrations updated; improved
override validation messages; ID regex loosened; formatter tweaks; add
schema fuzzer tests.
> - **Payments Lib**:
> - Rename APIs and logic (`offers`→`products`, `groupId`→`catalogId`),
subscription and item-quantity computation updated.
> - **Dashboard/UI**:
> - Routes, dialogs, editors, tables, and code samples switched to
products/catalogs; removed offers dummy data.
> - **SDK/Template**:
> - Client/server `createCheckoutUrl` now uses
`productId`/`InlineProduct`.
> - **Tests/Docs/Utilities**:
>   - E2E and unit tests updated; add legacy (pre-rename) tests.
> - Docs and knowledge base revised; minor script tweaks (recent-first,
limits).
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
e6e20ec. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: BilalG1 <bg2002@gmail.com>

Author: N2D4

.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.

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";

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())

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,

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();

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;
     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,
       }
     });

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({

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!),

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,
     }));
 

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"),
       },