refactor/fix: Move product info from stripe webhook to separate table

Stripe metadata has a character limit of 500.
We used to pass product info (including num of items) into the metadata of the stripe object.
So when we tried to invoke stripe with this metadata, if it was over 500 chars, it would cause stripe to return an error.
This was done because when the stripe webhook event fired, it would send the metadata along with it so our handler could pick it up.
We rework this to only passing an id for use in a new table lookup in the handler.
This decouples the product info from the webhook event.
We keep it backwards compatible because there are existing subscriptions that have the product in the metadata, the same way we kept the offer parsing code for the subscriptions that had offer in the metadata.
The productVersionId is hashed on the productJson to dedup it.

Author: nams1570

apps/backend/prisma/migrations/20260218194816_add_product_versions/migration.sql

@@ -0,0 +1,11 @@
+-- CreateTable
+CREATE TABLE "ProductVersion" (
+    "tenancyId" UUID NOT NULL,
+    "productVersionId" TEXT NOT NULL,
+    "productId" TEXT,
+    "productJson" JSONB NOT NULL,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "ProductVersion_pkey" PRIMARY KEY ("tenancyId","productVersionId")
+);
+

apps/backend/prisma/schema.prisma

@@ -99,8 +99,8 @@ model ExternalDbSyncMetadata {
 
   singleton BooleanTrue @unique @default(TRUE)
 
-  sequencerEnabled  Boolean @default(true)
-  pollerEnabled     Boolean @default(true)
+  sequencerEnabled Boolean @default(true)
+  pollerEnabled    Boolean @default(true)
 
   createdAt DateTime @default(now())
   updatedAt DateTime @updatedAt
@@ -1003,6 +1003,16 @@ model Subscription {
   @@unique([tenancyId, stripeSubscriptionId])
 }
 
+model ProductVersion {
+  tenancyId        String   @db.Uuid
+  productVersionId String
+  productId        String?
+  productJson      Json
+  createdAt        DateTime @default(now())
+
+  @@id([tenancyId, productVersionId])
+}
+
 model ItemQuantityChange {
   id           String       @default(uuid()) @db.Uuid
   tenancyId    String       @db.Uuid
@@ -1088,7 +1098,7 @@ model OutgoingRequest {
 
   qstashOptions       Json
   startedFulfillingAt DateTime?
-  deduplicationKey String?
+  deduplicationKey    String?
 
   @@unique([deduplicationKey])
   @@index([startedFulfillingAt, createdAt])

apps/backend/src/app/api/latest/integrations/stripe/webhooks/route.tsx

@@ -1,5 +1,6 @@
 import { sendEmailToMany, type EmailOutboxRecipient } from "@/lib/emails";
 import { listPermissions } from "@/lib/permissions";
+import { getProductVersion } from "@/lib/product-versions";
 import { getStackStripe, getStripeForAccount, syncStripeSubscriptions, upsertStripeInvoice } from "@/lib/stripe";
 import type { StripeOverridesMap } from "@/lib/stripe-proxy";
 import { getTelegramConfig, sendTelegramMessage } from "@/lib/telegram";
@@ -183,7 +184,12 @@ async function processStripeWebhookEvent(event: Stripe.Event): Promise<void> {
     }
     const tenancy = await getTenancyForStripeAccountId(accountId, mockData);
     const prisma = await getPrismaClientForTenancy(tenancy);
-    const product = JSON.parse(metadata.product || "{}");
+
+    const productVersionId = metadata.productVersionId as string | undefined;
+    const product = productVersionId
+      ? (await getProductVersion({ prisma, tenancyId: tenancy.id, productVersionId })).productJson
+      : JSON.parse(metadata.product || "{}");
+
     const qty = Math.max(1, Number(metadata.purchaseQuantity || 1));
     const stripePaymentIntentId = paymentIntent.id;
     if (!metadata.customerId || !metadata.customerType) {

apps/backend/src/app/api/latest/payments/products/[customer_type]/[customer_id]/switch/route.ts

@@ -1,5 +1,6 @@
 import { SubscriptionStatus } from "@/generated/prisma/client";
 import { ensureClientCanAccessCustomer, getCustomerPurchaseContext, getDefaultCardPaymentMethodSummary, getStripeCustomerForCustomerOrNull } from "@/lib/payments";
+import { upsertProductVersion } from "@/lib/product-versions";
 import { getStripeForAccount, sanitizeStripePeriodDates } from "@/lib/stripe";
 import { getPrismaClientForTenancy } from "@/prisma-client";
 import { createSmartRouteHandler } from "@/route-handlers/smart-route-handler";
@@ -169,6 +170,13 @@ export const POST = createSmartRouteHandler({
 
     const stripeProduct = await stripe.products.create({ name: toProduct.displayName || "Subscription" });
 
+    const productVersionId = await upsertProductVersion({
+      prisma,
+      tenancyId: auth.tenancy.id,
+      productId: body.to_product_id,
+      productJson: toProduct,
+    });
+
     if (subscription?.stripeSubscriptionId) {
       const existingStripeSub = await stripe.subscriptions.retrieve(subscription.stripeSubscriptionId);
       if (existingStripeSub.items.data.length === 0) {
@@ -194,7 +202,7 @@ export const POST = createSmartRouteHandler({
         }],
         metadata: {
           productId: body.to_product_id,
-          product: JSON.stringify(toProduct),
+          productVersionId,
           priceId: selectedPriceId,
         },
       });
@@ -239,7 +247,7 @@ export const POST = createSmartRouteHandler({
         }],
         metadata: {
           productId: body.to_product_id,
-          product: JSON.stringify(toProduct),
+          productVersionId,
           priceId: selectedPriceId,
         },
       });

apps/backend/src/app/api/latest/payments/purchases/purchase-session/route.tsx

@@ -1,9 +1,10 @@
+import { SubscriptionStatus } from "@/generated/prisma/client";
 import { getClientSecretFromStripeSubscription, validatePurchaseSession } from "@/lib/payments";
+import { upsertProductVersion } from "@/lib/product-versions";
 import { getStripeForAccount } from "@/lib/stripe";
 import { getTenancy } from "@/lib/tenancies";
 import { getPrismaClientForTenancy } from "@/prisma-client";
 import { createSmartRouteHandler } from "@/route-handlers/smart-route-handler";
-import { SubscriptionStatus } from "@/generated/prisma/client";
 import { KnownErrors } from "@stackframe/stack-shared";
 import { yupNumber, yupObject, yupString } from "@stackframe/stack-shared/dist/schema-fields";
 import { StackAssertionError, throwErr } from "@stackframe/stack-shared/dist/utils/errors";
@@ -73,6 +74,13 @@ export const POST = createSmartRouteHandler({
       throw new StackAssertionError("Price not resolved for purchase session");
     }
 
+    const productVersionId = await upsertProductVersion({
+      prisma,
+      tenancyId: tenancy.id,
+      productId: data.productId ?? null,
+      productJson: data.product,
+    });
+
     if (conflictingProductLineSubscriptions.length > 0) {
       const conflicting = conflictingProductLineSubscriptions[0];
       if (conflicting.stripeSubscriptionId) {
@@ -99,7 +107,7 @@ export const POST = createSmartRouteHandler({
             }],
             metadata: {
               productId: data.productId ?? null,
-              product: JSON.stringify(data.product),
+              productVersionId,
               priceId: price_id,
             },
           });
@@ -136,7 +144,7 @@ export const POST = createSmartRouteHandler({
         automatic_payment_methods: { enabled: true },
         metadata: {
           productId: data.productId || "",
-          product: JSON.stringify(data.product),
+          productVersionId,
           customerId: data.customerId,
           customerType: data.product.customerType,
           purchaseQuantity: String(quantity),
@@ -175,7 +183,7 @@ export const POST = createSmartRouteHandler({
       }],
       metadata: {
         productId: data.productId ?? null,
-        product: JSON.stringify(data.product),
+        productVersionId,
         priceId: price_id,
       },
     });

apps/backend/src/lib/product-versions.tsx

@@ -0,0 +1,154 @@
+import { PrismaClientTransaction } from "@/prisma-client";
+import { encodeBase64 } from "@stackframe/stack-shared/dist/utils/bytes";
+import { StackAssertionError } from "@stackframe/stack-shared/dist/utils/errors";
+import crypto from "crypto";
+
+/**
+ * Deterministically serializes an object to JSON with sorted keys.
+ * This ensures the same object always produces the same string regardless of property order.
+ */
+export function canonicalJsonStringify(obj: unknown): string {
+  return JSON.stringify(obj, (_, value) => {
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      return Object.keys(value)
+        .sort()
+        .reduce((sorted: Record<string, unknown>, key) => {
+          sorted[key] = value[key];
+          return sorted;
+        }, {});
+    }
+    return value;
+  });
+}
+
+/**
+ * Computes a deterministic version ID from a product JSON object.
+ * Uses SHA-256 hash of the canonical JSON representation.
+ */
+export function computeProductVersionId(productJson: unknown): string {
+  const canonical = canonicalJsonStringify(productJson);
+  const hash = crypto.createHash("sha256").update(canonical).digest();
+  return encodeBase64(hash);
+}
+
+/**
+ * Upserts a ProductVersion record and returns the productVersionId.
+ * If a record with the same (tenancyId, productVersionId) exists, it's a no-op.
+ */
+export async function upsertProductVersion(options: {
+  prisma: PrismaClientTransaction,
+  tenancyId: string,
+  productId: string | null,
+  productJson: unknown,
+}): Promise<string> {
+  const productVersionId = computeProductVersionId(options.productJson);
+
+  await options.prisma.productVersion.upsert({
+    where: {
+      tenancyId_productVersionId: {
+        tenancyId: options.tenancyId,
+        productVersionId,
+      },
+    },
+    create: {
+      tenancyId: options.tenancyId,
+      productVersionId,
+      productId: options.productId,
+      productJson: options.productJson as object,
+    },
+    update: {},
+  });
+
+  return productVersionId;
+}
+
+/**
+ * Retrieves a ProductVersion by tenancyId and productVersionId.
+ * Throws if not found.
+ */
+export async function getProductVersion(options: {
+  prisma: PrismaClientTransaction,
+  tenancyId: string,
+  productVersionId: string,
+}): Promise<{ productId: string | null, productJson: unknown }> {
+  const version = await options.prisma.productVersion.findUnique({
+    where: {
+      tenancyId_productVersionId: {
+        tenancyId: options.tenancyId,
+        productVersionId: options.productVersionId,
+      },
+    },
+  });
+
+  if (!version) {
+    throw new StackAssertionError(
+      "ProductVersion not found. This may indicate a race condition or deleted record.",
+      {
+        tenancyId: options.tenancyId,
+        productVersionId: options.productVersionId,
+      }
+    );
+  }
+
+  return {
+    productId: version.productId,
+    productJson: version.productJson,
+  };
+}
+
+import.meta.vitest?.describe("canonicalJsonStringify", (test) => {
+  test("produces same output regardless of key order", ({ expect }) => {
+    const obj1 = { b: 2, a: 1, c: 3 };
+    const obj2 = { a: 1, b: 2, c: 3 };
+    const obj3 = { c: 3, b: 2, a: 1 };
+
+    expect(canonicalJsonStringify(obj1)).toBe(canonicalJsonStringify(obj2));
+    expect(canonicalJsonStringify(obj2)).toBe(canonicalJsonStringify(obj3));
+  });
+
+  test("handles nested objects", ({ expect }) => {
+    const obj1 = { outer: { b: 2, a: 1 }, z: 1 };
+    const obj2 = { z: 1, outer: { a: 1, b: 2 } };
+
+    expect(canonicalJsonStringify(obj1)).toBe(canonicalJsonStringify(obj2));
+  });
+
+  test("preserves array order", ({ expect }) => {
+    const obj1 = { arr: [1, 2, 3] };
+    const obj2 = { arr: [3, 2, 1] };
+
+    expect(canonicalJsonStringify(obj1)).not.toBe(canonicalJsonStringify(obj2));
+  });
+
+  test("different objects produce different output", ({ expect }) => {
+    const obj1 = { a: 1 };
+    const obj2 = { a: 2 };
+
+    expect(canonicalJsonStringify(obj1)).not.toBe(canonicalJsonStringify(obj2));
+  });
+});
+
+import.meta.vitest?.describe("computeProductVersionId", (test) => {
+  test("produces same hash for same object with different key order", ({ expect }) => {
+    const obj1 = { b: 2, a: 1, c: 3 };
+    const obj2 = { a: 1, b: 2, c: 3 };
+
+    expect(computeProductVersionId(obj1)).toBe(computeProductVersionId(obj2));
+  });
+
+  test("produces different hash for different objects", ({ expect }) => {
+    const obj1 = { a: 1 };
+    const obj2 = { a: 2 };
+
+    expect(computeProductVersionId(obj1)).not.toBe(computeProductVersionId(obj2));
+  });
+
+  test("hash is deterministic", ({ expect }) => {
+    const obj = { foo: "bar", nested: { x: 1, y: 2 } };
+
+    const hash1 = computeProductVersionId(obj);
+    const hash2 = computeProductVersionId(obj);
+
+    expect(hash1).toBe(hash2);
+  });
+});

apps/backend/src/lib/stripe.tsx

@@ -1,4 +1,5 @@
 import { CustomerType } from "@/generated/prisma/client";
+import { getProductVersion } from "@/lib/product-versions";
 import { getTenancy, Tenancy } from "@/lib/tenancies";
 import { getPrismaClientForTenancy, globalPrismaClient } from "@/prisma-client";
 import { InputJsonValue } from "@prisma/client/runtime/client";
@@ -131,16 +132,30 @@ export async function syncStripeSubscriptions(stripe: Stripe, stripeAccountId: s
     const item = subscription.items.data[0];
     const sanitizedDates = sanitizeStripePeriodDates(item.current_period_start, item.current_period_end);
     const priceId = subscription.metadata.priceId as string | undefined;
-    // old subscriptions were created with offer metadata instead of product metadata
-    const productString = subscription.metadata.product as string | undefined ?? subscription.metadata.offer as string | undefined;
-    if (!productString) {
-      throw new StackAssertionError("Stripe subscription metadata missing product or offer", { subscriptionId: subscription.id });
-    }
+
     let productJson: InputJsonValue;
-    try {
-      productJson = JSON.parse(productString);
-    } catch (error) {
-      throw new StackAssertionError("Invalid JSON in Stripe subscription metadata", { subscriptionId: subscription.id, productString, error });
+    const productVersionId = subscription.metadata.productVersionId as string | undefined;
+    if (productVersionId) {
+      const version = await getProductVersion({
+        prisma,
+        tenancyId: tenancy.id,
+        productVersionId,
+      });
+      productJson = version.productJson as InputJsonValue;
+    } else {
+      // Backward compat: old subscriptions have product JSON directly in metadata or even older subscriptions were created with offer metadata
+      const productString = subscription.metadata.product as string | undefined ?? subscription.metadata.offer as string | undefined;
+      if (!productString) {
+        throw new StackAssertionError("Stripe subscription metadata missing productVersionId, product, or offer", {
+          subscriptionId: subscription.id,
+          tenancyId: tenancy.id,
+        });
+      }
+      try {
+        productJson = JSON.parse(productString);
+      } catch (error) {
+        throw new StackAssertionError("Invalid JSON in Stripe subscription metadata", { subscriptionId: subscription.id, productString, error });
+      }
     }
 
     await prisma.subscription.upsert({