Install it, read it, build on it

Stores without the Growth Dept app connect with a custom-app Admin API token. CRO then writes the gd-cro snippet to the theme and the configuration to the shop metafield gd_cro.config. Render the snippet above </head>:

  {% render 'gd-cro' %}
</head>

The pixel is a custom pixel pasted into Shopify's Customer events. Runtime files are served from https://cro.growthdept.ai/r/ with versioned names.

The middleware adapter reads the brand's published configuration, decides the visitor's arm on the server and rewrites split URL arms under the original address. It keeps a short in-memory cache with a stale fallback, so a slow request never blocks a page.

GET https://cro.growthdept.ai/c/<public key>/config.json

Access-Control-Allow-Origin: *
Cache-Control: public, max-age=30, stale-while-revalidate=300

The public key (pk_…) is on the brand's settings page.

For a static or custom site in front of a Shopify checkout, the Worker adapter makes the same decision at the edge and serves the arm without changing the address. It adds the visitor's arms to cart permalinks, so the checkout carries them.

When a brand runs a headless or static site beside its Shopify theme, set the cookie domain to the parent domain so both share one visitor and one arm.

The visitor id and arms live in the _cro cookie for one year, the config's cookie.days (Path=/, SameSite=Lax, Secure). QA visitors are marked in it and left out of results.

On a theme install the runtime exposes window.CRO once the page is parsed. These members are always there:

Switch on JavaScript API on the Integrations page for the rest. The store then loads one more small file, cached and loaded after the page is parsed:

To run code once the API is ready, listen for cro:ready on window or document, or set window.onCroReady to a function or an array of functions. Each callback runs in its own try with window.CRO; one set or pushed later runs at once. With the JavaScript API on, cro:ready waits for the whole API.

window.onCroReady = (cro) => {
  const tests = cro.getTests();
  if (tests.length) console.log(tests[0].name, tests[0].groupName);
};

Every assignment is pushed to window.dataLayer as a cro_assignment event with cro_test (the test id), cro_variant (the group key) and exp_variant_string (CRO - <test name> - <group name>), before Tag Manager's DOM Ready trigger. To send it to GA4 through Google Tag Manager:

1. Add a Data Layer Variable named exp_variant_string (and cro_test and cro_variant if you want the ids).
2. Add a Custom Event trigger for the event name cro_assignment.
3. Add a GA4 Event tag named experience_impression with the parameter exp_variant_string set to the variable, fired by that trigger.
4. Publish the container, and register exp_variant_string as an event-scoped custom dimension in GA4.

A store that loads GA4 with gtag.js and no Tag Manager can switch on Google Analytics 4 on the Integrations page instead: the runtime then calls gtag("event", "experience_impression", …) itself on each page view. If GA4 counts fewer visitors than the test does, check that the Google tag loads in the page's head and that window.gtag exists; GA4 also drops some hits that tests count, so compare orders with the test's own results, not GA4's.

Clarity, Hotjar, Amplitude, Heap and Segment get each group through their own browser API once they are switched on there; the runtime never loads a tool. Hotjar gets the event <test> - <group>, Amplitude cro_impression, Heap one CRO Impression event per page view, Segment its standard Experiment Viewed event, and Clarity the tags experiment_name and cro_test_group. To change how often a tool hears of a test, set this in the theme before the app embed:

<script>
  window.croSettings = { integrations: {
    segment: { trackMode: "assignment" },             // once per visitor and group
    heap: { trackMode: "timed", timeSinceAssignment: 3600 }
  } };
</script>

trackMode is impression (every page view; Heap and Segment by default), assignment (Amplitude's default), timed or session (Hotjar's default). Split URL redirects keep UTM tags and click ids.

Apps that switch a feature on or off for an A/B test usually read a cart attribute or a window flag. Set it in a content test's group JavaScript, which runs once per page view for that group (at once, after the page loads, or after a delay you choose). The control's JavaScript sets the other value.

fetch("/cart/update.js", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ attributes: { "_tm_hide_widgets": "true" } })
});

These attribute names are the ones each app documents for testing tools. We have not checked every app ourselves: start the test QA-only, open a preview link for each group and check the app before shoppers see it. Corso reads another tool's group id and needs its support team; ask us before testing it.

Price, shipping, offer and content tests need nothing extra for express checkout buttons such as JUST, since the discounts and prices are applied in Shopify's checkout. A free gift is the exception: the storefront adds it to the cart when the cart changes, so a button that goes from a product page straight to checkout skips it. Hide those buttons on product pages while a gift offer runs.

A checkout outside Shopify's (Checkout Champ, a custom checkout) must carry the _cro value onto the order as an order attribute, or the order is not counted in the test. With the JavaScript API on, read it from CRO.cartAttribute() when the shopper adds to cart and pass it on; the session must start on the store. Cart permalinks (/cart/<variant>:<qty>) on the store get the cart attributes when clicked; a permalink built in JavaScript should add attributes[_cro] itself. Checkouts that agents create through Shopify's Universal Commerce Protocol run the same discount and price Functions, but carry no _cro attribute, so those buyers get the control and are not counted.

Runtimes send exposures and page views, and the pixel sends add to cart, checkout and purchase events, to one collector:

POST https://cro.growthdept.ai/c/e
Content-Type: text/plain   (JSON body, sent with navigator.sendBeacon)

{ "b": "pk_...", ... }      batch field b is the brand's public key; 16 KB limit

The collector checks the key and the page's origin and drops malformed batches and bots. A purchase event never counts on its own: the order sync confirms it against Shopify's order.

Brand API keys are created on the brand's settings page and stored only as hashes. With a key, the public API under https://cro.growthdept.ai/api/v1 creates and edits draft tests, starts, pauses and ends them, reads their results with a verdict, segments, time series and exports, reads the sitewide dashboards, and serves message tests: the version for a recipient, and the events that follow.

Each key has rate limits: 50 requests, then 25 more every 30 seconds, with tighter limits for recomputed results (fresh=1), exports and sitewide analytics. Every answer says what is left in X-RateLimit-Remaining; past the limit the API answers 429 with Retry-After.

GET https://cro.growthdept.ai/api/v1/tests/<id>/verdict
Authorization: Bearer cro_...

{"code": "directional_win", "headline": "...", "action": "Keep the test running until ..."}

For the full reference, email hello@growthdept.ai.

Claude, ChatGPT, Gemini and any other assistant that speaks the Model Context Protocol can connect to https://cro.growthdept.ai/api/mcp (Streamable HTTP). Add it as a connector by that URL and sign in when the assistant asks: on Growth Dept CRO's consent page you choose the brand and what the assistant may do (read tests and results, change and pause tests, start tests shoppers see, read the sitewide dashboards). Viewers can allow reading only, and the assistant can never do more than your role allows. A client that sends headers can use a brand API key in the Authorization header instead. Either way the assistant sees only the tools its scopes cover, and each tool spends from the connection's rate limits like an API call. Disconnect in the assistant, or revoke the connection under Settings, API keys.

claude mcp add --transport http growth-dept-cro https://cro.growthdept.ai/api/mcp

claude mcp add --transport http growth-dept-cro https://cro.growthdept.ai/api/mcp \
  --header "Authorization: Bearer cro_..."

In Claude (web, desktop and mobile), add a custom connector with the URL under Customize, Connectors. In ChatGPT, add it as a connector in developer mode. Both then sign in.

A key with tests:read alone gives a read-only assistant. Money in the answers is in the store currency's minor units (cents for USD), rates are fractions and lifts are percent.