Designing the API Platform Behind a Modern VSR Commerce Experience

Project snapshot

Client / context: North Coast Medical / VSR modernization

Role: Full-stack design engineer

Focus: API architecture, product catalog modeling, cart and checkout services, sync pipelines, migration infrastructure

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

One-line version

I designed and built a Next.js API service that turned scattered VSR product, cart, checkout, affiliate, and migration logic into a clearer backend platform for modern storefronts and admin tools.

The challenge

VSR was evolving from a legacy affiliate/product ecosystem into a modern commerce experience, but the underlying product data and workflows were spread across older systems.

The service needed to support:

product and category reads for frontend consumers
cart sessions and line-item persistence
affiliate-aware checkout behavior
Stripe payment flows and webhook confirmation
category/product synchronization from legacy VSR/Ecwid sources
migration paths toward newer commerce tooling like Medusa
admin workflows for category structure, ordering, and images

The design challenge was creating a stable API boundary while the surrounding ecosystem was still in motion.

My role

I worked across API design, backend implementation, data modeling, integration work, and operational tooling. My contributions included:

shaping the V2 API contract for catalog, product, cart, and checkout routes
building typed response envelopes, request IDs, error contracts, pagination, and batch reads for frontend clients
implementing cache-aware catalog reads with ETag, Last-Modified, and stale-while-revalidate behavior
modeling cart state as persisted backend state rather than frontend-only state
wiring Stripe checkout, server-owned shipping and tax, return handling, metadata, confirmation numbers, and idempotent webhook processing
creating deterministic Ecwid-to-VSR identity resolution and sync tooling
creating sync/import scripts for category, product, meta-item, and Medusa workflows
adding admin category endpoints and category image upload/migration support
adding Sentry instrumentation and standalone Docker/Coolify deployment support
writing tests around API behavior, caching, checkout, cart metadata, sync logic, and migrations

Selected work

1. V2 API contract for frontend consumers

I helped move the service from one-off endpoints toward a documented V2 contract built for React Query-style consumers.

The API standardized around:

data, meta, and error response envelopes
request IDs and typed, retry-aware error payloads
cursor pagination for product lists
batch category and product-meta reads
typed product, category, product-meta, cart, and checkout payloads
explicit React Query keys and invalidation rules
clear cache semantics for catalog reads
no-store behavior for cart and checkout routes

I also documented the endpoint migration path so frontend teams could move from legacy and V1 routes without reconstructing the contract from implementation details. This gave frontend apps a predictable integration layer instead of binding them directly to legacy data quirks.

2. Catalog performance and cache strategy

Catalog routes needed to serve product and category data without repeatedly hammering the database or upstream systems.

I added cache-aware behavior and query optimizations:

ETag / Last-Modified validators for read-heavy endpoints
cached query helpers for product/category lookups
fixes for N+1 query behavior
batch serialization improvements
response shaping that kept product metadata and variants easier for clients to consume

The goal was not only faster endpoints, but a better contract between backend data shape and frontend rendering needs.

3. Product, variant, and inventory modeling

VSR product data had to bridge multiple concepts: categories, product metas, item numbers, variants, attributes, disabled sales states, inventory, list prices, media, and affiliate eligibility.

I implemented and refined behavior around:

product lookup by product ID or item number
metaItemId propagation through product and category responses
selectable product items and disabled-sales filtering
normalized availability states for in-stock, special-order, on-demand, out-of-stock, and unavailable items
attribute combination and variant data shaping on the API side
HTML entity normalization for human-readable catalog fields
filtering synchronized records marked as deleted upstream
category/product import behavior
meta sort ordering for category product display

This reduced client-side guesswork and made product data more usable for storefronts.

4. Legacy identity resolution and storefront decoupling

A critical migration problem was resolving identity across systems that did not share one clean product key. I introduced persistent Ecwid-to-meta-item mappings and deterministic resolution rules that could:

resolve parent META SKUs and item-number SKUs
use variant combinations when they agreed
reject ambiguous or malformed mappings instead of guessing
clean up stale mapping records after synchronization
support V2 lookup by legacy Ecwid product ID
return a product meta's primary storefront category path

This moved legacy matching logic into one tested backend boundary and let new clients transition without reproducing it.

5. Cart and checkout lifecycle design

The cart and checkout routes treated persisted backend cart state as the source of truth. That mattered because pricing, affiliate attribution, and checkout metadata could not safely live only in the browser.

I worked on:

cart session creation and item persistence
line-level bundle and affiliate metadata handling
affiliate ID propagation from persisted cart state
server-owned repricing, shipping, and tax behavior
Stripe Checkout and Payment Intent flows
shipping address collection
generated confirmation numbers and return summaries
idempotent webhook-event tracking before cart payment-state transitions

This created a more reliable path from product selection through payment confirmation.

6. Sync and migration pipeline

The service also acted as a data bridge between legacy VSR/Ecwid-style sources and newer platform targets.

I built and refined scripts for:

syncing categories and products across configured stores and category trees
syncing Ecwid meta-item mappings
classifying and reporting unresolved or ambiguous SKUs
backfilling category/meta-item assignments
building repeatable category and product import tooling for Medusa experiments
making category import idempotent

This made the API repo more than request handlers: it became operational infrastructure for migration and data-quality work.

7. Admin category and media workflows

VSR category management needed backend support for admin interfaces and future tooling.

I added or improved:

admin category create, update, and guarded delete behavior
category-tree reads with product counts
bulk reorder deltas with validation for duplicate IDs, invalid parents, cycles, and broken sibling ranks
ordered product-meta assignments that stayed synchronized with legacy category-item relationships
category meta sort-order import and storefront display support
Cloudflare Images upload for category images
dry-run-safe migration for existing category images with filters and concurrency controls
tests for image upload, migration, ordering, assignment, and admin category behavior

That work bridged design needs in management tools with backend operations.

8. Platform operations and reliability

The platform work also included the infrastructure required to operate and evolve the service:

Sentry instrumentation for server, edge, client, and request errors
a standalone multi-stage Docker build designed for Coolify deployment
request correlation through X-Request-Id
cache policies that distinguished catalog data from cart and checkout state
dry-run-first migration commands and focused audit scripts
automated coverage across critical catalog, admin, cart, checkout, synchronization, and migration behavior

These pieces made the API easier to diagnose, deploy, and change safely as the surrounding systems evolved.

Design engineering approach

Treat API design as product design

For VSR, the API was the product surface. Frontend usability depended on whether product variants, attributes, categories, availability, cart state, and checkout metadata came back in shapes that matched real user flows.

Build stable contracts around unstable systems

The legacy ecosystem was not clean, so the API contract had to absorb complexity. I used typed envelopes, response shaping, cache semantics, and persisted cart state to make downstream clients simpler.

Make migration operational, not theoretical

Migration was not just a planning exercise. The repo included scripts, imports, sync jobs, data-quality audits, tests, and admin endpoints that made data movement repeatable.

Platform delivered

The VSR API work created a concrete backend platform for modern VSR experiences.

It provided:

a stable, documented API boundary for VSR frontends
request IDs, typed errors, pagination, and batch catalog reads
cache-aware catalog endpoints
normalized product, variant, inventory, category, and meta response contracts
deterministic legacy Ecwid identity resolution
persisted cart and checkout state
server-owned shipping, tax, and affiliate attribution rules
Stripe checkout, confirmation, return-summary, and idempotent webhook support
sync and data-quality pipelines for legacy VSR/Ecwid data
repeatable Medusa import tooling for migration experiments
admin category ordering, assignment, and media endpoints
Sentry observability and standalone deployment infrastructure
automated coverage around critical catalog, cart, checkout, admin, sync, and migration behavior

What made this hard

The hardest part was not building endpoints. It was designing a backend that could sit between several moving systems:

legacy VSR/Ecwid product sources
evolving frontend storefront needs
affiliate and commission-adjacent identity rules
Stripe payment lifecycle requirements
admin tooling needs
category/media migration requirements
future commerce architecture experiments

The API had to be stable enough for clients while flexible enough for migration work.

Why it matters

This case study shows full-stack design engineering from the platform side. The visible interface was not a single screen; it was the contract that allowed screens, carts, checkout, admin tools, and migration scripts to work together.

I designed and implemented the backend layer that made new VSR product experiences possible.

Pull quote

I designed the backend platform that made modern VSR commerce experiences possible, turning product, cart, checkout, and migration logic into a stable API contract.

Short version for website card

Designed and built the backend API platform behind a modern VSR commerce experience. The service unified catalog reads, cart sessions, checkout, affiliate metadata, sync pipelines, and migration tooling into a clearer product contract for storefronts and admin tools.