Skip to content
Matt BiehlIndependent design + development
Back to work

Project

Designing the API Platform Behind a Modern VSR Commerce Experience

Designing and building a Next.js API service that consolidates scattered VSR product, cart, checkout, affiliate, and migration logic into a backend platform for modern storefronts and admin tools.

VSR commerce API workflow diagram, not a product screenshot
Workflow diagram

Editorial workflow diagram based on the published case study. Internal screens were not accessed or reconstructed.

View full-size View source

In detail

Portfolio source

Project snapshot

Client: North Coast Medical / VSR modernization

Role: Full-stack design engineer

Stack: Next.js route handlers, TypeScript, Drizzle, PostgreSQL, Stripe, Sentry, Cloudflare Images, VSR/Ecwid sync jobs, Medusa import scripts.

Problem

Product data and workflows spanned legacy systems while VSR moved toward modern commerce. The backend needed stable contracts for catalog reads, persisted carts, affiliate-aware checkout, payments, synchronization, admin operations, and migration experiments—even as frontend requirements and future architecture evolved.

Approach

I treated the API as a product surface. Response shapes followed real storefront, checkout, and administrative flows. Legacy complexity belongs behind stable contracts; authoritative cart and checkout state belongs on the server. Migration needed repeatable scripts, audits, imports, and synchronization.

Implementation

  • Documented a V2 contract with data/meta/error envelopes, request IDs, typed retry-aware errors, cursor pagination, batch reads, query keys, invalidation rules, and legacy/V1 migration guidance.
  • Added ETag, Last-Modified, stale-while-revalidate, cached query helpers, N+1 fixes, and batch serialization improvements. Cart/checkout routes use no-store behavior.
  • Normalized product lookup, metaItemId propagation, variants, attributes, availability, deleted-record filtering, and category meta ordering.
  • Built persistent Ecwid-to-meta-item mappings with deterministic parent-META and item-number resolution. Ambiguous or malformed mappings are rejected rather than guessed; stale mappings and unresolved SKUs are surfaced.
  • Made backend carts authoritative for line items, bundle metadata, affiliate attribution, and checkout metadata. Added server-owned repricing, shipping, tax, Stripe Checkout/Payment Intents, return summaries, confirmation numbers, and idempotent webhook-event tracking.
  • Created category/product sync, assignment backfills, repeatable Medusa imports, and idempotent category import tooling.
  • Added category administration and bulk reordering with validation against duplicate IDs, invalid parents, cycles, and broken sibling ranks.
  • Integrated Cloudflare Images and dry-run-safe image migration. Added Sentry, X-Request-Id correlation, a multi-stage Docker build for Coolify, audit scripts, and automated workflow tests.

Outcomes and limitations

Delivered a documented integration boundary, normalized catalog contracts, deterministic legacy identity resolution, persisted checkout state, and operational migration infrastructure. Medusa tooling supported experiments, not a reported completed migration. No quantitative performance or business results were supplied.

Adapted from portfolio text; images and navigation omitted.

Back to all work

What’s getting in
your product’s way?

Tell me what you’re building, where it gets difficult, and what you’d like to change.

Email your projectmatt@biehl.io
Designing the API Platform Behind a Modern VSR Commerce Experience — Matt Biehl | biehlux.com