@fantastic.dev/better-stripe 0.10.0 → 0.10.1

package/dist/client/utils/webhookEndpoints.js

@@ -1,3 +1,5 @@
+import { STRIPE_CUSTOMER_PREVIEW_API_VERSION } from "../apiVersion.js";
+import { throwStripeError } from "../errors.js";
 // =============================================================================
 // Webhook endpoint management
 // =============================================================================
@@ -63,6 +65,12 @@ export const BETTER_STRIPE_V2_WEBHOOK_EVENTS = [
     "v2.core.account_person.updated",
     "v2.core.account_link.returned",
 ];
+/** Minimal customer lifecycle subscription for non-Connect preview merchants. */
+export const BETTER_STRIPE_CUSTOMER_ACCOUNT_EVENTS = [
+    "v2.core.account.created",
+    "v2.core.account[configuration.customer].updated",
+    "v2.core.account[identity].updated",
+];
 /**
  * All events (V1 + V2) that better-stripe processes.
  * Use with setupEventDestination() for complete webhook coverage.
@@ -93,6 +101,11 @@ export async function createWebhookEndpoint(stripe, _ctx, opts) {
     }
     const endpoint = await stripe.webhookEndpoints.create({
         url: opts.url,
+        ...(opts.apiVersion
+            ? {
+                api_version: opts.apiVersion,
+            }
+            : {}),
         enabled_events: (opts.enabledEvents ??
             BETTER_STRIPE_WEBHOOK_EVENTS),
         description: opts.description ?? "Created by better-stripe createWebhookEndpoint",
@@ -132,7 +145,9 @@ export async function setupEventDestination(stripe, _ctx, opts) {
     const payloadType = opts.eventPayload ?? "thin";
     const events = opts.enabledEvents ??
         (payloadType === "thin"
-            ? [...BETTER_STRIPE_V2_WEBHOOK_EVENTS]
+            ? opts.apiVersion === STRIPE_CUSTOMER_PREVIEW_API_VERSION
+                ? [...BETTER_STRIPE_CUSTOMER_ACCOUNT_EVENTS]
+                : [...BETTER_STRIPE_V2_WEBHOOK_EVENTS]
             : [...BETTER_STRIPE_WEBHOOK_EVENTS]);
     const name = opts.name ??
         (payloadType === "thin" ? "better-stripe-v2" : "better-stripe");
@@ -145,6 +160,21 @@ export async function setupEventDestination(stripe, _ctx, opts) {
         include: ["webhook_endpoint.url"],
     });
     const match = existing.data.find((d) => d.webhook_endpoint?.url === opts.url && d.event_payload === payloadType);
+    if (match &&
+        payloadType === "snapshot" &&
+        opts.apiVersion &&
+        match.snapshot_api_version !== opts.apiVersion)
+        throwStripeError("INVALID_CONFIGURATION", "Existing snapshot destination API version differs. Create a replacement destination with the selected version and configure its signing secret before retiring the old destination.");
+    if (match && opts.apiVersion === STRIPE_CUSTOMER_PREVIEW_API_VERSION) {
+        const scopes = new Set((match.events_from ?? []).map((scope) => scope === "self"
+            ? "@self"
+            : scope === "other_accounts"
+                ? "@accounts"
+                : scope));
+        const required = payloadType === "thin" ? ["@self", "@accounts"] : ["@self"];
+        if (required.some((scope) => !scopes.has(scope)))
+            throwStripeError("INVALID_CONFIGURATION", "Existing destination event scope differs. Create a replacement with the customer preview scopes before retiring the old destination.");
+    }
     if (match) {
         const updated = await stripe.v2.core.eventDestinations.update(match.id, {
             name,
@@ -170,7 +200,16 @@ export async function setupEventDestination(stripe, _ctx, opts) {
         type: "webhook_endpoint",
         event_payload: payloadType,
         enabled_events: events,
-        events_from: payloadType === "thin" ? ["self", "other_accounts"] : ["self"],
+        ...(payloadType === "snapshot" && opts.apiVersion
+            ? { snapshot_api_version: opts.apiVersion }
+            : {}),
+        events_from: opts.apiVersion === STRIPE_CUSTOMER_PREVIEW_API_VERSION
+            ? payloadType === "thin"
+                ? ["@self", "@accounts"]
+                : ["@self"]
+            : payloadType === "thin"
+                ? ["self", "other_accounts"]
+                : ["self"],
         webhook_endpoint: { url: opts.url },
         include: ["webhook_endpoint.signing_secret", "webhook_endpoint.url"],
     });

package/dist/client/utils/webhookEndpoints.js.map

@@ -1 +1 @@
-{"version":3,"file":"webhookEndpoints.js","sourceRoot":"","sources":["../../../src/client/utils/webhookEndpoints.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"webhookEndpoints.js","sourceRoot":"","sources":["../../../src/client/utils/webhookEndpoints.ts"],"names":[],"mappings":"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"}

package/dist/client/webhooks/v2.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"v2.d.ts","sourceRoot":"","sources":["../../../src/client/webhooks/v2.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AAGjC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EACL,KAAK,cAAc,EAGpB,MAAM,cAAc,CAAC;AAMtB,wBAAsB,aAAa,CACjC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,WAAW,CAAC,CActB;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,cAAc,EACrB,SAAS,EAAE,WAAW,GACrB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA0FxB"}
+{"version":3,"file":"v2.d.ts","sourceRoot":"","sources":["../../../src/client/webhooks/v2.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AAGjC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EACL,KAAK,cAAc,EAGpB,MAAM,cAAc,CAAC;AAMtB,wBAAsB,aAAa,CACjC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,WAAW,CAAC,CActB;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,cAAc,EACrB,SAAS,EAAE,WAAW,GACrB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA6FxB"}

package/dist/client/webhooks/v2.js

@@ -1,3 +1,4 @@
+import { STRIPE_CUSTOMER_PREVIEW_API_VERSION } from "../apiVersion.js";
 import { deriveAccountStatus } from "../core/accountStatus.js";
 import { dispatchUpsert, extractIdentifiers, } from "./helpers.js";
 // =============================================================================
@@ -53,13 +54,15 @@ export async function handleV2Event(whCtx, thinEvent) {
         return null;
     }
     const retrieveParams = {
-        include: [
-            "configuration.merchant",
-            "configuration.recipient",
-            "configuration.customer",
-            "identity",
-            "requirements",
-        ],
+        include: whCtx.config?.stripeApiVersion === STRIPE_CUSTOMER_PREVIEW_API_VERSION
+            ? ["configuration.customer", "identity"]
+            : [
+                "configuration.merchant",
+                "configuration.recipient",
+                "configuration.customer",
+                "identity",
+                "requirements",
+            ],
     };
     // Preserve the verified notification's account/organization context when
     // fetching the latest resource; otherwise organization keys can fetch from

package/dist/client/webhooks/v2.js.map

@@ -1 +1 @@
-{"version":3,"file":"v2.js","sourceRoot":"","sources":["../../../src/client/webhooks/v2.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"v2.js","sourceRoot":"","sources":["../../../src/client/webhooks/v2.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mCAAmC,EAAE,MAAM,kBAAkB,CAAC;AAGvE,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAE/D,OAAO,EAEL,cAAc,EACd,kBAAkB,GACnB,MAAM,cAAc,CAAC;AAEtB,gFAAgF;AAChF,mBAAmB;AACnB,gFAAgF;AAEhF,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,MAAc,EACd,OAAe,EACf,SAAiB,EACjB,aAAqB;IAErB,oEAAoE;IACpE,mEAAmE;IACnE,0EAA0E;IAC1E,qEAAqE;IACrE,uEAAuE;IACvE,6CAA6C;IAC7C,MAAM,MAAM,CAAC,2BAA2B,CAAC,OAAO,EAAE,SAAS,EAAE,aAAa,CAAC,CAAC;IAE5E,uEAAuE;IACvE,wEAAwE;IACxE,wEAAwE;IACxE,wEAAwE;IACxE,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAgB,CAAC;AAC5C,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,KAAqB,EACrB,SAAsB;IAEtB,MAAM,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC;IAEzB,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,UAAU,CAAC,iBAAiB,CAAC,EAAE,CAAC;QAClD,OAAO,CAAC,IAAI,CAAC,4CAA4C,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC;QAC3E,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,aAAa,GAAG,SAAS,CAAC,cAAc,CAAC;IAC/C,IAAI,CAAC,aAAa,EAAE,CAAC;QACnB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,6EAA6E;IAC7E,gFAAgF;IAChF,yFAAyF;IACzF,IAAI,SAAiB,CAAC;IACtB,IAAI,aAAa,CAAC,IAAI,KAAK,iBAAiB,IAAI,aAAa,CAAC,EAAE,EAAE,CAAC;QACjE,SAAS,GAAG,aAAa,CAAC,EAAE,CAAC;IAC/B,CAAC;SAAM,IAAI,aAAa,CAAC,GAAG,EAAE,CAAC;QAC7B,MAAM,KAAK,GAAG,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC,iCAAiC,CAAC,CAAC;QACzE,IAAI,KAAK,EAAE,CAAC;YACV,SAAS,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACvB,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,IAAI,CACV,+DAA+D,SAAS,CAAC,IAAI,EAAE,CAChF,CAAC;YACF,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;SAAM,CAAC;QACN,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,cAAc,GAEhB;QACF,OAAO,EACL,KAAK,CAAC,MAAM,EAAE,gBAAgB,KAAK,mCAAmC;YACpE,CAAC,CAAC,CAAC,wBAAwB,EAAE,UAAU,CAAC;YACxC,CAAC,CAAC;gBACE,wBAAwB;gBACxB,yBAAyB;gBACzB,wBAAwB;gBACxB,UAAU;gBACV,cAAc;aACf;KACR,CAAC;IACF,yEAAyE;IACzE,2EAA2E;IAC3E,2EAA2E;IAC3E,MAAM,OAAO,GAAG,SAAS,CAAC,OAAO;QAC/B,CAAC,CAAC,MAAM,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,SAAS,EAAE,cAAc,EAAE;YAChE,aAAa,EAAE,SAAS,CAAC,OAAO;SACjC,CAAC;QACJ,CAAC,CAAC,MAAM,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC;IACtE,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;IAClC,MAAM,QAAQ,GAAG,CAAC,OAAO,CAAC,QAAQ,IAAI,EAAE,CAA2B,CAAC;IACpE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IACvD,MAAM,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,GAC7C,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAE/B,OAAO,CAAC,IAAI,CACV,+BAA+B,SAAS,YAAY,gBAAgB,aAAa,mBAAmB,CAAC,MAAM,aAAa,CAAC,OAAO,CAAC,sBAAsB,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAC3K,CAAC;IAEF,+EAA+E;IAC/E,MAAM,KAAK,GACT,OAAO,CAAC,aAAa,IAAI,QAAQ,EAAE,UAAU,EAAE,KAAK,IAAI,SAAS,CAAC;IACpE,4EAA4E;IAC5E,MAAM,IAAI,GACR,QAAQ,EAAE,gBAAgB,EAAE,eAAe;QAC3C,CAAC,QAAQ,EAAE,UAAU;YACnB,CAAC,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC,UAAU,EAAE,QAAQ,CAAC,UAAU,CAAC,OAAO,CAAC;iBAC1D,MAAM,CAAC,OAAO,CAAC;iBACf,IAAI,CAAC,GAAG,CAAC,IAAI,SAAS;YAC3B,CAAC,CAAC,SAAS,CAAC,CAAC;IAEjB,MAAM,cAAc,CAAC,KAAK,EAAE,iBAAiB,EAAE;QAC7C,eAAe,EAAE,OAAO,CAAC,EAAE;QAC3B,MAAM,EAAE,MAAM,IAAI,OAAO,CAAC,EAAE;QAC5B,KAAK;QACL,KAAK;QACL,IAAI;QACJ,OAAO,EAAE,QAAQ,EAAE,OAAO,IAAI,SAAS;QACvC,YAAY,EAAE,OAAO,CAAC,YAAY,IAAI,SAAS;QAC/C,aAAa,EAAE,OAAO,CAAC,aAAa,IAAI,SAAS;QACjD,qBAAqB,EAAE,OAAO,CAAC,sBAAsB,IAAI,SAAS;QAClE,gBAAgB;QAChB,mBAAmB;QACnB,QAAQ;KACT,CAAC,CAAC;IAEH,OAAO,OAAO,CAAC,EAAE,CAAC;AACpB,CAAC"}

package/dist/component/lib/stripeFactory.d.ts

@@ -1,7 +1,8 @@
 import Stripe from "stripe";
+import { type SupportedStripeApiVersion } from "../../client/apiVersion.js";
 /**
  * Get or create a Stripe SDK instance for the given API key.
- * Uses the component's pinned API version.
+ * Defaults to GA; an explicitly selected supported preview gets its own cache entry.
  */
-export declare function getStripe(apiKey: string): Stripe;
+export declare function getStripe(apiKey: string, apiVersion?: SupportedStripeApiVersion): Stripe;
 //# sourceMappingURL=stripeFactory.d.ts.map

package/dist/component/lib/stripeFactory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stripeFactory.d.ts","sourceRoot":"","sources":["../../../src/component/lib/stripeFactory.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,QAAQ,CAAC;AAc5B;;;GAGG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAWhD"}
+{"version":3,"file":"stripeFactory.d.ts","sourceRoot":"","sources":["../../../src/component/lib/stripeFactory.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,QAAQ,CAAC;AAE5B,OAAO,EAEL,KAAK,yBAAyB,EAC/B,MAAM,4BAA4B,CAAC;AAapC;;;GAGG;AACH,wBAAgB,SAAS,CACvB,MAAM,EAAE,MAAM,EACd,UAAU,CAAC,EAAE,yBAAyB,GACrC,MAAM,CAYR"}

package/dist/component/lib/stripeFactory.js

@@ -1,5 +1,5 @@
 import Stripe from "stripe";
-import { STRIPE_API_VERSION } from "../../client/constants.js";
+import { resolveStripeApiVersion, } from "../../client/apiVersion.js";
 /**
  * Keyed cache for Stripe SDK instances.
  * Safe for tests and mixed environments — different keys get different clients.
@@ -11,14 +11,15 @@ import { STRIPE_API_VERSION } from "../../client/constants.js";
 const _clients = new Map();
 /**
  * Get or create a Stripe SDK instance for the given API key.
- * Uses the component's pinned API version.
+ * Defaults to GA; an explicitly selected supported preview gets its own cache entry.
  */
-export function getStripe(apiKey) {
-    const cacheKey = `${apiKey}:${STRIPE_API_VERSION}`;
+export function getStripe(apiKey, apiVersion) {
+    const version = resolveStripeApiVersion(apiVersion);
+    const cacheKey = `${apiKey}:${version}`;
     let client = _clients.get(cacheKey);
     if (!client) {
         client = new Stripe(apiKey, {
-            apiVersion: STRIPE_API_VERSION,
+            apiVersion: version,
             typescript: true,
         });
         _clients.set(cacheKey, client);

package/dist/component/lib/stripeFactory.js.map

@@ -1 +1 @@
-{"version":3,"file":"stripeFactory.js","sourceRoot":"","sources":["../../../src/component/lib/stripeFactory.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,QAAQ,CAAC;AAE5B,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAE/D;;;;;;;GAOG;AACH,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAC;AAE3C;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,MAAc;IACtC,MAAM,QAAQ,GAAG,GAAG,MAAM,IAAI,kBAAkB,EAAE,CAAC;IACnD,IAAI,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACpC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,GAAG,IAAI,MAAM,CAAC,MAAM,EAAE;YAC1B,UAAU,EAAE,kBAAkB;YAC9B,UAAU,EAAE,IAAI;SACjB,CAAC,CAAC;QACH,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IACjC,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"stripeFactory.js","sourceRoot":"","sources":["../../../src/component/lib/stripeFactory.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,QAAQ,CAAC;AAE5B,OAAO,EACL,uBAAuB,GAExB,MAAM,4BAA4B,CAAC;AAGpC;;;;;;;GAOG;AACH,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAC;AAE3C;;;GAGG;AACH,MAAM,UAAU,SAAS,CACvB,MAAc,EACd,UAAsC;IAEtC,MAAM,OAAO,GAAG,uBAAuB,CAAC,UAAU,CAAC,CAAC;IACpD,MAAM,QAAQ,GAAG,GAAG,MAAM,IAAI,OAAO,EAAE,CAAC;IACxC,IAAI,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACpC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,GAAG,IAAI,MAAM,CAAC,MAAM,EAAE;YAC1B,UAAU,EAAE,OAA2B;YACvC,UAAU,EAAE,IAAI;SACjB,CAAC,CAAC;QACH,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IACjC,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/docs/accounts-v2-preview.md

@@ -0,0 +1,132 @@
+# Customer-only Accounts v2 preview
+
+Connect platforms keep the default `2026-09-30.endive` API version. Non-Connect
+merchants can explicitly opt into `2026-09-30.preview` for customer-configured
+Accounts. The package does not enable Connect or onboard a merchant/recipient
+when creating a buyer with `ensureCustomerAccount`.
+
+## Enable the sandbox feature first
+
+In the intended sandbox, the account owner must enable **Reusable payment
+methods for Global Payouts** under **Account previews and features**. If the toggle
+is unavailable, request access using Stripe's form. This also enables Stripe's
+reusable payout credentials preview; it is not a Connect onboarding flow.
+Changing an API version cannot enable the feature on the Stripe account.
+
+Enabling the preview synchronizes existing Customers with customer-configured
+Accounts and changes how Stripe-hosted integrations create customers. Review
+Stripe's limitations and migration behavior before changing any live account.
+See [Stripe's customer Account guide](https://docs.stripe.com/accounts-v2/use-accounts-as-customers).
+
+## Configure one client and its webhook route
+
+```ts
+// convex/stripe.ts
+import {
+  BetterStripe,
+  STRIPE_CUSTOMER_PREVIEW_API_VERSION,
+} from "@fantastic.dev/better-stripe";
+import { components } from "./_generated/api";
+
+export const stripe = new BetterStripe(components.betterStripe, {
+  STRIPE_SECRET_KEY: process.env.STRIPE_SECRET_KEY,
+  stripeApiVersion: STRIPE_CUSTOMER_PREVIEW_API_VERSION,
+});
+```
+
+```ts
+// convex/http.ts
+import { httpRouter } from "convex/server";
+import { stripe } from "./stripe";
+
+const http = httpRouter();
+stripe.registerRoutes(http, {
+  webhookPath: "/stripe/webhook",
+  webhookSecret: process.env.STRIPE_WEBHOOK_SECRET,
+  webhookSecretV2: process.env.STRIPE_WEBHOOK_SECRET_V2,
+  // Preserve your existing `webhooks` handler references and retry policy here.
+});
+export default http;
+```
+
+The instance route inherits its client's key and version. Conflicting explicit
+values fail at registration. The standalone `registerRoutes` function remains
+available; when using it, pass `stripeApiVersion: stripe.stripeApiVersion` and the
+same secret key explicitly. The client accepts only the supported GA and customer
+preview versions; unsupported values fail with `INVALID_CONFIGURATION`.
+
+All client operations use the selected version: account creation/configuration,
+Checkout, subscriptions, portal sessions, refunds, authoritative reads, and the
+provider calls made while handling webhooks. Component database writes remain
+provider-version independent. SDK caches separate clients by key and version.
+
+## Create a buyer and Checkout Session
+
+Authenticate the caller and validate ownership/prices on the server. The client
+is not an authorization boundary. Persist logical request identities in your host
+app so retries keep the same provider keys and new purchases use distinct keys.
+
+```ts
+const buyer = await stripe.ensureCustomerAccount(ctx, {
+  userId: identity.subject,
+  email: verifiedEmail,
+  idempotencyKey: accountProvisioningKey,
+});
+const checkout = await stripe.createCheckoutSession(ctx, {
+  userId: identity.subject,
+  accountId: buyer.stripeAccountId,
+  stripePriceId: authorizedPriceId,
+  mode: "subscription",
+  uiMode: "redirect",
+  returnUrl: "https://example.com/receipt?session_id={CHECKOUT_SESSION_ID}",
+  idempotencyKey: orderKey,
+});
+```
+
+The buyer is an `acct_` object with the customer configuration. Checkout uses
+`customer_account`, not a connected-account destination. No seller, recipient,
+transfer, or application fee is added by this configuration.
+
+After verifying buyer/order ownership, use `getCheckoutSessionFromStripe` to
+check current payment status. Completion alone does not prove payment: fulfill
+only when your payment policy accepts the authoritative status, and deduplicate
+fulfillment by a durable order key. Subscription and coupon reads use the same
+configured version. Cancellation/reactivation and refunds keep their existing
+public API signatures and caller idempotency behavior.
+
+## Match webhook payload versions and scope
+
+Snapshot destinations created through this client pin `snapshot_api_version` to
+the selected version. V1 webhook endpoints pin their `api_version`. Thin events
+are unversioned; their related customer Account is fetched with the selected
+request version and only customer/identity includes in customer-preview mode.
+
+The preview's default thin subscription covers Account creation, customer
+configuration changes, and identity changes, using Stripe's `@self` and
+`@accounts` scopes. Subscription and invoice changes continue to use V1 snapshot
+events. No merchant or recipient capability events are subscribed by default in
+customer-preview mode. The GA defaults retain their existing event selection.
+
+Stripe cannot update a destination's snapshot version or event scopes in place.
+`setupEventDestination` refuses an incompatible existing destination rather than
+silently reusing it. Create a replacement at a new webhook path, register the
+matching route and signing secret, verify deliveries, then retire the old
+endpoint. A low-level `createWebhookEndpoint` call retains its existing same-URL
+secret-rotation behavior; do not use it as an implicit migration plan.
+
+See [event destination creation](https://docs.stripe.com/api/v2/core/event-destinations/create)
+and [update restrictions](https://docs.stripe.com/api/v2/core/event-destinations/update).
+
+## Verification boundary
+
+Package tests exercise serialized SDK request headers, customer-only account
+configuration, idempotency keys, Checkout buyer binding, authoritative reads,
+subscription cancellation/reactivation, portal and refund calls, webhook route
+configuration, thin-event synchronization, and snapshot version/scope checks.
+The GA version has regression coverage alongside the preview version.
+
+A real non-Connect sandbox test additionally requires the owner-enabled preview
+and sandbox credentials. A Connect sandbox, mocked transport, or successful
+TypeScript compilation does not prove that separate eligibility requirement.
+Do not report checkout, receipt, renewal, portal or refund acceptance as verified
+for a non-Connect merchant until those flows run in its enabled sandbox.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fantastic.dev/better-stripe",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "description": "A Convex component for Stripe V2 Accounts API integration.",
   "keywords": [
     "stripe",
@@ -59,6 +59,7 @@
     "src",
     "docs/react-workflows.md",
     "docs/settlement.md",
+    "docs/accounts-v2-preview.md",
     "docs/react-workflows-audit.md",
     "CHANGELOG.md",
     "MIGRATION.md"

package/src/client/apiVersion.ts

@@ -0,0 +1,20 @@
+import { STRIPE_API_VERSION } from "./constants.js";
+import { throwStripeError } from "./errors.js";
+/** Explicit opt-in for Stripe's customer-only Accounts v2 public preview. */
+export const STRIPE_CUSTOMER_PREVIEW_API_VERSION = "2026-09-30.preview";
+export type SupportedStripeApiVersion =
+  typeof STRIPE_API_VERSION | typeof STRIPE_CUSTOMER_PREVIEW_API_VERSION;
+export function resolveStripeApiVersion(
+  version?: string,
+): SupportedStripeApiVersion {
+  if (version === undefined) return STRIPE_API_VERSION;
+  if (
+    version === STRIPE_API_VERSION ||
+    version === STRIPE_CUSTOMER_PREVIEW_API_VERSION
+  )
+    return version;
+  throwStripeError(
+    "INVALID_CONFIGURATION",
+    `Unsupported Stripe API version. Use ${STRIPE_API_VERSION} or ${STRIPE_CUSTOMER_PREVIEW_API_VERSION}.`,
+  );
+}

package/src/client/customer-preview-thin.test.ts

@@ -0,0 +1,41 @@
+import { componentsGeneric } from "convex/server";
+import { expect, it, vi } from "vitest";
+import { handleV2Event } from "./webhooks/v2.js";
+import type { WebhookContext } from "./webhooks/helpers.js";
+import type { V2ThinEvent } from "./types.js";
+it("syncs a preview customer without requesting merchant, recipient or Connect requirements", async () => {
+  const retrieve = vi.fn().mockResolvedValue({
+    id: "acct_buyer",
+    metadata: { userId: "buyer" },
+    configuration: { customer: { applied: true } },
+    applied_configurations: ["customer"],
+    identity: { country: "us" },
+  });
+  const runMutation = vi.fn();
+  const ctx = {
+    component: componentsGeneric().betterStripe,
+    ctx: { runMutation },
+    stripe: { v2: { core: { accounts: { retrieve } } } },
+    config: { stripeApiVersion: "2026-09-30.preview" },
+  } as unknown as WebhookContext;
+  await handleV2Event(ctx, {
+    id: "evt_preview",
+    type: "v2.core.account[configuration.customer].updated",
+    context: "acct_merchant",
+    related_object: { id: "acct_buyer", type: "v2.core.account" },
+  } as V2ThinEvent);
+  expect(retrieve).toHaveBeenCalledWith(
+    "acct_buyer",
+    { include: ["configuration.customer", "identity"] },
+    { stripeContext: "acct_merchant" },
+  );
+  expect(runMutation).toHaveBeenCalledWith(
+    expect.anything(),
+    expect.objectContaining({
+      userId: "buyer",
+      stripeAccountId: "acct_buyer",
+      appliedConfigurations: ["customer"],
+      onboardingStatus: "complete",
+    }),
+  );
+});

package/src/client/customer-preview-webhooks.test.ts

@@ -0,0 +1,150 @@
+import type Stripe from "stripe";
+import { componentsGeneric, type HttpRouter } from "convex/server";
+import { expect, it, vi } from "vitest";
+import { BetterStripe } from "./index.js";
+import type { Component, RunCtx } from "./helpers.js";
+import {
+  createWebhookEndpoint,
+  setupEventDestination,
+} from "./utils/webhookEndpoints.js";
+const handle = vi.hoisted(() => vi.fn(async () => new Response("ok")));
+vi.mock("./webhooks/handler.js", () => ({ handleWebhookRequest: handle }));
+const version = "2026-09-30.preview";
+const component = componentsGeneric().betterStripe as unknown as Component;
+it("instance routes inherit the selected client version and reject conflicting configuration", async () => {
+  const bs = new BetterStripe(component, {
+    STRIPE_SECRET_KEY: "sk_test_preview_routes",
+    stripeApiVersion: version,
+  });
+  const route = vi.fn();
+  bs.registerRoutes({ route } as unknown as HttpRouter, {
+    webhookSecret: "whsec_fixture",
+  });
+  const handler = route.mock.calls[0][0].handler as {
+    _handler: (ctx: unknown, request: Request) => Promise<Response>;
+  };
+  await handler._handler(
+    {},
+    new Request("https://example.com/stripe/webhook", { method: "POST" }),
+  );
+  expect(handle).toHaveBeenCalledWith(
+    expect.anything(),
+    expect.anything(),
+    component,
+    expect.objectContaining({
+      stripeApiVersion: version,
+      stripeSecretKey: "sk_test_preview_routes",
+      webhookSecret: "whsec_fixture",
+    }),
+  );
+  expect(() =>
+    bs.registerRoutes({ route } as unknown as HttpRouter, {
+      stripeApiVersion: "2026-09-30.endive",
+    }),
+  ).toThrow("match");
+  expect(route).toHaveBeenCalledTimes(1);
+});
+function sdk() {
+  const raw = {
+    webhookEndpoints: {
+      list: vi.fn().mockResolvedValue({ data: [] }),
+      create: vi.fn().mockResolvedValue({
+        id: "we_preview",
+        url: "https://example.com/events",
+        secret: "whsec_fixture",
+      }),
+    },
+    v2: {
+      core: {
+        eventDestinations: {
+          list: vi.fn().mockResolvedValue({ data: [] }),
+          create: vi.fn().mockResolvedValue({
+            id: "ed_preview",
+            enabled_events: [],
+            webhook_endpoint: { signing_secret: "whsec_fixture" },
+          }),
+          update: vi.fn(),
+        },
+      },
+    },
+  };
+  return { raw, stripe: raw as unknown as Stripe };
+}
+it("pins snapshot payloads, leaves thin payloads unversioned, and uses canonical preview scopes", async () => {
+  const { raw, stripe } = sdk(),
+    ctx = {} as RunCtx;
+  await createWebhookEndpoint(stripe, ctx, {
+    url: "https://example.com/events",
+    apiVersion: version,
+  });
+  expect(raw.webhookEndpoints.create).toHaveBeenCalledWith(
+    expect.objectContaining({ api_version: version }),
+  );
+  await setupEventDestination(stripe, ctx, {
+    url: "https://example.com/events",
+    eventPayload: "snapshot",
+    apiVersion: version,
+  });
+  expect(raw.v2.core.eventDestinations.create).toHaveBeenLastCalledWith(
+    expect.objectContaining({
+      snapshot_api_version: version,
+      events_from: ["@self"],
+    }),
+  );
+  await setupEventDestination(stripe, ctx, {
+    url: "https://example.com/events",
+    eventPayload: "thin",
+    apiVersion: version,
+  });
+  const thin = raw.v2.core.eventDestinations.create.mock.calls[1][0];
+  expect(thin).not.toHaveProperty("snapshot_api_version");
+  expect(thin.events_from).toEqual(["@self", "@accounts"]);
+  expect(thin.enabled_events).toEqual([
+    "v2.core.account.created",
+    "v2.core.account[configuration.customer].updated",
+    "v2.core.account[identity].updated",
+  ]);
+});
+it("refuses to reuse a snapshot destination whose immutable version differs", async () => {
+  const { raw, stripe } = sdk();
+  raw.v2.core.eventDestinations.list.mockResolvedValue({
+    data: [
+      {
+        id: "ed_old",
+        event_payload: "snapshot",
+        snapshot_api_version: "2026-09-30.endive",
+        webhook_endpoint: { url: "https://example.com/events" },
+      },
+    ],
+  });
+  await expect(
+    setupEventDestination(stripe, {} as RunCtx, {
+      url: "https://example.com/events",
+      eventPayload: "snapshot",
+      apiVersion: version,
+    }),
+  ).rejects.toThrow("version");
+  expect(raw.v2.core.eventDestinations.update).not.toHaveBeenCalled();
+  expect(raw.v2.core.eventDestinations.create).not.toHaveBeenCalled();
+});
+it("refuses a preview thin destination that cannot deliver managed customer account events", async () => {
+  const { raw, stripe } = sdk();
+  raw.v2.core.eventDestinations.list.mockResolvedValue({
+    data: [
+      {
+        id: "ed_old",
+        event_payload: "thin",
+        events_from: ["@self"],
+        webhook_endpoint: { url: "https://example.com/events" },
+      },
+    ],
+  });
+  await expect(
+    setupEventDestination(stripe, {} as RunCtx, {
+      url: "https://example.com/events",
+      eventPayload: "thin",
+      apiVersion: version,
+    }),
+  ).rejects.toThrow("scope");
+  expect(raw.v2.core.eventDestinations.update).not.toHaveBeenCalled();
+});