Install the NORG worker on a Shopify store (O2O)

⚠ Check your Cloudflare Workers plan before installing

On the Free Workers plan, a Cloudflare account is capped at 100,000 worker requests per day. Because this worker's route is {your-shop-domain}/*, once that cap is hit Cloudflare stops invoking the worker and errors every request to your store — shoppers included, not just AI agents. On any store where an outage costs you sales, move to the Workers Paid plan before adding the route.

What this worker does

Visitor	What they get
A person in a browser	Your storefront, byte-for-byte unchanged
Googlebot, Bingbot, other web-index crawlers	Your storefront, byte-for-byte unchanged
An AI agent asking for an already-rendered page	The NORG render, served at your own URL — no redirect
An AI agent asking for a page not yet rendered	Your page stripped to the token-dense facts, while NORG renders it in the background
Anyone on /checkout	Your Shopify checkout, untouched — Cloudflare disables Workers there in O2O setups

Two rules are built in and not configurable: it must never break your store (every failure path falls back to your Shopify-served response), and search engines always see exactly what humans see. NORG only ever mirrors pages from your sitemap — commerce endpoints like /cart are never rendered or mirrored.

Before you start

A custom domain connected under Shopify's Settings → Domains. A store reachable only at *.myshopify.com cannot use this install.
That domain's DNS managed in your own Cloudflare account. If Shopify manages the DNS and you don't want to move it, ask about the Shopify App Proxy integration instead.
A Cloudflare account that can create Workers (the free plan works to get started).
A SITE_ID and NORG_SITE_KEY, issued by NORG when you register the site for edge routing.

Set up Orange-to-Orange (O2O)

O2O is Cloudflare's supported way to put your own zone in front of Shopify's: traffic hits your zone first (where this worker runs), then flows on to Shopify, which serves your storefront exactly as before. It works on every Cloudflare plan, including free.

Before you start, your zone likely looks something like this — Shopify's own documented shape for a domain connected via third-party DNS, DNS only (grey cloud), nothing proxied through Cloudflare yet:

Type    Name   Content                Proxy status
A       @      23.227.38.65           DNS only
CNAME   www    shops.myshopify.com    DNS only

(Some older or manually-edited zones carry www as a second A record instead of that CNAME — same fix below, just applied to whichever record is actually there.) Neither reaches Cloudflare's network like this, so this worker cannot run yet — that's exactly what this step changes. Check which host your storefront actually loads at before you continue: many stores redirect the bare domain to www, in which case www is the real host, and both the CNAME below and the route in step 3 need to target it — not the apex.

Create the Shopify CNAME, proxied:

Type:    CNAME
Name:    your-shop.com        (or the subdomain your store lives on)
Target:  shops.myshopify.com
Proxy:   Proxied (orange cloud)

Then connect the domain in Shopify under Settings → Domains → Connect existing domain, and wait until Shopify shows it connected with SSL active.

Leave "Always Use HTTPS" OFF (Cloudflare zone → SSL/TLS → Edge Certificates). Shopify renews your certificate via Let's Encrypt HTTP-01 challenges against /.well-known/acme-challenge/*, and a blanket HTTPS redirect breaks those challenges — the failure shows up weeks later as an expired certificate. Want HTTP→HTTPS redirects anyway? Create a Redirect Rule that excludes that path instead of using the global toggle.

Sanity-check the storefront in a browser before moving on — it should look and behave exactly as before, with no domain errors in Shopify's admin.

Deploy the worker into your own Cloudflare account

Click Deploy to Cloudflare below. Cloudflare forks the worker's repo into your own GitHub/GitLab account and builds it from there — NORG never receives an API token, and never gets deploy access to anything in your account.

Deploy to Cloudflare →

When prompted, fill in two values. Everything else has a default baked into the worker:

SITE_ID — edge_sites.id, identifies this install to NORG.
NORG_SITE_KEY — the per-site key authenticating this install to NORG's API. NORG issues both when you register the site for edge routing; the key is shown once, so if you lose it, ask NORG to rotate it.

Set NORG_SITE_KEY as an encrypted variable (Settings → Variables → toggle Encrypt, or wrangler secret put NORG_SITE_KEY) — never a plain variable, and never committed anywhere.

Attach the route manually

In Workers & Pages → the worker → Settings → Domains & Routes → Add route:

Route:  your-shop.com/*
Zone:   your-shop.com

Use {your-shop-domain}/*, not a narrower path — the worker is written to see every request and pass through the ones it doesn't handle. You do not need to carve out /checkout: Cloudflare disables Workers on that path in an O2O setup regardless of the route pattern.

Verify the install

Run these against a real page on your store.

An AI agent gets the NORG treatment:

curl -sI -H "User-Agent: GPTBot" https://your-shop.com/products/some-product | grep -i x-norg-edge

X-Norg-Edge: mirror means a render was served; stripped means nothing has rendered yet; no header at all means the worker never saw the request.

A normal visitor is untouched (expect no output):

curl -sI -A "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0 Safari/537.36" \
  https://your-shop.com/products/some-product | grep -i x-norg-edge

Checkout is untouched (expect no output):

curl -sI -H "User-Agent: GPTBot" https://your-shop.com/checkout | grep -i x-norg-edge

Optional — is the worker alive at all?

curl -s -H "x-norg-edge-check: <your-site-key>" https://your-shop.com/ | head -c 200
# {"site_id":"…","version":"…","disabled":false,"ts":…}

A JSON reply confirms the script is deployed, routed, and holding the right key.

If this route doesn't work out

If the button flow fails, your setup can't support it, or you get stuck on any step above, you don't need to debug it alone. Give NORG a scoped Cloudflare API token instead and NORG deploys the worker, creates the route, and verifies the install end to end — including the Shopify-specific checks (O2O CNAME shape, Always Use HTTPS off) that this manual route leaves to you. Full walkthrough: Install a Cloudflare Worker mirror →

Troubleshooting

No X-Norg-Edge header for any user-agent, and the health probe returns the storefront instead of JSON. The worker isn't running on that request. Check, in order of likelihood: the CNAME to shops.myshopify.com is grey-clouded (must be proxied); the route was never added, or was added narrower than {your-shop-domain}/*; another Worker already owns that route and wins on precedence; the Worker was deployed into a different Cloudflare account than the one that owns the zone.
Shopify admin shows a warning about a Cloudflare proxy on the domain. Shopify's blanket warning covers proxy setups it can't reason about. A proxied CNAME to shops.myshopify.com — exactly this install — is the Orange-to-Orange shape Cloudflare documents and supports for Shopify. If the warning appears alongside real symptoms (SSL errors, pages not loading), treat it seriously and check the next item.
SSL certificate errors, or Shopify can't provision/renew the certificate. Almost always "Always Use HTTPS" (or an equivalent blanket redirect) at the Cloudflare layer. Shopify renews the certificate via HTTP requests to /.well-known/acme-challenge/*; a forced redirect breaks them. Turn the global toggle off and, for HTTP→HTTPS, use a Redirect Rule that excludes that path instead.
The worker never fires on /checkout — is something broken? No. Cloudflare disables Workers and Snippets on /checkout in O2O setups, by design. AI agents requesting checkout URLs simply get Shopify's normal response.
Health probe (or any request) returns HTTP 403 before the worker’s own logic runs. Cloudflare evaluates WAF Managed Rules and Bot Fight Mode before a Worker route fires, so either can block the health probe — and real agent traffic — before the worker ever sees it. Ask your NORG contact about the WAF skip-rule action available on the API-token install (see the fallback note above), which needs a token with Zone WAF: Edit.
Always "stripped", never "mirror". Nothing has been rendered for that path yet. Renders run at low priority and a first pass over a large store can take a while. If it persists more than a day, ask NORG to check whether its crawler can reach the storefront at all — Shopify's own bot protection challenging it means nothing will ever render.
Everything returns an error, humans included. Check the Cloudflare Workers request usage first — the account-wide free-plan cap above. To restore service immediately, set EDGE_DISABLED to true, or remove the route; the storefront is unaffected either way.

Limitations of the button install

A button install is a fork NORG cannot update — a Worker fix ships to every button-installed site only once someone in that account redeploys it. NORG can see the version drift (via heartbeats) and will email about it, but cannot act on it directly.
NORG's only remote control is invalidating the Site Key, which degrades the install to "always serve Shopify" — a safe stop, not an uninstall.
There is no route-conflict detection: if the zone already has a Worker on the same route, Cloudflare silently decides which one runs.
Config drift is invisible from NORG’s side — editing NORG_CONTENT_BASE or clearing NORG_SITE_KEY in the dashboard produces an install that looks deployed but serves nothing but the storefront.