t3dotgg stripe-recommendations

Always ensure a Stripe customer exists and is bound to your user ID in your KV store before initiating a checkout session. This prevents issues with ephemeral customers.

export async function GET(req: Request) {
  const user = auth(req);

  // Get the stripeCustomerId from your KV store
  let stripeCustomerId = await kv.get(`stripe:user:${user.id}`);

  // Create a new Stripe customer if this user doesn't have one
  if (!stripeCustomerId) {
    const newCustomer = await stripe.customers.create({
      email: user.email,
      metadata: {
        userId: user.id, // DO NOT FORGET THIS
      },
    });

    // Store the relation between userId and stripeCustomerId in your KV
    await kv.set(`stripe:user:${user.id}`, newCustomer.id);
    stripeCustomerId = newCustomer.id;
  }

  // ALWAYS create a checkout with a stripeCustomerId. They should enforce this.
  const checkout = await stripe.checkout.sessions.create({
    customer: stripeCustomerId,
    success_url: "https://t3.chat/success",
    ... 
  });
}

To avoid 'split-brain' states where your database and Stripe are out of sync, follow this specific flow:

1. Frontend: Call a generate-stripe-checkout endpoint when the user clicks 'Subscribe'.
2. Backend: Create a Stripe customer (if one doesn't exist).
3. Backend: Store the binding between Stripe's customerId and your app's userId in your KV store.
4. Backend: Create a Stripe checkout session with a success_url pointing to a dedicated /success route.
5. User: Completes payment and is redirected to /success.
6. Frontend: On the /success page load, trigger a backend function (API, Server Action, etc.) to sync data.
7. Backend: Use the userId to retrieve the customerId from KV, then call syncStripeDataToKV(customerId).
8. Frontend: Redirect the user to their dashboard/intended destination after sync succeeds.
9. Backend (Webhook): On all relevant Stripe events, call syncStripeDataToKV(customerId) to keep the KV store updated.

The webhook handler (/api/stripe) should verify the Stripe signature and then call a processing function. If using Next.js Pages Router, you must disable the body parser so Stripe can verify the raw request body.

// For Next.js Pages Router
export const config = {
  api: {
    bodyParser: false,
  },
};

// Webhook implementation sketch
export async function POST(req: Request) {
  const body = await req.text();
  const signature = (await headers()).get("Stripe-Signature");

  if (!signature) return NextResponse.json({}, { status: 400 });

  async function doEventProcessing() {
    if (typeof signature !== "string") {
      throw new Error("[STRIPE HOOK] Header isn't a string???");
    }

    const event = stripe.webhooks.constructEvent(
      body,
      signature,
      process.env.STRIPE_WEBHOOK_SECRET!
    );

    waitUntil(processEvent(event));
  }

  const { error } = await tryCatch(doEventProcessing());

  if (error) {
    console.error("[STRIPE HOOK] Error processing event", error);
  }

  return NextResponse.json({ received: true });
}

The syncStripeDataToKV(customerId: string) function is the core of this architecture. It fetches the latest subscription data from Stripe and overwrites the customer's state in your KV store. This should be called from both your /success endpoint and your Stripe webhook handler to prevent race conditions.

// The contents of this function should probably be wrapped in a try/catch
export async function syncStripeDataToKV(customerId: string) {
  // Fetch latest subscription data from Stripe
  const subscriptions = await stripe.subscriptions.list({
    customer: customerId,
    limit: 1,
    status: "all",
    expand: ["data.default_payment_method"],
  });

  if (subscriptions.data.length === 0) {
    const subData = { status: "none" };
    await kv.set(`stripe:customer:${customerId}`, subData);
    return subData;
  }

  // If a user can have multiple subscriptions, that's your problem
  const subscription = subscriptions.data[0];

  // Store complete subscription state
  const subData = {
    subscriptionId: subscription.id,
    status: subscription.status,
    priceId: subscription.items.data[0].price.id,
    currentPeriodEnd: subscription.current_period_end,
    currentPeriodStart: subscription.current_period_start,
    cancelAtPeriodEnd: subscription.cancel_at_period_end,
    paymentMethod:
      subscription.default_payment_method &&
      typeof subscription.default_payment_method !== "string"
        ? {
            brand: subscription.default_payment_method.card?.brand ?? null,
            last4: subscription.default_payment_method.card?.last4 ?? null,
          }
        : null,
  };

  // Store the data in your KV
  await kv.set(`stripe:customer:${customerId}`, subData);
  return subData;
}