Engineering / Commerce integration
Commerce checks that live on the server.
A 68-product Stripe-connected storefront with server-side price, quantity and stock validation, Clerk identity, signed webhooks and retry-aware stock updates.
- Context
- Measure Joy / Commerce rebuild
- Contribution
- Product & integration engineering
- Project type
- Engineering case study
Scope
A Stripe-connected storefront covering a 68-product catalog.
Contribution
Checkout validation, identity, webhooks and stock retry controls.
Verification
October 2026 validation recorded 94 passing tests.
01 / The problem
A convincing storefront is only the beginning.
The browser can display a product and collect a quantity, but it cannot be the authority for price, identity or available stock. Checkout also continues after the initial request through provider events and retryable work.
The rebuild connected the storefront to a 68-product Stripe catalog and put key commerce checks on the server. The work focused on validating what can be purchased and making repeated events and stock updates safer to handle.
Requests are untrusted
Client-supplied identity, prices and quantities need server-side checks.
Events can repeat
Webhook deliveries and provider operations need explicit retry behavior.
Stock is shared state
A validated quantity does not by itself create an atomic inventory reservation.
02 / My contribution
Connecting the customer surface to provider boundaries.
My work connected the storefront to Stripe and Clerk, with server-side price, quantity and stock checks, signed webhook handling and persisted stock targets. The retry path uses stored targets and idempotency controls so repeated attempts can be evaluated against an explicit intended update.
The stack includes Next.js, React, TypeScript and Node.js, with Stripe, Clerk, Supabase, Resend and Tailwind. Validation combines source review with tests of checkout inputs, webhook handling and retry behavior.
Validate checkout inputs
Resolve identity and check catalog price, quantity and stock on the server.
Verify provider events
Handle Stripe webhooks through signature verification and defined event processing.
Persist retry intent
Keep per-product stock targets and idempotency information available across attempts.
03 / How it works
Three boundaries behind a checkout flow.
Explore request validation, event handling and stock retries. The diagrams describe the engineering controls and their limits.
Identity → Catalog → Quantity
The server decides what the request is allowed to buy.
A browser request supplies intent; the server checks it against identity and provider-backed catalog data.
Clerk identity
The checkout boundary uses Clerk identity rather than trusting a customer identifier supplied by the browser. Identity and the requested commerce action are checked within the server workflow.
Conceptual portfolio reconstruction. It contains no customer, order, payment or private catalog records.
Read all model notes
Checkout request
- Clerk identity — The checkout boundary uses Clerk identity rather than trusting a customer identifier supplied by the browser. Identity and the requested commerce action are checked within the server workflow.
- Catalog & price — Server-side checks verify the requested product and its supported price. The client display does not establish the authoritative amount or make an arbitrary price identifier acceptable.
- Quantity & stock — The server checks quantity and stock before creating the checkout request. This reduces invalid requests, while remaining distinct from an atomic reservation across concurrent checkout sessions.
Provider event
- Receive event — The webhook endpoint is a separate boundary from the storefront and checkout request. Its input is a provider event, which requires its own validation and error handling.
- Verify signature — Signed webhook handling validates the provider signature before processing. A posted payload is not accepted as payment evidence merely because it resembles a Stripe event.
- Handle repetition — Webhook and retry tests exercise repeat handling and related failure paths. Passing those checks is implementation evidence; it does not establish that every live payment and downstream service journey has been verified.
Stock update
- Persist target — Persisted stock targets give the update a stable goal across attempts. That avoids treating every retry as a newly calculated subtraction with no connection to the earlier request.
- Use idempotency — Idempotency keys help provider calls recognize a repeated operation. Their protection has a finite provider-defined lifetime, so they do not eliminate the need for persisted application state.
- Check the boundary — These controls do not provide atomic inventory reservations. Distinct concurrent sessions can still oversell; preventing that requires a stronger inventory allocation mechanism than the one represented here.
Choose a perspective, then select a stage. Keyboard: arrow keys switch perspectives.
04 / Key decisions
The choices behind the solution.
Make price and quantity checks server-side.
Why it mattersThe purchase request needs an authority independent of the browser.
The tradeoffThe server must keep its validation aligned with the provider catalog and supported checkout behavior.
Verify webhook signatures before processing.
Why it mattersProvider events cross a separate trust boundary.
The tradeoffCorrect deployed webhook configuration remains necessary for the live path.
Persist stock targets and retry identifiers.
Why it mattersRepeated attempts need a stable operation intent.
The tradeoffRetries and idempotency do not solve concurrent inventory allocation or provide an unlimited provider guarantee.
05 / What it produced
A concrete integration with bounded verification.
The work connected a 68-product catalog to a storefront with Clerk identity, server-side commerce checks, signed webhook handling, persisted stock targets and retry/idempotency tests. October 2026 validation recorded 94 passing tests. That is a recorded validation result, not a claim of sales or a fresh test run for this portfolio publication.
Full live journeys were not all verified. Validation did not make real payments or perform live commerce writes, and production-only identity behavior and provider-configuration prerequisites limited end-to-end checks. Stock validation and retry controls do not provide atomic reservations; distinct concurrent sessions can oversell.
Server checkout boundary
Identity, price, quantity and stock checks connect the browser request to supported provider data.
Signed event handling
Webhook verification separates authenticated provider events from arbitrary posted payloads.
Retry regression coverage
Tests cover persisted stock targets and idempotency behavior within the supported implementation scope.
A passing test is evidence with a scope.
Commerce engineering requires clear distinctions between a checked request, a retryable provider operation and a fully verified live journey. Documenting those boundaries makes the implementation easier to assess and the remaining work easier to prioritize.
Project context & references
2026 · Engineering case study
Private implementation and validation materials support this study. The 94-test figure is the historical October 2026 validation record, not a fresh run reported by this page. No customer records, provider credentials, live payment evidence or private source links are published.
Next / Kahla AI Office