React Stripe Boilerplate

Rendering a pricing table and redirecting to Stripe Checkout is usually simpler than maintaining the webhook handler. Webhook delivery introduces ordering, duplication, and retry behavior that the integration has to handle explicitly.

When you evaluate a react stripe boilerplate, review its webhook handler as well as the pricing UI. This page explains the handler, the reasoning behind it, and two deliberate trade-offs.

A common failure in event-driven integrations

The natural way to write the handler is to treat each event as an instruction. customer.subscription.updated arrives, so patch the row. invoice.paid arrives, so flip the flag. Every event is a delta, and the handler applies deltas.

This approach becomes difficult when delivery does not match event order. Stripe delivers over HTTP, so events can arrive out of order, arrive twice, and be retried after your database has moved on. A handler built from deltas must account for those delivery patterns. If it does not, one customer can end up on the wrong plan without a clear application error.

Converge on current Stripe state

The billing pack does not read the event body for anything except the customer ID. It allow-lists the events it cares about, then re-reads that one customer's state from Stripe and overwrites the cache.

// libs/stripe/webhook.ts
export async function processStripeEvent(event: Stripe.Event): Promise<void> {
  if (!isAllowedEvent(event.type)) return;

  const { customer: customerId } = event.data.object as { customer: string };

  if (typeof customerId !== "string") {
    throw new Error(`[STRIPE HOOK] Customer ID is not a string. Event type: ${event.type}`);
  }

  await syncStripeDataToKV(customerId);
}

syncStripeDataToKV calls stripe.subscriptions.list({ customer, limit: 1, status: "all" }) and writes the result to one key. Replays converge instead of corrupting: the tenth delivery of a stale event produces the same state as the first, because the state comes from Stripe, not from the event.

Two consequences worth knowing before you adopt it. There is no processed-event ledger, so deduplication comes from convergence rather than from remembering event IDs. The handler also throws on failure instead of returning 200. The error middleware reports the failure and Stripe retries, so a temporary Valkey outage does not silently drop the update.

Where subscription state lives

The pack stores no subscription rows in Postgres. The three storage tiers are:

The upside is that there is no Postgres copy of subscription state to reconcile. The trade is that plan gating trusts the cache completely: getSubscriptionStatus does a plain Valkey read with no live Stripe call, so a cache miss reads as the free plan. Two paths keep it warm: the webhook and an eager sync on GET /checkout/success after the redirect. There is no admin re-sync route in the pack, so if you flush Valkey in production, paying customers read as free until their next webhook arrives. An admin re-sync endpoint can use the existing syncSubscription helper and is a useful addition if you operate Valkey as a disposable cache.

Read that helper before you deploy if you run Valkey as a disposable cache with no persistence. Fail-to-free is the more conservative billing default, but it may not fit a product whose free tier cannot serve paying customers. Choose the fallback behavior based on your access and availability requirements.

Lifecycle cases that are already wired

The code delegates lifecycle choices to Stripe where the Billing Portal already supports them. Cancellation is the clearest case. Decisions such as immediate versus period-end cancellation remain in Stripe's maintained interface, so the application does not implement a separate cancellation flow.

A reusable webhook pattern

Every file mentioned above lands in your repository as source. Open libs/stripe/webhook.ts and routes/checkout/index.ts to decide whether the implementation fits your billing model. If pricing requirements become more complex, these are among the files you will modify.

The pattern also applies outside Stripe. When consuming events from a system you do not control, you can accumulate deltas or converge on a current snapshot. Accumulating can use fewer reads, but it requires explicit handling for ordering, duplication, and partial failures. Converging adds a read in exchange for simpler replay behavior.

Convergence is a practical default when the extra read is acceptable. For high-volume systems where that read becomes material, a delta-based approach may be worth the additional state-management work.

Below is the stack running, and what installs into your repository, so you can read the handler before deciding whether you trust it.