Build a custom storefront with Lovable or v0 — one prompt

You can vibe-code a custom storefront and still let Quickshops run checkout.

Open Lovable, v0.dev, Cursor, or Bolt. Paste one prompt. Point the app at your Pro API key. You get a site that looks like your brand — while products, cart, Stripe Checkout, and delivery stay on Quickshops via @quickshops/sdk.

That is headless commerce for the AI age: you design the front; we stay the commerce brain.

Why headless + AI builders now

AI coding tools are finally good at SSR apps, Route Handlers, and cookie-backed sessions. They are still bad at inventing payment systems.

That split is useful. Let the agent own layout, typography, and cart UX. Do not let it invent card forms or order databases. Point it at a real SDK that already knows your catalog and your Stripe Connect account.

Quickshops already does that for the hosted storefront. The same stack is available for custom sites:

• TypeScript SDK @quickshops/sdk with useStore() (preferred)
• Optional UI @quickshops/sdk/react (Storefront.* composition primitives, CheckoutSuccess)
• Bearer API keys (qk_...) on Pro
• Buy-now checkout → Stripe-hosted payment page → your success URL

You keep creative control. You do not rebuild payments. Prefer useStore() + /react over hand-rolled REST or redirect strings.

What Quickshops provides

Think of Quickshops as the backend your vibecoded UI plugs into.

Flow stays simple:

1. Your server calls store.loadCatalog()
2. Your server calls store.buyNow({ productId }) (or optional cart helpers)
3. The browser redirects to the Stripe Checkout URL
4. Stripe returns the customer to your success page
5. Your success page calls store.getCheckoutSession(sessionId)

Payment UI stays on Stripe. Digital delivery stays on Quickshops. Your site never sees raw card data.

One-prompt install

Paste the master prompt from docs.quickshops.app/sdk/one-prompt-storefront into Lovable, v0, or Cursor.

That guide covers:

• Prerequisites (Pro, API key, Stripe Connect)
• Env vars (HEADLESS_API_KEY, optional HEADLESS_API_URL, SITE_URL)
• The hard rule: key never in the client; commerce via useStore()
• Optional UI via @quickshops/sdk/react (Storefront.Provider + slots; pass Server Actions as actions)
• Buy-now default (store.buyNow) — no cart cookie required
• Success-page status via store.getCheckoutSession
• A pasteable master prompt for Lovable / v0 / Bolt / Cursor

Optional for agents:

npx skills add valtterisa/quickshops --skill quickshops-headless-storefront

Your job as the human: upgrade to Pro, connect Stripe, issue a key under Settings → API keys, paste the master prompt, set env vars.

How it works with Lovable and v0 (SSR BFF)

Lovable and v0 like shipping interactive React. That is fine for buttons and layout. It is wrong for API keys.

Use a BFF (backend-for-frontend):

Browser  →  your /api or Server Actions  →  @quickshops/sdk (qk_...)  →  Stripe

In Next.js App Router terms:

• Instantiate @quickshops/sdk in a file with import "server-only"
• Read/write the cart from Server Actions or Route Handlers
• Pass catalog data into @quickshops/sdk/react (Storefront.Provider + composition slots)
• On checkout, create the session on the server, then redirect() (or return { url } for window.location)

Never call api.quickshops.app from a "use client" module. Never put HEADLESS_API_KEY in NEXT_PUBLIC_*. Do not teach the agent to fetch REST paths when the SDK covers the call.

Custom return URLs

Do not assemble redirect URLs yourself. useStore() reads SITE_URL and sets absolute return URLs for you.

const { buyNow } = useStore();
const { url } = await buyNow({ productId: "prod_01j..." });

Step-by-step

1. Upgrade to Pro — Account → Billing. API keys are Pro-only.
2. Connect Stripe — under Payments. Without Connect, checkout returns a conflict.
3. Publish products — at least one active digital or subscription product.
4. Issue an API key — Settings → API keys. Copy the qk_... value once.
5. Open your AI builder — Lovable, v0.dev, Cursor, or Bolt with a Next.js App Router project.
6. Paste the master prompt from the one-prompt docs.
7. Set env vars on the host:

HEADLESS_API_KEY=qk_...
HEADLESS_API_URL=https://api.quickshops.app
SITE_URL=https://your-deployed-storefront.example

8. Buy something in test — add to cart, checkout, complete Stripe test payment, land on /success.
9. Optional: webhooks — Settings → Webhooks, subscribe to order.completed if your app needs a server-side order hook.

Docs: SDK install and API overview (REST reference — prefer the SDK in apps).

What stays on Quickshops vs what you design

Stays on Quickshops

• Catalog edits (dashboard, AI Chat, MCP, Telegram — same store)
• Pricing, discounts configured in-product
• Stripe Connect and Checkout
• Order records and buyer email delivery
• Subscription lifecycle and member portal APIs
• Webhook delivery (order.completed, subscription events)

You design

• Marketing pages and product presentation
• Navigation, cart drawer, empty states
• Success and cancel experiences on your domain
• Any CMS, blog, or community around the shop

You can keep using the hosted Quickshops storefront for one audience and a vibecoded site for another. Both can sell the same catalog through the same store and Stripe account.

Who this is for

• Creators who want a fully custom look without rebuilding payments
• Teams already living in Lovable, v0, or Cursor
• Sellers on Pro who already use API keys for MCP or automation

Who should skip it

If the built-in storefront and themes are enough, stay there. Headless is optional power, not a requirement to sell.

Pro plan

API keys, MCP, and Telegram are Pro features.

Free still includes your hosted storefront, Stripe checkout, and in-app AI Chat with trial messages. Pro unlocks the integrations that meet you where you already work — including the headless API and @quickshops/sdk for custom storefronts.

See pricing for the comparison.

Start building

1. Upgrade to Pro if needed
2. Connect Stripe and issue a key under Settings → API keys
3. Follow the one-prompt storefront guide
4. Paste the master prompt into Lovable, v0, or Cursor

SDK: docs.quickshops.app/sdk/installation

If something fails at checkout, check the docs error table first (401 key, Pro required, empty cart, mixed subscription cart, missing Stripe). If you are still stuck, email valtteri@quickshops.app with your setup (builder + framework) and the error code.