DEV Community: Lucy

Why AI Projects Fail Between Prototype and Production

Lucy — Wed, 21 Oct 2026 07:26:49 +0000

An AI prototype can work perfectly during a demo and still fail when real users start using it.

The model returns accurate answers. The chatbot responds quickly. The AI agent completes its assigned task. Everything looks promising until the application encounters outdated data, unexpected requests, API failures, or hundreds of users at once.

This is where many AI projects run into trouble.

The problem is not always the model. More often, it is the engineering required to make that model work reliably inside a real application.

Moving AI from prototype to production means solving challenges involving data quality, integrations, evaluation, security, performance, and monitoring.

This challenge also shapes the work of LucentAI, Lucent Innovation’s dedicated AI engineering division. Its scope brings AI strategy, LLM and agent development, data engineering, integrations, and production operations together, rather than treating a successful model demo as a finished product.

Let's explore why these failures happen and what developers can do to prevent them.

TL;DR: Why AI Projects Fail in Production

Unreliable data: Production data is often incomplete, outdated, or inconsistent with test data.
Weak evaluation: A successful demo does not prove that an AI system handles unexpected inputs correctly.
Integration failures: External APIs, databases, and business applications introduce additional failure points.
Performance and cost issues: Latency and inference costs can increase as usage grows.
Security gaps: AI systems may expose sensitive information or perform unauthorized actions without proper controls.
Missing monitoring: Without observability, teams struggle to identify errors and maintain output quality. The solution is to treat AI as a complete software system, not just a model connected to an API.

Why a Working AI Prototype Is Not Production-Ready

A prototype is designed to answer an important question: Can this idea work?

Production systems must answer a different question: Can this application work reliably under real operating conditions?

Consider a company developing an AI-powered customer support assistant.

During development, the team connects an LLM to a small collection of support documents using retrieval-augmented generation (RAG).

The assistant answers questions correctly during testing. It retrieves relevant documents and produces useful responses.

The prototype gets approved.

But after deployment, the assistant begins receiving requests about outdated policies, missing orders, account-specific information, and situations that were never included in the original tests.

Some users ask multiple questions simultaneously. Others submit incomplete information. Occasionally, the CRM API becomes unavailable.

The system now has to handle much more than generating text.

A prototype demonstrates feasibility. Production readiness requires evidence that the complete system can operate within acceptable quality, performance, security, and cost limits.

6 Reasons AI Projects Fail Between Prototype and Production

1. Production Data Is Different From Test Data

AI applications often perform well with carefully prepared development datasets.

Real business data is rarely that clean.

It may contain duplicate records, missing fields, outdated documents, inconsistent formats, or conflicting information.

For RAG applications, data quality directly affects what the retrieval system can find and pass to the language model.

Example:

An AI support assistant uses a vector database containing company return policies.

During testing, it retrieves the correct policy and answers customer questions accurately.

After deployment, the business updates its return policy. However, the document ingestion pipeline does not refresh the vector index.

The assistant continues retrieving the previous policy.

The LLM may produce a fluent, well-structured answer, but the information is no longer correct.

Why this happens

Developers may focus on embeddings, chunking, vector search, and prompt design while overlooking the operational lifecycle of the underlying data.

A successful retrieval test does not guarantee that the information will remain accurate.

How to prevent it

Validate data quality before indexing.
Track document versions and ingestion timestamps.
Define refresh schedules or event-driven updates.
Test retrieval with representative production questions.
Detect missing or outdated source documents.
Preserve source references for generated answers. For RAG systems, evaluation should include both retrieval quality and the accuracy of the final response.

A better prompt cannot reliably compensate for missing or outdated information.

2. AI Outputs Are Not Evaluated Against Real Use Cases

One of the most common weaknesses in AI prototypes is limited testing.

A developer submits a few questions, reviews the responses, adjusts the prompt, and concludes that the application works.

This approach is useful during exploration, but it is not a reliable production evaluation strategy.

LLM outputs can vary across inputs, prompt versions, model versions, and retrieved context.

A system that performs well on ten manually selected questions may still fail on hundreds of realistic scenarios.

Example:

An AI assistant is asked:

"Can I return an item purchased during a clearance sale?"

The retrieved policy says clearance items are final sale, except when a product arrives damaged.

The assistant answers that clearance items cannot be returned under any circumstances.

The response sounds confident but misses an important exception.

This is not necessarily a retrieval failure. The correct document may have been available, but the generated answer was incomplete.

Why this happens

Teams sometimes evaluate whether a response sounds reasonable rather than checking whether it is supported by the available evidence and satisfies the task requirements.

How to prevent it

Create an evaluation dataset representing actual application behavior.

Include:

Common questions and expected answers
Ambiguous or incomplete requests
Questions requiring multiple documents
Cases where relevant information is unavailable
Conflicting or outdated source material
Requests the assistant should refuse or escalate

Track metrics relevant to the application, such as answer correctness, groundedness, retrieval relevance, and task completion.

Automated checks can help identify regressions, but high-impact scenarios may still require human review.

Run evaluations whenever prompts, retrieval settings, models, or important data sources change.

The goal is not to achieve perfect responses on every possible input. It is to measure whether the system meets defined quality requirements and identify situations where it must fail safely.

3. Enterprise Integrations Introduce Unexpected Failures

Most useful enterprise AI applications do more than generate answers.

They retrieve information from databases, query CRMs, access inventory systems, create support tickets, or trigger business workflows.

Every integration introduces another possible failure point.

Example:
An AI assistant receives a request to check an order status.

The expected workflow is straightforward:

Identify the order
Verify that the user is authorized to access it
Request order information from the CRM
Interpret the returned status
Respond to the user

But what happens when the CRM API takes too long to respond?

What if it returns an error?

What if the API accepts a ticket-creation request but the network connection fails before the response arrives?

Without proper controls, the assistant may return incorrect information or repeat an operation that has already succeeded.

Why this happens

Developers sometimes treat AI tool calls like ordinary function calls without accounting for distributed-system failures.

However, an LLM selecting a tool does not guarantee that the external operation will succeed.

How to prevent it

Build resilience into the application layer.

Use:

Request timeouts for external services.
Bounded retries with backoff for safely retryable operations.
Idempotency keys for supported write operations.
Input validation before executing tools.
Authorization checks independent of the LLM.
Structured error responses and safe fallbacks.

Consider this simplified Python example for a read-only CRM request:

import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

retry_policy = Retry(
    total=2,
    backoff_factor=0.5,
    status_forcelist=[429, 502, 503, 504],
    allowed_methods=["GET"],
)

session = requests.Session()
session.mount(
    "https://",
    HTTPAdapter(max_retries=retry_policy)
)

def get_order_status(order_id, access_token):
    try:
        response = session.get(
            f"https://crm.example.com/api/orders/{order_id}",
            headers={
                "Authorization": f"Bearer {access_token}"
            },
            timeout=(2, 5)
        )

        response.raise_for_status()
        return response.json()

    except requests.RequestException:
        return {
            "status": "unavailable",
            "message": "Order information is temporarily unavailable."
        }

This illustrative example introduces connection and read timeouts, limited retries, and controlled error handling.

It is not a complete production implementation. The calling application must still validate the order identifier, verify authorization, manage credentials securely, and distinguish a genuine business status from an infrastructure error.

In particular, the assistant should never translate "unavailable" into a fabricated order status.

For write operations, retries need additional safeguards because a failed response does not always mean the operation failed.

The key principle is simple: the AI model can help decide which operation to request, but the application must control how that operation is executed.

4. Performance and Inference Costs Become Unpredictable

A prototype may serve only a few requests during testing.

A production application can receive many concurrent requests, each consuming different amounts of compute, tokens, and external resources.

This introduces two challenges: performance and operating costs.

Example:
An internal knowledge assistant performs well when answering short questions.

Later, users begin submitting long documents and complex questions requiring multiple retrieval and tool-calling steps.

Each request may now involve:

Generating embeddings
Searching a vector database
Retrieving several documents
Constructing a larger model context
Making one or more LLM calls
Processing additional tool responses The system becomes slower, and the cost per request increases

Some responses may finish quickly while others take significantly longer.

Why this happens

Prototype tests often focus on whether the model produces the correct answer.

They may not measure system behavior under sustained traffic or complex request patterns.

How to prevent it

Measure performance at the application level, not only at the model level.

Useful metrics include:

Developers can also consider caching appropriate responses, limiting context size, batching suitable workloads, and routing simpler tasks to less expensive models.

However, each optimization should be tested against output quality.

For example, reducing retrieved context may improve latency while removing information needed for accurate answers.

The objective is not simply to make AI cheaper or faster. It is to maintain acceptable quality within defined performance and cost limits.

5. Security and Access Controls Are Added Too Late

AI applications introduce security risks when models can access enterprise information or interact with business tools.

One important issue is prompt injection.

An attacker may place malicious instructions inside a document, webpage, or tool response that the AI application processes.

If the application treats that content as trusted instructions, the model may attempt an unauthorized action.

Example:
An AI assistant retrieves a customer support document containing instructions that tell the assistant to ignore its original task and send account information to an external endpoint.

The document should be treated as untrusted content.

However, an insecure application may allow those instructions to influence tool selection or downstream actions.

This becomes especially dangerous when an AI agent has broad permissions across business systems.

The OWASP guidance on excessive agency highlights risks associated with excessive functionality, permissions, and autonomy in LLM-based applications.

Why this happens
Developers may assume that system prompts are sufficient to control model behavior.

But prompts alone are not reliable security boundaries.

How to prevent it
Enforce security controls outside the model.

These should include:

Least-privilege tool permissions
Server-side authentication and authorization
Strict validation of tool arguments
Separation of trusted instructions from retrieved content
Approval steps for sensitive or irreversible actions
Restrictions on external network destinations
Audit logs for important tool executions An AI assistant that can read order information should not automatically receive permission to modify orders, issue refunds, or export customer records.

Every action should be governed by application-level permissions and business rules.

Security is not a final prompt-engineering task. It is part of the system architecture.

6. Nobody Owns Monitoring and Reliability After Deployment

Deploying an AI application is not the end of its engineering lifecycle.

Models change. Business documents are updated. APIs behave differently. User requests evolve.

Without monitoring, these changes can gradually reduce application quality.

Example:

An AI support assistant initially retrieves relevant documents and resolves common customer questions.

Over time, the business introduces new products and changes its support documentation.

The retrieval pipeline continues running, but the assistant starts producing less relevant responses.

There may be no visible infrastructure outage.

The application is technically available, but its usefulness is declining.

Traditional uptime monitoring alone may not detect this problem.

Why this happens

Development teams often monitor server health and API availability without tracking AI-specific behavior.

Yet an AI application can return HTTP 200 responses while producing incorrect or unsupported answers.

How to prevent it

Monitor multiple layers of the system.

Infrastructure monitoring

Track service availability, request failures, latency, and resource utilization.

Model and application monitoring

Measure token usage, model errors, response quality, and relevant evaluation metrics.

Retrieval monitoring

Track document freshness, retrieval failures, and changes in retrieval relevance.

Tool execution monitoring

Record tool-call outcomes, authorization failures, timeouts, and retries.

Logging and tracing should use appropriate redaction and access controls to avoid exposing sensitive information.

Teams should also establish ownership for alerts, investigate recurring failures, and maintain rollback procedures for model, prompt, or application changes.

A production AI system needs the same operational discipline as other business-critical software, along with monitoring that accounts for AI-specific behavior.

A Practical Framework for Moving AI From Prototype to Production

The six failure scenarios point to a common issue: teams often validate the model before validating the entire application.

A more reliable approach is to introduce production requirements earlier in development.

The following five-stage framework provides a practical starting point.

Step 1: Define Production Success Criteria

Before building the complete application, define what success means.

This might include:

Minimum acceptable answer quality
Maximum response latency under expected load
Acceptable operating cost per task
Supported business actions
Security and access requirements
Expected behavior when dependencies fail

Deliverable: A documented set of measurable acceptance criteria

Step 2: Test With Realistic Data and Failure Cases

Move beyond curated test prompts.

Evaluate the application using representative data, edge cases, missing information, and unexpected requests.

Include negative scenarios such as unavailable documents, incorrect identifiers, and conflicting records.

Deliverable: A versioned evaluation dataset and repeatable tests.

Step 3: Engineer Reliable Integrations

Treat databases, external APIs, and AI tools as systems that may fail independently.

Implement authorization, validation, timeouts, bounded retries, and recovery behavior.

Separate the model's proposed actions from the application's execution permissions.

Deliverable: Tested integration contracts and documented failure-handling behavior.

Step 4: Validate Security, Performance, and Costs

Test the application under realistic workloads.

Review tool permissions, sensitive-data handling, prompt-injection risks, inference costs, and response latency.

Use the results to identify constraints before a wider rollout.

Deliverable: Performance, security, and cost validation reports.

Step 5: Deploy Gradually and Monitor Continuously

Begin with a limited rollout where appropriate.

Monitor production requests, investigate failures, and compare observed behavior with the original acceptance criteria.

Maintain an operational process for updating prompts, models, retrieval pipelines, and external integrations.

Deliverable: Monitoring dashboards, alerting rules, rollback procedures, and assigned operational ownership.

The important lesson is that production readiness cannot be delivered by improving prompts alone. It requires the entire application to behave reliably under realistic conditions.

Where LucentAI Fits Into the Prototype-to-Production Challenge

The six problems above are connected. A RAG application can have a capable model but fail because its data pipelines are stale. An AI agent can choose the correct tool but still create operational risk if application permissions are too broad. Better prompting alone will not fix either issue.

LucentAI is Lucent Innovation's AI engineering division, bringing several parts of the delivery process into one team:

AI readiness and strategy: Evaluate the business use case, technical constraints, success criteria, and a practical route from proof of concept to implementation.
Data engineering: Prepare reliable data sources and pipelines for retrieval, analytics, machine learning, and production AI applications, including work within the Databricks ecosystem.
LLMs, RAG, and AI agents: Design applications around real workflows, enterprise knowledge, model behavior, and integration boundaries.
Application integration: Connect AI components with existing business applications and controlled APIs rather than leaving them isolated in a demo environment.
Production engineering: Plan deployment, evaluation, monitoring, and optimization alongside the core AI application.

That combined approach is relevant when a team has already validated an AI idea but needs to make the complete system dependable. The details still depend on the use case: an internal document assistant and an AI agent permitted to update business records do not need identical safeguards.

Explore LucentAI's AI engineering and data capabilities for more on the division's approach to moving AI work into production.

The practical takeaway for developers is to assign ownership to every layer, from source-data freshness to tool permissions and post-release monitoring. A gap between those layers is often where a promising prototype stops being a reliable application.

How to Know Whether an AI System Is Ready for Production

There is no universal checklist that guarantees production readiness for every AI application.

A customer support chatbot, financial document processor, and autonomous workflow agent have different risk profiles.

However, developers can assess readiness across several common engineering areas.

These questions should be answered with test results and documented evidence wherever possible.

For example, instead of declaring an assistant "fast enough," measure its P95 response latency under expected traffic.

Instead of claiming that an agent is secure because its system prompt contains restrictions, test whether application-level controls prevent unauthorized operations.

The NIST AI Risk Management Framework also provides a useful reference for organizations evaluating and managing AI-related risks throughout the system lifecycle.

Production readiness is not a single deployment milestone. It is an ongoing process of verification, monitoring, and improvement.

What Final Verdict Says Is:

Production Success Requires More Than a Working Model
AI prototypes are valuable because they help teams validate ideas quickly.

But a successful demonstration does not automatically translate into a dependable production application.

Real environments introduce changing data, unpredictable requests, external dependencies, security requirements, and operational costs.

Solving these challenges requires more than selecting a capable LLM or improving a prompt.

It requires deliberate software engineering across the entire AI system.

For developers, the most useful mindset is to build for failure, measure actual behavior, and design recovery into the application from the beginning.

A successful AI project is not simply one that produces impressive answers during testing. It is one that continues delivering reliable results when real users, real data, and real-world failures become part of the system.

How to Fix Shopify POS and EDC Terminal Reconciliation Mismatches published

Lucy — Wed, 07 Oct 2026 08:55:53 +0000

The problem: two ledgers, one sale

A cashier taps "Pay by card" in Shopify POS. The customer pays on the EDC terminal. Shopify records a sale. The terminal records a charge. Later, the bank settles the money.

That is three records for one sale. If any one of them is off, your end-of-day numbers do not match.

We see this a lot in multi-store retail projects. The totals are off by a few hundred rupees, or a few dollars. Nobody knows which order caused it. Someone then spends hours with two spreadsheets.

Why the numbers drift

Most mismatches come from four cases. Knowing them makes the fix easier to design.

Partial payments.A customer pays half by card and half by cash. The terminal shows only the card part. Shopify shows one order with two payments.
Refunds and voids. A refund is started on the terminal but not recorded in Shopify, or the other way around.
Settlement delays. The terminal batch closes at night. The bank pays out one to three days later. A daily report compares two days that do not line up.
Offline or retried transactions. The network drops. The cashier retries. The terminal charges once, but Shopify gets two attempts, or none.

Notice what these have in common. Each one breaks a match that relies on amount and time alone. Two sales of the same amount in the same minute look identical.

The approach: match on a shared reference

So the first rule is simple. Never match by amount. Match by a reference that both systems can see.

Most EDC terminals print a retrieval reference number (RRN) and an auth code on every receipt. Those values are unique per transaction. If you save them on the Shopify order, you get a key that joins all three records.

Here is the plan in four parts:

Capture the RRN and auth code at the time of payment.
Save them on the Shopify order.
Pull terminal and bank reports on a schedule.
Match by reference and flag what is left. Let's build each part.

Step 1: Capture the reference at payment time

The cleanest option is to have the cashier flow pass the terminal response back to your app. If your terminal vendor has an SDK or API, use it to read the RRN and auth code right after approval.

If your terminal cannot talk to your app, fall back to a short manual field. Ask the cashier to type the last digits of the RRN. This is slower and has typos, so treat it as a second choice.

Either way, the goal is the same: one reference per card payment, attached to the order.

Step 2: Save the reference on the Shopify order

Store the values as order metafields so they are easy to query later. Here is a minimal example using the Admin GraphQL API.

const mutation = `
  mutation SetEdcRef($metafields: [MetafieldsSetInput!]!) {
    metafieldsSet(metafields: $metafields) {
      metafields { id key value }
      userErrors { field message }
    }
  }
`;

async function saveEdcReference(client, orderGid, rrn, authCode) {
  const variables = {
    metafields: [
      { ownerId: orderGid, namespace: "edc", key: "rrn", type: "single_line_text_field", value: rrn },
      { ownerId: orderGid, namespace: "edc", key: "auth_code", type: "single_line_text_field", value: authCode },
    ],
  };
  const res = await client.request(mutation, { variables });
  const errors = res.data.metafieldsSet.userErrors;
  if (errors.length) throw new Error(JSON.stringify(errors));
}

Always check userErrors. A silent failure here means an unmatched order later.

Also listen for the webhooks that change the money on an order. At minimum, subscribe to orders/create and refunds/create. When a webhook arrives, verify the HMAC signature before you trust it.

import crypto from "crypto";

function isValidShopifyWebhook(rawBody, hmacHeader, secret) {
  const digest = crypto
    .createHmac("sha256", secret)
    .update(rawBody, "utf8")
    .digest("base64");
  return crypto.timingSafeEqual(Buffer.from(digest), Buffer.from(hmacHeader));
}

Keep secrets in environment variables, never in source code.

Step 3: Pull terminal and bank data on a schedule

Most acquirers and terminal vendors offer a daily settlement file or an API. Pull it once a day. Save each row with its RRN, amount, status, and settlement date.

Two tips that save pain later:

Store raw files first. Keep the original file before you parse it. When a row looks wrong, you can go back to the source.
Make the import safe to run twice. Use the RRN as a unique key so a rerun does not create duplicates.

Step 4: Match by reference and sort the results

Now the matching job is small. For each terminal row, look for a Shopify order with the same RRN. Then compare the amount.

function reconcile(terminalRows, shopifyOrders) {
  const byRrn = new Map(shopifyOrders.map((o) => [o.rrn, o]));
  const result = { matched: [], amountMismatch: [], missingInShopify: [] };

  for (const row of terminalRows) {
    const order = byRrn.get(row.rrn);
    if (!order) {
      result.missingInShopify.push(row);
    } else if (order.cardAmount !== row.amount) {
      result.amountMismatch.push({ row, order });
    } else {
      result.matched.push({ row, order });
      byRrn.delete(row.rrn);
    }
  }

  const missingOnTerminal = [...byRrn.values()];
  return { ...result, missingOnTerminal };
}

This gives you four clear buckets:

Humans only look at the last three. On a normal day that is a short list, not a full spreadsheet.

Handle the tricky cases on purpose

A few rules make the job much more reliable.

Use a settlement window. A sale from Monday may settle on Wednesday. Do not flag it as missing on Tuesday. Wait for the expected settlement date, then flag it.
Compare card amounts only. For split payments, compare the card portion of the Shopify order, not the order total.
Link refunds to the original sale. Save the original RRN on the refund record. Then a refund is a second line on the same transaction, not a new mystery.
Log every change. Keep an audit trail of who fixed what and when. Finance teams will ask for it.
Protect customer data. Never store full card numbers. The RRN and auth code are enough for matching. Keep personal data out of logs, and use fake data in test environments.

Make it safe to ship

Roll this out in steps. Run the matching job in read-only mode first and compare its output with your current manual process for a week. Test on a staging store before you touch production. Use a feature flag so you can turn the sync off fast if something looks wrong.

If your payment flow involves custom terminals or several stores, a proper payment gateway integration design up front saves a lot of rework. We have built these kinds of flows at Lucent Innovation, and the pattern above is the one that has held up best.

For background on the Shopify side of POS data, see the related post Shopify POS + EDC Terminal Integration.

You can also check the Shopify Admin API docs for the exact fields on orders, transactions, and metafields.

FAQ

1. Why do my Shopify POS and EDC totals not match?
Because they are two separate records of the same sale. They drift when a partial payment, refund, delayed settlement, or offline retry is recorded on only one side.

2. What is the best key for matching card payments?
The RRN from the terminal. It is unique per transaction, and it appears on both the terminal report and the receipt. The auth code is a good second check.

3. Can I reconcile without a terminal API?
Yes. Use the daily settlement file from your acquirer and save the RRN on each order, even by manual entry. It is slower, but it still beats matching by amount.

4. How often should I run reconciliation?
Daily. Run it after the settlement file arrives, and use a short window so late settlements are not flagged too early.

5. How do I handle split payments?
Compare only the card portion of the Shopify order with the terminal amount. Cash and other methods should be reconciled separately.

Summary

Reconciliation breaks when you match by amount and time. It works when every card payment carries a shared reference.

To close the gap:

Capture the RRN and auth code at payment.
Save them on the Shopify order as metafields.
Pull terminal and settlement data daily.
Match by reference and review only the exceptions.
For brands running many stores, a Shopify Plus development setup can make this easier to scale, since every store follows the same pattern.

Start small, run it read-only for a week, and let the numbers show you where your gaps really are.

Shopify Data in Databricks: A First Look at the New Lakeflow Connect Shopify Connector

Lucy — Tue, 29 Sep 2026 12:25:03 +0000

Databricks now has a managed Shopify connector in Lakeflow Connect, released in Beta on September 22, 2026. It pulls products, orders, customers, inventory, fulfillments, and discounts from a Shopify store into Unity Catalog tables with incremental syncs, so you no longer need to write and maintain your own API extraction code. It is a strong default for analytics on Shopify data, with a few Beta limitations you should plan around before relying on it in production.

This guide covers how the connector fits into a lakehouse architecture, how to set it up end to end (Shopify app, Unity Catalog connection, and pipeline as code), what to build on top of the raw tables, and where a custom pipeline is still the better choice. Everything here is based on the official Databricks and Shopify documentation as of late September 2026. Because the connector is in Beta, check the linked docs for changes before you build on it.

What does the Lakeflow Connect Shopify connector actually do?

The connector is a managed ingestion pipeline: you point it at a Shopify store, pick the tables you want, and Databricks handles extraction, pagination, rate limiting, incremental cursors, and writing to Delta tables. According to the Shopify connector overview, it supports UI-based and API-based pipeline authoring, Declarative Automation Bundles, incremental ingestion, Unity Catalog governance, orchestration through Databricks Workflows, and SCD Type 2 history tracking.

The pipeline documentation lists 39 source tables in a default source schema. You can ingest individual tables or the whole schema in one declaration.

What it deliberately does not do matters just as much. The limitations page is explicit that the connector ingests raw data without transformations and expects you to handle modeling downstream. It also doesn't cover custom metafields, Shopify reports, or objects outside its 39 prebuilt tables. If your store runs heavily on metafields, that is the first thing to check.

How does it fit into a lakehouse architecture?

The connector replaces the extraction layer, the part most Shopify data teams build by hand with Admin API calls, pagination logic, and retry handling. Everything after it stays the same: bronze tables land in Unity Catalog, you transform them into silver and gold layers, and BI tools, Genie, or ML workloads read from the gold layer.

Two properties of this design are worth calling out.

Credentials live in Unity Catalog, not in code. The Shopify client ID and secret are stored in a Unity Catalog connection object. Pipeline definitions reference the connection by name, so secrets never show up in notebooks, YAML files, or Git history. If you've ever found an access token hardcoded in an old extraction script, this is a real improvement.

Governance applies from the first table. Because the landing tables are Unity Catalog tables, the same access controls, lineage, and auditing you use elsewhere apply to Shopify data immediately. That matters for customer data, which we'll come back to in the limitations section.

What do you need before you start?

The setup splits across Shopify and Databricks, and it's common for a different person to own each side. Check these before starting.

On the Databricks side, the pipeline requirements are:

A workspace enabled for Unity Catalog, with serverless compute turned on.
CREATE CONNECTION on the metastore to create the connection, or USE CONNECTION to use an existing one.
USE CATALOG on the target catalog, plus USE SCHEMA and CREATE TABLE on the target schema (or CREATE SCHEMA on the catalog).
A workspace admin must enable Lakeflow Connect for Shopify on the Previews page, since the connector is in Beta.
On the Shopify side, per the authentication setup guide:
Any Shopify plan works, because the connector reads through the Shopify Admin API, which is available on all plans.
An app created in the Shopify Dev Dashboard, in the same Shopify organization as the store.
The read_all_orders scope if you need order history older than 60 days. Shopify grants this scope by approval, so request it early. Without it, you only get the last 60 days of orders.
Shopify Payments on the store if you want the balance_transactions and disputes tables.
The read_all_orders approval is the step most likely to delay your project, because it depends on Shopify rather than on your team. If historical reporting is the goal, start that request before anything else.

How do you set up the connector step by step?

Setup has three stages: create the Shopify app, create the Unity Catalog connection, and define the ingestion pipeline.

Step 1: Create and install the Shopify app

The connector authenticates with the Shopify OAuth client credentials grant, a machine-to-machine flow with no interactive login. In the Shopify Dev Dashboard:

Create an app.
On the app's version, select the read scopes required for the tables you plan to ingest. The Databricks required access scopes list shows what each table needs.
Install the app on the store.
Under Settings, copy the Client ID and Client secret.
Note the store subdomain, which is the <shop> part of <shop>.myshopify.com. Only grant the scopes for the tables you actually need. A read-only app with a narrow scope list limits the damage if credentials ever leak, and it makes the access easier to justify in a security review.

Step 2: Create the Unity Catalog connection

Only grant the scopes for the tables you actually need. A read-only app with a narrow scope list limits the damage if credentials ever leak, and it makes the access easier to justify in a security review. If an agency manages the store's apps, involve them at this step, since they usually control the Dev Dashboard (for clients of Lucent's Shopify development services, that's our team).

Step 3: Define the pipeline as code

The UI wizard (Data Ingestion → Add data → Shopify) is fine for a first test. For anything you plan to keep, define the pipeline in a Declarative Automation Bundle so it can be reviewed, versioned, and promoted through environments.

The config below ingests three core tables and sets a backfill start date. Per the docs, start_datetime defaults to 365 days before the first sync and only affects that first sync. Later runs resume from the stored cursor.

# resources/shopify_pipeline.yml
resources:
  pipelines:
    shopify_pipeline:
      name: shopify_pipeline
      catalog: main
      target: shopify_bronze
      ingestion_definition:
        # References the Unity Catalog connection; no secrets in this file
        connection_name: shopify_connection
        source_configurations:
          - api_source_connector_config:
              configs:
                # Only applies to the first sync of each incremental table
                start_datetime: "2024-01-01T00:00:00+00:00"
        objects:
          - table:
              source_schema: default
              source_table: orders
              destination_catalog: main
              destination_schema: shopify_bronze
              destination_table: orders
          - table:
              source_schema: default
              source_table: customers
              destination_catalog: main
              destination_schema: shopify_bronze
              destination_table: customers
          - table:
              source_schema: default
              source_table: products
              destination_catalog: main
              destination_schema: shopify_bronze
              destination_table: products

Add a job file to control the refresh schedule. This one runs daily at midnight UTC:

# resources/shopify_job.yml
resources:
  jobs:
    shopify_job:
      name: shopify_job
      schedule:
        quartz_cron_expression: "0 0 0 * * ?"
        timezone_id: UTC
      tasks:
        - task_key: shopify_ingestion
          pipeline_task:
            pipeline_id: ${resources.pipelines.shopify_pipeline.id}

Deploy with databricks bundle deploy, starting with a development target. Run the first backfill against a dev or staging catalog before you point anything at production. A year of order history on a large store is a big first sync, and you want to confirm the table shapes before dashboards depend on them.

A note on the backfill date: if the app doesn't have read_all_orders, a start_datetime older than 60 days won't give you older orders. The date and the scope need to agree.

What should you build on top of the raw tables?

The connector lands raw data, so the next job is shaping it into something analysts and dashboards can use. The limitations page recommends Spark Declarative Pipelines for downstream transformations, and a materialized view is a simple starting point for a daily sales table.

The example below is illustrative. Check the connector reference for exact column names and types before you use it, since Beta schemas can change.

-- Gold-layer daily sales view (column names are placeholders:
-- verify them against the connector's table reference)
CREATE OR REPLACE MATERIALIZED VIEW main.shopify_gold.daily_sales AS
SELECT
  DATE(o.created_at)                        AS order_date,
  COUNT(DISTINCT o.id)                      AS orders,
  SUM(CAST(o.total_price AS DECIMAL(18,2))) AS gross_sales,
  COUNT(DISTINCT o.customer_id)             AS unique_customers
FROM main.shopify_bronze.orders AS o
WHERE o.cancelled_at IS NULL
GROUP BY DATE(o.created_at);

Two modeling decisions are worth making early.

Gross versus net sales. The view above reports gross sales. Net sales needs refunds and discounts subtracted, and those come from their own tables. Settle on one definition and document it, because a finance team and a marketing team pulling "revenue" from different tables is the most common source of dashboard arguments.

Customer history with SCD Type 2. With SCD Type 2 turned on, you keep every version of a customer record instead of only the latest. That lets you answer questions like which segment a customer belonged to when they placed an order. Keep in mind the Beta caveat below: tables with semi-structured columns can't use it.

What are the Beta limitations you should plan around?

Most of these are reasonable for a Beta connector, but a few can surprise you in production. The table below collects them from the overview, limitations, and troubleshooting pages.

Limitation	What it means in practice
39 prebuilt tables only; no custom metafields or reports	Stores that model key data in metafields need a separate path for those fields
`locations`, `shop`, `collects`, `disputes`, `countries`, `collection_product`, and `inventory_level` aren't incremental	Every run re-ingests these tables in full, so watch runtime and cost on frequent schedules
No SCD Type 2 on tables with VARIANT columns	Plan history tracking table by table, not as a blanket setting
Schema evolution handles new and deleted columns, but not type changes	A type change upstream needs manual handling
Column renames require a full refresh	Budget time for a re-sync when Shopify renames a field
Adding a column later doesn't backfill it	Run a full refresh on that table if you need its history
Renaming a destination table makes the pipeline API-only	Decide naming up front if your team relies on the UI
No API-based row filtering	You ingest whole tables and filter downstream
Alerts on scheduled pipelines fire on the next update, not immediately	Don't use pipeline alerts as real-time incident monitoring

Two more points deserve attention.

Protected customer data. The setup guide notes that some customer and order fields are protected customer data, and Shopify only returns them from non-development stores once the app meets its protected customer data requirements. If email or address fields come back empty in production but not in development, this is the likely cause. Once those fields do arrive, treat them as PII from day one. Unity Catalog's attribute-based access control can mask columns such as email and phone, and Databricks added metastore-level ABAC policies in Beta this month, so one masking rule can cover every catalog. Doing this before analysts get access is far easier than retrofitting it for GDPR requests later.

Rate limits. Shopify rate limits its GraphQL Admin API by query cost, with limits that depend on your plan. According to the troubleshooting guide, the connector waits and retries automatically when it's throttled. That's convenient, but other apps on the same store share that budget. A heavy backfill during peak trading hours can slow down other integrations, so schedule the first sync for a quiet period.

When should you still build a custom Shopify pipeline?

The managed connector should be your default for analytics ingestion. It removes a lot of code you'd otherwise have to maintain, and it gets governance right from the start. But it solves one problem well, and some requirements sit outside it.

Requirement	Managed connector	Custom pipeline
Scheduled analytics on core Shopify objects	Best fit	Unnecessary effort
Metafield-heavy data models	Not covered	Needed for those fields
Reacting to events within seconds (order confirmations, fraud checks)	Scheduled syncs	Webhooks with a queue
Writing data back to Shopify	Read-only	Required
Logic across many stores, such as shared catalogs	One connection per store	Often simpler to own

In practice, many teams will end up with a hybrid. The connector handles bulk analytics ingestion, and a small custom service handles metafields or real-time event reactions. If you've built webhook pipelines before, the reliability checks in our Shopify webhook debugging checklist still apply to that second half. The only difference is that your service no longer has to double as your analytics pipeline.

Where the boundary sits depends on the store. It comes down to how much of the data model lives in metafields, how fresh the data needs to be, and how many stores are involved. That trade-off analysis is most of what Lucent works through with commerce clients as a Databricks-focused data engineering company, and it's worth doing on paper before writing any pipeline code, whoever builds it.

How should you roll this out safely?

Because the connector is in Beta, treat the rollout as a staged migration rather than a switch.

Enable the preview in a non-production workspace first. Confirm the tables, scopes, and backfill behavior before production depends on them.
Request read_all_orders early if historical reporting matters.
Run both pipelines in parallel if you're replacing a custom one. Compare row counts and key totals for a week or two before retiring the old pipeline, and keep it available as a rollback until the numbers match.
Apply PII masking before granting analyst access, not after.
Pin the pipeline in a bundle so every change goes through code review. The Shopify connector removes the least interesting part of commerce analytics: extraction code that breaks whenever an API changes. What's left is the valuable work of modeling revenue correctly, protecting customer data, and deciding what really needs to be real time.

Are you planning to move an existing Shopify pipeline onto the managed connector, or keep a hybrid setup? I'd especially like to hear from anyone whose store relies heavily on metafields, since that's the gap I expect most teams to hit first.

Claude Opus 5.5 Is Now on Google Cloud, and I Think It's a Big Deal for Developers

Lucy — Wed, 23 Sep 2026 06:38:26 +0000

Anthropic released Claude Opus 5.5 this week, and it's available on Amazon Web Services, Google Cloud, and Microsoft Azure from day one. Google has also published its own model page for it. I spent some time going through the announcement and the Google Cloud docs, and this release stands out to me for one simple reason: it's more capable and cheaper at the same time. Here's what caught my attention and what you should know before you try it.

It's a big jump in capability

Opus 5.5 is the first model in the new Claude 5.5 family. Anthropic says it performs at the level of Claude Fable 5.1 on most work and costs 40% less to run than Opus 5. That's notable because Fable sits in Anthropic's higher, more expensive tier.

The benchmark numbers back this up. On Terminal-Bench 4.0, which tests multi-step tasks in a command line, Opus 5.5 scores 66.4%, compared with 55.8% for Fable 5.1 and 52.3% for Opus 5. Anthropic does add a fair caveat: at this level of capability, benchmark margins have become a less reliable guide to real-world differences.

The pricing is what excites me most

Input and output tokens now cost $4 and $20 per million, 20% less than Opus 5. Cache reads, which make up most of the cost in agentic and coding work, are $0.20 per million tokens, 60% cheaper than before. It also generates output more than 30% faster than Opus 5.

The savings add up because it also uses fewer tokens per task. Lower price per token plus fewer tokens nets out to a 40% cost drop.

One note: these are Anthropic's list prices. Google Cloud bills Claude usage through its own generative AI pricing page, so check the rates for your region before estimating costs.

It's built for long engineering work

Anthropic says Opus 5.5 is especially good at long, sprawling jobs like codebase-wide migrations and audits. A few examples from the announcement:

One early tester audited and fixed a 200,000-line codebase in under three hours, where Opus 5 took more than 20 hours and used 2.5x as many tokens.
In an internal test, Opus 5.5 and Fable 5.1 both translated HAProxy from C to Rust. Opus 5.5 finished in 9.5 hours versus 12 for Fable 5.1, at 51% lower cost.
When asked to cut load times across every page of a web app, Opus 5.5 succeeded 39 out of 40 times.

Its writing is clearer

This is a quieter change, but I think developers will appreciate it. Anthropic says Opus 5.5 puts the most important information first, is less likely to use jargon, and follows the writing rules you give it. If you've ever tried to review a long, rambling agent summary at the end of the day, you'll know why this matters.

Why I'd use it through Google Cloud

If your team already runs on Google Cloud, this is the easiest way in. You keep your existing IAM, billing, and monitoring, and you get data residency options: multi-region endpoints that route dynamically within the US or EU, or regional endpoints that guarantee routing through a specific region.

It's also useful for planning that Google lists the model's retirement date as no sooner than September 22, 2027, so you can build on it knowing it won't disappear anytime soon.

Getting started looks straightforward. First, install the SDK with Google Cloud support:

pip install -U "anthropic[vertex]"

Then enable the model in Model Garden, authenticate with Application Default Credentials (gcloud auth application-default login), and make a call:

import os
from anthropic import AnthropicVertex

# Keep the project ID in an environment variable, not in code
client = AnthropicVertex(
    project_id=os.environ["GCP_PROJECT_ID"],
    region="us",  # multi-region: "us" or "eu"
)

message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hey Claude!"}],
)
print(message.content[0].text)

If you call the REST API directly instead of using the SDK, there are two differences from Anthropic's own API: the model is specified in the endpoint URL rather than the request body, and anthropic_version goes in the body with the value vertex-2023-10-16. Anthropic's Claude on Google Cloud guide walks through the full setup.

Swapping the model ID is the easy part. The bigger work is usually fitting a new model into the systems around it: prompts, evals, cost monitoring, and fallbacks. That's the area our team focuses on in LLM development and integration, and it's where I'd spend most of the testing time before any switch.

Things to check before switching

Thinking is always on. Opus 5.5 can no longer be used with thinking switched off. If your integration disables it today, update that first.
Some requests are routed to other models. Opus 5.5 ships with safeguards similar to Fable 5.1's for cybersecurity, biology, and distillation, and these fall back to another model transparently. Routine bug finding and fixing still works normally, but most other cybersecurity tasks are re-routed to Opus 4.8.
Test in staging first. Whatever model you're moving from, run your own prompts and evals in a staging environment before switching production traffic.

Final Verdict

Anthropic says Claude Sonnet 5.5 and Claude Haiku 5.5 will follow in the coming weeks, with many of the same improvements to performance, efficiency, and safety. If those smaller models get similar efficiency gains, it'll be a very good few months for anyone building with AI.

I'm planning to try Opus 5.5 on our own workloads soon, and I'll share what I find in a follow-up post. Have you tried it yet? Let me know in the comments what you're building with it.

Official sources

Introducing Claude Opus 5.5 (Anthropic)
Claude Opus 5.5 on Google Cloud (Google Cloud docs)
Claude on Google Cloud setup guide (Anthropic docs)
Claude Opus 5.5 System Card (Anthropic)
Claude Opus 5.5 is now available on Google Cloud (Google AI on dev.to)

Running AWS-Backed Migrations Into Shopify Plus: A Technical Overview

Lucy — Wed, 16 Sep 2026 09:35:55 +0000

Direct answer: Once a catalog crosses roughly 50,000 SKUs, or the source system is a custom ERP rather than a standard cart, CSV imports and off-the-shelf migration apps stop being a data problem and start being a rate-limit and reconciliation problem. The fix isn't a bigger export file. It's treating the migration as a real ETL pipeline: extract with change data capture so the source stays live, stage and validate in S3, and load through Shopify's asynchronous Bulk Operations API instead of looping calls against the Admin API. This post walks through that architecture and where it breaks down at different scales.

Why the standard Shopify Plus migration path stops working at scale

Most Shopify Plus migrations start the same way: export CSVs from the old platform, clean them in a spreadsheet, and either run Shopify's native import or a migration app like Matrixify. That works fine for a few thousand SKUs with simple variant structures.

It stops working for two structural reasons, not just volume.

First, the Shopify Admin API is rate-limited by design, and the limit is enforced per shop regardless of which tool is calling it. Per Shopify's current API rate limit documentation, the GraphQL Admin API uses a calculated query-cost model: a Shopify Plus store restores 1,000 cost points per second against its bucket, versus 100 for a standard plan, and the REST Admin API caps Plus stores at 20 requests per second versus 2 for a standard plan. A migration app doesn't get a special exemption from this. If your product-plus-metafield-plus-variant graph requires four or five API calls per SKU, a six-figure catalog will take the better part of a week to load serially, and that's before retries.

Second, CSV round-trips lose structure. Metafields, metaobjects, B2B catalog assignments, and multi-location inventory don't map cleanly onto flat rows, so teams end up hand-patching data after import, which is exactly where SKUs go missing or price rules apply to the wrong customer group.

The practical implication: once you're migrating a catalog that's large, deeply structured, or sourced from a system with no clean export tool (a custom ERP, a legacy PIM, a headless commerce backend), the migration needs an actual extraction and transformation layer sitting in front of Shopify, not a spreadsheet.

What an AWS-backed migration pipeline actually looks like

The shape of this is closer to a data engineering pipeline than a website migration:

[Legacy DB / ERP / PIM]
        |
        v
  AWS DMS (full load + CDC)  ---->  Amazon S3 (raw zone)
        |
        v
  AWS Glue / Lambda (transform, dedupe, map schema)
        |
        v
  Amazon S3 (validated zone) ---->  reconciliation checks
        |
        v
  JSONL build (products, variants, metafields, customers, orders)
        |
        v
  Shopify staged upload  ---->  bulkOperationRunMutation
        |
        v
  Shopify Plus store (staging, then production)

Each arrow in that diagram is a place teams lose data if it's skipped, which is really the argument for building it this way rather than scripting a one-off exporter.

Extraction (AWS DMS). Rather than taking the source database offline for a bulk export, AWS DMS performs a full load of existing records and then switches to change data capture (CDC), continuously replicating inserts, updates, and deletes from the source until you're ready to cut over: the source database stays operational throughout, and the target stays synchronized for as long as you need before you switch over. That matters specifically for commerce migrations because orders and inventory keep changing during the weeks a large migration takes to build and test, so you can't just freeze the source system.

Staging and transformation (S3, Glue, Lambda). Raw extracted data lands in an S3 "raw zone" untouched, then a transform layer (Glue, a serverless data integration service with no infrastructure to provision, for anything approaching bulk ETL, paired with Lambda for lighter per-record logic) reshapes source rows into Shopify's object model: variant option combinations, metafield namespaces, customer-to-company relationships for B2B. AWS's own reference pattern for this kind of pipeline explicitly separates validation, transformation, and partitioning into distinct orchestrated steps with automated retry and error handling. It's worth copying directly, because "transform" and "validate" being separate steps is what lets you catch bad data before it reaches Shopify rather than after.

Orchestration (Step Functions or EventBridge). A migration isn't one job, it's a dependency graph: customers before orders, products before variants, collections before the products that reference them. Step Functions state machines make that sequencing and its error handling visible and restartable at the step that failed, rather than needing to rerun an entire script.

Loading into Shopify: bulk operations, not a request loop

This is the step where AWS-side engineering meets Shopify-side engineering, and it's the one most agencies underbuild.

Shopify's Bulk Operations API is built for exactly this case: instead of one GraphQL mutation per record, you upload a single JSONL file where each line holds one mutation's variables, reserve the upload target with stagedUploadsCreate, then run bulkOperationRunMutation against the uploaded file, and Shopify executes every line asynchronously in the background. This entirely bypasses the per-request rate limit that would otherwise throttle a six-figure catalog load.

A minimal shape of the mutation that kicks off the import:

mutation {
  bulkOperationRunMutation(
    mutation: "mutation call($input: ProductInput!) { productCreate(input: $input) { product { id } userErrors { field message } } }"
    stagedUploadPath: "tmp/4/bulk-op-inputs/product-import.jsonl"
  ) {
    bulkOperation {
      id
      status
    }
    userErrors {
      field
      message
    }
  }
}

Two constraints worth designing around from day one: per Shopify's own API reference, only one bulk mutation operation can run at a time per shop (a bulk query can run alongside it, but not another bulk mutation), and result files are only available for seven days after the operation completes, so your validation step needs to run promptly rather than "whenever someone gets to it." Neither of these is a big deal if you planned for a sequential pipeline; both cause real problems if your Step Functions state machine assumed it could parallelize product and variant loads freely.

The validation layer that actually prevents launch-day surprises

The failure mode nobody plans for isn't "the migration failed." It's "the migration succeeded and the numbers are quietly wrong." A price rule applies to the wrong customer group. Three thousand SKUs land without their images because the CDN path changed casing. Order history imports but loses the tax line because the source system stored tax differently than Shopify's tax model expects.

This is where having the migration built on a real data engineering stack pays off, because reconciliation is a data problem, not a migration-app checkbox. A working validation pass typically checks:

Row-count parity: does the object count in Shopify's bulk operation result match the row count in the source extract, per object type
Referential integrity: does every variant resolve to a real product, every order to a real customer, every metafield to a defined definition
Sampled field-level diffing: pull a random sample of records post-load and diff key fields (price, inventory quantity, SKU) against the source of truth, not just spot-check the ones that are easy to eyeball
Business-rule checks specific to the store: B2B price list assignment, subscription contract continuity, multi-location inventory splits None of this is exotic. It's the same reconciliation discipline used in a data warehouse load, applied to a commerce migration instead. The teams that skip it are the ones that find the discrepancy from a customer support ticket three weeks after go-live.

Cutover: the part where architecture becomes a business decision

Because DMS is running CDC rather than a one-time dump, the technical cutover moment is genuinely small, often measured in minutes rather than hours, since the target has been kept in sync continuously and the source can remain operational until you choose the switchover moment. But "small technical window" and "safe business cutover" aren't the same thing.

A cutover plan that holds up under pressure usually includes:

a defined freeze window for order-affecting writes on the source system, even if it's brief
a final CDC catch-up and reconciliation pass immediately before DNS/storefront cutover
a rollback path that doesn't require re-running the entire migration; usually this means keeping the old platform live and read-only for a defined window, not decommissioning it on day one
a named owner for the go/no-go decision, separate from the engineer running the migration The architecture buys you a short technical window. It doesn't remove the need for a plan if something is wrong when that window opens.

When you actually need this versus when a migration app is enough

Building DMS, S3, Glue, and Step Functions into a migration is real engineering overhead. It's not the default answer for every store moving to Shopify Plus.

Signal	Migration app / CSV is probably fine	AWS-backed pipeline is worth it
Catalog size	Under ~20,000 SKUs, simple variants	50,000+ SKUs, or complex variant/metafield structure
Source system	Standard cart (WooCommerce, BigCommerce, Magento with clean export)	Custom ERP, in-house PIM, or a system with no reliable bulk export
Order/inventory activity during migration	Can tolerate a short freeze window	Needs to stay live and transacting throughout the build
Data model complexity	Flat product catalog	B2B pricing, multi-location inventory, subscriptions, metaobjects
Historical data	Products and current inventory only	Full order history, customer accounts, and audit trail required

If you're in the left column, a well-run migration app project is faster and cheaper than standing up a DMS pipeline for its own sake. The pipeline earns its cost when the source system itself is the obstacle, not just the volume of rows.

What to test before you commit to an architecture

Before scoping a migration this way, it's worth running a small proof of concept rather than committing the full build:

Extract a representative slice (a few hundred SKUs with your messiest variant structure, not your cleanest ones) and run it end to end through the pipeline
Confirm the Bulk Operations import actually preserves the metafield and variant relationships you need. This is the step that most commonly reveals schema-mapping gaps
Time a DMS CDC catch-up under realistic write volume, not idle volume, to get a real cutover-window estimate
Decide your rollback trigger conditions in writing before go-live, not during an incident If that proof of concept surfaces more schema-mapping problems than rate-limit problems, that's a useful signal that the bottleneck was never really the API. It was the data model, and no amount of AWS infrastructure fixes a data model problem on its own. That's usually the point where it's worth bringing in a team that's done the Databricks-and-data-engineering side of this as often as the Shopify side, since Lucent Innovation's Shopify migration team works both ends of that pipeline rather than treating the AWS layer as an afterthought.

The short version

CSV imports and migration apps are the right tool until the source system or the catalog size makes them the bottleneck. Past that point, the pipeline that actually holds up looks like a data engineering job: CDC-based extraction so the source stays live, S3 as a staging and audit layer, Glue or Lambda for transformation, Step Functions for sequencing, and Shopify's Bulk Operations API, not a request loop, for the load itself. The architecture doesn't remove the need for reconciliation or a real cutover plan. It just gives you a pipeline where those things are possible to do properly instead of bolted on after the fact.

What's the largest catalog or messiest source system you've had to move onto Shopify Plus, and did the migration tooling hold up?

How to Fix Shopify POS and EDC Terminal Reconciliation Mismatches

Lucy — Tue, 08 Sep 2026 11:22:35 +0000

If your cashiers ring up the sale in Shopify POS and then key the same total into a separate EDC card terminal by hand, you already have two systems of record for the same transaction. This post walks through why that gap opens up, which integration model actually closes it, and what the API calls, webhook handling, and reconciliation logic look like when you build the bridge yourself.

Why Shopify POS and EDC Terminals Fall Out of Sync

Most retail counters running Shopify POS alongside a third-party EDC (Electronic Data Capture) terminal are running two independent systems that were never designed to talk to each other. The cashier totals the cart in Shopify POS, then re-enters that same amount on the terminal keypad, selects a payment mode, and waits for the customer to tap or insert a card.

At that point, two separate ledgers exist. Shopify has an order that is either unpaid or manually marked paid. The terminal has its own batch report with its own transaction ID, sitting in a completely different system. Nothing links the two unless a human writes the terminal's transaction ID onto a receipt or into an order note, and in practice, a lot of stores skip that step entirely because there's no fast way to do it at the counter under a queue of customers.

This is a known pattern in payments infrastructure, not a Shopify-specific quirk. Payment providers generally describe two ends of a spectrum: standalone terminals that process a card with zero coding effort but leave order and payment data unlinked, and integrated (or cloud) terminals that require an API integration but keep the two systems aligned automatically, as Airwallex's integrated terminal documentation lays out. Most EDC-based retail counters are running the standalone version today, and the reconciliation cost of that choice tends to stay invisible until someone adds up the hours.

Three Integration Models, and Why the Model You Pick Decides Your Reconciliation Story

Before writing a line of integration code, it's worth naming which model you're actually building toward, because each one has a different blast radius for PCI scope and engineering effort.

Model	How payment data flows	Reconciliation	Typical fit
Standalone terminal	Cashier re-keys the amount; terminal and POS never talk	Fully manual, batch report vs. order list	Single-location, low volume
Semi-integrated terminal	POS sends the amount and receives a result; card data stays on the terminal, out of the POS app	Automatic per-transaction match	Multi-location retail, the common target for EDC bridges
Fully integrated terminal	POS or its backend handles more of the payment flow directly with the processor	Automatic, tightest coupling	Vertical SaaS or processor-owned hardware

Semi-integration is the model most Shopify POS and EDC bridges land on, and for good reason. As Datatel Systems explains, a semi-integrated setup treats the terminal as the thing that actually touches card data, while the POS only ever sees an amount request and a result, which keeps sensitive data away from the POS application entirely. This is also the model that maps cleanly onto Shopify's own extension points, since the integration layer just needs to relay a request and listen for a confirmation, not process a card itself.

What Closing the Gap Looks Like at the API Level

Once the terminal confirms a payment, the job is to get that confirmation back into Shopify without a human re-typing anything. Shopify's Admin GraphQL API gives you two mutations built for exactly this kind of external payment record.

orderMarkAsPaid is built for orders where the outstanding balance needs to be cleared based on a payment that happened outside Shopify's standard checkout, which is precisely the situation once an EDC terminal confirms a card charge. According to Shopify's own mutation reference, the mutation either creates a new sale transaction for the full outstanding amount or captures an existing authorized transaction, and it updates the order's financial status once it succeeds.

mutation MarkOrderPaid($input: OrderMarkAsPaidInput!) {
  orderMarkAsPaid(input: $input) {
    order {
      id
      displayFinancialStatus
    }
    userErrors {
      field
      message
    }
  }
}

{
  "input": {
    "id": "gid://shopify/Order/820982911946154508"
  }
}

If you need to record the terminal's own transaction ID, timestamp, or payment method label alongside the payment rather than just flipping a status, orderCreateManualPayment is the better fit. It lets you pass an amount, a method name, and a processedAt timestamp, which matters if your webhook arrives a few seconds after the actual charge and you want the order's payment record to reflect when the customer's card was actually charged, not when your server got around to processing the event.

A Reference Architecture for the Bridge

The actual bridge is a small, boring service that sits between the EDC provider's webhook or SDK callback and Shopify's Admin API. A minimal version looks like this in Node.js:

const express = require('express');
const app = express();
app.use(express.json());

// Prevent double-processing if the provider retries the same event
const processedEvents = new Set();

app.post('/webhooks/edc-terminal', async (req, res) => {
  const { transactionId, orderId, amount, status } = req.body;

  if (processedEvents.has(transactionId)) {
    return res.status(200).send('already processed');
  }

  if (status !== 'approved') {
    // Log declines and cancellations for the reconciliation log,
    // but don't touch the Shopify order.
    return res.status(200).send('logged, no action needed');
  }

  try {
    await markShopifyOrderPaid({ orderId, transactionId, amount });
    processedEvents.add(transactionId);
    res.status(200).send('reconciled');
  } catch (err) {
    // Don't swallow the error. A missed webhook here is exactly
    // the gap this whole integration exists to close.
    console.error('reconciliation failed', transactionId, err);
    res.status(500).send('retry me');
  }
});

app.listen(3000);

Three things in that snippet matter more than they look:

Idempotency isn't optional. EDC providers commonly retry webhook delivery if they don't get a fast 200 response, and calling orderMarkAsPaid twice against the same order will surface a user error since the mutation checks that the order isn't already PAID, per the Order object's canMarkAsPaid field. A transaction-ID set (or a database table in production) avoids duplicate processing.
Declines and cancellations still need to be logged, even though they shouldn't touch the Shopify order. This is what makes the eventual reconciliation log complete instead of only showing successful payments.
Failures should return a 5xx, not swallow the error. If your bridge silently eats a failed API call, you've recreated the exact manual-matching problem this integration was built to remove, just one layer further from the counter where it's harder to spot. ## Where PCI Scope Actually Sits in This

A fair question from anyone reviewing this kind of integration is whether it touches cardholder data. It shouldn't, and if it does, the design needs to change before it ships.

In a semi-integrated model, the terminal captures and encrypts the card data itself, and the POS-side integration only ever sees an amount, a status, and a transaction reference. This is the architectural basis for PCI DSS scope reduction: as the PCI Security Standards Council notes in its own FAQ, devices that support Secure Reading and Exchange of Data can facilitate scope reduction for merchants when used as part of a validated point-to-point encryption solution, though a terminal being PTS-approved doesn't automatically guarantee that reduction on its own. The details vary by provider and by how the merchant's environment is segmented, which is why Adyen documents the reconciliation and payment-intent flow separately from card capture in its own point-of-sale API reference. The practical takeaway for anyone building this bridge: keep raw card data entirely off your server, treat the webhook payload as amount-and-status only, and confirm with the EDC provider exactly what their webhook or callback does and doesn't include before you write a single handler.

Common Mistakes When Teams Build This Themselves

A few patterns show up repeatedly in bridges like this, and most of them trace back to treating the integration as a one-off script instead of infrastructure.

No retry or dead-letter handling. A webhook that fails once and is never retried recreates the manual-matching problem for exactly the transactions that mattered enough to fail.
Assuming one terminal provider forever. Multi-location chains often run different EDC hardware in different regions. Building the bridge around a single provider's payload shape instead of a normalized internal event format makes adding a second provider a rewrite instead of a config change.
Skipping the reconciliation log. The API calls above solve the order-status half of the problem. The other half is a queryable log of every terminal event, successful or not, with order, store, provider, amount, status, and timestamp, so a finance team can filter by date range or location instead of stitching together exports by hand.
No plan for refunds. Getting a payment confirmation back into Shopify automatically is the first milestone, not the whole project. Refund flows initiated from the terminal side need the same kind of bridge in reverse, and teams that skip this end up back to manual reconciliation the moment a customer asks for money back. ## What "Good" Reconciliation Looks Like Once It's Live

Once the bridge is running, the operational difference is straightforward to describe: every terminal transaction, across every store and every provider, lands in one place with the same fields, instead of living in separate batch reports that someone has to manually cross-reference. A useful minimum schema for that log looks like this:

Field	Why it matters
Order ID	Links the terminal event back to the exact Shopify order
Store / location	Needed once you're past a single counter
Provider	Matters the moment you run more than one EDC vendor
Amount	The number that actually needs to match, transaction by transaction
Status	approved, declined, cancelled, or error, not just "paid"
Timestamp	Traces disputes back to a specific charge, not just a day

We wrote up how this played out for a real multi-location retailer, including what the manual process was actually costing them before the fix, in our case study on closing the Shopify POS and EDC terminal reconciliation gap. If you're evaluating whether this is worth building in-house versus bringing in a team that's done it before, that write-up covers the actual before-and-after numbers. For teams earlier in the process, still deciding on the underlying Shopify build before tackling hardware integrations, a broader look at what a custom Shopify development engagement typically covers is a reasonable next stop.

Reconciliation gaps like this rarely get fixed because nobody logs a single incident bad enough to justify the project. It's a few minutes here, a mismatched batch there, a slower month-end close, spread thin enough that it never tops anyone's priority list on its own. But once you can name the exact API calls and webhook shape that close it, it stops being an ops tax and becomes a two-to-four week engineering project.

Have you built (or inherited) a POS-to-payment-terminal bridge like this? What broke first once it hit production, webhook retries, idempotency, or something else nobody planned for? Curious to hear how other teams handled it.

Shopify GraphQL Rate Limits: A Query-Cost Optimization Guide

Lucy — Wed, 26 Aug 2026 13:06:24 +0000

Shopify's GraphQL Admin API does not limit you by how many requests you send. It limits you by how much each request costs. A query that asks for ten cheap fields can run far more often than one that asks for three expensive ones, and once you understand the cost formula, most 429 errors stop being a mystery and start being a math problem.

This guide breaks down how the cost model works. You'll learn how to read the numbers Shopify sends back with every response, and which query patterns quietly burn through your rate limit budget. It also covers when to stop optimizing a query and switch to a bulk operation instead.

Why Shopify moved away from counting requests

The REST Admin API charged a flat fee per call. A request for one product field cost the same as a request for fifty. That model was simple, but it rewarded sloppy queries and punished apps that made frequent small calls for good reasons, like polling a webhook queue.

Shopify has been unwinding REST in favor of GraphQL for a few years now. The REST Admin API became a legacy API on October 1, 2024, and starting April 1, 2025, every new public app submitted to the Shopify App Store has to run on GraphQL only, according to Shopify's developer changelog. Existing apps can keep calling REST for now, but new builds do not have that option. If you are scoping a new Shopify app in 2026, the query cost model is not an edge case to learn later. It is the rate limit you will live under from day one.

GraphQL made this different approach possible in the first place. The server can look at a query's shape before it runs and estimate the work involved, something a REST endpoint can't do. Shopify's engineering team wrote about the reasoning behind this shift in a detailed post on calculating GraphQL query complexity. It's worth reading for the full backstory.

How the cost model works

Shopify's GraphQL Admin API uses what it calls a calculated query cost, enforced through a leaky bucket. Picture a bucket that fills up as you make requests and drains at a steady rate every second. Send too many expensive queries too fast and the bucket overflows, and you get throttled until it has room again.

Every field in the schema carries a cost. According to Shopify's official API limits documentation, the defaults break down like this:

Field type	Cost
Scalar (string, int, boolean, etc.)	0
Enum	0
Object	1
Interface	Maximum of possible selections
Union	Maximum of possible selections
Connection (edges/nodes list)	Sized by `first` or `last` argument
Mutation	10

Two things jump out from that table. First, plain scalar fields are free, so asking for a product's title, handle, and status does not move the needle. Second, connections scale with how many items you request, and mutations carry a flat cost of 10 points regardless of how simple the write is, because a mutation triggers side effects like database writes and webhook dispatches that a read never does.

Your rate limit itself depends on your store's plan. Shopify's limits page lists these figures for the GraphQL Admin API:

Plan tier	Points restored per second
Standard (Basic and Shopify plans)	100
Advanced Shopify	200
Shopify Plus	1,000
Shopify for enterprise (Commerce Components)	2,000

No matter which tier you are on, a single query cannot exceed 1,000 points. That cap is enforced before the query runs, based on its requested cost, so a query that would cost 1,200 points gets rejected outright rather than partially executed.

Reading the cost data Shopify sends back

Every GraphQL Admin API response includes an extensions block. It tells you exactly what happened with your query's cost. Most developers skip this part of the response, right up until they're debugging a production incident at 2 a.m.

"extensions": {
  "cost": {
    "requestedQueryCost": 101,
    "actualQueryCost": 46,
    "throttleStatus": {
      "maximumAvailable": 1000,
      "currentlyAvailable": 954,
      "restoreRate": 50
    }
  }
}

Two numbers matter here. The requestedQueryCost is what Shopify estimated before running your query, based on the fields you asked for and the first/last arguments on any connections. The actualQueryCost is what it really cost once the query finished, and it is often lower, because a connection you asked to return 50 items might have only returned 12. Shopify refunds the difference back to your bucket automatically, so over-requesting a first argument is not free, but it is not as expensive as it looks either.

Want a field-by-field breakdown of where the cost comes from? Add the header Shopify-GraphQL-Cost-Debug: 1 to your request. The response then includes a fields array. It shows the cost each part of the query adds. This is the fastest way to find the one nested connection quietly eating your whole budget.

When a query costs more than your bucket can currently cover, you get an error back. The code is either MAX_COST_EXCEEDED or a general throttle response. Either way, the throttleStatus object tells you how many points you have left and how fast they're coming back. That's everything you need to build a sane retry.

Query patterns that quietly cost more than they should

A few habits are responsible for most of the throttling issues teams run into.

Unbounded or overly generous connections. Every edges { node { ... } } block gets sized by its first or last argument. Asking for first: 250 on a connection you only display 20 items from wastes budget on data you throw away. Request only what the page or job actually needs, and paginate deliberately instead of grabbing the maximum allowed size out of habit.

Deep nesting. Think about a query that pulls a product, then its variants, then each variant's inventory levels, then each location for those levels. Cost multiplies at every layer. Nesting isn't free just because each object only costs 1 point on its own. Flatten what you can. If a nested branch is optional data, split it into a second, shallower query instead.

Fetching fields you don't render. It's tempting to grab a wide product fragment once and reuse it everywhere, including screens that only need the title and price. Build narrower, purpose-specific fragments instead of one large one, especially for high-frequency queries like search-as-you-type or cart updates.

Chaining mutations without batching. Since every mutation costs a flat 10 points, updating 50 products one mutation at a time costs 500 points before you've touched a single connection field. Where Shopify offers a bulk-capable mutation for the operation you need, use it. Where it doesn't, queue the writes and pace them against your restore rate instead of firing them concurrently.

A useful habit: run new queries through the GraphiQL app in your Partner Dashboard first and check the extensions.cost block before you ship them. It's the cheapest testing you'll ever do.

When to stop optimizing and use a bulk operation instead

At some point, no amount of query tuning gets a large export under the 1,000-point single-query cap. Pulling every product, variant, and inventory level for a catalog of 50,000 SKUs is that kind of job. Forcing it through paginated single queries just means more requests, more throttling, and more code to manage the pacing.

Shopify's bulk operations API exists for exactly this case. You submit a query wrapped in a bulkOperationRunQuery mutation, Shopify processes it asynchronously in the background, and when it finishes, you get a URL to a JSONL file with every result. Bulk operations don't count against the query-cost rate limit at all, because they run outside the normal request path.

mutation {
  bulkOperationRunQuery(
    query: """
    {
      products {
        edges {
          node {
            id
            title
            variants {
              edges {
                node {
                  id
                  sku
                  inventoryQuantity
                }
              }
            }
          }
        }
      }
    }
    """
  ) {
    bulkOperation {
      id
      status
    }
    userErrors {
      field
      message
    }
  }
}

Here's a simple rule of thumb. If you're pulling more than roughly 1,000 records, reach for a bulk operation. The same goes for any connection nested more than two levels deep across a full catalog. Don't just reach for a bigger first argument instead. Bulk operations trade a little speed, since results aren't instant, for a rate limit ceiling that basically disappears.

Building a retry strategy that respects the restore rate

A backoff strategy that ignores throttleStatus is guessing. One that reads it is calculating.

async function shopifyGraphQL(query, variables) {
  const res = await fetch(SHOPIFY_ENDPOINT, {
    method: "POST",
    headers: adminHeaders,
    body: JSON.stringify({ query, variables }),
  });
  const data = await res.json();

  const throttle = data.extensions?.cost?.throttleStatus;
  const wasThrottled = data.errors?.some(
    (e) => e.extensions?.code === "THROTTLED"
  );

  if (wasThrottled && throttle) {
    const needed = data.extensions.cost.requestedQueryCost;
    const deficit = needed - throttle.currentlyAvailable;
    const waitMs = Math.ceil(deficit / throttle.restoreRate) * 1000;
    await new Promise((r) => setTimeout(r, waitMs));
    return shopifyGraphQL(query, variables);
  }

  return data;
}

This code isn't production-ready as written. A real version needs a retry limit, so it doesn't loop forever. It also needs some randomness in the wait time, so a whole fleet of workers doesn't wake up at the exact same moment and cause a new spike. But the core idea holds up: calculate the wait time from the real restore rate instead of guessing a fixed delay. Shopify recommends a one-second minimum backoff before any retry. Building your queue around the actual restore rate, instead of a flat delay, keeps your throughput closer to your true ceiling.

Where this fits into a bigger Shopify app build

Query cost discipline matters most once an app moves past a prototype. It matters the moment you start syncing real catalog volume, inventory, or order data on a schedule. This is one of the first things worth planning for. It shouldn't be a patch you add after the first wave of 429 errors hits production. On the custom Shopify app builds our team scopes, cost-aware pagination and bulk operations tend to be a default part of the data layer. It sits right alongside authentication and webhook handling, not as a cleanup task for later.

FAQ

What does a MAX_COST_EXCEEDED error mean in Shopify's GraphQL API?
It means the requested cost of a single query is over the 1,000-point cap that applies to every plan. The fix is almost always to lower the first/last values on connections or split the query, not to wait longer, since waiting won't help a query that could never fit.

Does having a large currentlyAvailable balance let me exceed the 1,000-point single-query cap?
No. The 1,000-point limit applies per query regardless of how much capacity is sitting in your bucket. A store with 10,000 points available still can't run a single query that costs more than 1,000.

Is the Storefront API rate-limited the same way?
No. Real buyer traffic on the Storefront API doesn't hit a fixed points limit. Shopify does throttle automated bot and crawler traffic on that API, according to the official limits documentation.

Do REST Admin API rate limits still matter if I'm migrating to GraphQL?
Only for as long as your app keeps making REST calls. Since new public apps have been required to use GraphQL exclusively since April 1, 2025, most new builds skip REST rate limits entirely and only need to design around the query-cost model from the start.

Can I request a higher GraphQL rate limit for my app?
Outside of moving to a higher Shopify plan tier, Shopify doesn't offer a general way to raise the per-app limit. The better lever is almost always reducing cost per query and offloading large reads to bulk operations.

What's the most stubborn 429 you've had to chase down in a Shopify integration, and did the fix end up being a query rewrite or a queue redesign? Drop it in the comments.

Architecting Reliable Bulk Variant Sync for Multi-Store Shopify Setups

Lucy — Tue, 18 Aug 2026 12:12:42 +0000

Running one Shopify store is hard enough. Running five, twenty, or a hundred of them, all sharing one catalog, is a different kind of hard.

Somewhere around store number three, a merchant's team usually hits the same wall. A color variant added in one store doesn't show up in another. A price update lands on nine out of ten storefronts. A "quick script" that worked fine last quarter starts throwing errors nobody wrote down.

This isn't a coding problem. It's an architecture problem. Bulk variant sync across multiple Shopify stores has to be treated like a distributed system, because that's exactly what it is.

What Bulk Variant Sync Actually Means

Multi-store Shopify setups usually exist for a real business reason. A brand might run separate storefronts per region, per wholesale channel, or per sub-brand.

Each store has its own product catalog, its own variant structure, and its own API rate limit. None of them know the others exist.

Bulk variant sync is the process of keeping variant data such as color, size, material, and price consistent across all of those independent catalogs, usually pushed out from one canonical source of truth.

Shopify's own variant ceiling per product has moved over time, climbing from a long-standing 100-variant cap toward higher limits as newer API versions roll out. That single detail already shapes how a sync system needs to batch its writes.

Picture a fashion brand running one storefront for direct-to-consumer traffic, a second for wholesale buyers, and a third for a regional market. A single new color, added to the master catalog, has to land correctly on all three, in the right currency, with the right option structure, without anyone re-typing anything by hand.

Why Naive Sync Scripts Break First

Most sync systems start life as a simple script. Loop through products, call the API, move to the next one. This works fine in testing.

Under real load, three things go wrong at once.

First, rate limits start rejecting requests, and a script with no backoff logic just keeps hammering an API that already said no.

Second, a request fails halfway through a batch. There's no clean way to tell which variants actually updated and which didn't.

Third, retrying a failed job creates duplicate variants or overwrites a value that already changed, because the retry has no memory of what it already tried.

Each problem is survivable alone. Together, across ten or more stores running in parallel, they turn into a support queue full of "why does this store look different" tickets.

Idempotency Comes Before Speed

The fix for all three problems starts in the same place: every sync job needs to be idempotent. Running it twice should produce the same result as running it once.

Each job needs a stable identifier, built from the store, the product, and the variant, not from a timestamp or a random ID. If the same job runs again after a crash or a timeout, it should land on the same variant state instead of creating a new one.

Stripe's idempotent request pattern is a good reference here, even outside payments. A client-generated key lets the server recognize a repeated request and return the same result, instead of processing it twice.

Once jobs are idempotent, retries stop being risky. A failed job can simply run again without anyone needing to check what state it left behind.

A Queue-First Design for Multiple Stores

With idempotency in place, the next piece is a job queue sitting between the source catalog and each Shopify store.

Instead of one script looping through every store, a producer breaks the sync into small, single-variant jobs and pushes them onto a queue. A pool of workers pulls jobs off that queue and sends them to Shopify.

This setup makes a few things much easier to manage:

Per-store isolation: one struggling store doesn't block sync to the others.
Controlled concurrency: workers can be capped per store, so nothing overwhelms a single rate limit bucket.
Retry with backoff: a failed job goes back on the queue with a delay, instead of failing silently.
Dead-letter handling: a job that fails repeatedly gets pulled aside for a person to review, instead of looping forever.

Teams that reach this point often find a spreadsheet-driven process, or a generic sync app, can't hold this much logic. That's usually the moment they start looking at custom Shopify integration work instead of a one-size-fits-all plugin.

Respecting Shopify's Rate Limits, Not Fighting Them

Shopify's GraphQL Admin API doesn't count requests. It scores them. Every query has a cost, based on the fields and connections requested, and that cost gets deducted from a bucket tied to that specific store.

The bucket refills at a fixed rate. Send too much at once, and the bucket drains to zero, which triggers a throttle response instead of a result.

Every response includes a cost block showing exactly how much room is left. A sync system that reads that number and slows down before hitting zero runs far smoother than one that waits for an error and reacts afterward.

Each store keeps its own independent bucket. A worker pool that respects per-store limits can run many stores in parallel, without one busy store stealing capacity from another.

Full details live in Shopify's rate limit documentation, worth reading closely before writing the first retry loop.

When Bulk Operations Are the Right Tool

Not every sync job needs a live mutation. For very large, one-time catalog changes, like an initial migration or a seasonal reset across every store, Shopify's bulk operations API is built for exactly that.

Bulk operations run asynchronously on Shopify's side. They're meant for large-scale reads and writes that would otherwise burn through a rate limit bucket in minutes.

Ongoing, incremental variant sync usually fits better with direct mutations run through a queue. Big, occasional catalog overhauls usually fit better with a bulk operation.

Mixing both, bulk operations for the heavy lifting and queued mutations for day-to-day updates, tends to hold up well once real merchants start using it.

The Linked Option Trap

One error catches almost every team building this for the first time: CANNOT_SET_NAME_FOR_LINKED_OPTION_VALUE.

It shows up when a product option, like color, is linked to a Shopify metafield or taxonomy value, and a sync job tries to set both a plain text name and a linked value at the same time.

The fix is simple once it's known. Send the linked metafield reference, not the plain text name, whenever an option is linked. Skipping this check is one of the most common causes of silent, partial sync failures in multi-store catalogs.

A good sync system checks each store's option configuration before writing, rather than assuming every store's "Color" option behaves the same way.

Rolling Out Without Breaking Live Stores

A sync system this central to the business shouldn't go live everywhere at once.

A safer path starts with one store, ideally a smaller one, running the new pipeline in a dry-run mode that logs what it would change without writing anything.

Once the dry run looks clean, real writes get turned on for that single store first. Only after a few sync cycles pass without incident does the rollout move to the next store, and then the rest.

This canary-style rollout catches configuration quirks, like a store with an unusual linked option setup, before they hit every storefront at once.

Observability Turns Failures Into Fixes

None of this matters if nobody can see what happened. A queue-based sync system should log, at minimum, which job ran, which store it targeted, what it changed, and whether it succeeded.

Dashboards showing queue depth, failure rate per store, and rate-limit headroom per store turn a mystery outage into a two-minute diagnosis. Alerts on a rising dead-letter count catch a broken integration long before a merchant notices missing stock on the storefront.

"The moment a sync system spans more than two or three stores, retries stop being an edge case. They become the backbone of the whole design," says Ashish Kasama, CTO at Lucent Innovation.

That framing matters. A multi-store sync system isn't a script with extra error handling bolted on. It's infrastructure, and it deserves to be designed like infrastructure from day one.

What This Looks Like in Production

Put together, a reliable bulk variant sync setup usually has five moving parts: a canonical source of truth, idempotent job definitions, a queue with per-store worker limits, rate-limit-aware backoff, and a dead-letter path with real observability.

None of these pieces are exotic on their own. What matters is that they exist together, from the start, instead of getting bolted on one at a time after each outage.

Lucent Innovation has worked on Shopify since 2013, and has been a Shopify Plus Partner since 2016. This exact failure pattern has shown up more than once across client catalogs of very different sizes.

This is the same pattern behind our mEM platform, which keeps variant data in sync across hundreds of independent merchant storefronts without anyone touching a spreadsheet.

Shopify Metaobjects vs Metafields: Choosing the Right Model

Lucy — Tue, 11 Aug 2026 11:25:06 +0000

Metafields add one custom field to something that already exists in Shopify: a product, an order, a customer. Metaobjects create something that didn't exist before, with its own set of fields, that other resources can point to.

The short version:

Data describes one thing? Use a metafield.
Data is a reusable "thing" in its own right, like a size chart, an author profile, or a set of store locations? Model it as a metaobject and reference it from wherever it needs to show up.

That's the easy part. The part that actually costs teams time isn't picking a definition. It's picking wrong early, then discovering the mistake after forty products already depend on it.

What's the actual difference between a metafield and a metaobject?

A metafield is a key-value pair attached directly to an existing Shopify resource. It has a namespace, a key, a type, and a value. Its full address looks like product.metafields.custom.warranty_info.

It doesn't exist independently. Delete the product, and the metafield goes with it.

A metaobject is a standalone entity. You define its shape once, then create as many entries as you need in Content → Metaobjects. The definition covers:

name
fields
validation rules
access permissions

Nothing about a metaobject entry ties it to a single product. A "Designer Profile" metaobject can sit unattached to anything, or be linked from fifty different products through a reference field.

Shopify's own framing is the cleanest way to hold this in your head:

Metafields let you add extra columns to an existing table.
Metaobjects let you create an entirely new table.

If you're coming from a relational-database background, here's the mapping:

A metaobject definition maps to a custom table.
A metaobject field maps to a column on that table.
A metaobject entry maps to a row.
A metafield reference to a metaobject works like a foreign key.

Use a proper reference type (metaobject_reference, list.metaobject_reference) for that last one. Don't store a handle or ID in a plain text field. A plain-text pointer breaks Liquid and Storefront API resolution and can't be queried efficiently.

When should you use a metafield instead of a metaobject?

Reach for a metafield whenever the data is a genuine attribute of one resource and nobody else needs to reference it independently. Practical signals:

The value only makes sense in the context of the parent resource. A "care instructions" field only means something attached to a specific product.
You need it to participate in admin search, filtering, or Shopify Flow. Metafield definitions support admin_filterable capabilities that let you query products by metafield value directly through the GraphQL Admin API.
It's a simple scalar or a short list: text, number, date, boolean, money, a single file, or a short list of these.
You want to lean on Shopify's standard metafield definitions (ISBNs, care instructions, product ratings, and similar well-known fields) instead of inventing your own schema. Standard definitions don't count against your plan's metafield limits and interoperate across apps by default.

A warranty field, a release date on an order, an internal SKU code, a care-instructions block. All metafields. None of these needs to be looked up or reused from somewhere else in the store.

When does a metaobject beat a metafield?

Flip to a metaobject once any of these is true:

The content is reusable across many resources. A "Designer Profile," "Store Location," or "Size Chart" needs to show up on dozens of product pages without you retyping the bio, address, or measurements each time.
The record needs more than one related field and its own identity. A metaobject definition can hold up to 40 fields, each with its own type and validation. That's a scale a single metafield can't reach.
You want a dedicated URL. Metaobject definitions support a renderable capability that generates a public page and SEO metadata per entry. That matters for something like an author directory you want indexed on its own.
The relationship itself carries data. Say you're modeling a many-to-many relationship where the link needs extra fields, like an ingredient with a quantity specific to one recipe. Shopify's own data-modeling guidance recommends an intermediate metaobject acting as a join table here, the same pattern as a join table in SQL.

Here's the tell that shows up in the wild most often. A merchant starts by cramming repeatable content into a long multi_line_text_field metafield ("just paste the bios in as JSON"). Six months later, they need to:

edit one bio without touching a blob of unstructured text
filter profiles by role
reuse the same profile on the About page and three product pages

That's a metaobject that got built as a metafield.

How do metafields and metaobjects work together?

In production, you rarely pick one exclusively. You connect them. The standard pattern:

Define the reusable entity as a metaobject (the "table").
Add a metafield on the resource that needs to point to it. Type it as metaobject_reference for a one-to-one link, or list.metaobject_reference for one-to-many.
Read the resolved data straight from the reference in Liquid. Shopify resolves the connected metaobject automatically, so you don't run a second query.

A minimal example: a reusable "Size Chart" metaobject referenced from multiple products.

# shopify.app.toml: define the reusable entity
[metaobjects.app.size_chart]
name = "Size Chart"
display_name_field = "chart_name"
access.admin = "merchant_read_write"

[metaobjects.app.size_chart.fields.chart_name]
name = "Chart Name"
type = "single_line_text_field"
required = true

[metaobjects.app.size_chart.fields.measurements]
name = "Measurements"
type = "multi_line_text_field"

# Attach the reference to Product
[product.metafields.app.size_chart_ref]
name = "Size Chart"
type = "metaobject_reference<$app:size_chart>"
access.admin = "merchant_read_write"
access.storefront = "public_read"

{% assign chart = product.metafields.app.size_chart_ref.value %}
{% if chart %}
  <h3>{{ chart.chart_name.value }}</h3>
  <p>{{ chart.measurements.value }}</p>
{% endif %}

Twelve products can now point at the same three size charts. Update the chart once, and every product referencing it updates in the same request. That's the behavior a plain-text metafield can't give you, because each product would be carrying its own disconnected copy.

What are the technical limits you'll actually hit at scale?

Limits rarely bite during a demo. They bite eight months in, when a catalog has grown and nobody remembers the original schema decision. Here's what's currently published:

	Metafields	Metaobjects
Definition cap	Up to 200 definitions per resource type, per app/merchant scope	128 definitions per plan (Basic/Shopify/Advanced); 256 on Plus/Enterprise
Fields per definition	N/A, one field, one value	Up to 40 fields per definition
Entry/value cap	Governed by resource and plan limits	Up to 1,000,000 entries per definition
Reusable across resources	No, bound to one resource instance	Yes, referenced from any number of resources
Own URL / SEO metadata	No	Yes, with the `renderable` capability
Standard access in Liquid	Always accessible	Must have Storefront access explicitly enabled to appear in the Storefront API (Liquid access is unaffected)

Two mistakes account for most of the support-forum traffic on this topic:

Forgetting that a metaobject definition is capped at 40 fields, then trying to force an entire product-spec sheet into one definition instead of splitting it into related metaobjects.
Forgetting to flip on Storefront API access for a metaobject definition, then wondering why a headless build returns nothing even though the same data renders fine in Liquid.

How does the choice affect Liquid and Storefront API performance?

This is the part a lot of comparison posts skip.

Reference-typed fields resolve efficiently. Shopify fetches the connected metaobject as part of the same GraphQL response, so a metaobject_reference doesn't cost you a second round trip.

The performance risk shows up one layer deeper, with nested references: a product referencing a metaobject that itself references another metaobject. Shopify's own data-modeling guidance flags this directly. Fetching "grandchild" data through an intermediate metaobject can hit nesting limits in the Storefront API, and it's harder to query than a flat list-of-references relationship.

If you're modeling a genuine many-to-many join, expect the query cost. Cache aggressively rather than resolving nested references on every storefront request.

The practical rule: keep reference chains one level deep wherever the storefront reads them on a hot path, like a PDP or collection grid. Push anything with a second layer of nesting into a build-time or cached read instead of a live per-request resolution.

What's the decision framework for OS 2.0 architecture?

Run new custom-data requirements through these questions, in order:

Does this value only ever apply to one resource instance? → Metafield.
Does it need to be edited, searched, or reused in more than one place? → Metaobject.
Does it need more than a handful of related fields, or its own indexed page? → Metaobject.
Is it a relationship between two things that itself carries data, like a quantity, a sort order, or a date range? → Intermediate metaobject acting as a join table.
Does it need to power admin filtering or a Shopify Flow trigger? → Metafield with the relevant capability enabled, even if the value also happens to reference a metaobject.

None of these are permanent decisions written in stone. Shopify allows changing some field-level settings after the fact. But changing a field's underlying type is tightly restricted once entries exist. The decision is far cheaper to get right at schema design time than to fix once a theme and forty products depend on it.

Migration: what happens if you chose wrong?

The most common wrong turn is starting with a large multi_line_text_field or JSON-in-a-text-field metafield for something that should have been a metaobject from day one.

The fix is mechanical but not instant:

Create the metaobject definition with the correct fields.
Backfill entries from the existing metafield values using the GraphQL Admin API. This is a scripted, one-time migration, not something to do by hand past a handful of records.
Add a new metaobject_reference metafield on the parent resource(s) and point it at the new entries.
Update theme sections to read from the reference instead of the flat text field.
Leave the old metafield in place until the new path is verified in production, then remove it.

The inverse mistake, over-modeling a single-use attribute as a metaobject, is cheaper to unwind. Fold the fields back into a metafield and delete the now-unused definition.

It's the direction most teams don't expect to need. That's exactly why it's worth checking before building: not every reusable-sounding field is actually reused anywhere yet.

FAQ

Can a metaobject reference another metaobject?
Yes. Reference fields can point from one metaobject to another, which is how join-table patterns work. Keep an eye on nesting depth. Storefront API queries that resolve several reference layers deep get more expensive and can hit query-cost limits.

Do metaobjects work in Liquid the same way as the Storefront API?
Liquid can read metaobject data regardless of the Storefront API access setting. Headless storefronts built on the Storefront API need access.storefront = "public_read" explicitly set on the definition, or the query returns nothing.

Is there a hard cap on how many metaobjects I can create?
Definitions are capped by plan: 128 on standard plans, 256 on Plus/Enterprise. Each definition can hold up to 1,000,000 entries. Standard metaobject definitions Shopify ships for things like product taxonomy don't count against that cap.

The default that scales

Most OS 2.0 builds settle into the same pattern once the catalog is big enough to notice:

metafields for the attributes that belong to one product, order, or customer
metaobjects for the content that has to look the same everywhere it appears
reference fields doing the connecting work in between

Getting that split right before the theme is built around it is the difference between a schema change and a rebuild. It's also the baseline architecture Lucent Innovation's Shopify Development team designs into every custom OS 2.0 storefront, so merchant content teams aren't stuck re-modeling data six months after launch.

What's the messiest metafield-vs-metaobject call you've had to untangle on a live store?

Debugging Shopify Webhook Delivery Failures: A Developer Checklist

Lucy — Tue, 04 Aug 2026 13:05:09 +0000

Quick answer: Most "missing webhook" bugs on Shopify aren't Shopify's fault. Your endpoint either takes longer than 5 seconds to respond, fails HMAC verification because the body was already parsed, or processes the same delivery twice because there's no dedupe check. Shopify retries a failed delivery 8 times over 4 hours with exponential backoff, then drops the event for good. This post walks through how to find out which of those it actually is, using Shopify's own delivery logs instead of guesswork.

If you've ever had a merchant email you about an order that "never showed up" in your system, only to find Shopify's dashboard says the order exists and the webhook fired, this is for you.

What actually causes Shopify webhook delivery failures?

In practice, almost every failed delivery falls into one of five buckets:

Timeout. Your endpoint didn't return a 200 within 5 seconds.
Signature mismatch. HMAC verification failed, usually because the raw body was mutated before verification ran.
Silent duplicate processing. The same event arrived twice and got processed twice, which looks like a data bug but is really a missing dedupe check.
Subscription removal. Repeated failures caused Shopify to auto-delete the subscription, so you stopped receiving anything and didn't notice.
Stale payload assumptions. A retried webhook carries the original payload from when it was first triggered, not the current state, so code that assumes "this payload is always fresh" quietly does the wrong thing. None of these show up as a stack trace in your own logs. They show up as a missing order, a duplicate charge, or a support ticket. The fastest way to tell them apart is to stop guessing and pull Shopify's own delivery data first, which is covered a few sections down.

How does Shopify's retry system actually work?

Shopify's current policy, in place since a September 2024 update, retries a failed webhook delivery up to 8 times over a 4-hour window using exponential backoff. A 200-series response counts as success. Anything else, including a 3xx redirect, counts as a failure and queues a retry. After the 8th failed attempt, Shopify stops trying and the event is gone unless you reconstruct it yourself from the Admin API.

Shopify doesn't publish the exact per-attempt schedule, only the total shape (8 attempts, 4 hours, exponential backoff), so treat the chart below as directional rather than a literal timetable. If you're reading an older tutorial describing a much longer retry window, it predates this change.

Two details in the retry mechanism changelog matter more than the headline number:

Retried deliveries reuse the original payload and address. If you change your endpoint URL mid-retry-cycle, the retry still goes to the old address. Keep the old endpoint alive for a while during any migration.
Use X-Shopify-Triggered-At, not "now," to judge freshness. If your handler assumes every delivery reflects the current state of the resource, a late retry will overwrite newer data with older data. ## Why do webhooks time out even when your server is healthy?

This is the failure mode that confuses people most, because their server looks fine in every other metric. According to Shopify's guidance on verifying deliveries, Shopify allows a one-second connection timeout and a five-second timeout for the entire request-response cycle. That five seconds has to cover TLS handshake, routing through any load balancer or serverless cold start, your handler's logic, and the response write.

The usual culprit is doing real work inside the request handler: writing to a database, calling a third-party API, resizing an image, or running any business logic before responding. If any of that occasionally takes more than a couple of seconds, you'll see intermittent failures that look mysterious, because the work usually finishes anyway, just after Shopify already marked the delivery as failed and queued a retry.

The fix Shopify itself recommends is to treat the webhook endpoint as a thin acknowledgment layer and nothing else:

// webhook-receiver.js
// Keep this handler doing almost nothing. Verify, queue, respond.
const express = require('express');
const crypto = require('crypto');
const app = express();

app.post('/webhooks/orders', express.raw({ type: '*/*' }), (req, res) => {
  const digest = crypto
    .createHmac('sha256', process.env.SHOPIFY_CLIENT_SECRET)
    .update(req.body)
    .digest('base64');

  const signature = req.headers['x-shopify-hmac-sha256'];
  const isValid = crypto.timingSafeEqual(
    Buffer.from(digest, 'base64'),
    Buffer.from(signature, 'base64')
  );

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  // Hand the raw payload to a queue and return immediately.
  // Do NOT touch a database or call another API before this line.
  jobQueue.enqueue('shopify-webhook', {
    webhookId: req.headers['x-shopify-webhook-id'],
    topic: req.headers['x-shopify-topic'],
    triggeredAt: req.headers['x-shopify-triggered-at'],
    body: req.body.toString('utf8'),
  });

  res.status(200).send('ok');
});

A background worker then pulls from that queue and does the actual database write or API call, on its own schedule, with no 5-second clock running. This single change eliminates most timeout-related failures without touching your retry or business logic at all.

How do you verify a delivery actually came from Shopify?

Every HTTPS delivery includes a base64-encoded HMAC-SHA256 signature in the X-Shopify-Hmac-Sha256 header, computed from your app's client secret and the raw request body, per Shopify's verification docs. Skipping this check, or getting it wrong, is the second most common source of "delivery failed" errors after timeouts.

Three mistakes account for almost all HMAC verification bugs:

Body already parsed. If express.json() or an equivalent middleware runs before your verification code, it has already mutated the body you need to hash. Verification must happen against the exact raw bytes Shopify sent, which means your raw-body middleware has to run first, not your JSON parser.
String comparison instead of constant-time comparison. Comparing signatures with === leaks timing information. Use crypto.timingSafeEqual (or your language's equivalent) instead.
Verifying against a secret that just rotated. If you rotate your app's client secret, Shopify notes it can take up to an hour before the HMAC digest is generated with the new secret. A verification failure right after a rotation isn't necessarily a bug in your code. Treat header names as case-insensitive in your code. Shopify documents that HTTP/2 often lowercases them, so X-Shopify-Hmac-Sha256 and x-shopify-hmac-sha256 need to resolve to the same value in your handler.

Why are you getting duplicate webhook deliveries?

Shopify's own documentation is direct about this: it minimizes duplicate deliveries but doesn't guarantee exactly-once delivery, so your app might receive the same webhook more than once, for example after a network timeout that happens right as your response is in flight. If your database write isn't idempotent, a duplicate delivery becomes a duplicate order note, a double-counted inventory adjustment, or a second email to a customer.

Two headers, documented in Shopify's delivery structure reference, matter here, and mixing them up is a common source of confusion:

Header	What it identifies	Use it to
`X-Shopify-Webhook-Id`	A unique key per individual delivery	Deduplicate a single delivery you may have already processed
`X-Shopify-Event-Id`	Shared across every delivery triggered by the same merchant action	Correlate deliveries across multiple subscriptions to the same topic

If you have more than one subscription listening to the same topic, you'll get a separate delivery, with a separate X-Shopify-Webhook-Id, for each one. Dedupe on the webhook ID, not the event ID, or you'll silently drop deliveries you actually needed.

The dedupe check itself is simple: before processing, look up the X-Shopify-Webhook-Id in whatever persistent store you're already using (Redis, a database table, whatever fits your stack). If it's been seen, skip processing and return success anyway, since Shopify already got the acknowledgment it needed. If it's new, save the ID and process it.

We've hit this exact problem doing custom Shopify webhook integration development for merchants pushing orders into an external system in near real time. The failure mode is never dramatic. It's a handful of orders that get written twice into an ERP because a retry landed a few seconds after the original delivery finished processing, and nobody notices until someone reconciles the numbers weeks later.

How do you read Shopify's delivery logs before building your own?

If your app was created through the Dev Dashboard or Shopify CLI, Shopify's troubleshooting guide points you to a delivery metrics report before you write a single line of custom monitoring. It's worth using this first, because it already has the data you'd otherwise have to reconstruct from your own logs.

The Monitoring page (Dev Dashboard → your app → Monitoring) shows, per topic, over the last 7 days:

Total deliveries and failed delivery rate
Response time at the 90th percentile
How many webhook subscriptions have been auto-removed
Shopify's own guidance on what counts as a real problem is specific enough to skip a lot of debate:
A failed delivery rate over 0.5% is higher than average and worth investigating.
Response times sitting between 4 and 5 seconds mean you're right at the timeout edge, not comfortably under it.
If every topic has a high failure rate at once, the problem is your backend being down, not any single handler.
If removed webhooks shows a nonzero count, you have subscriptions that stopped delivering and nobody re-created them.
The Logs page lets you inspect an individual delivery: response code, response time, payload size, delivery attempt number, and the HMAC signature that was sent. That last field is genuinely useful for a specific class of bug: when your local testing works, production HMAC verification doesn't, and you need to confirm whether the signature Shopify sent even matches what you're computing.

What happens after Shopify removes your webhook subscription?

This is the failure mode that does the most silent damage, because nothing errors, you just... stop getting data. If deliveries to a subscription keep failing, Shopify auto-removes it, and warning emails go to your app's emergency developer email address, which is easy to have pointed at an inbox nobody checks.

Recovery depends on how the subscription was created:

App-specific subscriptions (declared in shopify.app.toml and deployed with your app) don't need manual re-subscription; they're tied to the app's own configuration rather than a one-off API call.
Shop-specific subscriptions (created through the Admin API for an individual merchant) need to be recreated, and Shopify recommends checking existing subscriptions first so you only create what's missing. Either way, re-subscribing only fixes the going-forward problem. The gap in data during the outage still has to be backfilled by fetching the missing records from the Admin API and feeding them back through your normal processing path. This is the part teams skip, and it's the part that actually prevents a customer support ticket three weeks later asking why an order from last month never triggered a fulfillment.

A quick diagnostic checklist

Symptom	Likely cause	What to check first
Deliveries fail intermittently, server looks fine	Handler doing real work before responding	Response time in delivery logs, especially the 4-5s range
All deliveries return 401	HMAC secret mismatch or wrong raw body	Confirm raw-body middleware runs before any JSON parser
Same order processed twice	No dedupe check	Add a store keyed on `X-Shopify-Webhook-Id`
Data stopped arriving entirely, no errors anywhere	Subscription auto-removed after repeated failures	Dev Dashboard "Removed webhooks" metric, emergency developer email
Old data overwriting new data after an outage	Retry delivered a stale, original payload	Compare `X-Shopify-Triggered-At` against current record timestamp
Works locally, fails in production	Different secret, or a proxy mutating the body	Re-verify HMAC using the exact production request body

Building retry logic that survives a longer outage

Shopify's 4-hour retry window is generous for a blip, not for a real outage. If your own deployment goes down for longer than that, you need your own resilience layer on top of Shopify's, not instead of it. The pattern that holds up in production, echoed in AWS's canonical guidance on backoff and jitter and its Well-Architected Framework retry guidance, comes down to a short list: acknowledge fast, classify errors so only transient ones get retried, add jitter so recovering clients don't all retry in the same instant, cap the number of attempts, and reconcile against the source of truth afterward rather than assuming your queue caught everything.

None of that is Shopify-specific. It's the same reason exponential backoff without jitter still clusters retries into waves, and why a dead letter queue matters more than a longer retry window.

This is exactly why we hit similar sync issues building custom order-sync middleware for a manufacturing client, connecting Shopify to an ERP and a 3PL provider. Retry tuning helped. A reconciliation job that periodically compared both systems and caught what fell through is what actually stopped orders from silently going missing.

What's the strangest webhook failure you've had to track down, and did Shopify's own delivery logs actually explain it, or did you end up debugging blind? Drop it in the comments, I'd like to compare notes.

Shopify AI Search Optimization: How to Make Your Store Visible Inside ChatGPT, Perplexity, and Google AI Mode

Lucy — Wed, 29 Jul 2026 06:22:47 +0000

Direct answer: Shopify AI search optimization (GEO) means structuring your product and content pages so ChatGPT, Perplexity, Google AI Mode, and Copilot can read, trust, and cite them. In practice that comes down to three things: clean schema.org markup on every product page, a healthy Google/Bing Merchant Center feed, and content written in a self-contained, fact-dense style that AI systems can lift and quote. Below is exactly how the major platforms pull Shopify product data in 2026, and a checklist you can run today.

Why Shopify Merchants Can't Ignore AI Search Anymore

For most of the last decade, "getting found" meant ranking in ten blue links. That's no longer the whole game. Shoppers now ask ChatGPT to compare running shoes, ask Perplexity what the best gift is for a new homeowner, and ask Google AI Mode to shortlist skincare brands before they ever open a browser tab to search normally.

The interesting part is that this isn't a hypothetical shift for Shopify merchants specifically. Shopify has already built the plumbing for it. Shopify Catalog automatically syndicates product data to connected AI platforms including Perplexity, ChatGPT, and Google AI Mode, and when a shopper completes a purchase through one of these assistants, checkout still happens on the merchant's own store using their existing payment setup, according to Shopify's own guide to Perplexity Shopping. In other words, the infrastructure exists. Most stores just aren't feeding it correctly.

That's the gap this post covers: what "AI search optimization" (often called Generative Engine Optimization, or GEO) actually means for a Shopify store, how each AI platform sources its data, and what a merchant or their dev team should fix first.

How Do AI Shopping Assistants Actually Find Your Products?

This is the part most merchants get wrong, because it's easy to assume ChatGPT "crawls your site" the way Googlebot does. It mostly doesn't. Each platform has a different pipeline, and knowing which one matters for you changes where you spend effort.

ChatGPT Shopping draws roughly 83% of its product recommendations from Google Shopping's organic index, based on a March 2026 analysis of 43,000 carousel products that found base64-encoded Google Shopping parameters embedded in ChatGPT's source code, confirming a direct pipeline from Google Merchant Center feeds into ChatGPT's results, according to a feed-optimization breakdown of that research. Shopify merchants in the US get automatic catalog syndication into ChatGPT through Shopify's own Agentic Storefront integration.
Perplexity Shopping is closer to a real-time researcher. It crawls your live HTML and cites the exact page it pulled facts from, and its shoppers convert at a notably higher average order value than other AI referral traffic, per Shopify's Perplexity guide.
Google AI Mode leans on the existing Shopping Graph, meaning your Google Merchant Center feed and on-page schema still do most of the work.
Microsoft Copilot runs on Bing Merchant Center and, as of a January 2026 rollout, offers checkout inside the chat window itself for eligible Shopify merchants, per an ecommerce AI platform comparison.

Platform	Primary data source	What actually moves the needle
ChatGPT Shopping	Google Shopping feed (via Shopify Agentic Storefront)	Clean Merchant Center feed, GTIN, full descriptions
Perplexity Shopping	Live HTML crawl + Shopify Catalog	On-page schema, real prices, return policy fields
Google AI Mode	Shopping Graph	Merchant Center feed + Product/Offer schema
Microsoft Copilot	Bing Merchant Center	Feed hygiene + Copilot Checkout enrollment

The practical takeaway: your Google Merchant Center feed and your on-page schema aren't separate SEO and "AI SEO" tasks anymore. They're the same infrastructure two different systems are reading.

What Structured Data Does an AI Engine Actually Need From a Product Page?

Structured data is how you tell a machine that "$89" is a price and "4.7/5" is a rating, rather than making it guess from surrounding text. Most Shopify themes add basic Product schema automatically, but an audit of 2,400 Shopify product pages found only 9% carried the structured data required for ChatGPT or Perplexity to reliably recommend them, per an analysis of Shopify AI visibility. The gap is usually in the fields nobody thinks about: shipping details, return policy, and review counts.

A reasonably complete Product schema block looks like this:

{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Example Product Name",
  "image": "https://cdn.shopify.com/example.jpg",
  "description": "A full, specific product description, not a five-word title restated.",
  "brand": { "@type": "Brand", "name": "Your Brand" },
  "sku": "SKU-1234",
  "gtin13": "0012345678905",
  "offers": {
    "@type": "Offer",
    "priceCurrency": "USD",
    "price": "89.00",
    "availability": "https://schema.org/InStock",
    "shippingDetails": {
      "@type": "OfferShippingDetails",
      "shippingRate": { "@type": "MonetaryAmount", "value": "0", "currency": "USD" }
    },
    "hasMerchantReturnPolicy": {
      "@type": "MerchantReturnPolicy",
      "returnPolicyCategory": "https://schema.org/MerchantReturnFiniteReturnWindow",
      "merchantReturnDays": 30
    }
  },
  "aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": "4.7",
    "reviewCount": "182"
  }
}

Two fields worth flagging specifically because they're the ones most themes skip: hasMerchantReturnPolicy and shippingDetails. Shipping and return terms are now a comparison criterion AI assistants use to decide between two similar products, not just legal boilerplate buried in a footer link.

Does llms.txt Actually Help a Shopify Store Get Cited?

This one deserves an honest answer rather than a hype-cycle one. llms.txt is a proposed standard, introduced in September 2024 by Jeremy Howard of Answer.AI, that puts a curated Markdown map of a site's key pages at the domain root, similar in spirit to robots.txt but aimed at language models instead of search crawlers, as documented in Search Engine Land's coverage of the proposal.

It has real traction in one specific use case: developer documentation for coding assistants and AI agents. It is far shakier as a general AI-search ranking lever. One large-scale analysis of AI bot traffic found that requests to /llms.txt were statistically negligible among the user agents that actually drive citations, such as GPTBot, ClaudeBot, and PerplexityBot, meaning most AI systems answering shopping questions in 2026 simply aren't reading it yet.

The pragmatic move for a Shopify store: add a lightweight llms.txt if it takes an hour, since there's no real downside, but don't treat it as a substitute for the fundamentals above. Structured data and feed hygiene are doing the actual work right now.

How Should Product and Blog Content Be Written So AI Engines Want to Quote It?

Generative engines retrieve short passages, not whole pages, so the unit of content that gets cited is a sentence or two, not a paragraph. Research from Princeton, Georgia Tech, and IIT Delhi found that content optimized for this pattern achieved measurably higher visibility in AI-generated answers, with the biggest single gains coming from adding verifiable statistics to a passage and from leading with a definition-first sentence rather than a scene-setting one, according to a summary of that research.

What that looks like in practice on a Shopify blog or PDP:

Lead with the answer. Put the direct, factual sentence first in every section, something like "A composting bin needs airflow on at least two sides," before the supporting explanation.
Make each paragraph stand alone. Assume an AI system will lift that one paragraph out of context and quote it. Don't rely on "as mentioned above."
Use question-style H2s. "What size composting bin do I need for a family of four?" mirrors how people actually phrase prompts, far more than "Composting Bin Sizes."
Cite something verifiable. A specific number, a named study, or a dated fact gets picked up far more often than a general claim.
Refresh the page. AI engines weigh recency when choosing which source to cite, so a guide last touched in 2023 loses ground to a competitor's 2026 update on the same topic.

A Practical GEO Checklist for Shopify Merchants

Audit every product page for Offer, AggregateRating, MerchantReturnPolicy, and OfferShippingDetails schema, not just basic Product markup.
Check your Google Merchant Center and Bing Merchant Center feeds for stale "in stock" flags. This is one of the fastest ways to get a feed quality-flagged and dropped from AI shopping results.
Confirm your robots.txt isn't accidentally blocking GPTBot, PerplexityBot, or OAI-SearchBot. Cloudflare's default configuration change in 2025 caused a wave of sites to block AI bots without realizing it.
Make sure product pages render server-side. AI crawlers generally don't execute heavy client-side JavaScript the way a human browser does.
Write full, specific product descriptions. A 15-word description gives an AI system almost nothing to reason over when it's matching your product to a conversational query.
Republish or refresh cornerstone guides at least twice a year with a visible "last updated" date.

Who Should Actually Run This Audit?

None of the above is exotic engineering, but it does touch theme templates, feed configuration, and content strategy at the same time, which is exactly where things get missed on a live store. This is the kind of cross-cutting technical and content work a team of dedicated Shopify specialists is set up to audit and implement properly, because it means checking schema output against the live theme, not just the store's settings panel, and tying that back into how product copy is actually written.

If you're not sure where your own store stands on any of the checklist above, that's usually the first thing worth having someone independently look at before you spend a quarter chasing individual AI platforms one by one.

Frequently Asked Questions

Does GEO replace traditional SEO for a Shopify store?
No. GEO builds on the same technical foundation as SEO (crawlability, structured data, fast pages) and adds a layer on top for how AI systems retrieve and cite content.

Which AI shopping platform should a Shopify merchant prioritize first?
Start with your Google Merchant Center feed. It feeds Google Shopping, Google AI Mode, and indirectly a large share of ChatGPT Shopping's results, so fixing it once pays off across multiple platforms.

Is llms.txt required for a Shopify store?
No. It's optional and low-cost to add, but current data suggests the major AI shopping crawlers aren't reading it in meaningful volume yet.

How long does it take to see AI citations after making these changes?
Perplexity, which relies on real-time web retrieval, can pick up freshly published or updated content within days. Feed-based platforms like ChatGPT Shopping and Google AI Mode typically lag behind the next feed refresh cycle, which can take longer.

Have you checked whether your own product pages actually render their schema correctly once the theme's JavaScript runs? Curious what others are finding when they audit their live Shopify stores for this. Drop what you find in the comments.

Shopify Checkout UI Extension Development: A Step-by-Step Guide (2026)

Lucy — Tue, 21 Jul 2026 07:05:17 +0000

Shopify checkout UI extension development means building a small, sandboxed React or Preact component that Shopify renders inside a fixed slot in checkout, such as a block on the Thank you page or a static area next to the cart line items. This guide scaffolds one from a real Shopify CLI project, reads and writes checkout data through the current shopify global object, tests it locally, and deploys it under the platform's actual constraints. By the end you'll have a working delivery-instructions extension and a clear list of the places these extensions tend to fail once real customers start using them.

What You're Building (and What This Guide Skips)

The extension in this walkthrough adds a text field to checkout where a customer can leave a note for the courier, and it shows the current order subtotal above the field. That's deliberately small. It exercises the three things almost every checkout UI extension needs: a target, a read from the shopify object, and a write back to the order.

This guide does not cover Shopify Functions (server-side discount, shipping, and payment logic), the Branding API (colors, fonts, and layout), or post-purchase upsell offers. Those are real parts of checkout extensibility, but they solve different problems and deserve their own walkthroughs. Shopify maintains its own custom fields tutorial covering a similar delivery-instructions pattern, worth a look once you want the officially maintained reference version alongside this one. The next section explains how to tell which one you actually need.

Checkout UI Extensions vs. Shopify Functions: Which One Do You Actually Need?

If the customer needs to see or interact with something, you want a UI extension. If you need to change a price, a discount, a shipping rate, or which payment methods appear, you want a Function. UI extensions render interface inside a sandboxed environment; Functions run server-side with no rendering at all, according to Shopify's documentation on apps in checkout.

	Checkout UI Extensions	Shopify Functions
Renders visible UI	Yes	No
Runs where	Client-side, inside a Web Worker sandbox	Server-side, on Shopify's infrastructure
Typical use	Custom fields, banners, upsell blocks, trust badges	Discount logic, shipping rate changes, payment method ordering
Data access	Reads/writes cart and checkout data through the `shopify` object	Reads structured input, returns structured output, no direct cart mutation
Plan requirement	Available on all plans; the information, shipping, and payment steps still require Shopify Plus	Available broadly, most often paired with Plus-tier checkout customization

Teams often reach for a UI extension when the real problem is a Function, which is why a custom field ends up trying to also silently change a shipping rate through a side channel. Keep the two separate. If your logic doesn't need to be seen, it probably belongs in a Function instead.

It's also worth knowing what these two tools replaced. Shopify Scripts, the old way to write custom discount and shipping logic for Plus stores, stopped executing on June 30, 2026, after running alongside checkout extensions during a transition window that Shopify's own documentation confirms. Anything still living in an old Script needs to move to a Function now, not a UI extension.

Prerequisites

You'll need:

Node.js and a recent Shopify CLI install
A Partner account and a development store with checkout extensibility enabled
An existing custom or public app to attach the extension to (or scaffold a new one with shopify app init)

Set the API version to the latest stable release in your configuration file rather than pinning to whatever version a tutorial used months ago. Each stable version stays supported for a minimum of 12 months, and the CLI blocks deploys against versions older than that window.

Scaffold the Extension

From inside your app directory, generate the extension:

cd my-app
shopify app generate extension --template checkout_ui

This creates a folder with a shopify.extension.toml configuration file and a templated JSX entry point. Edit the TOML to point at a block target, which is the placement type merchants can position themselves using the checkout editor:

api_version = "2026-07"

[[extensions]]
type = "ui_extension"
name = "Delivery Notes"
handle = "delivery-notes"
uid = "generate-this-with-shopify-cli"

  [[extensions.targeting]]
  target = "purchase.checkout.block.render"
  module = "./src/DeliveryNotes.jsx"

Block targets are one of three target types. Static targets render automatically in a fixed spot, like right after the cart line items, and can't be repositioned. Runnable targets don't render anything at all; they fire in response to an event, such as a keystroke in an address field, and return data. Block targets sit in between: merchants place them through the checkout editor, and up to three extensions can share the same slot. The Shopify CLI documentation covers the full set of scaffold and dev-server flags if you need to target a specific store or app configuration.

Read Checkout Data With the `shopify` Global Object

Inside the extension, Shopify injects a global shopify object that exposes checkout data as properties. There's no import needed for it: it's simply available at runtime, similar to how window behaves in a normal browser page, except this one runs inside a Web Worker with no DOM access.

import '@shopify/ui-extensions/preact';
import {render} from 'preact';
import {useState} from 'preact/hooks';

export default function extension() {
  render(<DeliveryNotes />, document.body);
}

function DeliveryNotes() {
  const [note, setNote] = useState('');
  const subtotal = shopify.cost.subtotalAmount.value;

  return (
    <s-stack border="base" padding="base">
      <s-heading>Delivery instructions</s-heading>
      <s-text type="small">
        Subtotal: {subtotal.amount} {subtotal.currencyCode}
      </s-text>
      <s-text-field
        label="Leave a note for the courier"
        value={note}
        onChange={(event) => setNote(event.target.value)}
      />
    </s-stack>
  );
}

shopify.cost.subtotalAmount updates automatically as the cart changes, and reading it doesn't cost you anything in terms of rate limits since it's a read, not a write. The s-stack, s-heading, s-text, and s-text-field elements are web components from Shopify's Polaris-based checkout component library, not raw HTML, so they inherit the store's checkout styling without extra CSS work on your part.

Run shopify app dev at this point to preview the extension live on your dev store before writing a single line of persistence logic. Confirming the field renders and the subtotal updates is the cheapest bug you'll ever catch.

Write Changes Back to the Order

Reading data is half the job. The other half is persisting what the customer typed, which happens through applyAttributeChange:

async function handleChange(event) {
  const value = event.target.value;
  setNote(value);

  await shopify.applyAttributeChange({
    type: 'updateAttribute',
    key: 'deliveryInstructions',
    value,
  });
}

Swap this in for the inline onChange in the component above. applyAttributeChange returns a promise that resolves once Shopify has applied the change and the corresponding property has updated, and the attribute becomes visible on the order in the admin once it's placed.

Two boundaries matter here. First, extensions that fire too many attribute or metafield changes in a short window get rate-limited for the rest of that buyer's session, so batch related writes with Promise.all instead of firing one call per keystroke. Second, an attribute set this way lands on the order object, not inside the payment step; if you need something reflected in pricing or payment method availability, that's a Function's job, not this one.

Test the Extension Before It Touches Real Checkouts

shopify app dev gives you a live preview against a real dev store, and it reloads automatically as you edit. That covers manual testing. As of API version 2026-04, Shopify also ships @shopify/ui-extensions-tester for writing actual unit tests against your extension code, which matters once the component grows past a single field and you want regression coverage without opening a browser every time.

Two checkpoints are worth running before you touch a production store:

Confirm the field appears in the correct slot using the checkout editor's preview, since block target placement is merchant-configurable and easy to get wrong during first setup.
Place a real test order and check that the attribute shows up on the order detail page in the admin. If it's missing, the write silently failed or the promise was never awaited, not a rendering problem.

Deploy It, and Respect the 64 KB Ceiling

Deployment is a single command:

shopify app deploy

The CLI builds your extension bundle and uploads it to Shopify. There's a hard constraint worth planning around early: a compiled UI extension bundle can't exceed 64 KB, and Shopify enforces this at deploy time. A single text field extension won't come close, but adding a chart library or a large icon set will get you there faster than expected. Analyze your bundle size before you're surprised by a failed deploy the day before launch.

If your extension needs more than the default sandbox allows, such as calling your own backend or collecting SMS marketing consent, you declare that explicitly in the TOML under [extensions.capabilities] (network_access, api_access, collect_buyer_consent, block_progress). Requesting a capability you don't end up using is a common reason review takes longer than expected, so keep the list matched to what the code actually does.

Where Do Checkout Extensions Actually Break in Production?

Two failure patterns show up more than any other.

The first is a mismatch between an extension's declared api_version and the version a linked extension expects, most commonly on payment-related targets. One developer on the Shopify community forum hit a crash where checkout failed with a TypeError before their React component even rendered, tied to a payment extension linked to a UI extension through ui_extension_handle. The lesson generalizes: when two extensions are wired together, verify the target string and API version match exactly, and don't assume a typo in a config field will surface as a readable error. It often surfaces as a crash somewhere upstream of your own code.

The second is the sandbox itself. The extension runs inside a Web Worker with no access to window or the DOM, which means a third-party error-reporting tool that assumes a normal browser environment will silently fail to initialize unless you disable its default integrations and attach error and unhandledrejection listeners manually. If you're not seeing errors you know are happening, this is usually why.

Neither failure mode is exotic. Both come from treating a sandboxed, upgrade-safe environment as if it were a regular webpage, which it deliberately isn't.

Build It Yourself or Bring in a Shopify Team?

A single custom field like the one in this guide is a reasonable first project for a developer who's comfortable with React and hasn't touched Shopify's extension model before; budget a day or two including the review cycle. The calculation changes once you're coordinating multiple targets, metafields across international markets, post-purchase offers, or a Scripts-to-Functions migration against a hard deadline. That's less a coding problem than a project-management one, and it's the same reasoning Shopify gives store owners directly in its own upgrade guidance: build the extension yourself, or bring in a service partner to build it for you.

For merchants in that second situation, Lucent Innovation's Shopify development team handles exactly this kind of checkout migration and extension work as part of its Shopify Plus practice. Either path is legitimate. The point of this guide is that you now have enough to make that call with a working extension in front of you, not a guess.

What's Next

You've got a checkout UI extension that reads live cart data and writes an attribute back to the order, scaffolded, tested, and deployed under the real constraints Shopify enforces at build time. The natural next step is a Shopify Function if your use case needs to touch pricing or shipping logic rather than just displaying something.

Have you run into the Web Worker sandbox limitations while wiring up error tracking, or found a cleaner pattern for requesting capabilities without triggering a longer review? Drop it in the comments, it's the kind of detail that doesn't make it into the docs.