How to Build a Custom Ecommerce Store with Thor Commerce and AI
Thor Commerce lets developers build flexible, headless storefronts that stay aligned with a robust commerce backend. By pairing Thor with AI coding agents, you can rapidly prototype, customize, and deploy a fully functional storefront while keeping commerce logic safe and consistent.
Thor Commerce has shifted the balance in ecommerce development. Instead of choosing between a rigid template or rebuilding every core feature from scratch, headless commerce lets you keep a powerful, purpose‑built backend while designing a storefront that reflects your brand and buying journey. This guide walks you through building a custom storefront with Thor Commerce’s open‑source Next.js starter and an AI coding agent such as Claude Code, Codex, or Cursor.
What is Thor Commerce?
Thor Commerce is a headless platform that handles catalog, contextual pricing, inventory, customers, carts, checkout, and orders. Its Admin API is the control plane for server‑side tasks—adding products, setting prices, managing inventory, and processing orders—while the Storefront API powers buyer‑facing flows. Both APIs are GraphQL, so you can request only the data you need and benefit from generated TypeScript types that keep your code in sync with the schema.
Thor’s real strength lies in context‑aware commerce. A single product can have different availability or pricing depending on store, country, currency, price channel, or customer group. This is especially useful for businesses that sell both DTC and B2B from the same catalog.
Why Thor Works Well with AI Coding Agents
AI agents excel when they operate within clear boundaries and a reliable source of truth. Thor provides exactly that: typed GraphQL contracts, task‑oriented documentation, agent‑ready source files, and a reference implementation that demonstrates proper credential handling, request context, and cart persistence. With these guardrails, an agent can focus on modifying UI components or adding new features without risking commerce logic errors.
Getting Started: Setting Up the Storefront
Begin by cloning Thor’s Next.js reference storefront:
- git clone https://github.com/thor-commerce/next-thor-storefront
- cd next-thor-storefront
- pnpm install
Before asking the AI to make changes, prompt it to read AGENTS.md and the relevant Thor Commerce Storefront API skill. This gives the agent context about the available GraphQL operations and the repository structure.
Connecting to Your Thor Project
Copy the example environment file and fill in your project details:
- THOR_PROJECT – your project slug from the Thor dashboard
- THOR_STOREFRONT_API_KEY – the Storefront API token
- BETTER_AUTH_SECRET – a new secret for authentication
- BETTER_AUTH_URL – your local development URL
- NEXT_SERVER_ACTIONS_ENCRYPTION_KEY – a persistent key for server actions
Update src/lib/thorcommerce/config.ts with your market configuration, ensuring country codes, store IDs, and currencies match the Thor project. The storefront will then resolve products, prices, and inventory for the specified markets.
Generating Types and Running the App
Generate TypeScript types from the GraphQL documents:
- pnpm codegen
Start the development server:
- pnpm dev
Navigate to http://localhost:3000. The middleware should redirect you to a country‑prefixed route such as /dk, and you should see products from the configured store. Test adding a product to the cart and verify that the cart persists after a page refresh.
Customizing the Design
Thor’s codebase is organized by commerce domain, making targeted changes straightforward:
- Product queries –
src/lib/thorcommerce/storefront/queries/products.graphql - Product UI –
src/features/products - Cart logic –
src/features/cart - Checkout steps –
src/features/checkout - Customer accounts –
src/features/accountandsrc/lib/auth.ts - Market routing –
src/lib/thorcommerce/config.ts,src/lib/request-context.ts,src/middleware.ts
Provide the AI with a brief that specifies the visual changes you want while preserving the existing data flow. For example, “Redesign product pages for a Scandinavian homeware brand, keeping Thor’s pricing and inventory logic intact.”
Adding a Custom Commerce Feature
Suppose you want to display a structured material specification on product pages. Thor supports typed metafields, so you can define a new field, update the Admin input to set its value, add the selection to the Storefront query, regenerate types, and render the data. Ask the AI to start with the contract and verify that the field exists before making changes.
Testing Cart and Checkout Flows
After each change, run:
- pnpm lint
- pnpm build
Test a full purchase flow using a test payment method. Verify that variant selection, quantity updates, cart persistence, shipping, payment, and order creation all work as expected. Also test failure paths such as out‑of‑stock items, expired sessions, and rejected discount codes to ensure the storefront handles errors gracefully.
Deploying to Production
Thor’s starter includes OpenNext and Wrangler configurations for Cloudflare Workers. Review resource names, bindings, and environment variables before deploying. If you choose a different platform, adjust country detection logic in src/middleware.ts. Ensure that production secrets are stored securely and that the storefront can still access the correct Thor project and market IDs.
By following this workflow, you can rapidly prototype, customize, and deploy a production‑ready ecommerce storefront that leverages Thor Commerce’s robust backend and AI coding agents’ speed.
Why it matters
A headless approach lets businesses tailor the shopping experience without compromising core commerce functionality, while AI agents accelerate development and reduce the risk of errors in critical payment and inventory logic.
Key points
- Thor Commerce separates backend commerce logic from the storefront, enabling flexible UI design.
- Typed GraphQL contracts and documentation give AI agents a reliable source of truth.
- The starter includes a reference implementation that demonstrates proper credential handling and cart persistence.
- Custom features like metafields can be added safely by following Thor’s contract‑first approach.
- Full purchase flow and failure‑path testing ensure a production‑ready storefront.
- Deployment requires careful review of environment variables and platform‑specific settings.
Frequently asked questions
What is the difference between Thor’s Admin API and Storefront API?
The Admin API handles server‑side operations such as product creation, pricing, inventory, and order management, while the Storefront API powers buyer‑facing features like product discovery, cart, checkout, and customer accounts.
Can I use Thor Commerce for both B2B and DTC sales?
Yes. Thor’s context‑aware commerce lets the same catalog serve different pricing, availability, and customer groups for B2B and DTC channels.
How do I keep my secrets safe when using an AI coding agent?
Store all credentials in environment files or your hosting provider’s secret store, never expose them with a NEXT_PUBLIC prefix, and avoid committing them to version control.
What platform can I deploy the Next.js storefront to?
The starter includes OpenNext and Wrangler configs for Cloudflare Workers, but you can adapt it to any Next.js‑compatible platform by adjusting country detection and environment variables.
