How to Integrate Vercel with Fourthwall

Build a custom storefront on Vercel, powered by Fourthwall's Storefront API and the official Next.js template

The Fourthwall Storefront API lets you build a fully custom shopping experience while Fourthwall handles products, checkout, and fulfillment behind the scenes. The official vercel-commerce template gives you a production-ready Next.js App Router storefront that you can deploy to Vercel in one click.

Prerequisites

Before you start, make sure you have:

• A Fourthwall store with at least one published product
• At least one collection set up (the default "all" collection works too)
• A storefront token from Settings > For Developers in your Fourthwall dashboard
• A Vercel account

note

Your storefront token starts with ptkn_. Keep it safe, as it grants read access to your product catalog and collections.

Deploy the template to Vercel

The fastest way to get started is the one-click deploy button on the vercel-commerce GitHub repository.

Step 1: Go to github.com/FourthwallHQ/vercel-commerce and click Deploy with Vercel.

Step 2: Vercel will prompt you to create a new repository and configure the project. Set the following environment variables during setup:

• NEXT_PUBLIC_FW_STOREFRONT_TOKEN (required): Your storefront token, e.g. ptkn_...
• NEXT_PUBLIC_FW_CHECKOUT (required): Your Fourthwall store URL used for checkout redirects, e.g. vercel-shop.fourthwall.com
• NEXT_PUBLIC_VERCEL_URL (required): Your Vercel site URL, used for sitemap.xml and robots.txt, e.g. fw-commerce.vercel.app
• NEXT_PUBLIC_FW_COLLECTION (optional): A specific collection handle to display instead of all products
• FOURTHWALL_WEBHOOK_SECRET (optional): A secure random string for webhook-based cache invalidation

Step 3: Click Deploy. Vercel builds and deploys your storefront automatically.

You can also set or update environment variables later through the Vercel dashboard or CLI with vercel env.

Run locally for development

If you want to customize the template before deploying, you can run it on your local machine.

1. Install the Vercel CLI: npm i -g vercel
2. Clone your repository and link it to Vercel: vercel link
3. Pull your environment variables: vercel env pull
4. Install dependencies and start the dev server:

pnpm install
pnpm dev

Your storefront will be available at localhost:3000.

Environment variables reference

Variable	Required	Description
NEXT_PUBLIC_FW_STOREFRONT_TOKEN	Yes	Your storefront token from Settings > For Developers
NEXT_PUBLIC_FW_CHECKOUT	Yes	Your Fourthwall store URL for checkout redirects
NEXT_PUBLIC_VERCEL_URL	Yes	Your Vercel deployment URL for sitemap and robots.txt
NEXT_PUBLIC_FW_COLLECTION	No	Collection handle to display a specific collection
FOURTHWALL_WEBHOOK_SECRET	No	Secret for HMAC-SHA256 webhook signature verification
NEXT_PUBLIC_USE_FW_IMAGE_OPTIMIZATION	No	Set to "true" to use Fourthwall's built-in image optimization instead of Vercel's

How checkout works

When a supporter adds items to their cart and proceeds to checkout, they are redirected to Fourthwall's hosted checkout page. The checkout URL follows this format:

https://{your_checkout_domain}/checkout/?cartCurrency={currency_code}&cartId={cart_id}

You can style the checkout experience in your Fourthwall dashboard by selecting a simple theme (such as Clean Frame), applying consistent colors and typography, and connecting a custom domain like checkout.yourstore.com.

For more details on checkout styling, see the Storefront checkout documentation.

Caching and Incremental Static Regeneration (ISR)

The template uses Incremental Static Regeneration (ISR) to serve fast, cached pages while keeping product data up to date.

• Home page: Pre-built at deploy time for USD, EUR, GBP, and CAD currencies
• Product and collection pages: Built on first request, then cached. Currency is part of the URL path (e.g. /USD/product/my-product) so each currency variant gets its own cached page
• Auto-revalidation: All pages revalidate every hour (revalidate = 3600)
• Cart: Fetched on the client side so product pages stay fully static

This means your storefront loads quickly for supporters without requiring a server to render pages on every request.

Set up webhook cache invalidation

For real-time product updates, you can configure Fourthwall webhooks to purge cached pages whenever you change a product or collection.

Step 1: Set the FOURTHWALL_WEBHOOK_SECRET environment variable in your Vercel project to a secure random string.

Step 2: In your Fourthwall dashboard, add a webhook pointing to:

https://your-site.com/api/webhooks/fourthwall

Step 3: Subscribe to the following events:

• PRODUCT_CREATED
• PRODUCT_UPDATED
• COLLECTION_UPDATED

The template verifies each incoming webhook using HMAC-SHA256 signature verification, so only requests signed with your secret are processed.

Image optimization

By default, the template uses Vercel's built-in image optimization service. If you prefer to use Fourthwall's image optimization instead, set the following environment variable:

NEXT_PUBLIC_USE_FW_IMAGE_OPTIMIZATION="true"

Both options resize and compress images for faster loading. Choose the one that best fits your hosting setup.

Analytics

The template automatically fetches your analytics configuration from your Fourthwall store via {NEXT_PUBLIC_FW_CHECKOUT}/platform/analytics.json. This configuration is cached for one hour.

Google Tag Manager reads window.* variables set by this configuration, so any analytics tools you've connected in your Fourthwall dashboard (Google Analytics, Meta Pixel, etc.) work automatically on your custom storefront.

If the analytics endpoint is unavailable, the template falls back to environment variable configuration.

Frequently asked questions

What is a collection handle?

A collection handle is the URL slug that identifies a collection. The default "all" collection contains all your public products. To find a specific handle, go to Collections in your dashboard, click the collection, and copy the last part of the URL.

Can I use this with a custom domain?

Yes. Configure your custom domain in your Vercel project settings. You can also connect a custom domain for the checkout page through your Fourthwall dashboard.

Do I need to rebuild my site when I add new products?

No. With ISR, new product pages are built automatically on the first request. If you set up webhook cache invalidation, existing pages update within seconds of a product change.

What happens if I don't set FOURTHWALL_WEBHOOK_SECRET?

Your storefront still works, but product pages rely on the hourly auto-revalidation cycle to pick up changes. Setting up webhooks gives you near-instant updates.

---

If you have any questions, do not hesitate to contact us at support@fourthwall.com.