apps/backend/prisma/migrations/20250820164831_custom_customer_types/migration.sql (1)

1-16: Adding NOT NULL column without default can fail on non-empty tables.

This will error if ItemQuantityChange has rows. Use a two-step migration: add as nullable, backfill, then set NOT NULL. Also ensure backfill uses the correct customerType derived from your data.

Here’s a safe pattern to adapt:

 -- AlterEnum
 ALTER TYPE "CustomerType" ADD VALUE 'CUSTOM';

--- AlterTable
-ALTER TABLE "ItemQuantityChange" ADD COLUMN     "customerType" "CustomerType" NOT NULL,
-ALTER COLUMN "customerId" SET DATA TYPE TEXT;
+-- AlterTable (step 1: add nullable)
+ALTER TABLE "ItemQuantityChange" 
+  ADD COLUMN "customerType" "CustomerType",
+  ALTER COLUMN "customerId" SET DATA TYPE TEXT;
+
+-- Backfill (step 2: set proper values; adjust logic to your data model)
+-- Example placeholder (set all to USER if that's guaranteed safe; otherwise join against items config)
+-- UPDATE "ItemQuantityChange" ic SET "customerType" = 'USER' WHERE "customerType" IS NULL;
+
+-- AlterTable (step 3: enforce NOT NULL)
+ALTER TABLE "ItemQuantityChange" 
+  ALTER COLUMN "customerType" SET NOT NULL;

 -- AlterTable
 ALTER TABLE "Subscription" ALTER COLUMN "customerId" SET DATA TYPE TEXT;

If the table is guaranteed empty in all environments, keeping NOT NULL in a single step is fine; otherwise, prefer the two-step approach.

packages/stack-shared/src/interface/client-interface.ts (1)

1779-1801: Use stringifyJson per code patterns (JSON.stringify is disallowed here)

This file adheres to a rule to use stringifyJson from stack-shared/utils/json. The changed line still uses JSON.stringify.

Apply within the changed range:

-        body: JSON.stringify({ customer_type, customer_id, ...offerBody }),
+        body: stringifyJson({ customer_type, customer_id, ...offerBody }),

And add the import (outside the changed hunk):

// at the top alongside ReadonlyJson
import { ReadonlyJson, stringifyJson } from '../utils/json';

packages/stack-shared/src/interface/server-interface.ts (1)

862-867: Encode path segments (customerType/customerId/itemId) to avoid malformed URLs and potential routing issues.

The template literal inserts unencoded values into the path. If any identifier contains reserved characters (e.g., spaces, slashes, unicode), requests can break or misroute. Encode each segment or use the project’s urlString util consistently.

-      `/payments/items/${customerType}/${customerId}/${itemId}/update-quantity?${queryParams.toString()}`,
+      `/payments/items/${encodeURIComponent(customerType)}/${encodeURIComponent(customerId)}/${encodeURIComponent(itemId)}/update-quantity?${queryParams.toString()}`,

Alternatively (for consistency with the rest of this file), you can switch to urlString for the path and append the query string:

const path = urlString`/payments/items/${customerType}/${customerId}/${itemId}/update-quantity` + `?${queryParams.toString()}`;
await this.sendServerRequest(path, { /* ... */ }, null);

packages/template/src/lib/stack-app/apps/implementations/admin-app-impl.ts (1)

511-518: Remove any-cast; narrow the discriminated union safely.

The current approach uses (options as any).customId. Prefer standard discriminated narrowing to retain type safety.

-  async createItemQuantityChange(options: (
-    { userId: string, itemId: string, quantity: number, expiresAt?: string, description?: string } |
-    { teamId: string, itemId: string, quantity: number, expiresAt?: string, description?: string } |
-    { customId: string, itemId: string, quantity: number, expiresAt?: string, description?: string }
-  )): Promise<void> {
+  async createItemQuantityChange(options: (
+    { userId: string, itemId: string, quantity: number, expiresAt?: string, description?: string } |
+    { teamId: string, itemId: string, quantity: number, expiresAt?: string, description?: string } |
+    { customId: string, itemId: string, quantity: number, expiresAt?: string, description?: string }
+  )): Promise<void> {
     await this._interface.updateItemQuantity(
-      { itemId: options.itemId, ...("userId" in options ? { userId: options.userId } : ("teamId" in options ? { teamId: options.teamId } : { customId: (options as any).customId })) },
+      {
+        itemId: options.itemId,
+        ...("userId" in options
+          ? { userId: options.userId }
+          : ("teamId" in options
+            ? { teamId: options.teamId }
+            : { customId: options.customId }))
+      },
       {
         delta: options.quantity,
         expires_at: options.expiresAt,
         description: options.description,
       }
     );
   }

apps/backend/prisma/schema.prisma (2)

22-22: Confirm unrelated change to ownerTeamId.

Line 22 is marked as modified, but it’s effectively the same declaration. If this was accidental churn (e.g., whitespace/formatting), consider dropping it to reduce noise. If intentional, ignore.

---

753-765: Consider indexing customerType for query efficiency.

Likely hot paths filter by tenancyId + customerType + customerId + itemId (+ expiresAt). Current index omits customerType and itemId, which can degrade performance with the new dimension.

Apply this diff to add a composite index:

 model ItemQuantityChange {
   id           String       @default(uuid()) @db.Uuid
   tenancyId    String       @db.Uuid
   customerType CustomerType
   customerId   String
   itemId       String
   quantity     Int
   description  String?
   expiresAt    DateTime?
   createdAt    DateTime     @default(now())

   @@id([tenancyId, id])
-  @@index([tenancyId, customerId, expiresAt])
+  @@index([tenancyId, customerId, expiresAt])
+  @@index([tenancyId, customerType, customerId, itemId, expiresAt])
 }

apps/backend/src/lib/payments.tsx (1)

58-101: Customer-type aware quantity calculation looks correct; add DB indexes to keep queries fast

The switch to filtering by customerType (uppercased) in both Subscription and ItemQuantityChange is correct and consistent with the new enum. To prevent regressions at scale, add composite indexes aligned with these where-clauses.

Suggested indexes (pseudo-sql/Prisma):

• Subscription: (tenancyId, customerType, customerId, status)
• ItemQuantityChange: (tenancyId, customerType, customerId, itemId, expiresAt)

These match the high-selectivity filters used by getItemQuantityForCustomer.

apps/e2e/tests/backend/endpoints/api/v1/payments/purchase-session.test.ts (1)

94-113: Optionally add coverage for mismatched customer_type vs inline_offer.customer_type

A negative test asserting OfferCustomerTypeDoesNotMatch would harden the contract.

If helpful, I can draft an additional test case that sends a mismatched pair and expects the known error response.

packages/template/src/lib/stack-app/apps/interfaces/server-app.ts (1)

58-63: Deduplicate the “item key” union across client/server

The exact union type for item keys is duplicated here and in the client interface. Consider extracting a shared alias (e.g., ItemKey = { itemId: string } & ({ userId: string } | { teamId: string } | { customId: string })) in customers/index.ts and importing it in both places to avoid drift.

Example:

// packages/template/src/lib/stack-app/customers/index.ts
export type ItemKey =
  | { itemId: string, userId: string }
  | { itemId: string, teamId: string }
  | { itemId: string, customId: string };

Then here:

-  & AsyncStoreProperty<
-    "item",
-    [{ itemId: string, userId: string } | { itemId: string, teamId: string } | { itemId: string, customId: string }],
-    ServerItem,
-    false
-  >
+  & AsyncStoreProperty<"item", [ItemKey], ServerItem, false>

apps/e2e/tests/backend/endpoints/api/v1/payments/create-purchase-url.test.ts (2)

232-238: Avoid snapshotting dynamic purchase URL — reduce flakiness

Inline snapshot asserts the full URL including a generated token. Even with "", the remaining random suffix may change. Prefer asserting status + URL shape (you already do with the regex below) and skip the full inline snapshot.

Replace the snapshot with a direct status assertion:

-  expect(response).toMatchInlineSnapshot(`
-    NiceResponse {
-      "status": 200,
-      "body": { "url": "http://localhost:8101/purchase/<stripped UUID>_cngg259jnn72d55dxfzmafzan54vcw7n429evq7bfbaa0" },
-      "headers": Headers { <some fields may have been hidden> },
-    }
-  `);
+  expect(response.status).toBe(200);

---

171-201: Nit: duplicate customer_type in nested offer_inline

You’re specifying customer_type at both the top-level request and inside offer_inline. If the route requires both, ignore this. Otherwise consider relying on a single source of truth to avoid divergence in future edits.

If only one is required, consider removing the redundant one in the client-path negative test to simplify payload.

Also applies to: 211-231

apps/dashboard/src/app/(main)/(protected)/projects/[projectId]/payments/page-client.tsx (1)

171-171: DRY up duplicated customer type literals

The allowed values and select options are repeated for offers and items. Consider centralizing:

• A shared union literal array (e.g., const customerTypeOptions = [{ value: "user", ...}, ...]) and reuse in both forms.
• A shared yup schema (if not already in stack-shared) imported here to avoid drift.

Example:

const customerTypeOptions = [
  { value: "user", label: "User" },
  { value: "team", label: "Team" },
  { value: "custom", label: "Custom" },
];

// In both schemas:
yup.string().oneOf(customerTypeOptions.map(o => o.value as const)).defined().label("Customer Type");

Also applies to: 233-239

packages/template/src/lib/stack-app/apps/interfaces/client-app.ts (1)

80-85: Avoid duplicating the item key union across client/server

Same suggestion as server interface: extract a shared ItemKey type to customers/index.ts and reuse here for consistency and easier evolution.

-  & AsyncStoreProperty<
-    "item",
-    [{ itemId: string, userId: string } | { itemId: string, teamId: string } | { itemId: string, customId: string }],
-    Item,
-    false
-  >
+  & AsyncStoreProperty<"item", [ItemKey], Item, false>

apps/e2e/tests/backend/endpoints/api/v1/payments/items.test.ts (1)

165-172: Reduce URL construction duplication with small helpers

The file repeats building item paths and querystrings. Consider tiny helpers to reduce duplication and make future route-shape changes safer.

Example at top of file:

function itemUrl(scope: "user" | "team" | "custom", id: string, itemId: string) {
  return `/api/latest/payments/items/${scope}/${id}/${itemId}`;
}
function updateQuantityUrl(scope: "user" | "team" | "custom", id: string, itemId: string, allowNegative: boolean) {
  return `${itemUrl(scope, id, itemId)}/update-quantity?allow_negative=${allowNegative ? "true" : "false"}`;
}

Then:

await niceBackendFetch(updateQuantityUrl("user", user.userId, "test-item", false), { ... })

Also applies to: 194-199, 224-229, 255-261, 424-428

packages/template/src/lib/stack-app/apps/interfaces/admin-app.ts (1)

79-83: Type union looks good; consider DRYing shared fields for maintainability.

Options share the same item fields; extracting a base type reduces duplication and helps future changes (e.g., adding a new optional field once).

Apply this minimal change inside the existing union (optional), or introduce shared types at file scope:

-    createItemQuantityChange(options: (
-      { userId: string, itemId: string, quantity: number, expiresAt?: string, description?: string } |
-      { teamId: string, itemId: string, quantity: number, expiresAt?: string, description?: string } |
-      { customId: string, itemId: string, quantity: number, expiresAt?: string, description?: string }
-    )): Promise<void>,
+    createItemQuantityChange(options: (
+      ({ userId: string } | { teamId: string } | { customId: string })
+      & { itemId: string, quantity: number, expiresAt?: string, description?: string }
+    )): Promise<void>,

If you prefer explicit names, add these near the top of the file and then reference them:

type ItemQuantityChangeCore = { itemId: string; quantity: number; expiresAt?: string; description?: string };
type ItemOwner = { userId: string } | { teamId: string } | { customId: string };
type CreateItemQuantityChangeOptions = ItemOwner & ItemQuantityChangeCore;
// ...
// createItemQuantityChange(options: CreateItemQuantityChangeOptions): Promise<void>

packages/stack-shared/src/interface/server-interface.ts (1)

845-846: Remove redundant type annotation; rely on inference.

Minor cleanup: the explicit type on itemId is redundant.

-    const itemId: string = options.itemId;
+    const { itemId } = options;

packages/template/src/lib/stack-app/apps/implementations/client-app-impl.ts (1)

1206-1217: Deduplicate getItem branch logic.

This can be simplified while keeping behavior intact.

-  async getItem(options: { itemId: string, userId: string } | { itemId: string, teamId: string } | { itemId: string, customId: string }): Promise<Item> {
-    const session = await this._getSession();
-    let crud: ItemCrud['Client']['Read'];
-    if ("userId" in options) {
-      crud = Result.orThrow(await this._userItemCache.getOrWait([session, options.userId, options.itemId], "write-only"));
-    } else if ("teamId" in options) {
-      crud = Result.orThrow(await this._teamItemCache.getOrWait([session, options.teamId, options.itemId], "write-only"));
-    } else {
-      crud = Result.orThrow(await this._customItemCache.getOrWait([session, options.customId, options.itemId], "write-only"));
-    }
-    return this._clientItemFromCrud(crud);
-  }
+  async getItem(options: { itemId: string, userId: string } | { itemId: string, teamId: string } | { itemId: string, customId: string }): Promise<Item> {
+    const session = await this._getSession();
+    const [cache, ownerId] =
+      "userId" in options ? [this._userItemCache, options.userId] :
+      "teamId" in options ? [this._teamItemCache, options.teamId] :
+                            [this._customItemCache, options.customId];
+    const crud = Result.orThrow(await cache.getOrWait([session, ownerId, options.itemId] as const, "write-only"));
+    return this._clientItemFromCrud(crud);
+  }

apps/e2e/tests/js/payments.test.ts (1)

192-192: Strengthen assertion: expect the specific KnownError.

Asserting the precise error type improves signal and avoids false positives.

-  await expect(adminApp.createItemQuantityChange({ teamId: team.id, itemId, quantity: -1 }))
-    .rejects.toThrow();
+  await expect(
+    adminApp.createItemQuantityChange({ teamId: team.id, itemId, quantity: -1 })
+  ).rejects.toThrow(KnownErrors.ItemQuantityInsufficientAmount);

Add this import at the top of the file:

import { KnownErrors } from "@stackframe/stack-shared";

apps/backend/src/app/api/latest/payments/items/[customer_type]/[customer_id]/[item_id]/route.ts (1)

20-23: Prefer shared schema: use customerTypeSchema for a single source of truth.

Inline oneOf duplicates definitions across the codebase. Importing the shared schema keeps enum values consistent with future changes.

-      customer_type: yupString().oneOf(["user", "team", "custom"]).defined(),
+      customer_type: customerTypeSchema.defined(),

Add to the existing schema-fields import:

import { adaptSchema, clientOrHigherAuthTypeSchema, yupNumber, yupObject, yupString, customerTypeSchema } from "@stackframe/stack-shared/dist/schema-fields";

apps/backend/src/app/api/latest/payments/purchases/create-purchase-url/route.ts (1)

22-24: Add light schema validation for customer_id

Although we escape single quotes when constructing the Stripe query, constraining customer_id at the schema level helps guard against malformed or malicious inputs and avoids query errors.

• File: apps/backend/src/app/api/latest/payments/purchases/create-purchase-url/route.ts
Lines: 22–24

Suggested diff:

   customer_type: yupString().oneOf(["user", "team", "custom"]).defined(),
-  customer_id: yupString().defined(),
+  customer_id: yupString()
+    .matches(/^[A-Za-z0-9_-]+$/, "customer_id may only contain letters, numbers, hyphens, and underscores")
+    .defined(),
   offer_id: yupString().optional(),

apps/backend/src/app/api/latest/payments/items/[customer_type]/[customer_id]/[item_id]/update-quantity/route.ts (1)

69-74: Validate expires_at as an ISO date to avoid Invalid Date writes.

new Date(req.body.expires_at) will produce Invalid Date for malformed input, which can bubble into runtime/DB errors. Prefer explicit date validation.

-      expires_at: yupString().optional(),
+      // If ISO 8601 is expected, enforce it at the edge
+      expires_at: yupString().matches(
+        /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/,
+        "expires_at must be an ISO 8601 UTC timestamp"
+      ).optional(),

Alternatively, use a yup date schema if available and acceptable across the codebase.

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

Learnt from: CR
PR: stack-auth/stack-auth#0
File: CLAUDE.md:0-0
Timestamp: 2025-08-04T22:25:51.260Z
Learning: Applies to apps/backend/prisma/schema.prisma : Database models use Prisma

apps/e2e/tests/backend/endpoints/api/v1/payments/create-purchase-url.test.ts (1)

5-27: Consider adding at least one positive/negative case for customer_type: "custom".

Since this PR adds "custom" support across the stack, adding a basic acceptance test here (valid customId path + mismatch/error path) would tighten coverage for the purchases endpoint too.

I can draft two focused tests: one success with offer_id configured for "custom", and one mismatch returning OFFER_CUSTOMER_TYPE_DOES_NOT_MATCH. Want me to add them?

Also applies to: 29-78, 134-173, 176-206, 208-239, 241-278

apps/backend/src/lib/payments.tsx (1)

103-140: ensureCustomerExists: use UserIdDoesNotExist for users and guard “custom” IDs

For consistency and better DX:

• UserNotFound’s constructor takes zero arguments, so don’t pass customerId to it. If you want the ID in the error, swap to
  throw new KnownErrors.UserIdDoesNotExist(options.customerId)
• Add an explicit guard for empty IDs when customerType === "custom"

Changes:

• In apps/backend/src/lib/payments.tsx

@@ export async function ensureCustomerExists(options: {
   if (options.customerType === "user") {
     if (!isUuid(options.customerId)) {
-      throw new KnownErrors.UserNotFound();
+      throw new KnownErrors.UserIdDoesNotExist(options.customerId);
     }
     const user = await options.prisma.projectUser.findUnique({
@@
     if (!user) {
-      throw new KnownErrors.UserNotFound();
+      throw new KnownErrors.UserIdDoesNotExist(options.customerId);
     }
   } else if (options.customerType === "team") {
@@
-  }
+  } else if (options.customerType === "custom") {
+    if (options.customerId.trim().length === 0) {
+      // Keep error shape consistent with other 4xx validation paths
+      throw new StatusError(400, "customer_id must be non-empty for custom customers");
+    }
+  }

• Add import at top if not already present:

import { StatusError } from "@stackframe/stack-shared/dist/utils/errors";

apps/dashboard/src/components/data-table/payment-item-table.tsx (1)

147-151: Updated error handling matches new backend semantics.

Switching to UserNotFound/TeamNotFound is consistent with the new ensureCustomerExists flow. Consider adding a specific message for invalid/empty Custom IDs if you adopt a non-empty check server-side.

apps/backend/src/app/api/latest/payments/items/[customer_type]/[customer_id]/[item_id]/route.ts (1)

20-23: Optionally enforce non-empty custom customer_id.

Currently customer_id uses yupString().defined(), which allows empty strings. For "custom", that would flow through and produce changes for an empty identifier. Consider a minimal runtime check here (lighter than a schema-level conditional):

   if (!itemConfig) {
     throw new KnownErrors.ItemNotFound(req.params.item_id);
   }
+  if (req.params.customer_type === "custom" && req.params.customer_id.trim().length === 0) {
+    throw new StatusError(400, "customer_id must be non-empty for custom customers");
+  }

You’d need to import StatusError:

import { StatusError } from "@stackframe/stack-shared/dist/utils/errors";

If you’d prefer schema-level validation, we can add a conditional yup.when on customer_type.

Also applies to: 42-44

apps/backend/src/app/api/latest/payments/items/[customer_type]/[customer_id]/[item_id]/update-quantity/route.ts (2)

20-23: End-to-end: customer_type wiring and persistence look solid; validate expires_at to avoid invalid dates.

• The route schema and mismatch check are correct.
• ensureCustomerExists and uppercasing for persistence match the DB enum.
• One potential footgun: expires_at is a free-form string. If it’s malformed, new Date(...) yields Invalid Date, which can lead to DB errors or bad data.

Strengthen the body schema or add a runtime guard:

Schema-level (minimal change using a test):

 body: yupObject({
   delta: yupNumber().integer().defined(),
-  expires_at: yupString().optional(),
+  expires_at: yupString()
+    .test("is-iso-date", "expires_at must be a valid ISO date string", v => !v || !Number.isNaN(Date.parse(v)))
+    .optional(),
   description: yupString().optional(),
 }).defined(),

Or runtime guard before create:

const expiresAt = req.body.expires_at ? new Date(req.body.expires_at) : null;
if (expiresAt && Number.isNaN(expiresAt.getTime())) {
  throw new StatusError(400, "expires_at must be a valid ISO date string");
}

(For this runtime approach, import StatusError from @stackframe/stack-shared/dist/utils/errors.)

Also applies to: 49-51, 53-58, 65-67, 75-80

---

25-26: Nit: consider a boolean query param for allow_negative.

Using "true"/"false" strings is fine, but switching to a boolean in the schema (and auto-parsing) would be a small DX improvement.

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

packages/template/src/lib/stack-app/apps/implementations/client-app-impl.ts (1)

1220-1229: Conditional hook issue fixed — useAsyncCache is now called unconditionally.

This addresses the prior Biome error on conditional hooks in useItem.

packages/template/src/lib/stack-app/apps/implementations/client-app-impl.ts (1)

605-609: Wording nit: reference the actual tokenStore values.

Error message currently suggests tokenStore value 'cookies', while the code uses 'cookie' and 'nextjs-cookie'.

Apply this small wording tweak:

-      throw new Error("Cannot call this function on a Stack app without a persistent token store. Make sure the tokenStore option on the constructor is set to a non-null value when initializing Stack.\n\nStack uses token stores to access access tokens of the current user. For example, on web frontends it is commonly the string value 'cookies' for cookie storage.");
+      throw new Error("Cannot call this function on a Stack app without a persistent token store. Make sure the tokenStore option on the constructor is set to a non-null value when initializing Stack.\n\nStack uses token stores to access access tokens of the current user. For example, on web frontends the tokenStore is commonly 'cookie' or 'nextjs-cookie'.");

packages/template/src/lib/stack-app/apps/implementations/admin-app-impl.ts (1)

517-523: Minor readability refactor: extract owner object before calling updateItemQuantity.

Current nested spread is correct but a bit dense to read.

Apply this small refactor:

-    await this._interface.updateItemQuantity(
-      { itemId: options.itemId, ...("userId" in options ? { userId: options.userId } : ("teamId" in options ? { teamId: options.teamId } : { customId: options.customId })) },
+    const owner =
+      "userId" in options ? { userId: options.userId } :
+      "teamId" in options ? { teamId: options.teamId } :
+                            { customId: options.customId };
+    await this._interface.updateItemQuantity(
+      { itemId: options.itemId, ...owner },
       {
         delta: options.quantity,
         expires_at: options.expiresAt,
         description: options.description,
       }
     );

packages/template/src/lib/stack-app/apps/implementations/server-app-impl.ts (1)

1011-1035: Add missing dependencies to useMemo to avoid stale closures.

The returned ServerItem captures type and id inside useMemo but only depends on result. Include id and type to be safe when the discriminator changes.

Apply this minimal fix:

-    return useMemo(() => this._serverItemFromCrud({ type, id }, result), [result]);
+    return useMemo(() => this._serverItemFromCrud({ type, id }, result), [result, id, type]);

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

packages/stack-shared/src/interface/server-interface.ts (1)

866-871: Encode path segments; avoid raw template literals for user-supplied IDs.

customerType/customerId/itemId can include characters (e.g., slashes) that break the path or cause route mismatches. Use the existing urlString template tag (or encodeURIComponent per segment) to prevent path injection and 404s. This was flagged earlier; elevating to a correctness/security fix.

Apply one of the following diffs:

Option A — preferred (urlString helper):

-      `/payments/items/${customerType}/${customerId}/${itemId}/update-quantity?${queryParams.toString()}`,
+      urlString`/payments/items/${customerType}/${customerId}/${itemId}/update-quantity?${queryParams.toString()}`,

Option B — explicit encoding:

-      `/payments/items/${customerType}/${customerId}/${itemId}/update-quantity?${queryParams.toString()}`,
+      `/payments/items/${encodeURIComponent(customerType)}/${encodeURIComponent(customerId)}/${encodeURIComponent(itemId)}/update-quantity?${queryParams.toString()}`,

packages/stack-shared/src/interface/client-interface.ts (3)

17-17: Good fix: use urlString for safe path templating (encodes segments).

This import enables encoded path construction and resolves prior concerns about unencoded dynamic segments in item routes.

---

1776-1778: Path now encodes all dynamic segments.

urlString\/payments/items/${customerType}/${customerId}/${options.itemId}`` correctly encodes every segment. This closes the routing breakage when IDs contain reserved characters.

---

1796-1801: Follow code-patterns: prefer stringifyJson over JSON.stringify for request bodies.

The repo’s rule requires using stringifyJson to guarantee deterministic serialization and safe error handling.

Apply:

-        body: JSON.stringify({ customer_type, customer_id, ...offerBody }),
+        body: stringifyJson({ customer_type, customer_id, ...offerBody }),

And add/import stringifyJson (outside this hunk):

// near the top with other utils
import { ReadonlyJson, stringifyJson } from '../utils/json';

Check remaining direct uses in this file to avoid future bot comments:

#!/bin/bash
rg -nP --glob '!**/node_modules/**' 'JSON\.stringify\(' packages/stack-shared/src/interface/client-interface.ts

packages/template/src/lib/stack-app/apps/implementations/client-app-impl.ts (1)

1224-1231: Hook order fixed: single unconditional useAsyncCache call.

This addresses the previous “conditional hook” lint error for useItem.

packages/stack-shared/src/interface/server-interface.ts (2)

847-863: Guard against multiple identifiers being provided simultaneously.

At runtime, an object could contain more than one of userId/teamId/customCustomerId (e.g., from spread-merging). Today the first matching branch wins silently. Add a defensive check to ensure exactly one is set; fail fast with a clear error.

Apply this diff within this block:

-    if ("userId" in options) {
+    const idsProvided = ["userId", "teamId", "customCustomerId"].filter((k) => k in options);
+    if (idsProvided.length !== 1) {
+      throw new StackAssertionError(`updateItemQuantity requires exactly one of userId, teamId, or customCustomerId (got: ${idsProvided.join(", ") || "none"})`);
+    }
+
+    if ("userId" in options) {
       customerType = "user";
       customerId = options.userId;
     } else if ("teamId" in options) {
       customerType = "team";
       customerId = options.teamId;
     } else if ("customCustomerId" in options) {
       customerType = "custom";
       customerId = options.customCustomerId;
-    } else {
-      throw new StackAssertionError("updateItemQuantity requires one of userId, teamId, or customCustomerId");
-    }
+    }

---

869-870: Header casing consistency.

The file mixes "content-type" and "Content-Type". HTTP is case-insensitive, but pick one for consistency.

Apply this tiny diff here:

-        headers: { "content-type": "application/json" },
+        headers: { "Content-Type": "application/json" },

packages/template/src/lib/stack-app/apps/implementations/admin-app-impl.ts (3)

521-522: Replace nested ternary with clearer branching.

The nested ternary with "in" checks is hard to scan and easy to break if extended. Use an if/else chain mirroring server-interface for readability and parity.

Apply this refactor:

-      { itemId: options.itemId, ...("userId" in options ? { userId: options.userId } : ("teamId" in options ? { teamId: options.teamId } : { customCustomerId: options.customCustomerId })) },
+      (() => {
+        if ("userId" in options) return { itemId: options.itemId, userId: options.userId };
+        if ("teamId" in options) return { itemId: options.itemId, teamId: options.teamId };
+        return { itemId: options.itemId, customCustomerId: options.customCustomerId };
+      })(),

---

515-519: Support decrements via allowNegative or auto-detect.

The server call honors allow_negative via a query param, but this admin method has no way to set it. If quantity can be negative (revokes/credits), calls will fail or be rejected. Either expose allowNegative?: boolean, or infer it when quantity < 0.

Apply this minimal, backward-compatible change:

-  async createItemQuantityChange(options: (
-    { userId: string, itemId: string, quantity: number, expiresAt?: string, description?: string } |
-    { teamId: string, itemId: string, quantity: number, expiresAt?: string, description?: string } |
-    { customCustomerId: string, itemId: string, quantity: number, expiresAt?: string, description?: string }
-  )): Promise<void> {
+  async createItemQuantityChange(options: (
+    { userId: string, itemId: string, quantity: number, expiresAt?: string, description?: string, allowNegative?: boolean } |
+    { teamId: string, itemId: string, quantity: number, expiresAt?: string, description?: string, allowNegative?: boolean } |
+    { customCustomerId: string, itemId: string, quantity: number, expiresAt?: string, description?: string, allowNegative?: boolean }
+  )): Promise<void> {

And include the flag in the payload mapping:

       {
         delta: options.quantity,
         expires_at: options.expiresAt,
         description: options.description,
+        allow_negative: options.allowNegative ?? (options.quantity < 0),
       }

Note: If ItemCrud['Server']['Update'] doesn’t include allow_negative in the body and only as a query param, alternatively plumb it into the first arg and let the interface derive the query param. If you prefer that, I can provide a matching change to the interface method.

---

515-527: Type hygiene: consider extracting a shared scope type.

Both admin and server interfaces model the same tri-scope shape. Extract a shared type (e.g., ItemQuantityScope) in stack-shared to prevent divergence.

I can prep a small PR to add:

• packages/stack-shared/src/interface/types.ts: export type ItemQuantityScope = …
• Use it in both places.
  Would you like me to draft that?

packages/template/src/lib/stack-app/apps/implementations/client-app-impl.ts (1)

685-697: Minor: prefer method shorthand to avoid accidental this rebinding.

Defining methods with function () {} relies on call-site binding; destructuring (const { isValid } = key) would break this. Use method shorthand to keep semantics and improve readability.

Apply:

-      isValid: function () {
+      isValid() {
         return this.whyInvalid() === null;
       },
-      whyInvalid: function () {
+      whyInvalid() {
         if (this.manuallyRevokedAt) {
           return "manually-revoked";
         }
         if (this.expiresAt && this.expiresAt < new Date()) {
           return "expired";
         }
         return null;
       },

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

apps/backend/src/lib/payments.tsx (1)

64-65: Ensure all getItemQuantityForCustomer call sites pass customerType.

The signature now requires customerType. Please verify all invocations were updated; older sites may still omit it.

Run to list argument objects and quickly spot missing keys:

#!/bin/bash
# Show all call sites and the argument object for getItemQuantityForCustomer
rg -nP -C2 --type=ts '\bgetItemQuantityForCustomer\s*\(\s*\{[^}]*\}\s*\)' \
  | sed -n '1,200p'
# Specifically highlight lines lacking 'customerType'
rg -nP --type=ts '\bgetItemQuantityForCustomer\s*\(\s*\{(?![^}]*\bcustomerType\b)' -C1

apps/dashboard/src/components/data-table/payment-item-table.tsx (1)

148-154: Make customerType required; don’t silently fall back to “custom”.

Leaving customerType optional means undefined flows to the “custom” branch in submit. Make it required in props and guard before submission.

 type CreateItemQuantityChangeDialogProps = {
   open: boolean,
   onOpenChange: (open: boolean) => void,
   itemId: string,
-  customerType: "user" | "team" | "custom" | undefined,
+  customerType: "user" | "team" | "custom",
 }

And in submit (below), add a defensive guard (see next comment).

apps/dashboard/src/lib/utils.tsx (1)

24-29: Good move to safer parsing; add a narrow-to-string[] guard to avoid accidental non-string entries.

parseJson shields against throws, but JSON can still be an array with non-string elements. Filter to string[] before includes to keep behavior predictable.

Apply:

-  const allowedProjectIds = parseJson(getPublicEnvVar("NEXT_PUBLIC_STACK_ENABLE_DEVELOPMENT_FEATURES_PROJECT_IDS") || "[]");
-  if (allowedProjectIds.status !== "ok" || !Array.isArray(allowedProjectIds.data)) {
-    return false;
-  }
-  return allowedProjectIds.data.includes(projectId);
+  const parsed = parseJson(getPublicEnvVar("NEXT_PUBLIC_STACK_ENABLE_DEVELOPMENT_FEATURES_PROJECT_IDS") || "[]");
+  if (parsed.status !== "ok" || !Array.isArray(parsed.data)) {
+    return false;
+  }
+  const ids = parsed.data.filter((v): v is string => typeof v === "string");
+  return ids.includes(projectId);

Optional: normalize whitespace to reduce surprises from hand-edited envs:

-  const ids = parsed.data.filter((v): v is string => typeof v === "string");
+  const ids = parsed.data
+    .filter((v): v is string => typeof v === "string")
+    .map(s => s.trim());

apps/dashboard/src/app/(main)/(protected)/projects/[projectId]/payments/page-client.tsx (2)

80-84: Gate rendering of Connect UI until setup is complete; also avoid inline style.

• Rendering <ConnectPayments /> when stripeAccountSetupComplete is false can produce confusing UX or errors, depending on how your Connect instance is configured.
• Prefer Tailwind classes over inline style for consistency and easier theming.

Apply this diff:

-      <div className="flex justify-center">
-        <div style={{ maxWidth: 1250, width: '100%' }}>
-          <ConnectPayments />
-        </div>
-      </div>
+      {paymentsConfig.stripeAccountSetupComplete ? (
+        <div className="flex justify-center">
+          <div className="w-full max-w-[1250px]">
+            <ConnectPayments />
+          </div>
+        </div>
+      ) : (
+        <div className="flex justify-center">
+          <Button onClick={setupPayments}>Complete Setup</Button>
+        </div>
+      )}

If the page is not already wrapped by ConnectComponentsProvider, you’ll also need to wrap the component:

// outside the selected range; illustrative only
import { ConnectComponentsProvider, ConnectPayments } from "@stripe/react-connect-js";
import { loadConnectAndInitialize, type ConnectInstance } from "@stripe/connect-js";
import { useEffect, useState } from "react";

function PaymentsPanel() {
  const [connectInstance, setConnectInstance] = useState<ConnectInstance | null>(null);

  useEffect(() => {
    let mounted = true;
    (async () => {
      // TODO: replace with your real publisher key and client-secret fetcher
      const instance = await loadConnectAndInitialize({
        publishableKey: process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY!,
        fetchClientSecret: async () => (await fetch("/api/stripe/connect/client-secret")).text(),
      });
      if (mounted) setConnectInstance(instance);
    })();
    return () => { mounted = false; };
  }, []);

  if (!connectInstance) return null; // or a skeleton

  return (
    <ConnectComponentsProvider connectInstance={connectInstance}>
      <ConnectPayments />
    </ConnectComponentsProvider>
  );
}

---

26-30: Add error handling around payments setup redirect.

A network failure or server error from setupPayments() will currently surface as an unhandled promise rejection. Show a toast and avoid redirect attempts when the call fails.

-  const setupPayments = async () => {
-    const { url } = await stackAdminApp.setupPayments();
-    window.location.href = url;
-    await wait(2000);
-  };
+  const setupPayments = async () => {
+    try {
+      const { url } = await stackAdminApp.setupPayments();
+      window.location.href = url;
+      await wait(2000);
+    } catch (err: any) {
+      toast({
+        title: "Failed to start payments setup",
+        description: err?.message ?? "Please try again.",
+        variant: "destructive",
+      });
+    }
+  };

apps/backend/src/lib/stripe.tsx (1)

87-87: Prefer Prisma enum over string literal for creationSource

Use the generated Prisma enum to avoid drift and get compile-time checks.

-import { CustomerType } from "@prisma/client";
+import { CustomerType, SubscriptionCreationSource } from "@prisma/client";
…
-        creationSource: "PURCHASE_PAGE"
+        creationSource: SubscriptionCreationSource.PURCHASE_PAGE

apps/dashboard/tailwind.config.ts (1)

80-81: Consider reduced-motion accessibility for fade-in

If these animations are applied broadly, prefer guarding via motion-safe or providing motion-reduce variants in usage to respect prefers-reduced-motion.

Example usage in components:

• className="motion-safe:animate-fade-in"
• or className="animate-fade-in motion-reduce:animate-none"

apps/backend/prisma/migrations/20250821175509_test_mode_subscriptions/migration.sql (1)

1-13: Confirm and Enforce Single TEST_MODE Subscription per Tenancy

We’ve dropped NOT NULL on stripeSubscriptionId in apps/backend/prisma/migrations/20250821175509_test_mode_subscriptions/migration.sql (ALTER COLUMN "stripeSubscriptionId" DROP NOT NULL) while preserving the composite unique on (tenancyId, stripeSubscriptionId) in your Prisma schema (@@unique([tenancyId, stripeSubscriptionId]) in apps/backend/prisma/schema.prisma at line 755). In Postgres, a UNIQUE index treats multiple NULLs as distinct, so this change will allow multiple TEST_MODE subscriptions (which rely on stripeSubscriptionId = NULL) for the same tenancy.

• If you’re relying on this composite unique for Prisma upserts, ensure you never upsert with stripeSubscriptionId: null, otherwise each upsert will insert a new TEST_MODE row.
• To enforce “one TEST_MODE subscription per tenancy” at the database level, add a partial unique index in a follow-up migration:

CREATE UNIQUE INDEX "Subscription_tenancyId_testMode_key"
  ON "Subscription"("tenancyId")
  WHERE "creationSource" = 'TEST_MODE';

• Alternatively, enforce this invariant in application logic (e.g. throw or upsert only if no existing TEST_MODE row exists).

By adding a targeted constraint (or guarding in code), you’ll prevent unintended duplicates of TEST_MODE subscriptions per tenancy.

apps/dashboard/src/components/dialog-opener.tsx (1)

20-22: Avoid accidental form submission by setting Button type="button"

If DialogOpener is used inside a form, the Button may submit the form depending on the underlying implementation. Safer to set an explicit type.

-        <Button onClick={() => setIsOpen(true)}>
+        <Button type="button" onClick={() => setIsOpen(true)}>
           {triggerLabel}
         </Button>

apps/backend/src/app/api/latest/internal/payments/test-mode-purchase-session/route.tsx (3)

40-42: Return a 501 StatusError instead of throwing an assertion for unsupported one-time prices.

This is a feature gap, not a server invariant violation. Using 501 communicates intent better and yields a client error payload consistent with StatusError.

Apply this diff:

-    if (!selectedPrice.interval) {
-      throw new StackAssertionError("unimplemented; prices without an interval are currently not supported");
-    }
+    if (!selectedPrice.interval) {
+      throw new StatusError(StatusError.NotImplemented, "Prices without an interval are not yet supported in test mode");
+    }

---

50-52: Avoid micro-drift between start and end timestamps.

Compute currentPeriodEnd from the same base timestamp used for currentPeriodStart.

Apply this diff:

-    await prisma.subscription.create({
+    const now = new Date();
+    await prisma.subscription.create({
       data: {
         tenancyId: auth.tenancy.id,
         customerId: data.customerId,
         customerType: typedToUppercase(data.offer.customerType),
         status: "active",
         offer: data.offer,
-        currentPeriodStart: new Date(),
-        currentPeriodEnd: addInterval(new Date(), selectedPrice.interval),
+        currentPeriodStart: now,
+        currentPeriodEnd: addInterval(now, selectedPrice.interval),
         cancelAtPeriodEnd: false,
         creationSource: "TEST_MODE",
       },
     });

---

43-55: Consider including the selected price id in the created subscription for traceability.

If your Subscription model or metadata has a field for the chosen price id, persisting price_id helps auditing and post-hoc reconciliation in test mode. If no such field exists, ignore this.

apps/dashboard/src/components/payments/included-item-editor.tsx (1)

72-72: Offer an explicit “No repeat” unset option for UX parity with the price editor.

DayIntervalSelectorField now supports unsetLabel. Since repeat is optional, exposing an unset choice clarifies intent and aligns with the price editor’s “One time”.

Apply this diff:

-            <DayIntervalSelectorField control={sub.control} name={"repeat"} label="Repeat" includeNever />
+            <DayIntervalSelectorField control={sub.control} name={"repeat"} label="Repeat" includeNever unsetLabel="No repeat" />

apps/dashboard/src/app/(main)/(protected)/projects/[projectId]/sidebar-layout.tsx (1)

230-245: Broaden regex to keep nav selection active on nested routes.

Current regexes only match the list pages exactly. If you later add nested routes (e.g., /payments/items/[itemId] or /payments/offers/[offerId]), the sidebar item will not appear selected. Consider allowing optional subpaths.

Apply this diff:

   {
     name: "Offers",
     href: "/payments/offers",
-    regex: /^\/projects\/[^\/]+\/payments\/offers$/,
+    regex: /^\/projects\/[^\/]+\/payments\/offers(?:\/.*)?$/,
     icon: SquarePen,
     type: 'item',
     requiresDevFeatureFlag: true,
   },
   {
     name: "Items",
     href: "/payments/items",
-    regex: /^\/projects\/[^\/]+\/payments\/items$/,
+    regex: /^\/projects\/[^\/]+\/payments\/items(?:\/.*)?$/,
     icon: Box,
     type: 'item',
     requiresDevFeatureFlag: true,
   },

packages/stack-shared/src/schema-fields.ts (1)

574-579: Quantity in includedItems is now required — verify parity with inline schema.

offerSchema.includedItems[...].quantity is defined(), but the corresponding field in inlineOfferSchema remains optional. If this discrepancy is unintentional, align both.

Apply this diff if you want parity:

   included_items: yupRecord(
     userSpecifiedIdSchema("itemId"),
     yupObject({
-      quantity: yupNumber(),
+      quantity: yupNumber().defined(),
       repeat: dayIntervalOrNeverSchema.optional(),
       expires: yupString().oneOf(['never', 'when-purchase-expires', 'when-repeated']).optional(),
     }),
   ),

If the intent is for inline offers to be looser, consider adding a comment to document the divergence.

apps/dashboard/src/app/(main)/(protected)/projects/[projectId]/payments/offers/page.tsx (1)

5-7: Optional: Type the metadata

Annotate for better editor help and consistency with Next.js typing.

-import { notFound } from "next/navigation";
+import { notFound } from "next/navigation";
+import type { Metadata } from "next";
@@
-export const metadata = {
+export const metadata: Metadata = {
   title: "Offers",
 };

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

68-71: Harden code revocation (retry/log) to avoid inconsistencies

If revocation fails after creating a subscription, the client gets a 500 and the code remains reusable. Consider best-effort revocation with logging and retry while still returning success if Stripe creation succeeded.

-    await purchaseUrlVerificationCodeHandler.revokeCode({
-      tenancy,
-      id: codeId,
-    });
+    try {
+      await purchaseUrlVerificationCodeHandler.revokeCode({ tenancy, id: codeId });
+    } catch (e) {
+      console.warn("Failed to revoke purchase verification code", { codeId, tenancyId: tenancy.id, error: (e as Error).message });
+      // Optionally: enqueue a background retry here
+    }

---

65-66: Consider avoiding large metadata payloads

offer: JSON.stringify(data.offer) risks exceeding Stripe metadata limits (key/value size). Prefer storing a compact identifier (e.g., offer id/version) and fetch details server-side when needed.

apps/dashboard/src/app/(main)/purchase/return/page-client.tsx (1)

94-96: Guard retry link when purchaseFullCode is missing

If purchaseFullCode is undefined, the link points to /purchase/undefined. Hide or disable the link in that case.

-            <StyledLink href={`/purchase/${purchaseFullCode}`}>Click here</StyledLink> to try making your purchase again.
+            {purchaseFullCode ? (
+              <StyledLink href={`/purchase/${purchaseFullCode}`}>Click here</StyledLink>
+            ) : (
+              <span>Return to the purchase page</span>
+            )} to try making your purchase again.

apps/dashboard/src/components/form-fields/day-interval-selector-field.tsx (1)

34-66: Optional: Control the Select value instead of using defaultValue

Using defaultValue with RHF can desync UI from form state after the first change. Prefer passing value={formatDayInterval(field.value as DayInterval | "never")}.

-              defaultValue={formatDayInterval(field.value as DayInterval | "never")}
+              value={formatDayInterval(field.value as DayInterval | "never")}

packages/stack-shared/src/interface/admin-interface.ts (1)

519-529: Optional: Bubble up non-2xx errors explicitly

If sendAdminRequest doesn’t throw on non-OK, consider asserting response.ok and surfacing backend error text for better DX.

-  async testModePurchase(options: { price_id: string, full_code: string }): Promise<void> {
-    await this.sendAdminRequest(
+  async testModePurchase(options: { price_id: string, full_code: string }): Promise<void> {
+    const res = await this.sendAdminRequest(
       "/internal/payments/test-mode-purchase-session",
       {
         method: "POST",
         headers: { "content-type": "application/json" },
         body: JSON.stringify(options),
       },
       null,
     );
+    if (!res.ok) {
+      throw new Error(`testModePurchase failed: ${res.status} ${await res.text()}`);
+    }
   }

apps/backend/src/app/api/latest/payments/purchases/validate-code/route.ts (3)

32-35: Tenancy lookup error type: confirm desired client semantics vs internal assertion

Throwing StackAssertionError here will typically surface as a 5xx/internal assertion. If a stale/invalid code can realistically reach this handler (e.g., revoked tenancy, migration gaps), consider returning a 404/400 known error instead to avoid flagging it as an internal bug. If this path truly represents an invariant violation, keep the assertion—but please confirm that this is intentional.

Example change if you want a client-facing 404:

-    if (!tenancy) {
-      throw new StackAssertionError(`No tenancy found for given tenancyId`);
-    }
+    if (!tenancy) {
+      // Consider a known error/404 here instead of an assertion
+      return {
+        statusCode: 404,
+        bodyType: "json",
+        body: "Tenancy not found for the verification code",
+      };
+    }

---

39-39: customer_type no longer falls back to "user" — verify backward compatibility of older codes

You now propagate offer.customerType directly. If any historical verification codes were generated without customerType, this can become undefined and violate the response schema. If such codes are impossible, all good; otherwise consider a safe fallback.

-      customer_type: offer.customerType,
+      customer_type: offer.customerType ?? "user",

---

2-2: Remove unused imports

adaptSchema and clientOrHigherAuthTypeSchema are imported but unused in this file.

-import { adaptSchema, clientOrHigherAuthTypeSchema, inlineOfferSchema, yupNumber, yupObject, yupString } from "@stackframe/stack-shared/dist/schema-fields";
+import { inlineOfferSchema, yupNumber, yupObject, yupString } from "@stackframe/stack-shared/dist/schema-fields";

apps/backend/prisma/schema.prisma (1)

758-771: Add composite index including customerType for common read-paths

Item quantity lookups often include customerType + customerId. Consider indexing (tenancyId, customerType, customerId, expiresAt) to improve selectivity vs the current (tenancyId, customerId, expiresAt).

 model ItemQuantityChange {
   id           String       @default(uuid()) @db.Uuid
   tenancyId    String       @db.Uuid
   customerType CustomerType
   customerId   String
   itemId       String
   quantity     Int
   description  String?
   expiresAt    DateTime?
   createdAt    DateTime     @default(now())

   @@id([tenancyId, id])
-  @@index([tenancyId, customerId, expiresAt])
+  @@index([tenancyId, customerId, expiresAt])
+  @@index([tenancyId, customerType, customerId, expiresAt])
 }

apps/dashboard/src/components/payments/item-dialog.tsx (1)

88-88: Expose "Never" option for repeat interval (schema supports it)

The validation allows dayIntervalOrNeverSchema but the UI doesn’t offer “Never”. Consider enabling it for consistency.

-                <DayIntervalSelectorField control={form.control} name={"defaultRepeat"} label="Repeat" unsetLabel="None" />
+                <DayIntervalSelectorField control={form.control} name={"defaultRepeat"} label="Repeat" unsetLabel="None" includeNever />

apps/e2e/tests/backend/endpoints/api/v1/payments/purchase-session.test.ts (1)

1-305: Add one E2E for the new "custom" customer type

Given the introduction of CUSTOM end-to-end, consider adding a test mirroring the “user” path, but with a customCustomerId and a custom-typed item to ensure all layers (create URL → purchase session/test-mode → items API) work end-to-end.

Proposed test (append to this file):

+it("creates subscription in test mode for custom customer and increases included item quantity", async ({ expect }) => {
+  await Project.createAndSwitch();
+  await Project.updateConfig({
+    payments: {
+      stripeAccountId: "acct_test123",
+      items: {
+        "custom-item": {
+          displayName: "Custom Item",
+          customerType: "custom",
+          default: { quantity: 0 },
+        },
+      },
+      offers: {
+        "custom-offer": {
+          displayName: "Custom Offer",
+          customerType: "custom",
+          serverOnly: false,
+          stackable: false,
+          prices: {
+            monthly: { USD: "1000", interval: [1, "month"] },
+          },
+          includedItems: { "custom-item": { quantity: 3 } },
+        },
+      },
+    },
+  });
+
+  const customId = "acme-42";
+  const createUrlResponse = await niceBackendFetch("/api/latest/payments/purchases/create-purchase-url", {
+    method: "POST",
+    accessType: "client",
+    body: {
+      customer_type: "custom",
+      customer_id: customId,
+      offer_id: "custom-offer",
+    },
+  });
+  expect(createUrlResponse.status).toBe(200);
+  const body = createUrlResponse.body as { url: string };
+  const code = body.url.match(/\/purchase\/([a-z0-9-_]+)/)?.[1];
+  expect(code).toBeDefined();
+
+  const before = await niceBackendFetch(`/api/latest/payments/items/custom/${customId}/custom-item`, { accessType: "client" });
+  expect(before.status).toBe(200);
+  expect(before.body.quantity).toBe(0);
+
+  const sessionRes = await niceBackendFetch("/api/latest/internal/payments/test-mode-purchase-session", {
+    method: "POST",
+    accessType: "admin",
+    body: { full_code: code, price_id: "monthly" },
+  });
+  expect(sessionRes.status).toBe(200);
+
+  const after = await niceBackendFetch(`/api/latest/payments/items/custom/${customId}/custom-item`, { accessType: "client" });
+  expect(after.status).toBe(200);
+  expect(after.body.quantity).toBe(3);
+});

apps/dashboard/src/app/(main)/purchase/[code]/page-client.tsx (2)

43-48: Guard against missing USD amounts to avoid NaN and invalid Stripe amounts

If a price lacks USD (or contains a non-numeric string), Number(undefined) yields NaN and StripeElementsProvider receives an invalid amount. Fail closed or add a currency selection strategy.

-  const currentAmount = useMemo(() => {
-    if (!selectedPriceId || !data?.offer?.prices) {
-      return 0;
-    }
-    return Number(data.offer.prices[selectedPriceId].USD) * 100;
-  }, [data, selectedPriceId]);
+  const currentAmount = useMemo(() => {
+    if (!selectedPriceId || !data?.offer?.prices) return 0;
+    const usd = data.offer.prices[selectedPriceId]?.USD;
+    return usd ? Math.round(Number(usd) * 100) : 0; // default to 0 if USD is absent
+  }, [data, selectedPriceId]);

If multi-currency is planned, we should thread currency alongside amount and configure Stripe accordingly.

---

98-107: Bypass handler: consider disabling button until selectedPriceId is set

Minor UX: to avoid a no-op click path, disable the bypass button while selectedPriceId is null/undefined.

You can pass disabled={!selectedPriceId} to the Button in BypassInfo, or early-return with a toast.

apps/dashboard/src/components/data-table/payment-offer-table.tsx (3)

51-51: Consider Map over Record for offers prop (guideline).

The component currently takes offers as a Record. If feasible, prefer ES6 Map to align with codebase guidance and avoid accidental key collisions with prototype properties.

Example refactor sketch:

-export function PaymentOfferTable({ offers }: { offers: Record<string, yup.InferType<typeof branchPaymentsSchema>["offers"][string]> }) {
-  const data: PaymentOffer[] = Object.entries(offers).map(([id, offer]) => ({
+export function PaymentOfferTable({ offers }: {
+  offers: Map<string, yup.InferType<typeof branchPaymentsSchema>["offers"][string]> | Record<string, yup.InferType<typeof branchPaymentsSchema>["offers"][string]>
+}) {
+  const entries = offers instanceof Map ? [...offers.entries()] : Object.entries(offers);
+  const data: PaymentOffer[] = entries.map(([id, offer]) => ({
     id,
     ...offer,
   }));

---

34-38: Free Trial rendering: prefer readable formatter over array join.

If available in UI utilities, use a readable interval formatter instead of freeTrial?.join(" "). This avoids coupling to tuple shape and keeps display consistent with other places (e.g., PriceEditor).

- cell: ({ row }) => <TextCell>{row.original.freeTrial?.join(" ") ?? ""}</TextCell>,
+ cell: ({ row }) => <TextCell>{row.original.freeTrial ? readableInterval(row.original.freeTrial) : ""}</TextCell>,

Note: add the corresponding import if readableInterval is available in your shared utils.

---

96-109: Deletion should also clean up references in exclusivity groups.

Offers can be referenced under payments.exclusivityGroups. Consider removing the offer id from any groups before/while deleting to prevent stale config references.

-          onClick: async () => {
-            await project.updateConfig({ [`payments.offers.${offer.id}`]: null });
+          onClick: async () => {
+            const cfg = await project.getConfig();
+            const updates: Record<string, any> = { [`payments.offers.${offer.id}`]: null };
+            for (const [groupId, group] of Object.entries(cfg.payments.exclusivityGroups ?? {})) {
+              if (group && Object.prototype.hasOwnProperty.call(group, offer.id)) {
+                updates[`payments.exclusivityGroups.${groupId}.${offer.id}`] = undefined;
+              }
+            }
+            await project.updateConfig(updates);
             toast({ title: "Offer deleted" });
           },

apps/dashboard/src/components/payments/offer-dialog.tsx (1)

43-46: Strengthen validation: use dayIntervalOrNeverSchema for repeat.

yup.mixed() weakens validation. Reuse the shared dayIntervalOrNeverSchema to keep client validation aligned with server-side schema.

-import { offerPriceSchema, offerSchema, userSpecifiedIdSchema, yupRecord } from "@stackframe/stack-shared/dist/schema-fields";
+import { offerPriceSchema, offerSchema, userSpecifiedIdSchema, yupRecord, dayIntervalOrNeverSchema } from "@stackframe/stack-shared/dist/schema-fields";
@@
-        repeat: yup.mixed().optional(),
+        repeat: dayIntervalOrNeverSchema.optional(),

apps/backend/src/lib/payments.tsx (1)

103-140: Existence checks cover user/team; clarify custom semantics.

The guard correctly validates UUID shape and existence for user/team. For custom, intentionally skipping existence checks seems aligned with the “opaque identifier” design. If empty strings should be rejected for custom IDs, consider a minimal non-empty check.

-  } else if (options.customerType === "team") {
+  } else if (options.customerType === "team") {
     …
-  }
+  } else {
+    // customerType === "custom"
+    if (options.customerId.length === 0) {
+      throw new KnownErrors.CustomerDoesNotExist(options.customerId);
+    }
+  }

apps/dashboard/src/components/data-table/payment-item-table.tsx (3)

63-63: Consider Map over Record for items prop (guideline).

Similar to offers, prefer ES6 Map for items data sources when feasible to match the codebase guideline and avoid prototype pitfalls.

-export function PaymentItemTable({ items }: { items: Record<string, yup.InferType<typeof branchPaymentsSchema>["items"][string]> }) {
-  const data: PaymentItem[] = Object.entries(items).map(([id, item]) => ({
+export function PaymentItemTable({ items }: {
+  items: Map<string, yup.InferType<typeof branchPaymentsSchema>["items"][string]> | Record<string, yup.InferType<typeof branchPaymentsSchema>["items"][string]>
+}) {
+  const entries = items instanceof Map ? [...items.entries()] : Object.entries(items);
+  const data: PaymentItem[] = entries.map(([id, item]) => ({
     id,
     ...item,
   }));

---

159-164: Tighten validation for Customer ID by type and add guard.

For user/team, validate UUID to reduce avoidable roundtrips; for custom, accept any non-empty string. Also guard undefined customerType (if any).

-  const schema = yup.object({
-    customerId: yup.string().defined().label("Customer ID"),
+  const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+  const schema = yup.object({
+    customerId: (customerType === "custom"
+      ? yup.string().trim().min(1, "ID is required").defined()
+      : yup.string().matches(uuid, "Must be a valid UUID (v4)").defined()
+    ).label("Customer ID"),
     quantity: yup.number().defined().label("Quantity"),
     description: yup.string().optional().label("Description"),
     expiresAt: yup.date().optional().label("Expires At"),
   });
@@
-  const submit = async (values: yup.InferType<typeof schema>) => {
+  const submit = async (values: yup.InferType<typeof schema>) => {
+    if (!customerType) {
+      toast({ title: "Item has no customer type configured", variant: "destructive" });
+      return "prevent-close" as const;
+    }
     const result = await Result.fromPromise(stackAdminApp.createItemQuantityChange({
       ...(customerType === "user" ?
         { userId: values.customerId } :
         customerType === "team" ?
           { teamId: values.customerId } :
           { customCustomerId: values.customerId }
       ),

Also applies to: 166-173

---

183-189: Optional: handle CustomerDoesNotExist for custom IDs.

If the backend ever validates custom IDs existence, map KnownErrors.CustomerDoesNotExist to a specific message instead of the generic fallback.

-    } else if (result.error instanceof KnownErrors.TeamNotFound) {
+    } else if (result.error instanceof KnownErrors.TeamNotFound) {
       toast({ title: "No team found with the given ID", variant: "destructive" });
+    } else if (result.error instanceof KnownErrors.CustomerDoesNotExist) {
+      toast({ title: "No custom customer found with the given ID", variant: "destructive" });

packages/template/src/lib/stack-app/apps/implementations/admin-app-impl.ts (1)

515-522: Minor: factor id-container mapping into a helper for reuse and exhaustiveness.

A small helper improves readability and enables a never-check for future union expansions.

-    await this._interface.updateItemQuantity(
-      { itemId: options.itemId, ...("userId" in options ? { userId: options.userId } : ("teamId" in options ? { teamId: options.teamId } : { customCustomerId: options.customCustomerId })) },
+    const idContainer =
+      "userId" in options ? { userId: options.userId } :
+      "teamId" in options ? { teamId: options.teamId } :
+      "customCustomerId" in options ? { customCustomerId: options.customCustomerId } :
+      ((): never => { throw new Error("Invalid options"); })();
+    await this._interface.updateItemQuantity(
+      { itemId: options.itemId, ...idContainer },
       {
         delta: options.quantity,
         expires_at: options.expiresAt,
         description: options.description,
       }
     );

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.