How Hygge works
A high-level walkthrough of the data flow from buyer click to synced Shopify order — and why we chose this design.
Hygge sits between Shopify (the storefront + order book) and Whop (the payment processor) without ever becoming the merchant of record. This page is the developer-shaped explanation of the same thing the Getting Started page describes for merchants.
The flow, end to end#
Buyer adds to cart on Shopify storefront
│
▼
Hygge script tag intercepts the "Checkout" click
│
▼
POST /api/checkout/create-from-cart ── verifies prices via Shopify Admin API
│ creates a `checkouts` row in Supabase
▼
POST /api/checkout/get-plan ── checks merchant's monthly transaction limit
│ creates a one-shot Whop plan via merchant's API key
▼
Buyer sees Hygge drawer → completes payment on Whop
│
▼
Whop sends `payment.succeeded` webhook
│
▼
POST /api/webhooks/whop ── verifies HMAC, records transaction,
posts paid order to Shopify Admin API
│
▼
Order appears in Shopify admin tagged `hygge-checkout`
Receipt + fulfillment trigger normally
Each arrow is a real network hop, but the perceived buyer latency is sub-second on the create + redirect path. The Whop webhook and Shopify order sync happen after the buyer completes payment, so that part doesn't gate UX.
Key concepts#
Connector model. Hygge never becomes the Merchant of Record. Each merchant brings their own Whop API key and webhook secret; payments settle to their Whop account; we collect a flat 0.5% platform fee on top of Whop's processor fees. We don't custody buyer funds at any point.
Script tag injection, not theme edits. When a merchant installs the Shopify app, we register one script tag (payhygge.com/embed/cart.js) with display_scope=online_store. The script listens for cart events and opens our drawer when the buyer hits Checkout. Uninstalling the app removes the script tag automatically — no theme rollback needed.
Per-merchant Whop isolation. The merchant's Whop API key and webhook signing secret are stored encrypted in the merchants table. Every Whop webhook is HMAC-verified against that merchant's secret (never a shared one), so even if our shared WHOP_WEBHOOK_SECRET_HYGGE (used for SaaS subscription events) leaked, buyer-payment events for any individual merchant would still be tamper-proof.
Why this design#
We made three load-bearing trade-offs early:
-
No MoR. Becoming Merchant of Record means inheriting buyer disputes, regulatory KYC, and processor relationships at scale. We picked Whop precisely because they handle that — and it's also why our fees can be 5-10x lower than MoR-style competitors.
-
No theme writes. The fastest way to onboard a merchant is to never ask them to touch their theme. Script tag injection is invisible to the storefront design and survives theme switches.
-
Server-side price verification. Every cart total is re-checked against the Shopify Admin API (
/variants/{id}.json) before we accept it. Client-supplied totals are never trusted — the buyer could edit the payload in DevTools, and that's the most obvious price-tampering vector.
What you don't have to think about#
- Buyer card data — Whop handles it.
- PCI compliance — Whop's scope, not yours, not ours.
- Order receipts — Shopify sends them when we POST the order.
- Inventory — Shopify decrements when we POST the order.
- Refunds — handled in Shopify admin, propagate through Whop's standard refund flow.
For specific subsystems, jump to Architecture or Webhooks.