Anass Ez-zouaine — Senior Backend Engineer · Software Architect · AI Engineer — Shopify

Your quick-start guide to Shopify UCP: do this before June 15

Thu, 28 May 2026 00:00:00 GMT

Your store is effectively invisible to the biggest spenders of 2026. I'm not talking about Gen Z or Alpha. I'm talking about AI agents.

If Google Gemini or OpenAI's "Operator" can't find a machine-readable map of your Shopify store, it won't recommend your products. It definitely won't buy them.

Traditional SEO was built for humans with eyeballs. The Universal Commerce Protocol (UCP) is built for agents with wallets.

The rollout is moving fast. If you haven't configured your UCP manifest by June 15, you are opting out of the agentic economy.

Here is how to fix that.

Why your legacy SEO is failing

For ten years, we've obsessed over meta tags and JSON-LD schema. That was enough when Google was just a list of links. But we've entered the era of agentic commerce on Shopify.

Agents like Gemini don't "browse" your collections. They don't look at your hero banners. They want to know three things:

What do you sell?
Can I buy it right now?
Which API do I call to checkout?

If your site doesn't answer these questions in a standardized way, the agent moves to a competitor who does. Legacy schema tells an agent what a product is. UCP tells an agent how to transact.

What is the Universal Commerce Protocol?

UCP is an open standard backed by Google and Shopify. It creates a "handshake" between a merchant and an AI agent.

The core of this handshake is the /.well-known/ucp endpoint.

It's a simple JSON file that acts as a discovery manifest. When an agent hits your domain, it looks for this file to understand your capabilities. It's the robots.txt of the AI era, but for money.

Here is what a raw UCP manifest looks like:

{
  "ucp": {
    "version": "2026-01-11"
  },
  "role": "merchant",
  "capabilities": {
    "checkout": {
      "endpoints": {
        "create_session": "https://api.yourstore.com/ucp/checkout/sessions"
      }
    },
    "payment": {
      "handlers": ["shop_pay", "google_pay"]
    }
  }
}

This manifest tells the agent exactly where to send the payment data. No scraping required. No "guessing" where the add-to-cart button is.

How to enable UCP on Shopify

If you are running a standard Shopify or Shopify Plus store, the good news is you don't have to write this JSON manually. Shopify is baking this directly into the core.

But it isn't always on by default.

To ensure you're ready for the June 15 deadline, go to your Shopify admin. Navigate to Settings > Apps and sales channels. Look for Agentic storefronts.

Once you toggle this on, Shopify automatically generates and hosts the manifest at your-store.com/.well-known/ucp.

If you are running a headless setup with Hydrogen or a custom frontend, you'll need to ensure your middleware correctly proxies this path back to Shopify's servers. We see a lot of developers break their agentic discovery because their Vercel or Netlify rewrites aren't handling the .well-known directory.

The June 15 deadline: why now?

Why is everyone panicking about mid-June?

Google is moving "AI Mode" out of beta for a massive segment of search users. When Gemini becomes the default shopping assistant, it will prioritize stores that support the UCP handshake.

This is also when Shopify begins its wider rollout of MCP context-aware agents. These agents use the Model Context Protocol to link your store's live data directly into the LLM's reasoning loop.

If your manifest is missing, your store is a black box. The agent will see your products in the search index, but it won't be able to fulfill the request "buy me the best hiking boots from a local store." It will choose the store where it can verify the checkout capability instantly.

Auditing your implementation

Don't just flip a switch and hope. You need to verify that your manifest is actually reachable by external bots.

Open a private browser window.
Go to https://yourdomain.com/.well-known/ucp.
You should see a raw JSON object.
If you see a 404 or a redirect to your homepage, your theme or app is blocking the path.

Check your robots.txt file as well. Ensure you aren't accidentally disallowing agents from crawling the .well-known directory.

If you are using a custom Laravel backend to power your Shopify store's logic, make sure your routes file includes a specific entry for this endpoint. At ansezz, we often see custom middleware stripping out these hidden directories for "security" reasons. In 2026, that security is just costing you sales.

Technical takeaways

Here is your pre-June 15 checklist:

Enable Agentic storefronts in your Shopify admin.
Verify the /.well-known/ucp path returns valid JSON.
Ensure your payment handlers (Shop Pay, Google Pay) are correctly listed in the manifest.
Test your site with an agentic browser or a UCP validator tool.
Check your Coolify Docker SaaS hosting configs if you're hosting custom middleware, to ensure the path isn't being dropped by your reverse proxy.

The transition from a human-centric web to agent-centric commerce is happening whether we're ready or not. UCP is the first real step toward making your store a first-class citizen in the AI economy.

Are you letting agents shop your store, or are you still building for a world that clicks? Drop a note via contact — let's get your manifest live before the deadline. 🤘

Shopify Storefront Web Components: headless commerce for the rest of us

Tue, 19 May 2026 00:00:00 GMT

Headless used to mean hiring a team of six engineers just to show a "Buy" button.

If you wanted a custom Shopify experience outside of their Liquid-based themes, you were usually forced into a massive architectural decision. You had to build a full React or Hydrogen app, manage server-side rendering, handle complex routing, and pray your SEO didn't tank. For many startups and established brands, this was like buying a semi-truck when all they needed was a bicycle.

The complexity of traditional headless was a gatekeeper. It prevented simple content-driven sites on platforms like Astro or WordPress from easily selling products without a jarring transition to a subdomain. We've spent years over-engineering solutions for problems that could have been solved with a few custom elements.

Shopify Storefront Web Components have changed the math. Now, adding commerce to any site is as simple as dropping in a script tag.

The headless headache

Building a headless store often feels like building a house from scratch. You have to worry about the foundation (hosting), the plumbing (GraphQL queries), and the wiring (state management).

If you are a senior engineer, you know the drill. You spend weeks configuring Shopify Hydrogen or a custom Next.js setup just to get a cart that actually works. And once it's live, you're the one who has to maintain the Node.js environment and the middleware.

It's expensive. It's slow to deploy. And for 80% of use cases, it is total overkill. We need a way to get the flexibility of headless without the technical debt of a heavy framework.

Entering the era of custom elements

Shopify Storefront Web Components are framework-agnostic. They are standard Web Components (custom elements) that handle the heavy lifting of communicating with Shopify's Storefront API.

You don't need React. You don't need a build step. You just need HTML.

This "headless light" approach lets you embed products, collections, and a fully functional cart directly into your existing stack. Whether you are using a static site generator or a legacy CMS, these components act as bridge-builders. They let you keep your content where it is and pull the commerce in dynamically.

How to get started in 5 minutes

Getting these up and running is refreshing for any developer used to complex APIs. Here is the workflow I use when I want to move fast.

1. Connect your store

The first step is adding the script tag and the <shopify-store> component to your HTML. This establishes the connection to your Shopify domain.

<script src="https://webcomponents.shopify.dev/components.js"></script>

<shopify-store store-domain="your-store.myshopify.com"></shopify-store>

If you need inventory counts or custom data, add a public-access-token from the Shopify headless channel. For basic title and price display, you don't even need that.

2. Define the context

The magic happens with <shopify-context>. This tells the page which product or collection it should be looking at. You just pass the handle from your Shopify admin.

<shopify-context type="product" handle="awesome-tshirt">
  <template>
    <!-- your content goes here -->
  </template>
</shopify-context>

3. Display the data

Inside that template, you use <shopify-data> to pull specific fields. It uses dot notation, making it feel very familiar to anyone who has worked with Liquid or JavaScript objects.

<shopify-data query="product.title"></shopify-data>
<shopify-money query="product.variants.first.price"></shopify-money>

The secret sauce: llms.txt

Here is the part where it gets interesting for modern developers. Shopify has released a specific llms.txt file.

If you've been following the rise of agentic workflows and vibe coding, you know that providing context to an AI model is everything. By pointing your AI agent (like Claude or ChatGPT) to this text file, it learns exactly how to write code for these specific Web Components.

This eliminates the hallucination problem. Instead of the AI guessing how a Shopify component should look, it uses the official spec. I've found that including this link in my system prompt lets me generate entire product landing pages in seconds that actually work on the first try.

It turns "development" into "orchestration." For more on how to leverage these tools, check out how MCP context-aware agents are changing the way we handle technical docs.

When to use Web Components vs Hydrogen

As a senior engineer, you have to pick the right tool for the job. Here is my rule of thumb.

Use Storefront Web Components if:

You have an existing marketing site and want to add "buy buttons" or a mini-cart.
You are building a landing page and need speed above all else.
Your team doesn't want to maintain a React/Node.js infrastructure.
You want to stay framework-agnostic.

Use Shopify Hydrogen if:

You are building a mission-critical, full-scale custom storefront.
You need complex server-side logic and deep integrations with multiple APIs.
You require the absolute highest level of performance optimization via streaming and edge rendering.

For most people starting out or modernizing a digital presence, Web Components are the winning choice. They offer the best balance of AI-driven development and production stability.

Takeaways for the modern dev

Web Components are the "headless light" solution we've been waiting for.
They work anywhere — WordPress, Astro, plain HTML, or even a local static file.
Use the llms.txt file to train your AI assistant for perfect code generation.
Avoid over-engineering — if you don't need a massive React app, don't build one.

Building for the web in 2026 is about reducing friction. Shopify has finally removed the friction from headless.

Are you still building full React apps for simple stores, or are you ready to embrace the simplicity of custom elements? Drop a note via contact — I love this conversation. 🤘

Why agentic commerce will change the way you build Shopify stores

Mon, 18 May 2026 00:00:00 GMT

Your beautiful Shopify theme is about to become invisible.

For a decade, we have obsessed over conversion rate optimization, pixel-perfect layouts, and fast-loading Liquid templates. We built for human eyes. But a new type of shopper is arriving at the digital storefront. They don't have eyes, they don't click buttons, and they certainly don't care about your hero slider.

They are autonomous AI agents.

The shift from human-centric browsing to agentic commerce is the biggest architectural pivot Shopify has ever seen. If you are still just "the theme guy" or "the Liquid expert," your skillset is about to hit a massive wall. I have been building on the web for over ten years, and I can tell you that the era of building for agents is here. It is time to move from designing pixels to designing protocols.

The problem: the end of the traditional funnel

Most developers are still stuck in the old way of thinking. We build a site, drive traffic to a landing page, and hope the user navigates to the checkout. This is a manual, high-friction process.

Today, buyers are increasingly using tools like ChatGPT, Gemini, or Microsoft Copilot to do the "work" of shopping. They ask for a waterproof hiking boot under $150 with specific shipping requirements. The AI doesn't visit your store to browse. It queries data. If your store isn't built to be "read" by an agent, you simply don't exist in that transaction.

The agitation: why your current apps aren't enough

We have spent years building "utility" apps that handle simple automations. But Shopify is moving fast to pull those features into the core. With tools like Shopify Magic and Sidekick, the basic stuff — copywriting, image editing, simple workflows — is being commoditized.

The real value is moving deeper into the stack. Agents need more than just a product description. They need structured data, real-time inventory logic, and a way to execute a checkout without a browser window. If you are relying on "fake" variants or messy metafields, you are breaking the agent's ability to reason about your store.

When an agent fails to understand your product structure, the buyer gets a "no results found" or a hallucinated alternative. That is a lost sale for your client and a failed project for you.

The solution: welcome to agentic commerce

Agentic commerce is a system where AI agents take over the discovery, comparison, and execution phases of shopping. Shopify is already laying the groundwork for this with three major pillars:

Shopify Catalog — a centralized layer that broadcasts your structured data to AI platforms.
UCP (Universal Commerce Protocol) — a standard developed with companies like Google to allow agents to handle the entire journey, from discovery to cart and order.
Agentic Storefronts — a layer that packages your catalog and checkout into a form AI agents can consume programmatically.

As developers, our job is shifting. We are no longer just building visual storefronts. We are building "agent-ready" infrastructure.

Why schema is the new CSS

In the agentic era, your structured data is your most important asset. A perfectly optimized JSON-LD schema or a clean set of Shopify Metaobjects is now more valuable than a fancy hover effect.

Agents rely on clarity. They need to know if a product is compatible with another, what the specific material breakdown is, and exactly when it will arrive. If you want to see how I've helped businesses modernize their digital presence through better architecture, check out some of my previous work.

The focus for developers must move toward:

Native variants only — stop using "split products" or custom Liquid hacks to show variants. Agents need standard ProductVariant records to function.
Rich Metaobjects — use these to build knowledge bases that agents can query. Think compatibility tables, brand story, and detailed technical specs.
GraphQL mastery — the Shopify Admin and Storefront APIs are the primary languages of agents. If you aren't comfortable with complex GraphQL queries, you are already behind.

Building custom agents with MCP and Shopify

The most exciting part of this shift is building our own agents. The Model Context Protocol (MCP) allows us to connect AI models to external data sources like the Shopify API.

Imagine building an "inventory agent" for a merchant that doesn't just alert them when stock is low. Instead, it queries recent sales trends via the Admin API, checks lead times from a supplier, and suggests a restock amount — all through a chat interface.

This is where tools like Laravel and Docker come in handy. We can build custom middleware that acts as an MCP server, exposing specific Shopify "tools" to an AI agent. This is the type of deep technical work that differentiates a senior engineer from a freelancer who just installs themes.

The Shopify developer's new roadmap

To thrive in the next five years, I recommend focusing on these specific technical areas.

1. Data hygiene as a service Start offering "agent-readiness" audits. Clean up product data, normalize attributes, and ensure all metadata is machine-readable. This is the new SEO.

2. Headless and API-first builds While Liquid isn't dead, headless architectures using Hydrogen and Oxygen are much more aligned with the agentic future. They force you to think in terms of data and APIs rather than just templates.

3. RAG and vector databases Learn how to use RAG (Retrieval-Augmented Generation) and tools like pgvector. This allows you to build agents that can search through thousands of product reviews or support docs to provide "expert" advice to shoppers.

4. Focus on the "agentic plan" Shopify is rolling out levels of agentic integration. Stay ahead by understanding how to implement Level 3 — where your store is fully AI-native and provides direct API access for agents to build carts and checkout.

Final takeaways for the agentic shift

The change is happening faster than most of us realize. By 2026, AI-driven traffic will be a double-digit percentage of total orders on major platforms.

If you want to stay relevant, here is your checklist:

Move your product logic into native Shopify structures.
Double down on GraphQL and API integration.
Start experimenting with MCP servers and local LLMs for internal store operations.
Remember that the agent is your new "user." Optimize for its understanding first.

We are moving into a world where commerce is autonomous and frictionless. It is an incredible time to be a developer if you are willing to learn the new protocols. If you want to learn more about my background in high-quality web applications, you can read more about me.

The question is — are you building a store that only humans can see, or are you building a store that the whole world can buy from?

Are you ready to start building your first AI-native Shopify tool, or are you still holding onto your CSS hacks? Drop a note via contact — I love this conversation. 🤘

Shopify Liquid vs. headless: choosing the right stack for scale

Sun, 28 Dec 2025 00:00:00 GMT

Your store is making money, but every new change feels like surgery on a moving car.

Traffic is up. Orders are up. Pressure is up. But the theme layer is starting to fight back. Simple feature requests turn into fragile hacks. App scripts pile up. Mobile performance gets softer with every install. What used to feel fast and convenient now feels like a ceiling.

This is where a lot of brands start looking at headless. The promise sounds great. More freedom. Better performance. Cleaner frontend architecture. But this is also where expensive mistakes happen. A headless rebuild can solve real problems — or create a second system your team now has to babysit forever.

The real question is not which stack sounds more modern. The real question is which stack fits your stage, your team, and your operational reality.

The Liquid reality: why it still wins for most stores

Liquid is still the default winner for a reason. It is tightly integrated with Shopify, fast to ship, and much easier to maintain than a custom headless frontend.

For most growth-stage stores, Liquid gives the best speed-to-market. Online Store 2.0 made theme architecture much more modular than the old days, so a solid theme setup can go a long way before it becomes a real blocker.

This is the part people underestimate. A good Liquid stack is like a well-tuned production van. It is not flashy, but it moves product reliably, gets updated quickly, and does not need a pit crew every week.

The problem shows up when business needs outgrow theme constraints. Maybe the storefront needs deeply custom interactions. Maybe product data has to come from an ERP, a PIM, and a custom backend at the same time. Maybe merchandising logic is getting too complex for theme code to stay clean. That is usually the point where headless becomes a serious conversation, not just a trendy one.

Performance is the primary driver

Performance is the most common reason teams start looking at headless. And yes, milliseconds matter. On e-commerce storefronts, small delays compound into lower conversion rates, weaker ad efficiency, and a worse mobile experience.

A well-built headless stack using Hydrogen and Oxygen can push performance much further than a typical theme setup. You get finer control over rendering, data loading, caching, and frontend execution. That opens the door for lower LCP and a more responsive storefront.

But this is where the hype needs a reality check. Headless does not automatically mean faster. It only gets faster when the frontend architecture is actually good.

If the team over-fetches GraphQL data, hydrates too much JavaScript, or ships a bloated component tree, the custom storefront can end up slower than a decent Liquid theme. That happens more often than people admit.

So yes, headless can be a performance win. But only if the implementation is disciplined.

The hidden complexity of going headless

Going headless means splitting commerce from presentation. Shopify still handles products, checkout, and admin workflows. Your custom frontend handles the customer experience.

That sounds clean on paper. In practice, it means you now own two systems instead of one.

You need to manage hosting, deployments, caching, GraphQL queries, error handling, observability, and integration behavior across services. Every app in the stack has to be checked for API compatibility. If an app only works by injecting snippets into a theme, that convenience is gone.

This is the part that catches teams off guard. In Liquid, many features feel plug-and-play. In headless, the same features often become custom integration work. Reviews, loyalty, search, subscriptions, personalization, analytics. All of it may need extra engineering.

The easiest way to think about it is this: Liquid is renting a well-equipped shop. Headless is designing your own building. You get more freedom, but now plumbing, wiring, and maintenance are your problem too.

Time and money: the real cost of freedom

Time and budget usually decide this faster than architecture opinions do.

A custom Liquid theme can often be launched in weeks. That means faster testing, faster iteration, and lower implementation cost. If the business mainly needs merchandising flexibility, better UX, and cleaner performance hygiene, Liquid usually gives a better return.

Headless is a different category of investment. The build takes longer. The team needs stronger frontend engineering. The integration surface is bigger. And maintenance does not stop after launch.

This is the important part. With headless, you are not just paying for a redesign. You are taking on a software product that needs ongoing care. Deployments, monitoring, API changes, dependency updates, caching strategy, and developer ownership all become part of normal operations.

For many stores, that trade-off is not worth it yet. More freedom is great, but freedom is expensive when the business does not fully need it.

My decision framework: which one should you choose?

I like to reduce this decision to a few practical questions.

Is the current theme actually blocking revenue? If conversion is healthy and the main pain is taste or minor flexibility, Liquid is probably still the right call.
Does the team have the engineering depth to own a custom storefront long term? Headless is not a one-time build. It is an operating model.
Are the integration requirements genuinely complex? If the storefront needs to combine Shopify with custom product logic, external systems, or a bespoke application layer, headless starts to make more sense.
Is performance a code problem or an architecture problem? Many slow stores do not need headless. They need script cleanup, better image handling, less app bloat, and tighter theme code.

The simplest stack that solves the real bottleneck is usually the best stack. Building a spaceship to cross the street is still a bad decision.

Practical takeaways for your next move

If you are stuck between Liquid and headless, start here:

Audit site speed before making architectural decisions. If LCP is acceptable, the problem may not be the stack.
Remove app bloat. A lot of slow Liquid stores are just carrying too many scripts and too much leftover code.
Map every integration. List what works natively, what depends on theme injection, and what would break in headless.
Estimate ownership cost, not just build cost. Launch is only the first invoice.
Look at Hydrogen if the business really needs headless — but keep the scope tight.

Choosing a stack is a long-term commitment. The right answer is not the most advanced one. It is the one that solves the current bottleneck without creating three new ones.

Are you dealing with real technical limits in Shopify, or just feeling the pull of a more customizable stack? Drop me a line — happy to do a 30-minute architecture sanity check.