Alessandro Desantis

Alberto Vena

Shopify has spent years building one of the most extensible commerce platforms available. You can customize the checkout. You can inject logic into Shopify’s pricing and discount engine via Functions. You can build UI components that render natively inside the admin. You can run a full custom app that talks to every corner of the platform.

What Shopify didn’t build, to anywhere near the same degree, is an automated testing toolchain.

With Shopify moving ever more aggressively into the enterprise segment, that gap matters more than it used to. A complex Shopify build today may span any of the following:

- **Shopify theme:** Liquid templates, section schemas, and increasingly complex rendering logic that runs in Shopify’s CDN and is never in your hands at runtime.
- **Shopify Functions:** business logic that compiles to WebAssembly and runs inside Shopify’s infrastructure (pricing rules, discount logic, payment method filtering).
- **UI Extensions:** React components that render inside the checkout, the order status page, or the Shopify admin, inside an iframe you don’t control.
- **Custom app(s):** good old web applications that may receive and respond to webhooks from Shopify, render Liquid or Admin UI via the App Proxy, and anything else that doesn’t fit in Shopify’s existing extension points.

For each of these layers, automated testing requires different tools, poses different constraints, and calls for different workarounds. Shopify offers some testing solutions in their documentation. Others, we’ve had to figure out ourselves.

Let’s take a look at the state of the art, shall we?

## Testing Shopify Themes

Shopify has no official testing framework for themes. No test runner, no test helpers, no fixture system.

Our main approach is to run Playwright against a preview theme. The workflow: when a PR is opened, we generate a preview theme from the live theme, run Playwright against it (accessibility and performance checks, end-to-end purchase flows, and anything else we need), and require all the checks to pass before the PR can be merged.

It works, with a couple of constraints:

- The main constraint is that you can’t alter the Shopify store’s state before running the tests, as that would alter your production configuration. For example, if you need to verify behavior that depends on a specific product configuration, that product needs to already exist in the store when the test runs. If it doesn’t, you can’t test the scenario.
- You cannot easily test the Shopify checkout, as that would require placing a real order with a real credit card. For some clients, we have done this with virtual cards and a Shopify Flow that auto-cancels any test orders coming from specific email addresses, but it’s a cumbersome solution.

A possible solution to both problems is to run the tests against your staging store rather than the production one. That comes with its own issues, which we walked through in [our video on staging-production parity](https://www.youtube.com/watch?v=-zNSIuhg1Wg).

For snippets with significant branching logic, Playwright wasn’t enough. So we built [`minitest_shopify_themes`](https://github.com/nebulab/minitest_shopify_themes), an experimental library that renders Shopify theme snippets and sections in isolation using Minitest and Capybara. You pass in data fixtures directly rather than depending on store state, which means you can test dozens of combinations quickly and deterministically. Check it out!

We’re calling it an experiment because that’s what it is: it works well for what it covers, but dynamic blocks and inter-snippet rendering don’t behave correctly in a test environment, and since Shopify doesn’t officially support this approach, there’s no guarantee it stays viable as the platform evolves. We use it selectively: Playwright as the base, `minitest_shopify_themes` for snippets where the logic branches enough that combinatorial coverage is worth the investment.

## Testing Shopify Functions

For Shopify Functions, testing is a much gentler beast to tame.

Much of it is a result of the underlying architecture. Shopify Functions compile to WebAssembly and run as pure functions: they receive a GraphQL input, produce a GraphQL output, and have no access to network or external state (unless you’re one of the very few Shopify Enterprise customers with network access). Because of this, there’s nothing to mock. The whole function is its own test fixture.

This means you can import a Function directly into a test file and call it like any other JavaScript function. Write your input, assert against the output. We run these tests across all extensions from a single `npm run test` command at the project root, and they gate deployments in CI: if a Function’s tests fail, the build doesn’t ship.

Furthermore, Shopify provides a type generation tool (`typegen`) that generates TypeScript types from your GraphQL query. The practical effect is autocomplete and compile-time checking against Shopify’s actual schema, which catches structural mismatches before they reach production.

The one limit to keep in mind is that this approach doesn’t tell you whether the Function will behave correctly against your real Shopify data in your real Shopify store. For testing Shopify Functions in integration, you can either use Playwright or exercise your store’s Storefront API.

## Testing Shopify UI Extensions

UI extensions that alter the checkout, customer account, or admin panel all run in Shopify-served iframes. You can’t control the context in which they run, and Shopify does not provide an official testing path for these either. So we are back to building our own, though the shape of the answer differs from themes.

Playwright covers the happy path. Where extension logic branches, we mock Shopify’s extension library APIs at the module level, using global mocks that let extension code run in isolation from the Shopify host. That is what buys us coverage on the conditional rendering Playwright can’t reach without a real order sitting in a real checkout.

The risk is that the mocks rot. Shopify changes an API, our mock keeps returning the old shape, and the suite goes green against behavior that no longer exists. That is worse than having no test at all: a failing test gets fixed, while a test that passes for the wrong reason ships a broken extension and tells you the build is fine.

Ultimately, there’s no good answer here. You’re picking which way you’d rather be wrong: fewer tests and thinner coverage, or more tests and the chance that some of them are lying to you.

We pick the second and keep Playwright around to catch the lies. Smoke tests run against the real host, so they’re the only thing that spots the drift. Unit tests sit on top and buy coverage on the branches. Drop the smoke tests and you’re trusting your own fiction about how Shopify behaves.

## Testing Custom Shopify Apps

Because they sit outside the Shopify runtime, custom apps are typically the easiest part to test: just use whatever test tooling is offered by your language or framework of choice. For us, that’s usually RSpec for Ruby on Rails or Vitest for Next.js and Nest.js.

That said, a couple of caveats still apply.

**The first one has to do with webhook versioning.** Shopify webhooks carry the payload structure from the API version configured in your app, and your test fixtures are written to mirror that structure. When you upgrade API versions, which Shopify requires as it deprecates older ones, your mocked payloads can silently diverge from what Shopify now sends. The tests keep passing against payloads that no longer reflect reality, right up until a live order arrives and the app chokes on a field that moved. Catching this takes deliberate attention at every version bump: pull up the webhook fixtures, check them against the new version’s schema, and update anything that changed. Ask us how we know.

**The second caveat is about App Bridge,** Shopify’s JavaScript SDK for building native admin UI inside your app. App Bridge relies on the Shopify admin’s iframe context to authenticate and render, and that context cannot be reproduced in a test environment. The most reliable approach we’ve found is to move all business logic out of the App Bridge components and test that logic on its own. App Bridge then becomes a thin presentation layer, and the code worth testing lives underneath it. If logic and presentation are already tangled together inside your App Bridge components, pulling them apart is expensive, but there is no other route to decent coverage.

## The Integration Layer That Doesn’t Exist

Unfortunately, there’s a harder problem underneath all of this, and no tool currently solves it.

Each layer can be tested, in varying degrees, with the approaches above. What can’t be tested reliably is how all the layers behave *together*. A Function modifies cart line items. A checkout extension reads those line items to determine what to display. The theme renders an element that reflects the extension’s output. The app records the resulting order event. Test each layer in isolation and all four pass. Whether they compose correctly under real conditions, with real data, in a real checkout… well, that’s a different question.

This is the classic problem of distributed systems testing: individual components can be correct while the system as a whole is still wrong. Shopify’s ecosystem is vast and compositional by design. That’s the point of it. But composability and testability pull in opposite directions, and in a stack this distributed, full integration testing is slow, fragile, and expensive to maintain, and often prohibitively so.

How do you solve this problem, you ask? Well, you don’t. You just manage it.

What we’ve found helps:

- Monorepos for your code, so that changes across layers can be merged and deployed atomically.
- Contracts between layers, written down: what does this Function guarantee about the shape of its output?
- Change management discipline, so that a change in one layer reaches whoever owns the layers downstream of it.
- An end-to-end smoke suite covering the highest-stakes paths: add to cart, checkout, order confirmation.

## What Good Looks Like on a Shopify Stack

If you come from a more structured software engineering or digital product background, this is the part that stings: full coverage of a Shopify stack simply isn’t on the menu. That’s not a failure of your team. It’s a structural property of a platform where much of your code runs on someone else’s infrastructure, in a context you can’t reproduce.

So the goal moves. You aren’t chasing a coverage number anymore. You’re deciding, deliberately, where you’re exposed and whether you can live with it.

On the teams where this works well, three things tend to be true. Everyone can say how well each layer is covered and where the thin spots are, so nobody reads a green build as a safe deploy. The code is written so it can be exercised in isolation, with business logic kept away from rendering and rendering kept away from Shopify. And somebody has gone to the trouble of mocking Shopify’s primitives for the parts that look untestable, which, with AI writing most of the mock, is a far cheaper thing to attempt than it was two years ago.

None of this gets you to full coverage. It gets you to knowing exactly which parts of your store you are shipping on faith.

And if this is the kind of problem your team is working through, [we’d be glad to talk about it](https://nebulab.com/contact-us).

How We Test Enterprise Shopify Stores

Massimiliano Lattanzio

Nicolò Rebughini

Most Shopify planning conversations contain a moment that goes by too fast. The team has spent two hours on checkout customization, catalog structure, and storefront performance. Then, fifteen minutes before the meeting ends, someone asks: "and what about the customer account area?" The decision deserved an hour. It gets five minutes, ends with "we'll go custom" or "Shopify's accounts are fine," and the consequences show up eighteen months later when retention numbers don't match the deck.

The decision keeps biting because most teams frame it the wrong way. They ask "what can we customize?" when the question that matters is "does our retention depend on this?" The first is a feature comparison. The second is a business-model question, and the right customer-portal architecture follows almost entirely from it.

This year the decision is also happening at a forcing moment. Shopify [deprecated legacy customer accounts in February 2026](https://shopify.dev/changelog/legacy-customer-accounts-are-deprecated) and will announce a final sunset date before the year is out. Brands that picked an architecture in 2022 are reopening the choice whether they planned to or not.

If you're going to reopen it, reopen it correctly.

## The decision people get wrong

The most common mistake is choosing a custom build because the brand team wants control over the visual experience of the account page. It's a reasonable instinct. Most luxury and premium brands operate on the principle that every touchpoint should feel like the brand.

But brand fidelity on the customer account page is not, on its own, a sufficient reason to take on a perpetual maintenance contract.

On one luxury engagement, we walked the client away from a custom build whose only real justification was branding. The reason is operational, not philosophical. A custom portal is a second application your team owns. It has to be deployed, monitored, patched, and updated every time Shopify ships a primitive that matters or an upstream app changes its API. The cost of those updates compounds. Two years in, the maintenance bill usually outweighs the gap between the bespoke UI and what Shopify's design system could have delivered.

## The four architectures

The maintenance argument isn't an argument against custom builds. It's an argument for choosing on operating cost and business fit rather than on visual control. Four architectures are available on Shopify today, and they differ less in what they can do than in what they cost to run and what kind of business they suit.

One caveat before the tour. These four are rarely mutually exclusive in practice. Plenty of stores run native accounts for orders and addresses, hand subscriptions to Recharge's portal, and bolt on a single custom page at `/apps/`. The real question is usually not which architecture you use, but which one owns the primary surface and how much of the experience you're willing to let the others define.

### Shopify Customer Accounts with UI extensions

Shopify hosts the portal and renders it. You extend it with UI extensions, the same model checkout UI extensions established: app blocks on the order index, order status, and profile pages, plus full pages of your own inside the account area.

<figure>
  <img src="https://cdn.sanity.io/images/kqgmf0g2/production/83b029500d7b7e40498513ec3986255954318df6-3054x1548.png?fit=clip">
  <caption>The Customer Account portal with some custom blocks</caption>
</figure>

What you get is everything Shopify ships, without your team touching it: passwordless login via Shop Pay, native order tracking, self-serve returns, address management. Apps that have built UI extensions plug in without integration work.

What you accept is the design system. Polaris-grounded layout, no CSS override, no bespoke interaction patterns. You ship features at the pace of Shopify and whichever app vendors are building extensions for the area you care about.

This is the right answer for most brands, especially brands where the post-purchase moment is transactional: a customer comes in, checks an order, updates a card, leaves. The native experience does that well, and it improves every quarter without your team writing a line of code.

### App-based portal

Many of the apps your store already runs ship their own customer-portal UIs (e.g., Recharge, Loop). You can drop them in as embedded pages or theme blocks, point your customer there, and let the vendor handle the rest.

<figure>
  <img src="https://cdn.sanity.io/images/kqgmf0g2/production/6426d83b66f28ee54d2d46b860280e2a550c0651-3054x1992.png?fit=clip">
  <caption>An example of the Customer Portal offered by Loop, a popular subscriptions app. Everything is configurable from the app itself, without the need for custom integrations</caption>
</figure>

What you get is speed. No build, no infrastructure, and a surface each vendor keeps current on your behalf.

What you accept is fragmentation. A customer at a typical mid-market DTC brand running three of these apps learns three sidebars, three navigation models, and sometimes three login flows just to manage one relationship with the brand. Each app vendor is a competent designer for their own surface. Together they're a patchwork. You can paper over some of the visual difference with theming, but the interaction patterns aren't yours to set.

The app-based approach is right when one app handles most of what customers do in your portal. A subscription business where the subscription app carries 80% of the activity can live with this. A brand where post-purchase activity is spread across three apps usually can't.

### External custom portal

The external approach is a standalone web application (your own Rails, Next, or whatever stack) running on a subdomain like `account.brand.com`. 

It authenticates against Shopify via the Customer Account API and integrates with subscription, loyalty, returns, and other vendors through their APIs. The portal lives outside the theme entirely.

<figure>
  <img src="https://cdn.sanity.io/images/kqgmf0g2/production/596588599489991f20af764f6fd490ad424dad89-3054x1992.png?fit=clip">
  <caption>The custom customer portal we built for Cometeer. It connects with Recharge APIs to manage subscription data and exposes several custom-built functionalities, including a bespoke coffee box management experience powered by their proprietary recommendation algorithm.</caption>
</figure>

What you get is total freedom. No design ceiling, no platform conventions to inherit, no Liquid object shapes to reconstruct. The information architecture is yours, the performance characteristics are yours, every interaction is yours.

What you accept is the cost of running another application: deploy, monitor, secure, scale. Every integration depends on an API surface someone else controls. If Recharge sunsets an endpoint or Loop changes a payload, you adjust.

Take Cometeer as an example. We built their custom portal because their business needed it: subscription management with a bespoke recommendation algorithm, churn flows tuned to their economics, and a native mobile app. Recharge's stock portal was too slow and too rigid for the standard they held themselves to. [The Cometeer case study](https://nebulab.com/case-studies/cometeer) covers what the engagement looked like.

### Embedded custom portal

The embedded approach builds a custom portal that lives inside your storefront, served from your own domain. Mechanically, you build a Shopify app exposed via app proxy at a path like `/apps/account/`. When a customer hits that path, Shopify forwards the request to your app, which returns either JSON (your theme's JavaScript renders the response) or Liquid (Shopify renders it server-side, and the Liquid can call snippets already in your theme).

The Liquid path is the one most teams haven't seen, and it's the reason to pick this architecture. It lets the portal render with the same components the rest of the storefront uses. Your store locator, your product card, your typography: all of it stays in one place, applied consistently to a custom account experience.

<figure>
  <img src="https://cdn.sanity.io/images/kqgmf0g2/production/8975c51a684cd68270e4b6e8bedd918f8974be4a-2336x2106.png?fit=clip">
  <caption>The plan management screen from the portal we built for DogHeroes, where customers switch between dogs and adjust the food plan for each one. The layout, typography, and components come from the theme itself.</caption>
</figure>

What you get is theme parity. A custom experience that inherits the storefront's components and content instead of reimplementing them.

What you accept is the same infrastructure burden as the external option: the Shopify app still has to be deployed, monitored, patched, and maintained against an evolving platform.

Take DogHeroes as an example. Their portal is a Rails app sitting behind an app proxy at `/apps/paws/`, so a customer who opens `/apps/paws/subscriptions` never leaves the storefront. Rails handles authentication and the subscription data, then answers with Liquid that calls snippets kept in the theme itself, named `dogheroes--portal--*.liquid`. Shopify renders the result. The plan management screens look like the rest of the store because they are built from the rest of the store.

This earns its place when you need a custom portal and you need it to reuse pieces already in the theme: a store locator, a configurator, a content section that powers part of the storefront experience.


## The questions you should actually ask

Polaris and UI extensions can replicate almost any account-page UX a brand can describe, if you spend the engineering hours. Whether those hours move your business is a different question, and it's the one that belonged at the top of the agenda.

The shortest test we know: ask what a customer does in your account area and how often. If the answer is "checks an order, updates a card, redeems points twice a year," native is fine. The ceiling on what you can build there is largely irrelevant to whether they come back.

If the answer is different, if your retention loop runs through the account page, if customers spend real time there managing subscriptions, reconfiguring upcoming orders, working through churn-prevention flows, learning a complicated product, then every step of friction you remove compounds.

For most brands the account page is a service surface. For a few, it's the room the customer lives in.

Which one you're running settles the architecture, and it comes down to four questions:

1. **Does the customer-portal experience materially affect retention, or is it a transactional necessity?** If it's transactional, stop here: native accounts, or an app portal if one vendor already owns the surface. If it's material, keep going.
2. **Is one app responsible for more than 80% of customer-portal activity?** If yes, app-based stays honest even at the material end. If no, fragmentation will hurt and keep hurting, and you're building something custom.
3. **Do you need to reuse anything already in the theme, like components, content, or configurators?** Yes: embedded. No: external is simpler.
4. **Do you have, or want, a mobile app within two years?** If yes, weight external more heavily than question 3 suggests. The portal's API layer is also the mobile app's API layer, and an external build gets you there with less rework.

## Build the portal your business model needs

The right portal isn't the most flexible one or the cheapest one. It's the one that matches your brand's value proposition.

If you're sitting on this decision now, building a new store, reworking the one you already run, or revisiting a portal that hasn't aged well, [we can help you make that call](https://nebulab.com/contact-us).


Standard vs. Custom Account Portals in Shopify: How to Choose

Every six months, Shopify ships an Edition. And every six months, our clients ask us the same thing: *So what's in it for us?*

It's a reasonable question. Roughly 150 updates ship in every Edition, and the average brand only needs to care about a handful of them.

But this time, if you step back from those 150 updates and look at the bigger picture, a pattern emerges: for two decades, Shopify has been selling you the software you needed to build the best possible e-commerce website.

This Edition is the strongest sign yet that they are now ready to turn into the digital commerce layer that powers the entire World Wide Web.

For DTC brands, that's both good news and bad news. Here's why.

## Your Catalog Is Now Our Catalog

When Shopify entered the agentic commerce race, they did so with their usual strategy: a new discovery channel was just emerging, and they wanted to be front and center, enabling their merchants to succeed in this new world. To accomplish this, they partnered with the major AI platforms (ChatGPT, Copilot, Perplexity) to syndicate each merchant's product catalog and, in some cases, allow direct checkout.

The technical approach included a few false starts, but ultimately it involved partnering with Google to release UCP (Universal Commerce Protocol), a protocol that enables LLMs (or any third-party system, for that matter) to seamlessly browse a merchant's catalog, manage a persistent cart, and check out. I will spare you the technicalities of the protocol, but if you're curious, I recently published [a more detailed breakdown](https://www.linkedin.com/posts/alessandro-desantis_ecommerce-ai-shopify-activity-7416461741892734976-2fjP/) of UCP and what makes it so cool (and better than OpenAI's ACP, in my humble opinion).

Back then, we speculated that this created the potential (and the danger) for the entire Internet to turn into a giant Amazon, where every single product on Earth is just one prompt away. The theory went that, due to the very nature of conversational shopping, this may allow an entire long tail of brands to emerge and compete with the incumbents without having to match their gargantuan marketing budgets. At the same time, we also speculated that this may lead to the decline of the DTC storefront, especially in some of the more commoditized categories.

These were very long-term bets, and we're still waiting to see how they play out. So far, it's turned out that the tricks that make a brand surface in AI conversations are very similar to the ones that make brands surface on Google, Meta, and all the other channels we already know and love. As for the demise of the DTC website, even though we work with tens of brands in eight- and nine-figure territory, we do not have a single client for which AI sales make up more than 0.5% of online GMV (if you exclude Shop, which Shopify disingenuously rolls up into their Agentic dashboard—more on that below).

However, what *has* changed with this Edition is that Shopify has made its entire merchant base more accessible and omnipresent than ever. In addition to syndicating their merchants' products to all the usual suspects, anyone can now integrate with the Catalog MCP, Cart MCP, and Checkout MCP (the three modules that make up the UCP specification) to build a full-fledged shopping experience powered by Shopify's infrastructure.

While they were at it, [Shopify also strengthened the Catalog MCP](https://shopify.dev/docs/agents/catalog/global-catalog-extension) with:

- Image and similarity search (both pretty self-explanatory).
- Offers from multiple sellers. The same product can be offered by multiple Shopify stores, each with its own listing.
- Affiliate placements (invite-only). By opting into the feature, platforms can surface paid placements in the search results and receive a commission on sales.

To show how some of the new functionality could be used in the wild (and, I guess, to let their dev team have some fun), Shopify released a few cool demos to go with it:

- [All Set](https://www.shopify.com/editions/demos/all-set), where you can tell an AI about your trip and get product recommendations.
- [Sourced](https://www.shopify.com/editions/demos/sourced), where you can upload a picture and buy the products in it.
- [Showroom](https://www.shopify.com/editions/demos/showroom), where you can buy the products featured in your favorite movies and TV series.
- [Starred](https://www.shopify.com/editions/demos/starred), where you can get product recommendations based on your daily horoscope.
- [Pippin](https://www.shopify.com/editions/demos/pippin), where the 21st-century version of Clippy gives you board game recommendations.

I encourage you to check them out, because they're really fun!

## The Shop App and the Buyer Identity Play

If the agentic infrastructure is the plumbing, Shop is where it becomes something a consumer can actually interact with. In this Edition, Shopify has improved the app in several ways.

First of all, Shopify is exposing new surfaces within the Shop app to help consumers discover the products they're looking for. This includes:

- Merchandised categories, curated both by Shopify and by third parties (e.g., [Selleb](https://www.selleb.com/)), that showcase select products and brands.
- [Shop Minis](https://shop.app/minis), third-party mini-apps that run within Shop and create new ways for the consumer to engage with the ecosystem (e.g., recipe trackers).
- The [Shop skill](https://shop.app/skill), which allows consumers to easily connect the Shop universe to an LLM/harness (e.g., Hermes, OpenClaw).

But the more interesting development, if you ask me, is how Shopify is starting to integrate Shop within the rest of its ecosystem.

Thanks to the years it has spent evolving the Shop app and pushing Shopify merchants to enable Shop-based sign-in in their storefronts and checkouts, Shopify is now sitting on what is probably (after Amazon's) the largest consumer identity graph in the digital commerce industry. They are now starting to activate that data in pretty interesting ways.

More specifically, Shopify has announced that the Catalog MCP will soon support [personalized searches.](https://shopify.dev/docs/agents/catalog/global-catalog#personalized-search) As long as you authenticate users via Shop (which you can now do even outside of a Shopify site), you can pass a buyer-linked token when making requests to Shopify's catalog. When that happens, the search results will be personalized according to the information Shopify has about the buyer's preferences and behavior.

What would be incredible—and this is a very long shot—is if merchants could leverage that same data on their storefronts as well. How cool would it be if you could have your customers authenticate via Shop and use Shopify's identity graph to seamlessly surface personalized collections and search results? Given the privacy issues involved and the architectural limitations of merchandising in Online Store (we have an article coming out about this soon), I don't see this coming any time soon—but hey, a man can still dream.

With these features and improvements, Shopify has turned Shop into the *de facto* demo for what can be accomplished with their catalog. In fact, I wouldn't be surprised if the Shop app had been recently rewritten, at least in part, to use the new UCP specification rather than Shopify's internal APIs, so that it can serve as a sort of reference implementation for the new capabilities.

## How Should Merchants Feel About All This?

For two decades, Shopify has told its merchants that it had no plans of becoming a marketplace (despite some marketplace-y functionality coming to Shop way before ChatGPT was ever a thing). Instead, they were focused on providing the best possible tools for each merchant to build their beautiful walled garden.

What no one could foresee is that a new shopping surface would come along that would force *the entire Internet* to turn into one huge marketplace.

When that happened, they decided the best strategy was to ride the wave rather than hide from it. And Shopify being the powerhouse it is, they nailed it: between their work on UCP and the identity graph they are building with Shop, it's not an exaggeration to say that they have become the commerce infrastructure for the open Web—so much so that they have now got Amazon [scrambling to catch up](https://www.readtheaisle.com/p/amazon-agentic-commerce-jobs-hiring-ai-shopping). Whatever shifts happen next, I fully trust that Shopify merchants will be in the best possible position to benefit from them.

At the same time, make no mistake: *some* disintermediation is coming. Just like marketplaces, agentic commerce offers merchants a new distribution channel but also requires them to give up control over the shopping experience. Sure, UCP affords some flexibility, but it will never be able to replicate your merchandising strategy or your in-cart upsells, nor should it necessarily: when a consumer is checking out via ChatGPT, they are often in a very different state of mind than when they are browsing your site.

This last point, I think (hope?), is *the* point we should all be focusing on: as agentic shopping channels get bigger and bigger, the website is not going away, but it will definitely evolve: rather than being a channel consumers *have* to interact with, it will gradually become one consumers *want* to interact with.

Because of this, DTC websites may end up getting less traffic than before, but (most of) that traffic will likely be much more engaged. Customers will end up on your site having already done their homework, and looking to really immerse themselves in your brand universe. This will allow merchants to create much richer, deeper, weirder DTC experiences that aim to create a connection, not just usher the customer out the door as quickly as possible—what our friends at Future Commerce called [Dork Mode](https://www.futurecommerce.com/posts/insiders-107-dork-mode-an-antidote-to-the-sea-of-sameness) in a prescient 2021 article.

And while no one knows what form this will take (more on our possible futures in an upcoming article) or how long it will take for us to get there (remember: on average, agentic sales make up 0.5% of GMV for our clients), that is something I can get excited about.

Shopify's Agentic Strategy and the Future of DTC

Here's a conversation we've had more than once. An e-commerce director comes to a check-in and says: "Our CFO wants to know why we spent all that money on an accessibility audit and we're still not compliant."

It's a fair question. The audit was real. The remediation was real. The Shopify store launched on time. And then, in the months that followed, the team shipped a run of new seasonal sections, published product updates across the catalog, and added several third-party scripts, none of which had been through any kind of accessibility review.

The audit wasn't wrong. It was accurate on the day it was done. But it was designed to answer a point-in-time question, and the CFO was asking a continuous one.

## Why the audit feels like the finish line

The audit-and-fix model makes intuitive sense. It produces a deliverable: a WCAG violations report, a remediation checklist, a re-test confirmation. It has a beginning and an end. For a team tackling accessibility seriously for the first time, running an audit and fixing what it finds represents real, visible progress.

The problem is that this model treats accessibility the same way a brand might treat a website redesign: something you do, complete, and move on from. But your site doesn't stop changing. Features ship. Sections get added. Content editors upload assets. A new app gets installed. Every change is new surface area, and none of it was in the report.

In 2025, plaintiffs filed 3,117 website accessibility lawsuits in federal court, a 27% increase from the year before, according to [Seyfarth Shaw's annual tracking](https://www.adatitleiii.com/2026/03/federal-court-website-accessibility-lawsuit-filings-bounce-back-in-2025/). Those lawsuits don't come with grace periods for "we passed an audit at launch." And increasingly, they don't come from disabled users who were blocked from completing a purchase. They come from automated bots crawling storefronts specifically looking for WCAG violations to generate demand letters at scale.

The exposure is continuous. The one-time audit is not.

## What "compliant" actually means on a living site

WCAG 2.1 AA is the practical standard that both US law (ADA) and European regulation (EAA) converge on. The EAA is more explicit about requirements and mandates an accessibility statement; its provisions apply to any brand selling into Europe, not only brands headquartered there.

But the standard itself isn't the hard part. What's hard is accepting that compliance isn't a state you achieve, it's a state your site is in or out of at any given moment.

Think about what a typical Shopify brand ships in a month: new product pages, seasonal campaign sections, an updated checkout flow, a third-party review app, a new loyalty widget. Each of those is a new set of DOM elements, a new interaction, a new potential WCAG failure. The audit covered the site that existed when the auditors logged in. It said nothing about the site you'd have sixty days later.

This is the reframe the CFO question requires. The audit was never going to keep the brand compliant. That was never its job. The question is what does.

## The three-layer discipline

What did you say? "Run more audits!"? Nope, that's not the solution. It's building three overlapping layers of coverage that catch different classes of issues at different points in the workflow.

**Layer one: developer-time tooling.** A browser extension like axe DevTools or WAVE installed in every developer's browser catches violations during development, before anything ships. Issues found here cost almost nothing to fix. Issues found in an annual audit cost an order of magnitude more in remediation time, in blocked releases, and sometimes in legal fees.

**Layer two: automated CI testing.** This is where most teams have a gap, and where the choice of tooling matters more than teams usually realize. Many rely on Lighthouse, which runs accessibility checks as part of its standard audit suite. Lighthouse is useful. It is not sufficient.

The problem is that Lighthouse tests a static page state, what the browser renders on load. It cannot test a drawer that's only visible after a click, a modal that opens mid-checkout, or a navigation menu that appears on hover. A significant share of interactive e-commerce UI never appears in a static page scan. A better approach is Playwright, or similar end-to-end testing tools with the axe SDK: you script the interaction first ("open the cart drawer, then run the accessibility check"), so the test covers the actual user path rather than the idle page.

**Layer three: periodic manual audits.** Automated tools catch roughly a third of WCAG violations. The rest require human judgment, whether alt text is meaningful, whether reading order makes semantic sense, whether a custom widget works correctly with a screen reader. Automated tools can confirm that an alt text attribute exists; they cannot tell you whether it says "image.jpg" or something a screen reader user would actually find useful.

Manual audits run quarterly are categorically different from those run annually, not just quantitatively. The site you're reviewing is closer to what you actually shipped. Issues caught at three months are cheaper to fix than issues that have been live for twelve.

## The gap no tool will find

Here's the part that gets left out of most accessibility conversations: three layers of technical tooling will still leave you exposed, because not all accessibility failures live in the code.

They live in the content.

A product image where the product name is rendered as a font inside the JPEG. A campaign banner where the call-to-action text is baked into the graphic. A blog post where every image lacks alt text because the editor who published it didn't know the field existed. No automated scanner catches any of these. They return clean. They fail WCAG 1.1.1 categorically.

Shopify's section architecture can help, but only if it's designed that way from the start. Section schemas can include required alt-text fields, mandatory aria-label inputs, and constraints that make non-compliant content harder to publish than compliant content. On projects where we've built sections with those requirements baked into the schema, content editors make fewer violations, not because they've read the WCAG spec, but because the form won't let them skip the field.

That's not a complete solution. An editor can still type "hero image" in an alt-text field and move on. Editorial guidelines and a basic accessibility orientation for anyone who publishes content are the other half. Less glamorous than CI tooling, harder to automate, and responsible for a disproportionate share of the violations that surface in real audits.

## Building the model that actually holds

Getting from "we had an audit" to "we have a workflow" requires three things beyond the initial report: CI tooling in the development process, content guidelines for the people who publish, and a vendor relationship structured for ongoing coverage, not event-based reviews.

That last one deserves more scrutiny than it usually gets. Some contracts give a brand a fixed number of manual reviews per year and charge per-review after that. The effect is predictable: teams ration their reviews, save them for after major launches, and end up with months of unreviewed surface area in between. You're rationing your own safety, and the gaps happen on a schedule.

Other managed services take a different approach: they monitor your site, identify violations, and deliver pull requests with fixes on a regular cadence. The output quality is often high. But there's a window between when you publish non-compliant code and when the fix arrives, and during that window, you're exposed. Whether that gap creates real legal risk depends on your specific situation, but it's worth pricing into the decision before you sign up.

We'll be direct: building this model takes time, and most brands are already behind. The audit-first approach isn't the wrong starting point, you need to know where you stand. But it becomes the wrong approach the moment it's treated as a destination.

## What keeps you compliant

The CFO question deserves a real answer, not a defensive one.

The audit was a snapshot. It told you where you were on one specific day. Everything that came after, the new sections, the content uploads, the app additions, wasn't covered, because it didn't exist yet. No audit covers a site that hasn't been built.

What keeps a brand compliant is everything that runs after the snapshot: the extension that catches an issue before it ships, the CI test that fails a PR because a new modal has no focus trap, the content editor who knows what alt text should actually say, the quarterly manual review that surfaces what automation missed.

The question worth asking isn't "have we passed an accessibility audit."

It's "would we pass one today?"

If accessibility is on your roadmap, whether as part of a Shopify replatform or as a standalone initiative, [we're happy to talk](https://nebulab.com/contact-us) through what the right model looks like for your team.

No, Your Shopify Accessibility Audit Won't Keep You Compliant

A discovery workshop we ran last year with a mid-market DTC brand, somewhere around hour three. The team was replatforming to Shopify, the architecture conversation had drifted toward Hydrogen, and one of the senior people in the room said something we hear in some form on most of these calls. *One day, we might want a custom account portal. Or a loyalty experience we can't fully picture yet. We need the flexibility.*

The room agreed. There was nothing on the current roadmap that Liquid couldn't handle. There was no integration that would have failed. The day-one storefront could have been built on the Shopify online store in a quarter of the time and a fraction of the cost. None of that mattered, because the conversation had stopped being about the day-one storefront. It had quietly become a conversation about a future that nobody could describe, and the team was about to commit twelve months and substantial budget to it.

Most of the headless decisions we sit in on aren't engineering decisions. They're decisions about a future that may never arrive, paid for in present-day complexity. And in 2026, that complexity is heavier, and harder to recover from, than it was three years ago.

## The Future That May Never Arrive

By the time most brands ask whether they should go Hydrogen, the answer has already been shaped by everything except their own roadmap. Competitor sites they admire. Agency pitches that lean prestige. An internal champion who built a Hydrogen storefront somewhere else and wants to do it again. A creeping fear that staying on Liquid is the basic choice, the choice an ambitious brand wouldn't make.

The decision arrives pre-loaded into the workshop. What was supposed to be an architecture conversation becomes a search for justifications: features that *might* need Hydrogen, hypothetical capabilities that *might* be useful, edge cases that *might* not fit Liquid. The reasoning is real. The framing isn't. We aren't asking what the brand needs to build; we're asking what's wrong with the platform we've already decided we don't want.

Once you notice that pattern, the next question becomes the harder one: what are people actually buying when they buy Hydrogen?

## What Hydrogen Costs You

A Hydrogen build moves a large amount of work *from* Shopify *onto* you. That transfer is the real price tag, and most proposals quantify the upside without quantifying the transfer.

Start with the CMS. On a Liquid theme, the Shopify online store *is* the CMS: sections, blocks, theme settings, the metaobject system. Editors know how to use it. Engineers don't have to build it. Hydrogen ships none of that. You pick a CMS, integrate it, and operate it—Sanity, Contentful, or whatever else fits the editorial workflow your merchandising team actually does. The picking is the easy part. The hard part is everything downstream: templates, scheduled publishing, metaobject integrations, the dozens of small editorial conveniences that Online Store gives you for free.

Then the apps. Backend apps still work fine: order management, fulfillment, tax, payments. Anything that interacts with the storefront is a different story. Reviews, wishlists, swatch pickers, the merchandising UI a search vendor ships alongside their integration—every one of those rebuilds from scratch, even when the vendor publishes an SDK. The SDK gives you primitives. It doesn't give you the convenience of a theme editor toggle. Multiply that across the ten or fifteen apps a typical brand depends on, and the engineering bill starts getting scary.

Then infrastructure. The hosting that disappeared the day you went on Shopify reappears the day you go on Hydrogen. Deploys, environments, performance regressions, edge runtime quirks, the slow accretion of platform-operations work that someone on your team has to own. It rarely shows up in the original estimate, because at planning time it looks like a flat cost. It isn't. It compounds.

And then the team. A Liquid team and a Hydrogen team aren't the same team. If you have one and need the other, that's a hiring program, an upskilling track, and acceptance that some people on your current team won't make the transition. We've seen brands try to soft-pedal this and end up with a storefront nobody internally feels confident touching.

Every one of these is survivable. The question is whether the thing you're getting in exchange is worth carrying the burden.

## The Headless Bet Got Worse, Not Better

This hasn't always been our point of view on the Hydrogen-vs-Liquid debate.

We're a deeply technical team, and Hydrogen had every reason to win us over. A modern stack on top of Shopify's commerce engine. Real developer experience after a decade of Liquid's idiosyncrasies. The promise of working inside Shopify's ecosystem without inheriting its frontend constraints. On paper, joyful to work with. We were genuinely excited, and on the early projects we recommended it on, we built it well.

Then the bill came in. Not on day one, mind you, but quietly across the first eighteen months. Apps that didn't translate. Editorial workflows that had to be rebuilt because the headless CMS didn't behave the way merchandising teams expected. The slow widening of the operational surface area, where every quarter we'd find ourselves explaining a new piece of infrastructure to clients who thought they were buying a storefront. We changed our mind, and we changed our advice with it.

The ecosystem-level case has gotten worse alongside our own reading of it. Shopify's visible investment has moved elsewhere: AI surfaces, agentic commerce, the merchant-facing tools that drive their next phase of growth. Hydrogen release cadence has softened. Public commitments have softened. The volume of new documentation, the number of dotdev sessions, the velocity of the surrounding ecosystem, all of it has cooled relative to where it was in 2022. Fewer brands going Hydrogen means fewer frontend app vendors investing in headless SDKs, which means more rebuild-from-scratch work for whoever's still going there. The flywheel isn't spinning the way it used to.

The wider industry hype that carried headless—composable, MACH, the whole storefront-as-frontend pitch—has moved on too. The buzzword stack today is AI. The peers and prestige signals that made Hydrogen feel inevitable in 2022 don't push the same way now. None of that, on its own, is a reason to reject the architecture. But replatforming locks you in for years, and trajectory matters as much as the current snapshot. The right answer in 2022 isn't automatically the right answer today.

## When Headless Is (Actually) Justified

This isn't a piece against Hydrogen. There are real reasons to go headless on Shopify in 2026. They're narrower than the proposals suggest, but they exist—and if you're in one of them, the costs above are a tradeoff worth making.

There are technical constraints you can't change on a Liquid-rendered storefront. URL structures locked in for SEO reasons, theme-layer behaviors that don't reach the surface you need. If the constraint is real and material to the business, Hydrogen gives you back the control.

There are storefronts so unconventional they don't fit the Homepage / PLP / PDP / Checkout shape Shopify themes assume. A generative AI storefront. An interactive editorial layer. An experience that isn't really a page in the traditional sense. If the storefront experience *is* the product, and not a wrapper around the product, Liquid will fight you and Hydrogen will fit.

There's multi-backend routing. A storefront that has to front Shopify in one market and a different commerce backend in another (e.g., Salesforce, a legacy bespoke platform, a marketplace integration) behind a single customer experience. Liquid wasn't built for that. Hydrogen can be.

There's merchandising and personalization deep enough that integration with tools like Nosto or Algolia becomes the structural concern. When the duplication of HTML and styling across Liquid blocks is a bigger problem than the platform itself, the equation flips.

And there are brands that are partially publications: content workflows closer to a newsroom than a merchandising calendar, where the editorial complexity needs a frontend the online store editor can't accommodate. Crossover commerce-content sites have always sat awkwardly on Shopify.

These are legitimate use cases, but having one of them is a reason to consider Hydrogen, not a mandate.

Treating Hydrogen as a default for ambitious brands is how the present pays for a future that may never arrive.

## The Question You Should Be Asking

The decision improves the moment you replace the platform question with a present-tense business question.

Not *what might we want to build one day*. That question never resolves; the right answer is always "we don't know," and headless will always look like insurance against that uncertainty. Insurance you pay for upfront, every quarter, regardless of whether you ever make a claim.

The question that resolves is the present-tense one: *what are we trying to do that Liquid won't let us do, now or in the next twelve months?* If you can name the constraint—a specific roadmap item that hits a wall, a real cost of staying on Liquid that shows up in numbers, an experience your customer needs that the theme layer can't deliver—the headless conversation gets useful fast. If you can't, the conversation is happening in the wrong register.

Replatforming is already a big, messy project. (Anyone who tells you otherwise is lying.) Adding an architecture choice that nobody can defend in present-tense business terms is how messes become disasters.

## Choose the Platform You Can Defend Now

A Hydrogen yes, in 2026, should feel like accepting a limitation as much as gaining a capability.

More often than not, the limitations you're accepting are larger and more durable than the capability you're gaining: a CMS to operate, a frontend app catalog to rebuild, infrastructure to maintain, a team to retool. Some brands are in the rare position where the capability outweighs all of that. Most aren't.

If the tradeoff still reads as worth it after you've evaluated the pros and cons, go for it. Otherwise, Liquid isn't the cautious choice. It's the right one.

If you're in the middle of this decision and want a second opinion from a team that's lived it on both sides, [we should probably talk.](https://nebulab.com/contact-us)

Is Shopify Hydrogen Worth It in 2026?

Alessandro Mori

The brief looked familiar.

A mid-sized fashion brand was struggling with customers not finding what they were looking for: their bounce rate for visitors coming from certain creatives was skyrocketing; others were dropping off on the PLP, or after running a search; the take rate on PDP product recommendations was abysmal.

The brief was clear: review the entire upper funnel, identify opportunities to improve the UX, and execute.

So we did. We mapped their user flows, audited the product discovery UX, looked at their heatmaps. We identified friction points and proposed solutions.

But as we got to work, we started an uphill battle against an awfully maintained product catalog:

- Shoes were organized by gender, while apparel and accessories were unisex. A customer clicking on "Women" landed on footwear and found no path to jackets. A customer clicking on "Jackets" couldn't filter by gender.
- Attributes were filled in unevenly: different names for the same color, some products with detailed specs and others with none, variant names that followed internal naming conventions rather than how the customer thinks.
- A lot of the attributes customers want to filter or search by—occasion, fit, fabric—were not being captured in a structured format at all. There was no data to filter on, so there was no filter to build.

No matter how beautiful we made their search, filters, or recommendations, the data powering these features was too scarce and inconsistent to produce good results. Every improvement we made felt like putting lipstick on a pig.

And while we could have just shipped the cosmetic improvements and called it a day—that's what the brief asked for, after all—we thought they deserved better. So we went back to the drawing board: we scheduled an all-hands-on-deck workshop, involving everyone from their team who was responsible for or impacted by the structure of the catalog, and figured out a richer, cleaner structure that would allow the new UX to really shine. It wasn't easy, and it went from a one-month project to a multi-month nightmare of coordination, attribute enrichment, and data migrations. But it was worth it.

In systems thinking, you'd call the catalog structure a _leverage point_—the bottleneck that prevents everything else from working correctly. If you only work downstream of the leverage point, you will have minimal impact. But if you re-focus your efforts on the leverage point instead, that can unlock results you couldn't have dreamt of before.

Back to the project: our initial UX work wasn't wasted, but it was work at the wrong leverage point. The real problem was in the taxonomy, the attribute schema, the naming conventions. Once we helped the client restructure those around how customers actually browse, the discovery experience became much easier to solve. The interface hadn't changed dramatically—it just finally had something coherent to represent.

This is, we've come to believe, what CRO work looks like when it's doing its real job. Not shipping UI improvements, but using the discipline of studying how customers interact with a store as a diagnostic lens—one that, if you follow it honestly, keeps leading you to the real source of the problem.

## Finding Leverage Is Only Half the Work

Unfortunately, not every project has a happy ending. Sometimes, you find the leverage point and still can't get anyone to act on it.

Not that long ago, a subscription brand came to us with a retention problem. Their churn was insane, with most subscribers canceling by month six, and they wanted some help figuring out a strategy.

In our very first conversation with them, we threw around some ideas: redesigning the cancellation flow with better copy and deflection offers; launching a loyalty program to incentivize customers to stay; building new CRM flows to remind customers of all the value they were receiving.

But when we dug more into the data, we realized they had a deeper problem: as is often the case with subscription brands, most customers were just canceling because they had too much product.

You see, this particular brand had built a subscription model around regular shipments of a single, durable product category. By month three, most subscribers felt like they had more than they would ever use. By month six, what started out as a fun monthly treat had become an expensive annoyance.

Just like in our fashion project, working on the cancellation flow, loyalty offer, or product education wouldn't do anything to fix the fundamental misalignment between what the brand offered and what the customer needed. And just like in our fashion project, the work wasn't useless, but it was not aimed at the leverage point.

As we continued our data exploration, we realized there was a strong opportunity to rethink the subscription model itself, moving from a single-product cadence to a membership that gave customers access to a much broader catalog, giving them more ways to spend with the brand on their own terms. Less accumulation, more agency.

But this was a _very_ different project from the one we had been hired to do. What had started as a conversation with the Director of E-commerce now involved the CEO, the CMO, merchandising, logistics, and a willingness to rethink the business model from the ground up. The project was also very risky: while they already had the product they needed to support our proposal, everything else was a bet placed by a business that was already struggling. Yes, it could have turned the business around, but it could also have dug them an even deeper hole.

We built the case and presented it. They listened, asked many good questions, and decided they were fine with the problems they had.

This is the struggle with leverage points: at the end of the day, finding them is not enough. Because they're so cross-cutting, you will still need to make your case to people whose work will be affected. Some of these people may have never even asked for your opinion in the first place, and some of them may prefer things to stay the way they are, for a million reasons that you'll find very hard to understand. The deeper the intervention, the wider the coalition you need, and the more political the conversation becomes.

## Becoming a Better Player

While there's no formula for getting people to act on leverage points, there are a few things we've learned—some of them the hard way.

The place to start is almost always the org chart, not the system. In the subscription project, we spent our opening conversations with the Director of Ecom. That made sense given how the brief was scoped. But the decision we were ultimately asking for required many, many more people—people who hadn't been part of the conversation and weren't that eager to be involved. By the time we figured that out, we were already in the wrong room. Before you start making the case, figure out who the actual decision-maker is, who influences them, and what their agenda is.

Once you know that, don't limit yourself to data, but build a story instead. When you're asking for something this uncomfortable, people need to be able to picture the other side and see a real account of what life looks like once the work is done. How would a more flexible membership model fit within the lives of our customers? What cool things can we do with product recommendations once the data is actually clean? The clearer that picture, the easier it is for someone to imagine saying yes.

But while the story serves as your destination, you still need to figure out the smallest thing you can propose that actually proves your point. A full business model overhaul is a hard sell for a business that's already struggling (ask us how we know). A more contained bet, like offering a broader catalog to a small cohort of at-risk subscribers, would have been a much harder ask to refuse. And if it had worked, the bigger case would have made itself. The more cross-cutting the change, the more valuable a small proof point becomes.

To be clear, none of these will guarantee victory. Organizations have their own, opaque logic, and sometimes—alright, most of the time—that logic wins. This can be frustrating: we have been in more than one room where we felt like we were screaming into the void, while we could have just laid back and done what the brief was asking for.

Despite all this, it's still a battle worth fighting. The whole e-commerce industry is, by its very nature, extremely focused on the short term. We want results, and we want them yesterday. That's what makes UX and CRO improvements so appealing—and granted, they do have their place.

But at the same time, investing in cosmetic improvements in the presence of much deeper problems can lead to a lot of wheelspinning. When that's the case, you need someone with the ability to take a deep breath, find the one thing that matter, and focus all their efforts on it.

If this feels like the kind of work your brand needs to do, [perhaps we should have a chat.](https://nebulab.com/contact-us)

This Is Why Your E-Commerce CRO Program Isn't Working

Every replatform has two projects running in parallel. There's the technical migration, which is complex but ultimately predictable. And there's the organizational one: keeping tens of people with competing priorities, different levels of technical fluency, and their own agendas aligned for months on end. The second project is where most replatforms actually succeed or fail.

In a previous article, we covered the structural mistakes agencies make with enterprise migrations. This piece zooms in on one of those challenges: stakeholder management. Specifically, how to keep alignment from the earliest conversations all the way through launch, and what to do when that alignment breaks down.

## Replatforms Are Political Projects

Most agencies walk into a replatform expecting a clean org chart. There's a product owner on the brand side who gathers requirements, makes decisions, and serves as the single point of contact. The agency talks to that person, that person talks to everyone else, and information flows neatly in both directions.

This almost never reflects reality at enterprise scale.

In practice, the product owner can answer some questions but not others. They know the e-commerce team's priorities, but they don't fully understand how the warehouse processes returns, or why the finance team needs a specific field at checkout, or what the content team's daily workflow actually looks like. They're a generalist in an organization full of specialists, and funneling every conversation through them creates a bottleneck that slows the project down and filters out critical context.

The deeper problem is that this model treats the brand as a monolith, a single entity with a unified set of requirements. Enterprise organizations are collections of teams with their own professional goals, personal motivations, and fears about what the migration means for them:

- **The CFO** wants to see the cost savings that justified the project.
- **The content team** wants a CMS that doesn't make their job miserable.
- **Marketing** wants campaign flexibility without filing dev tickets.

These agendas overlap in some places and directly conflict in others, and every one of them competes for priority within a fixed budget and timeline.

Underneath the professional priorities, there are personal ones that rarely get articulated:

- An operations team might drag their feet on UAT because they're worried the new system will expose inefficiencies in their current process.
- A department head who championed the existing platform may see the migration as an implicit criticism of their original decision.
- A team that has spent years building custom workarounds for the old system's limitations may fear that their institutional knowledge becomes worthless overnight.

These fears are real, they shape behavior, and if you don't account for them, you'll find yourself dealing with resistance that seems irrational on the surface but makes perfect sense once you understand the motivation behind it.

There's also emotional attachment to existing tools and workflows. People build their daily rhythm around specific software and workflows, and they will resist changing them, regardless of whether a better option exists. Those attachments are rational: the team knows the status quo works, they've invested time in learning it, and switching carries real risk for their day-to-day productivity. Dismissing these concerns as resistance to change is a fast way to lose trust.

Mapping these dynamics, both the professional priorities and the personal motivations, is work that starts during discovery and never really stops. As you learn more about the organization, your understanding of who cares about what will evolve. New stakeholders will surface. Priorities will shift. The political map you drew in week one will look different by month three. Keeping it current is part of the job.

Understanding all of this requires something fundamentally different from the traditional agency-client relationship. There can't be gatekeeping on either side. The agency can't hide behind a project manager who shields the team from organizational complexity, and the brand can't funnel everything through a single point of contact who lacks the full picture. The project needs to be deeply embedded, with both teams working side by side, building direct relationships across departments, and developing a nuanced understanding of how the organization actually operates.

This is all very uncomfortable for agencies that prefer clean boundaries. It also happens to be the only way to account for the real complexity of enterprise organizations.

## Discovery Is a Mindset, Not a Phase

There's a famous line often attributed to Eisenhower: plans are useless, but planning is everything. The same principle applies to discovery in a replatform. While initial discovery matters (we'll cover that in depth in a separate article), the real value is in establishing a discipline of continuous questioning that persists throughout the entire project.

The beginning of a project is, paradoxically, the moment when you have the least information. You're making a plan based on what stakeholders tell you they need, filtered through what they remember to mention. As the project progresses, you accumulate context that reshapes your understanding of the business.

This means the principles that guide a good discovery workshop should guide every conversation throughout the project. For every requirement that surfaces, ask why it matters and what the business impact actually is. When someone tells you a feature is critical, dig into how often the scenario occurs and what happens if it simply doesn't exist at launch. Many requirements that feel urgent in the abstract turn out to be low-frequency edge cases that can wait.

The other side of continuous discovery is **proactive requirement gathering**. Stakeholders have full-time jobs outside of your replatform, and getting answers takes longer than you'd expect. Waiting until you actually need a decision to ask for it is a recipe for blocked work. This is also where the embedded model pays off: when you have direct relationships across departments, you can go to the source for answers instead of waiting for information to trickle through a single point of contact.

## Getting The Platform in Their Hands Early

One of the most effective stakeholder management techniques has nothing to do with meetings or frameworks. Give people access to the new platform as early as possible.

You can talk about a new platform all you want. You can run workshops, share screenshots, walk through slide decks. None of it compares to the moment an operations team member opens the new admin, performs a task that used to take fifteen minutes, and sees it happen in two clicks. That's when passive tolerance turns into active advocacy. People who were indifferent to the migration start pushing for it to launch sooner.

This is also the single best antidote to the fears and emotional attachments that surface in the opening weeks of a project. Remember the operations team worried that the new system will expose their process gaps? When they can explore the platform at their own pace, on their own terms, they start to see it as a tool they can shape rather than a threat imposed on them. The department head who felt the migration was a referendum on their original platform choice? Watching the new system handle something their old one couldn't softens that defensiveness faster than any reassurance in a meeting. Early access turns abstract anxiety into concrete, answerable questions: How does this work? Can it do this? What happens when I try that?

Early access serves three purposes at once:

1. **It builds genuine buy-in** based on experience rather than promises.
2. **It functions as training in disguise:** stakeholders learn the new system gradually as it takes shape, which means launch day feels like a natural transition rather than a cliff.
3. **It surfaces feedback when you can still act on it.** A workflow issue spotted in month two is a fixable problem. The same issue spotted the week before launch is a crisis.

The same logic extends to validation. QA and UAT should happen continuously throughout the project, not in a single frantic phase before launch. Give stakeholders a staging environment and encourage them to validate work as it's completed, sprint by sprint. This keeps expectations calibrated, catches issues early, and reinforces the feedback loop that makes continuous discovery work. When stakeholders are reviewing working software regularly, they surface requirements and concerns that no amount of upfront planning would have uncovered. A massive UAT crunch at the end is where timelines go to die.

## Navigating Conflicts and Trade-Offs

Conflicts during a replatform are inevitable. The question is whether you have a process for resolving them or whether each one becomes an ad hoc political negotiation.

When a decision needs to be made, **involve the right people**. This sounds obvious, but the common mistake is consulting only the executive who owns the budget. The person who chooses the logistics tool is often not the person who uses it fifty times a day. Gathering input from operational teams, the people who live with the consequences of decisions, prevents the kind of post-launch frustration that comes from choices made in a vacuum.

This matters even more when you consider the personal dynamics at play. A team that already fears their expertise is being devalued by the migration will read exclusion from key decisions as confirmation. Bringing them into the conversation, even when their input doesn't change the outcome, signals that their experience matters. And often, their input *does* change the outcome, because they know things about daily operations that nobody at the executive level has visibility into.

**Use a structured approach to depersonalize the conversation.** Document each option with its pros, cons, and business impact so the discussion shifts from competing opinions to a shared view of trade-offs. When you can show that one path reduces operational overhead but requires a longer integration timeline while another ships faster but adds manual work for the operations team, the conversation becomes concrete. Stakeholders can disagree about which trade-off to accept, but at least they're disagreeing about the same facts.

Once a decision is made with input from all relevant parties, apply the principle of **disagree and commit**. Everyone moves forward together, even those who advocated for a different approach. Relitigating settled decisions is one of the fastest ways to kill momentum.

## Don't Lose Sight of the Big Picture

The further you get into a replatform, the easier it is to lose the thread. Sprints fill up, integration issues multiply, and the day-to-day mechanics of the project start to crowd out the original goals. Teams that were once aligned on outcomes start optimizing for outputs: tickets closed, features shipped, milestones hit. This is how projects arrive at launch having delivered everything on the plan and still feel like a disappointment.

The antidote is maintaining a regular cadence of communication with senior stakeholders that operates at a different altitude from your sprint reviews and status updates. Not a report on what got done last week, but an honest conversation about whether the project is still pointed in the right direction. Are the decisions being made at the ground level still consistent with the business goals that justified this migration? Are the trade-offs accumulating in ways that nobody has explicitly acknowledged? These conversations are harder to schedule and easier to skip, which is exactly why they matter.

Senior stakeholders are well-positioned for this. They're removed enough from the day-to-day to hold the original vision clearly, and senior enough to unblock things when the project drifts or gets stuck. But they can only play that role if they have an accurate picture. The instinct in a difficult moment is to manage upward carefully, softening the message to avoid alarm. Resist it. Communicating with senior stakeholders requires a different register: not sprint-level detail, but a clear, honest view of where the project stands, what the risks are, and where you might need their help.

This big-picture framing also gives you a natural framework for handling change when it comes, and it will come. Scope cuts and timeline shifts are easier to evaluate when you can hold them against the original goals rather than just the current plan. Deferring a feature is a reasonable call if it doesn't compromise day-one operations. It's a much harder call if it quietly undermines the business case that got the migration approved in the first place. Keeping that context alive throughout the project is what allows you to make those judgments clearly, and to bring stakeholders along when the answer is uncomfortable.

## Your Vendors Are Stakeholders Too

There's one category of stakeholder that often gets overlooked: external vendors. Your SEO agency, your logistics provider, your payment processor, your ERP partner. Each of these has their own agenda, their own timeline, and their own level of investment in your migration's success. Managing them well can accelerate the project in surprising ways. Ignoring them can quietly derail it.

**First, understand each vendor's agenda.** A vendor whose contract is up for renewal around the same time as your migration has a very different motivation than one with a multi-year agreement in place. A vendor who is being replaced as part of the replatform has little incentive to invest time helping you migrate away from their system. A vendor who sees the migration as an opportunity to upsell you on additional services will be eager to help, but their recommendations may not always be aligned with your best interests. None of this makes vendors adversarial by default, but it does mean you need to approach each relationship with clear eyes about what's driving their behavior.

**Second, figure out how each vendor can contribute to the project.** This is where the surprising upside lives. Your logistics provider may have already migrated dozens of clients to the new platform and can handle their side of the integration with minimal guidance. Your payment processor might have a dedicated migrations team that can run testing in parallel with your own QA. Your ERP vendor might be able to take on the data mapping work for their integration, freeing up your development team to focus elsewhere. If you don't ask, you won't know. And if you treat vendors as passive participants who just need to flip a switch on launch day, you're leaving significant help on the table.

**Third, build vendor dependencies into your project plan with the same rigor you apply to internal workstreams.** Vendors have their own release cycles, their own resource constraints, and their own priorities. If your logistics provider needs four weeks to configure their integration and you give them two weeks' notice, that's your problem, not theirs. Map out what each vendor needs to do, when they need to do it, and what information they need from you to get started. At launch time, every actor in the system needs to do their part at the right moment, and the vendors you forgot to coordinate with are the ones most likely to cause a last-minute scramble.

## Replatforms Are Won or Lost in the Messy Middle

Stakeholder management doesn't have a dramatic moment where it either works or doesn't. It plays out across hundreds of small interactions that never show up in a project plan and rarely get acknowledged.

The replatforms that land well aren't distinguished by a smarter technical approach or a more detailed requirements document. They're distinguished by the sustained, thankless work of keeping people aligned across months of competing priorities, shifting context, and accumulated tension.

That kind of work requires genuine embeddedness. Not a clean agency-client boundary with a project manager filtering the complexity out, but both teams working close enough to the organization to understand how it actually operates.

Need help keeping your stakeholders aligned through a complex migration? [Let's talk.](https://nebulab.com/contact-us)

E-Commerce Replatforms Fail Because of People, Not Technology

For an enterprise brand that wants to move to Shopify, picking an agency partner that can execute a smooth migration can be challenging.

Most Shopify agencies built their expertise working with mid-market brands doing anywhere from $5M to $30M in annual GMV. They've developed processes, templates, and technology stacks optimized for that segment. When an enterprise brand approaches them, they scale up the team size and timeline but keep the same fundamental approach. The result is a migration that either goes over budget, misses the mark on business requirements, or both.

In this guide, we're going to show you the most common failure modes for an enterprise Shopify replatform, and how to identify the right partner.

## Mistake #1: Failing to Account for Enterprise Risk

The core difference between mid-market and enterprise migrations is risk. If your store goes down for two hours, what does that cost you? If a data migration error corrupts your marketing opt-ins, what's the likelihood you'll get sued? If you launch a new design that introduces friction, what's the impact on conversion rate?

Mid-market brands can absorb these risks more easily. They're smaller, more agile, and often still figuring out their optimal processes. A failed migration is painful but recoverable. For an enterprise brand doing $100M or more annually, even a small dip in conversion during a botched cutover can translate to hundreds of thousands in lost revenue in a matter of days. The math changes everything about how you plan.

**The risk mitigation that enterprise requires looks different:**

- **Longer testing cycles** with real data volumes, not sample datasets
- **Staged rollouts** that let you validate functionality before full cutover
- **Detailed rollback plans** for when (not if) something goes wrong
- **Parallel running** of old and new systems during transition periods
- **More conservative timelines** that account for organizational complexity

Agencies that treat enterprise as scaled-up mid-market skip these steps or treat them as optional. They've run dozens of migrations where you flip the switch on launch day and deal with problems as they come up. That approach works when you're doing $10M annually and have a small team that can move fast. It falls apart when you have multiple departments, established SLAs with customers, and operational dependencies that can't just pause while you fix issues.

## Mistake #2: Leading with Technology Instead of Business Outcomes

Shopify has opinions about how e-commerce should work. Many of those opinions are good. The platform's constraints force simplification, which often leads to better customer experiences and more maintainable code. But Shopify's way is not always the right way for every business.

Agencies that lead with technology start from the assumption that you should adapt your business to fit Shopify's model. If you have a complex pricing structure, simplify it. If you have custom fulfillment workflows, standardize them. If your checkout has specific fields required by your finance team, find a workaround or drop them.

For a newer brand without established processes, this can be liberating. You get to build on top of best practices rather than carrying forward legacy decisions. But for an enterprise brand with a proven value proposition and market positioning, this approach can denature the business.

The right approach balances platform constraints with business requirements. A good agency knows when Shopify's opinion should win (because it genuinely leads to better outcomes) and when you need to work around platform limitations (because your business model depends on it). They start by understanding what drives your business, then figure out how to map that onto Shopify.

This requires flexibility. Rather than having a ready-made solution that worked for the last five clients, they need to understand your specific drivers, constraints, and competitive positioning. The reassurance of a proven template is tempting, but every migration at this level has its own characteristics and needs a tailored approach.

## Mistake #3: Lacking the Technical Depth for Complex Migrations

Understanding what needs to happen strategically is different from having the technical skills to execute it. An agency might grasp your business requirements perfectly but still fail if they don't have deep technical expertise in both your current platform and Shopify's architecture.

Every e-commerce platform has different affordandces and constraints. Migrating from Magento, Salesforce Commerce Cloud, or a custom stack to Shopify requires engineers who understand both systems deeply. You need people who can look at your current data structure and understand not just what it contains, but why it's structured that way, what business logic depends on it, and how it needs to transform to fit Shopify's model.

This goes beyond general web development skills. You need specialists who have worked with:

- **Complex data migrations** at scale, handling millions of records with referential integrity
- **API architecture** across different platforms and integration patterns
- **Custom Shopify development** beyond themes (apps, checkout extensions, custom account portals)

The gap shows up in estimation and execution. Agencies without this depth will underestimate the effort required for data migration, integration work, and custom development. They discover problems late in the project when they're already committed to timelines and budgets. The result is either rushed solutions that create technical debt or delays that push back the launch date.

An agency with real depth will surface complexity you hadn't anticipated—uncomfortable questions about your data structure, your integration dependencies, your edge cases. The difference is hard to spot in a proposal and obvious six months in.

## Mistake #4: Trying to Tackle Too Much at Once

Migrations are an opportunity to fix things. That's both true and dangerous.

The temptation is to change everything at once: new platform, new design, new third-party vendors, new operational workflows, new team structure. After all, you're already disrupting the business. Why not get everything right in one go?

Because every change introduces risk and complexity. When you change multiple variables simultaneously, it becomes nearly impossible to isolate problems. If conversion rates drop after launch, is it the new platform, the new design, or the new merchandising solution? You won't know.

The discipline of a good migration is changing only what the platform transition requires. If your current design works and your team can implement it on Shopify, keep it. If your vendor relationships are solid and the integrations are feasible, maintain them. Save the redesign, the vendor consolidation, and the workflow optimization for after the migration stabilizes.

This doesn't mean never changing anything beyond the platform. It means having a strategic reason for each change and understanding the risk you're accepting. If your current design is built around platform-specific features that don't exist in Shopify, you need a new design. If a vendor doesn't have a Shopify integration and building one would take three months, you might need a new vendor. But make those decisions deliberately, not opportunistically.

## Mistake #5: Underestimating Governance Complexity

Projects at this scale are not linear. You don't gather requirements upfront, disappear for six months, and emerge with a finished product. They're iterative processes involving multiple stakeholders with different priorities, evolving requirements as you learn more, and organizational dynamics that can't be predicted from a kickoff meeting.

The challenge goes beyond technical complexity: it requires coordinating between departments that don't normally work together closely. Your e-commerce team might want to simplify the checkout flow, but finance needs specific fields for tax compliance. Marketing wants content flexibility for campaigns, but brand wants to retain visual control. Operations has workflows built around the current platform that can't just stop working.

Agencies that lack enterprise project governance try to contain this complexity by locking down scope early. They want a detailed requirements document signed off before development starts. They communicate through a project manager who shields the team from stakeholder chaos. They resist changes once the project is underway because changes threaten their timeline and budget.

This approach fails because it's impossible to collect all the context upfront. You discover requirements as you dig into the migration. Stakeholders realize implications of decisions only when they see working prototypes. Business priorities shift during a six-month project. An agency that can't adapt to these realities will either deliver something that doesn't meet your actual needs or blow up the timeline fighting scope changes.

**What good enterprise governance looks like:**

- **Continuous stakeholder communication** throughout the project, not just at milestones
- **Iterative requirement gathering** that expects to learn more as you go
- **Flexible planning** that can absorb changes without derailing the entire timeline
- **Direct access** between your team and the agency's developers and strategists
- **Transparent trade-off discussions** when requirements conflict or timelines need adjustment

The agencies that succeed at this level understand that flexibility and discipline are not opposites. You need structure to manage complexity, but that structure has to accommodate the reality that complex projects involve learning and adaptation. If an agency wants to disappear for months and only surface for status updates, they don't understand how projects of this complexity actually work.

## How These Mistakes Show Up in Practice

Let's say you're evaluating two Shopify Plus agencies for your migration. Both come highly recommended. Both have strong portfolios. But their approaches diverge in ways that reveal everything about how they'll handle your project.

**The first agency** comes prepared with a polished presentation. They've reviewed your site, identified improvements, and mapped out a six-month timeline with fixed pricing and clear deliverables. They show you similar brands they've migrated.

- **Data migration:** They have a tool that handles most of it automatically.
- **Changing requirements:** They emphasize the importance of locking down scope early.
- **Communication:** Everything flows through a project manager.
- **Vendors:** They have preferred partnerships that streamline integration.

Everything feels professional and reassuring.

**The second agency** asks more questions than they answer. What drove the decision to migrate? How is your team structured? What does your integration landscape look like? They propose a paid discovery phase before committing to a timeline or estimate.

- **Data migration:** They want to understand your data structure first because they've seen Magento migrations with custom models that don't map cleanly to Shopify.
- **Changing requirements:** They call it inevitable at enterprise scale.
- **Communication:** You'll have direct access to your design and development team.
- **Vendors:** No locked-in partnerships; they'll evaluate what fits your needs.

The contrast is telling. The first agency is selling you a solution they've refined across previous clients. Their confidence comes from pattern-matching: they're betting your requirements will fit their established approach. If they're right, you get a smooth project. If they're wrong, you discover the mismatch months in when it's expensive to change course.

The second agency is investing in understanding your specific situation before committing to an approach. The uncertainty is honest. Their discovery phase catches the complexity that a templated proposal would miss. Their flexible process accommodates the learning that inevitably happens during enterprise migrations.

The agency that makes you feel most confident during the sales process may be the one least equipped to handle the reality of your migration. Confidence is easy when you're applying a template. Look for the agency that asks harder questions, that wants discovery before committing to answers, and that treats your migration as genuinely unique rather than another variation of the last one they completed.

## Choosing the Partner Who Understands Enterprise Complexity

The mistakes outlined here share a common root: treating enterprise migrations as bigger versions of mid-market projects. Instead, these projects require a fundamentally different approach to risk, planning, technical execution, scope management, and governance. The agency that gets this right will be the one that resists the temptation to apply a proven template and instead invests in understanding what makes your business, your data, and your organization unique.

When you're evaluating partners, pay less attention to polished proposals and more attention to the quality of questions being asked. The right agency will make you slightly uncomfortable with how much they want to learn before committing to a plan. That discomfort is a sign they understand what they're getting into.

Need help navigating your migration to Shopify Plus? We'd be happy to talk through your specific situation and share what we've learned from working with enterprise brands. [Let's talk.](https://nebulab.com/contact-us)

Why Most Shopify Agencies Get Enterprise Replatforms Wrong

If you've built a Shopify app with a Rails backend, you know the routine. You write a verbose GraphQL query string, fire it through the client, then start drilling into a nested hash response: `response["data"]["customer"]["defaultEmailAddress"]["emailAddress"]`. Repeat that across dozens of queries, each returning a slightly different shape, and your codebase turns into an archaeology dig site where nobody remembers which hash key lives where.

Shopify has been pushing hard toward GraphQL as the primary API surface, deprecating REST endpoints and funneling developers toward a more powerful but significantly more verbose interface. The problem is that Shopify's official Ruby tooling stops at giving you a client and an OpenStruct-style response. There's no domain modeling layer, no way to say "a Product always looks like this" across your entire codebase.

We built [ActiveShopifyGraphQL](https://github.com/nebulab/active_shopify_graphql) to fix that. 

## The Hidden Cost of Raw GraphQL Queries

The pain starts small. You write one query to fetch a product's title and price. Then another to fetch variants. Then someone needs metafields. Before long, you have query classes, query superclasses, helper methods for parsing responses, and OpenStruct wrappers that give you dot notation but still require you to know the exact shape of every response. 

Here's what a typical Shopify GraphQL interaction looks like in Ruby without any abstraction:

```ruby
query = <<~GRAPHQL
  query($id: ID!) {
    customer(id: $id) {
      id
      displayName
      defaultEmailAddress {
        emailAddress
      }
      orders(first: 10) {
        edges {
          node {
            id
            name
          }
        }
      }
    }
  }
GRAPHQL

response = client.query(query: query, variables: { id: "gid://shopify/Customer/123" })
customer = response.body["data"]["customer"]
email = customer["defaultEmailAddress"]["emailAddress"]
created_at = Time.parse(customer["createdAt"])
orders = customer["orders"]["edges"].map { |e| e["node"] }
```

This works, sure. But now multiply it by every entity in your app, and you start having problems:

- **Inconsistent object shapes.** Because GraphQL encourages fetching only what you need, the same conceptual entity (a product, a variant) ends up with different attributes in different parts of your codebase. In one place a variant has a SKU; in another, only a price. Your brain has to work overtime to track which version you're dealing with. 
- **Multiple API schemas for the same data.** If you're building a customer account portal, you might use Shopify's Customer Account API alongside the Admin API. Both can return a customer, but the email address lives at `defaultEmailAddress.emailAddress` in the Admin API and `emailAddress.emailAddress` in the Customer Account API. Same concept, different paths, different code. 
- **Maintenance burden at scale.** When Shopify updates their API version, you need to hunt down every query string scattered across your codebase, update field names, fix response parsing, and update all the tests. That time goes into maintaining plumbing instead of shipping features. 

At Nebulab, we deal with the GraphQL API every day, so we set out to solve the problem once and for all.

## What ActiveShopifyGraphQL Does

The gem lets you define Shopify entities as Ruby model classes with typed attributes, path mappings, and associations. It then auto-generates GraphQL fragments from those definitions, executes queries, and maps responses back to your model instances. No hand-written query strings for standard reads.

Here's the same customer interaction from above:

```ruby
class Customer < ActiveShopifyGraphQL::Model
  graphql_type "Customer"

  attribute :id, type: :string
  attribute :name, path: "displayName", type: :string
  attribute :email, path: "defaultEmailAddress.emailAddress", type: :string
  attribute :created_at, type: :datetime

  has_many_connected :orders, default_arguments: { first: 10 }
end

customer = Customer.includes(:orders).find(123456789)
customer.name       # => "John Doe"
customer.email      # => "john@example.com"
customer.created_at # => 2024-03-15 14:30:00 UTC
customer.orders     # Already loaded, no additional query
```

A few things are happening automatically here:

- The `path` option tells the gem where to find a value in the GraphQL response, so `defaultEmailAddress.emailAddress` gets mapped to a simple `email` attribute on your model.
- Type coercion handles the conversion (strings stay strings, `createdAt` becomes a Ruby `Time` object). 
- camelCase to snake_case conversion is automatic: you define `created_at`, and the gem knows to request `createdAt` from the API.

The `graphql_type` declaration is optional when your class name matches the Shopify type. A class called `Product` will automatically map to the `Product` GraphQL type, but you can override it when Shopify's naming diverges from yours, which happens more often than you'd expect!

### The Query API You Know and Love

If you've used ActiveRecord, the query interface will feel immediately familiar:

```ruby
# Find by GID or numeric ID
customer = Customer.find("gid://shopify/Customer/123456789")
customer = Customer.find(123456789)

# Filter with hash syntax
Customer.where(email: "john@example.com")

# Or Shopify's search query syntax for wildcards
Customer.where("email:*@example.com")

# Chain methods
Customer.where(email: "@example.com")
        .order(sort_key: "CREATED_AT", reverse: true)
        .limit(25)

# Select specific fields to reduce API cost
Customer.select(:id, :name).find(123)
```

The `where` method accepts either a hash (which gets auto-escaped and formatted into Shopify's search syntax) or a raw query string for more complex filtering. Error handling works too: if you query on an unsupported attribute, the gem surfaces Shopify's validation error rather than silently failing. 

Pagination is cursor-based under the hood, as Shopify's GraphQL API requires. The gem handles this transparently:

```ruby
# Automatic pagination up to a limit
ProductVariant.where("-sku:''").limit(100).to_a

# Batch processing with explicit page control
ProductVariant.where("sku:FRZ*").in_pages(of: 50) do |page|
  page.each { |variant| process(variant) }
end

# Lazy enumeration
Customer.where(email: "@example.com").each { |c| puts c.name }
```

### Using Connections and Eager Loading

GraphQL connections (the `edges { node { ... } }` pattern) are one of the most tedious parts of working with Shopify's API. ActiveShopifyGraphQL models them as associations:

```ruby
class Product < ActiveShopifyGraphQL::Model
  attribute :id, type: :string
  attribute :title, type: :string

  has_many_connected :variants,
    class_name: "ProductVariant",
    default_arguments: { first: 10 },
    inverse_of: :product
end

class ProductVariant < ActiveShopifyGraphQL::Model
  attribute :id, type: :string
  attribute :sku, type: :string
  attribute :price, type: :string

  has_one_connected :product, inverse_of: :variants
end
```

By default, connections are lazy loaded. Calling `product.variants` triggers a separate GraphQL query only when you actually access the variants. But when you know you'll need them, `includes` lets you eager load everything in a single query: 

```ruby
# One query fetches the product AND its variants
product = Product.includes(:variants).find(123)
product.variants.each { |v| puts v.sku }  # No additional queries
```

The `inverse_of` option enables bidirectional caching. When you eager load a product with its variants, each variant already knows its parent product without making another round trip: 

```ruby
product = Product.includes(:variants).find(123)
product.variants.first.product  # Returns cached parent, no query
```

This matters because Shopify's GraphQL API has rate limits measured in query cost points: every unnecessary round trip burns through your budget. Eager loading and inverse caching let you get more data in fewer, cheaper queries.

### Bridging the GraphQL API with Your ActiveRecord Models

Most Shopify apps store some data locally in a relational database while pulling other data from Shopify's API.

ActiveShopifyGraphQL includes a `GraphQLAssociations` module that bridges the two worlds:

```ruby
class Rating < ApplicationRecord
  include ActiveShopifyGraphQL::GraphQLAssociations

  belongs_to_graphql :product
  # Expects a `shopify_product_id` column in your ratings table
end

rating = Rating.find(1)
rating.product  # Loads Product from Shopify via GraphQL using shopify_product_id
```

The convention follows a `shopify_{association_name}_id` pattern for foreign keys, but you can override it with `foreign_key:`.

Oh, and going the other direction works too: a GraphQL model can declare `has_many :ratings` to query your local database for associated records.

### Switching Between Admin and Customer Account APIs

One of the trickiest aspects of Shopify development is dealing with the Admin API and Customer Account API simultaneously. They return the same conceptual entities but with different response structures. 

ActiveShopifyGraphQL handles this with the `for_loader` block: 

```ruby
class Customer < ActiveShopifyGraphQL::Model
  graphql_type "Customer"

  attribute :id, type: :string
  attribute :name, path: "displayName", type: :string

  # Admin API: email lives here
  for_loader ActiveShopifyGraphQL::Loaders::AdminApiLoader do
    attribute :email, path: "defaultEmailAddress.emailAddress", type: :string
  end

  # Customer Account API: email lives here instead
  for_loader ActiveShopifyGraphQL::Loaders::CustomerAccountApiLoader do
    attribute :email, path: "emailAddress.emailAddress", type: :string
  end
end

# Same model, different data sources
admin_customer = Customer.with_admin_api.find(123)
account_customer = Customer.with_customer_account_api(token).find(123)

admin_customer.email    # Works
account_customer.email  # Also works, different underlying path
```

Your application code doesn't need to care which API the data came from. A `Customer` is a `Customer`. The cognitive load drops significantly when your team can reason about stable domain objects instead of tracking API-specific response shapes. 

### Loading Metafields and Custom Data

Shopify merchants rely heavily on metafields for custom product data. The gem provides a dedicated `metafield_attribute` method that handles the query generation and response parsing:

```ruby
class Product < ActiveShopifyGraphQL::Model
  attribute :id, type: :string
  attribute :title, type: :string

  metafield_attribute :boxes_available,
    namespace: "custom",
    key: "available_boxes",
    type: :integer

  metafield_attribute :seo_description,
    namespace: "seo",
    key: "meta_description",
    type: :string

  metafield_attribute :product_data,
    namespace: "custom",
    key: "data",
    type: :json
end

product = Product.find(123)
product.boxes_available  # => 24
product.product_data     # => { "weight" => "2.5kg", "origin" => "Italy" }
```

For more complex scenarios like metaobjects (Shopify's custom data models), the gem also supports raw GraphQL injection with custom transforms. This is the escape hatch for when the standard attribute mapping can't express what you need. 

### Setting Up a Shared Base Class

ActiveShopifyGraphQL allows you to configure a base class that your models will inherit from.

At Nebulab, we use this to standardize ID handling across all our models. Shopify uses GIDs (Global IDs like `gid://shopify/Product/123`), but you often need the numeric part for database lookups or URL construction:

```ruby
class ApplicationShopifyRecord < ActiveShopifyGraphQL::Model
  attribute :id, transform: ->(gid) { gid.split("/").last }
  attribute :gid, path: "id"
end

class Product < ApplicationShopifyRecord
  attribute :title, type: :string
  attribute :vendor, type: :string
end

product = Product.find(123)
product.id   # => "123" (numeric part only)
product.gid  # => "gid://shopify/Product/123" (full GID)
```

This eliminates the constant GID-to-numeric-ID conversion that plagues Shopify codebases, especially when you need to compare IDs coming from Liquid themes (numeric) with IDs from GraphQL (GIDs). 

Of course, you can also use the shared base class for custom helpers and any other logic you don't want to duplicate.

## Where the Gem Is Headed

Right now, ActiveShopifyGraphQL is read-only. Mutation support is on the roadmap but presents some challenges due to how inconsistent Shopify mutations are.

The roadmap also includes metaobject modeling as first-class models, a caching layer, advanced error handling with retry mechanisms, and rate limit management.

We'll keep building these features as the need arises in our client projects, so stay tuned for updates!

## Ready to Put the Joy Back Into graphQL?

Raw GraphQL in a growing Shopify app creates a maintenance burden that compounds over time: inconsistent object shapes, duplicated query logic, manual type coercion, and the constant mental overhead of tracking which hash key lives where.

ActiveShopifyGraphQL replaces that with stable domain models, typed attributes, and an interface that Rails developers already know.

The library is production-tested, available as a [Ruby gem](https://badge.fury.io/rb/active_shopify_graphql), and ready to drop into your existing Shopify app. Give it a try, open an issue if something breaks, and let us know what you'd build on top of it!

And if you're building a Shopify app or custom storefront and drowning in GraphQL boilerplate, we've been there. [Let's talk!](https://nebulab.com)


ActiveShopifyGraphQL: The Library That Puts The Joy Back into Shopify's GraphQL API

Andrea Vassallo

Every week, the same tension fills boardrooms across the DTC landscape. As the week closes, the gap between projected and actual revenue widens, and the instinct is always the same: sacrifice price to force volume.

Blanket discounting becomes the business model. It starts as a temporary fix (a 30% off site-wide sale to bridge a revenue gap) but quickly metastasizes into a long-term dependency. While the immediate revenue spike provides short-term relief, the hangover is severe. Margins erode, brand equity dilutes, and most dangerously, customers are trained to wait.

Strategic discounting is a powerful lever for growth; panic discounting is a slow-motion liquidation of brand value. But if your business has real discount dependency, you already know that simply stopping isn't an option. You cannot turn off the tap without crashing cash flow.

The solution isn't to stop discounting overnight. The solution is to transition strategically. This guide outlines exactly why you are stuck and provides a phased operational roadmap to recover your pricing power without destroying your business.

## The Anatomy of Brand Erosion

To build the internal case for change, you must articulate the full cost of your current strategy. It goes beyond simple margin loss; it's about the structural degradation of your business model.

### Customer Conditioning

You are training your customers to be price-sensitive. Reference price theory explains why discounts work so well in the short term: customers enter with a price expectation shaped by the market, and when your offer undercuts it, the deal feels like a win. They buy.

But here's the trap: that discounted price becomes their new anchor. The next time they see your product at full price, it doesn't feel like the actual price. It feels like a markup. You won the acquisition and lost the customer's willingness to pay.

The pattern is consistent across the DTC brands we work with: customers acquired on deep discounts buy less often, churn faster, and generate significantly lower lifetime value than full-price cohorts. You aren't just acquiring cheaper customers; you're acquiring worse ones.

### Margin Math

The math of discounting is punishing. Consider a product with a $100 price point and $55 cost of goods (a healthy 45% gross margin). At a 30% discount, the selling price drops to $70 but the cost of goods stays at $55, compressing gross profit from $45 to $15 per unit. To maintain the same gross profit dollars, you now need to sell three units for every one you used to sell at full price.

At first, discount-driven audiences are large, cheap to reach, and fast to convert. The CAC looks great on a dashboard. But you've just tripled your volume while cutting your margin per unit by two-thirds, and you've filled your customer file with buyers who were attracted by price, not by your brand. They'll wait for the next sale, and the next one, and the next one. In the meantime, your CAC will keep rising as you exhaust your in-market audience, compressing your margins more and more until you're actually losing money, not making money.

## The Alternatives to Discounting

If blanket discounts are bleeding your margins, what's the alternative? You've likely tried some of these tactics before. The difference comes down to execution discipline, not the tactics themselves. These three strategies work when applied systematically, not as one-off experiments.

### Strategy 1: Lock Cash into Your Ecosystem

Instead of giving customers 30% off that they can take anywhere, give them that value back in a form that requires them to return to your brand. This means loyalty points or store credit.

The mechanics are simple: a customer who would have received a 30% discount instead receives equivalent value as points in a loyalty program or as a credit applied to their account. The cost to you is lower due to breakage (not everyone redeems), and you maintain your reference price. A $100 product stays $100; the customer just has $30 in their account to use on the next purchase.

Store credit works particularly well for win-back flows and cart abandonment. Instead of sending a percentage-off coupon, send a $20 credit. It maintains pricing integrity and typically increases AOV, as customers often spend more to use up the credit rather than letting it expire.

Loyalty points offer similar mechanics but with more flexibility in how customers redeem. Cash-back points are the default, but you can also allow redemption for other benefits depending on your program structure. The key advantage over direct discounts is breakage and the psychological commitment to your brand that comes with an account balance.

### Strategy 2: Add Value Instead of Cutting Price

Shift the offer from price reduction to value addition. The principle is simple: give customers something that feels valuable but costs you less than a percentage-off discount.

This includes tangible additions like free shipping, extended returns, or gifts-with-purchase using slow-moving inventory. But it also includes access and exclusivity: early access to new drops, exclusive products, VIP experiences, or priority support. These carry high perceived value at a fraction of the cost of a cash discount.

Value-adds work best when the perceived value is high but the actual cost is low. Free shipping on orders over a threshold costs you the shipping subsidy but increases AOV. An extended return window costs you nothing unless the customer actually returns something. Early access costs you nothing but makes customers feel special. A GWP using dead stock turns a sunk cost into a conversion driver.

### Strategy 3: Improve Your Discount Targeting

If you're going to offer cash discounts, stop broadcasting them. The damage comes from giving discounts to people who would have paid full price. Narrow targeting protects your full-price buyers while still giving you a tool for acquisition and reactivation.

This means retiring site-wide promotional codes and homepage sale banners. Instead, send discounts only to specific audiences via email or SMS: lapsed customers who haven't purchased in 6+ months, cart abandoners, first-time visitors who didn't convert. Use unique, single-use codes tied to the recipient so the offer can't leak to your full-price audience.

The key is channel discipline. Discounts sent via direct channels (email, SMS, retargeting ads) stay contained. Discounts displayed on-site or in social posts get shared, screenshot, and distributed to people who didn't need the incentive. If a customer is already on your product page ready to buy, don't show them a discount. If they abandoned their cart or haven't returned in months, that's when the offer goes out.

Narrow targeting also gives you attribution clarity. When every offer uses a unique code, you know exactly which customers are discount-dependent and which aren't. That data becomes the foundation for further refinement.

## Pulling the Plug on Discounts

With your alternative toolkit in place, you can begin the transition. This is not about flipping a switch overnight; it's about systematically replacing blanket discounting with targeted offers and alternative mechanisms that protect margin while maintaining revenue.

### Measure the Problem

Before you change anything, you need to understand how deeply discounting has penetrated your business model. Pull 12 months of order data and calculate three metrics:

1. **Discount penetration rate**: What percentage of total orders used a discount code? This tells you how normalized discounting has become in your customer experience.  
2. **Revenue at risk**: What percentage of total revenue came from discounted orders? If the majority of your revenue required a promotional code to convert, you have a structural dependency problem.  
3. **Average discount depth**: Across all discounted orders, what was the average percentage off? A brand running 15% average discounts has a different problem than one running 35% average discounts.

These three numbers determine your transition timeline. Brands with 70%+ discount penetration and deep average discounts typically need 12 to 18 months to fully recover pricing power without cratering revenue. Brands under 40% penetration can move faster, sometimes within a single quarter. The key is matching your pace to your dependency level.

### Execute the Transition

The transition is conceptually simple: stop giving discounts to people who don't need them, and change what you give to people who do. In practice, this means progressively applying your three strategies (narrow targeting, ecosystem lock-in, and value-adds) to replace blanket promotions.

Here's what that looks like over a typical quarter:

1. **Audit your promo calendar.** List every discount you're running: site-wide sales, email blasts with promo codes, homepage banners, cart abandonment offers, welcome discounts. Calculate how much revenue each one drives. This is your baseline.  
2. **Start tightening the screws.** Remove discount messaging from your homepage. Retire one site-wide sale and replace it with targeted offers sent only to lapsed customers via email using unique codes. Swap percentage-off codes in your cart abandonment flow for store credit. Test early access against cash discounts for engaged customers.  
3. **Measure the impact and iterate.** If revenue drops too much, you moved too fast. Stabilize and try a smaller change. If revenue holds or margins improve without significant volume loss, continue tightening.

Over time, your promotional architecture shifts. Lapsed customers get aggressive win-back offers via email, but never on-site. Cart abandoners get store credit, not percentage-off codes. Loyal customers get early access and exclusive products. New visitors see full price with strong brand storytelling.

As this happens, expect revenue to stay flat or dip slightly in the short term. You're replacing low-quality volume with full-price purchases, and that's a slower build. But the composition of that revenue changes fundamentally: gross margin dollars grow because you're no longer giving away significant percentages of every other transaction, and customer quality improves as your file tilts toward buyers who don't need a coupon to convert.

## What It Looks Like on the Other Side

Eighteen months into a disciplined transition, the business looks fundamentally different. Discount penetration drops from 70% to under 30%. Gross margin per order increases by 15 to 20 percentage points. Customer cohorts acquired at full price show 2x to 3x higher LTV than legacy discount cohorts.

But the hardest part isn't the tactics. The hardest part is the internal conversation. Finance sees short-term revenue risk. Marketing sees CAC spike as you stop subsidizing acquisition with margin-destroying discounts. The executive team has to hold the line while the business rebalances.

Need help planning and building the infrastructure to execute this transition? [We can help!](https://nebulab.com/contact-us)

Stop Killing Your Margins: A Guide to Smarter E-Commerce Discounting

We are the full-service eCommerce agency behind some of the world’s most innovative digital brands. Let's talk about your project.

The Nebulab

How We Test Enterprise Shopify Stores

Subscribe to our newsletter

Standard vs. Custom Account Portals in Shopify: How to Choose

Shopify's Agentic Strategy and the Future of DTC

No, Your Shopify Accessibility Audit Won't Keep You Compliant

Is Shopify Hydrogen Worth It in 2026?

This Is Why Your E-Commerce CRO Program Isn't Working

E-Commerce Replatforms Fail Because of People, Not Technology

Why Most Shopify Agencies Get Enterprise Replatforms Wrong

ActiveShopifyGraphQL: The Library That Puts The Joy Back into Shopify's GraphQL API

Stop Killing Your Margins: A Guide to Smarter E-Commerce Discounting

Are you ready to explore the
new commerce frontier?

The Nebulab

How We Test Enterprise Shopify Stores

Subscribe to our newsletter

Standard vs. Custom Account Portals in Shopify: How to Choose

Shopify's Agentic Strategy and the Future of DTC

No, Your Shopify Accessibility Audit Won't Keep You Compliant

Is Shopify Hydrogen Worth It in 2026?

This Is Why Your E-Commerce CRO Program Isn't Working

E-Commerce Replatforms Fail Because of People, Not Technology

Why Most Shopify Agencies Get Enterprise Replatforms Wrong

ActiveShopifyGraphQL: The Library That Puts The Joy Back into Shopify's GraphQL API

Stop Killing Your Margins: A Guide to Smarter E-Commerce Discounting

Are you ready to explore the new commerce frontier?

Are you ready to explore the
new commerce frontier?