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

@@ -1073,6 +1073,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

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) {
@@ -264,7 +270,10 @@ async function processStripeWebhookEvent(event: Stripe.Event): Promise<void> {
       customerType,
       customerId: metadata.customerId,
     });
-    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 productName = typeof product?.displayName === "string" ? product.displayName : "Purchase";
     const failureReason = paymentIntent.last_payment_error?.message;
     const extraVariables: Record<string, string | number> = {

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,12 +202,16 @@ export const POST = createSmartRouteHandler({
         }],
         metadata: {
           productId: body.to_product_id,
-          product: JSON.stringify(toProduct),
+          productVersionId,
           priceId: selectedPriceId,
         },
       });
       const updatedSubscription = updated as Stripe.Subscription;
-      const sanitizedUpdateDates = sanitizeStripePeriodDates(existingItem.current_period_start, existingItem.current_period_end);
+      const sanitizedUpdateDates = sanitizeStripePeriodDates(
+        existingItem.current_period_start,
+        existingItem.current_period_end,
+        { subscriptionId: subscription.stripeSubscriptionId, tenancyId: auth.tenancy.id }
+      );
 
       await prisma.subscription.update({
         where: {
@@ -239,7 +251,7 @@ export const POST = createSmartRouteHandler({
         }],
         metadata: {
           productId: body.to_product_id,
-          product: JSON.stringify(toProduct),
+          productVersionId,
           priceId: selectedPriceId,
         },
       });
@@ -248,7 +260,11 @@ export const POST = createSmartRouteHandler({
         throw new StackAssertionError("Stripe subscription has no items", { stripeSubscriptionId: createdSubscription.id });
       }
       const createdItem = createdSubscription.items.data[0];
-      const sanitizedCreateDates = sanitizeStripePeriodDates(createdItem.current_period_start, createdItem.current_period_end);
+      const sanitizedCreateDates = sanitizeStripePeriodDates(
+        createdItem.current_period_start,
+        createdItem.current_period_end,
+        { subscriptionId: createdSubscription.id, tenancyId: auth.tenancy.id }
+      );
 
       await prisma.subscription.create({
         data: {

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,177 @@
+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 productId and product JSON object.
+ * Uses SHA-256 hash of the canonical JSON representation.
+ *
+ * Including productId ensures different products with identical JSON get separate rows.
+ * Inline products (null productId) with identical JSON will still share a row,
+ * which is acceptable since if they have the same productJson, semantically they are the same product.
+ */
+export function computeProductVersionId(productId: string | null, productJson: unknown): string {
+  const canonical = canonicalJsonStringify({ productId, 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.productId, 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 productId and object with different key order", ({ expect }) => {
+    const obj1 = { b: 2, a: 1, c: 3 };
+    const obj2 = { a: 1, b: 2, c: 3 };
+
+    expect(computeProductVersionId("prod-1", obj1)).toBe(computeProductVersionId("prod-1", obj2));
+  });
+
+  test("produces different hash for different objects", ({ expect }) => {
+    const obj1 = { a: 1 };
+    const obj2 = { a: 2 };
+
+    expect(computeProductVersionId("prod-1", obj1)).not.toBe(computeProductVersionId("prod-1", obj2));
+  });
+
+  test("produces different hash for different productIds with same object", ({ expect }) => {
+    const obj = { a: 1 };
+
+    expect(computeProductVersionId("prod-1", obj)).not.toBe(computeProductVersionId("prod-2", obj));
+  });
+
+  test("produces same hash for null productIds with same object", ({ expect }) => {
+    const obj = { a: 1 };
+
+    expect(computeProductVersionId(null, obj)).toBe(computeProductVersionId(null, obj));
+  });
+
+  test("produces different hash for null productIds with different objects", ({ expect }) => {
+    const obj1 = { a: 1 };
+    const obj2 = { a: 2 };
+
+    expect(computeProductVersionId(null, obj1)).not.toBe(computeProductVersionId(null, obj2));
+  });
+
+  test("hash is deterministic", ({ expect }) => {
+    const obj = { foo: "bar", nested: { x: 1, y: 2 } };
+
+    const hash1 = computeProductVersionId("prod-1", obj);
+    const hash2 = computeProductVersionId("prod-1", obj);
+
+    expect(hash1).toBe(hash2);
+  });
+});