Set up your shop

How it works

This template is a complete small shop. Everything you see is designed natively in Webstudio on the Craft design system. Commerce runs on Merchant, an open-source backend for Cloudflare Workers and Stripe.

A purchase, step by step

1. The shopper adds products. The cart lives in the browser (localStorage) until checkout, because Merchant carts need an email address up front.
2. On /cart they fill in contact details and the shipping address in a form designed in Webstudio. bridge.js creates a Merchant cart, and Merchant re-prices every item, checks stock and applies the discount code.
3. Merchant opens a Stripe Checkout session with that address. Only a compact Stripe payment box appears on the page (card, Apple Pay, Google Pay, Link).
4. After payment Stripe returns the shopper to /checkout/success. Stripe's webhook tells Merchant to create the order and reduce stock.
5. The shopper can sign in at /account with a one-time email link to see their orders and tracking.

Server and browser

Webstudio renders every page on the server. That covers everything that is the same for all visitors. Anything that belongs to one visitor (their cart, their payment, their account) can only happen in the browser, and that is the job of bridge.js.

Why Webstudio needs a bridge

• Resources run on the server once per page request. They can read public data such as the product catalog, but not a visitor's own state: a cart in localStorage or a sign-in session only exists in that visitor's browser.
• Checkout is a sequence of calls (create cart, add items, apply discount, start payment) whose results feed the next step and end in Stripe's payment form. That needs code running on the page, and Stripe.js only runs in the browser.
• Secret keys must never reach Webstudio. Everything that needs Merchant's admin key (orders, customers) goes through the account Worker, which only returns the signed-in customer's own orders.

How the bridge stays out of the design

• The bridge draws no layout. It finds elements you designed by data-* attributes and only fills in text, toggles hidden and clones the hidden templates. Moving or restyling elements in Webstudio never breaks it.
• It is one dependency-free script inside the Shop Bridge HTML Embed of the Header slot, so every page has it and copying the project copies it. Its readable source is webstudio/bridge.js in the template repository.
• It starts after Webstudio has hydrated the page and watches for client-side navigation, so it works across page changes without a reload.
• It handles its forms before Webstudio's router does, which otherwise would turn a submit into a page navigation.

What you need

• A Webstudio plan with dynamic data (Resources).
• A Cloudflare account. The Workers free plan is enough to start; Merchant uses Durable Objects and R2, the account Worker uses D1.
• A domain on Cloudflare DNS if you want sign-in emails (Cloudflare Email Sending).
• A Stripe account. Test mode works for everything below.
• Node.js 20+ on your computer for the one-time setup commands.

Get the code from the template repository. It contains account/ (the account Worker), merchant.patch (additions and fixes for Merchant, see Changes to Merchant) and webstudio/bridge.js (the readable source of the Shop Bridge). Merchant itself always comes from its own repository; the template does not ship a fork.

Choose your checkout

The template supports two checkouts. You pick one by filling in, or leaving empty, stripePublishableKey in the shop variable.

Countries offered for shipping come from the options of the Country select on /cart, in both modes. Edit them in Webstudio.

1. Deploy Merchant

git clone https://github.com/ygwyg/merchant.gitcd merchantgit apply ../webstudio-merchant-template/merchant.patch   # skip for hosted checkoutnpm installnpx wrangler loginnpx wrangler deploy

Optionally rename the Worker in wrangler.jsonc ("name"); the account Worker refers to Merchant by this name. If you want order emails, also add "compatibility_flags": ["global_fetch_strictly_public"] there: it lets Merchant's webhooks reach the account Worker on the same Cloudflare account.

Wrangler prints your Merchant URL, for example https://webstudio-merchant.your-subdomain.workers.dev. Now create the API keys. This works exactly once per store:

MERCHANT_URL=https://webstudio-merchant.your-subdomain.workers.dev npx tsx scripts/init.ts --remote

Run the init command right after deploying. Until keys exist, anyone who finds the URL could create them first.

2. Connect Stripe

1. In Stripe → Developers → Webhooks, add an endpoint MERCHANT_URL/v1/webhooks/stripe for the events checkout.session.completed and checkout.session.expired. Copy its signing secret (whsec_…).
2. Give Merchant your secret key and the signing secret. Merchant reads the key in two places, so set both:

npx wrangler secret put STRIPE_SECRET_KEYcurl -X POST $MERCHANT_URL/v1/setup/stripe \  -H "Authorization: Bearer sk_…" -H "content-type: application/json" \  -d '{"stripe_secret_key":"sk_test_…","stripe_webhook_secret":"whsec_…"}'

Copy your publishable key (pk_test_… or pk_live_…) from Stripe → Developers → API keys. It goes into the Webstudio shop variable and enables the payment form on your own page. Leave it empty to send shoppers to Stripe's hosted page instead.

Taxes

STRIPE_AUTOMATIC_TAX in merchant/wrangler.jsonc controls Stripe Tax. It is "false" in this template. Set it to "true" only after Stripe Tax is active on your Stripe account, otherwise every checkout fails.

3. Deploy the account Worker

Open account/wrangler.jsonc and set:

cd accountnpm installnpx wrangler deploynpx wrangler d1 execute webstudio-merchant-account --remote --file=schema.sqlnpx wrangler secret put MERCHANT_ADMIN_KEY

Sign-in emails

In Cloudflare go to Compute → Email Service → Email Sending and onboard your domain or a subdomain. Cloudflare adds the SPF, DKIM and DMARC records for you. Onboarding a subdomain keeps your main domain's email untouched.

Until email is set up, the sign-in form answers “Sign-in by email isn't set up for this shop yet.” Everything else works.

Order emails

With the account Worker deployed, every paid order sends two emails through Cloudflare Email Sending:

Merchant tells the account Worker about new orders with its signed order.created webhook. Register it once and store the secret Merchant returns:

curl -X POST $MERCHANT_URL/v1/webhooks -H "Authorization: Bearer sk_…" \  -H "content-type: application/json" \  -d '{"url":"https://ACCOUNT_WORKER_URL/hooks/merchant","events":["order.created"]}'cd account && npx wrangler secret put MERCHANT_WEBHOOK_SECRET   # paste the returned whsec_…

• The Worker checks Merchant's signature on every call and sends each order's emails only once, even when Merchant retries.
• Customers who sign in at /account with the same email see every order with items, prices, totals, shipping address, status and tracking.

4. Configure the Webstudio project

All connection settings live in one place: the shop variable on Global Root (Data variables panel). Edit it and publish.

Leave accountUrl empty if you don't deploy the account Worker: the shop and checkout work without it, and only sign-in and the order number on the confirmation page need it.

A fresh copy of this template is still connected to the ELECOS demo backend in Stripe test mode, so it works right away. Replace the shop values with your own before you publish your shop; until then, test orders from your copy land in the demo store.

5. Test a purchase

While Merchant uses Stripe test keys (sk_test_…, pk_test_…), no real money moves. Add something to the cart, continue to payment and use:

To test other outcomes, use 4000 0025 0000 3155 (asks for 3-D Secure confirmation) or 4000 0000 0000 9995 (declined: insufficient funds). Stripe lists more in its testing documentation.

After paying you land on /checkout/success with your order number. The order appears in Merchant's admin, and signing in at /account with the same email shows it in the order history.

Going live

1. Switch Stripe to live mode and repeat step 2 with live keys: STRIPE_SECRET_KEY, a live webhook endpoint and its signing secret, and POST /v1/setup/stripe.
2. Put the live publishable key (pk_live_…) into the shop variable.
3. Delete the Demo Notice on the cart page (inside the Payment section) and replace the placeholder legal pages.
4. Publish, then place one real order and refund it through Merchant to confirm the whole flow.

Managing products

The easiest way is Merchant's admin dashboard. It ships with Merchant and deploys as its own small Worker:

cd merchant/adminnpm install && npm run buildnpx wrangler deploy

Open the URL Wrangler prints and sign in with your Merchant URL and admin key (sk_…). The key stays in that browser only. The dashboard manages products, variants, stock, images, orders, customers and discounts.

You can also use the API directly:

# 1. Create a product (starts as draft)curl -X POST $MERCHANT_URL/v1/products -H "Authorization: Bearer sk_…" \  -H "content-type: application/json" -d '{"title":"Everyday Mug","description":"…"}'# 2. Upload an image, then add a variant (price in cents)curl -X POST $MERCHANT_URL/v1/images -H "Authorization: Bearer sk_…" -F file=@mug.jpgcurl -X POST $MERCHANT_URL/v1/products/PRODUCT_ID/variants -H "Authorization: Bearer sk_…" \  -H "content-type: application/json" \  -d '{"sku":"MUG-SAND","title":"Sand","price_cents":2800,"image_url":"https://…/v1/images/…"}'# 3. Add stock and publishcurl -X POST $MERCHANT_URL/v1/inventory/MUG-SAND/adjust -H "Authorization: Bearer sk_…" \  -H "content-type: application/json" -d '{"delta":40,"reason":"restock"}'curl -X PATCH $MERCHANT_URL/v1/products/PRODUCT_ID -H "Authorization: Bearer sk_…" \  -H "content-type: application/json" -d '{"status":"active"}'

• Only active products appear in the shop. Product changes need no republish of the site.
• Merchant stores one image per variant. The product page turns them into a gallery: each thumbnail selects its variant, so photo, price and option always match. Products with one variant show a single photo.
• Cards show the first variant's image and price. Create the cheapest variant first so “From $X” is right.
• Discount codes are created with POST /v1/discounts and entered by shoppers on the cart page.

Changing the design

The project follows Craft: theme variables → semantic variables → composite Tokens, all on Global Root. See the style guide for every color pairing, Token and extension.

Tokens such as button, card, heading and Product Card only use semantic variables, so re-theming never requires editing a Token.

Moving and restyling elements

bridge.js finds elements by data-* attributes, not by position or class. Restyle or move anything freely, but keep these attributes (Settings → Attributes) on the element that should do the job:

Fulfilling orders

Orders appear in Merchant once Stripe confirms payment. Mark an order as shipped with a tracking link, and the customer sees it in their account:

curl -X PATCH $MERCHANT_URL/v1/orders/ORDER_ID -H "Authorization: Bearer sk_…" \  -H "content-type: application/json" \  -d '{"status":"shipped","tracking_number":"1Z…","tracking_url":"https://…"}'

Refunds: POST /v1/orders/ORDER_ID/refund, optionally with amount_cents for a partial refund. Merchant can also call your own webhooks on order.created, order.shipped and inventory.low.

Keys and security

• Sign-in links work once and expire after 15 minutes; sessions last 30 days. Only SHA-256 hashes of tokens are stored.
• The account Worker answers only origins listed in SITE_ORIGIN and ALLOWED_ORIGINS.
• Prices always come from Merchant at checkout; the browser cart can't change what a shopper pays.

Good to know

• Merchant has no product slugs or categories. Product URLs use the product ID, and the shop is one list.
• Stock is not visible with the public key. If an item runs out, the shopper gets a clear message at checkout.
• The legal pages contain placeholder text. Replace it before you launch.
• Merchant keeps inventory reserved while a checkout is open; abandoned sessions release it when they expire.

Changes to Merchant

The template uses unmodified Merchant plus merchant.patch: four small, backwards-compatible additions for the embedded checkout and one bug fix for stock reservations (about 110 lines in src/). Existing Merchant clients keep working. The hosted checkout needs none of the additions, but the stock fix is worth applying either way. The patch was checked against Merchant commit 1b42cbb.

If Merchant changes and the patch no longer applies, git apply --3way ../webstudio-merchant-template/merchant.patch usually resolves it. These changes are good candidates for a pull request upstream; once merged, the patch step goes away.