API reference overview

The developer API for AB Test lives on your storefront: a small window.abtest object, its configuration, and the endpoint that assigns visitors to variants — everything you need to build JavaScript API tests and custom integrations.

Who this is for

This reference is for developers. Most of AB Test needs no code: URL, template, and theme tests are set up entirely in the admin, and the app never creates or edits your theme files. You only need this section when you are building a JavaScript API test — where your own theme or app code renders each variant — or when you want to understand exactly how assignment and revenue attribution work on the storefront.

If you are a merchant looking to configure and read tests, start with the documentation instead. Come here when you need method signatures, the shape of the on-page config, or the details of the assignment request.

Only the JavaScript API test type requires code. URL, template, and theme tests are handled for you and are documented in the main documentation.

What this reference covers

The storefront surface is intentionally small. These pages document each part of it.

PageWhat it covers
window.abtest API The methods you call from your code, including isHypothesisActive() to ask whether a variant is active and getState() to read the current assignment state, plus the ready queue for calling them safely.
window.__ABTEST__ config The configuration object the app embed writes onto the page — the running experiments, variant ids, and settings the API reads from.
JavaScript test workflow Building a JavaScript API test end to end: copying variant ids, rendering variants, avoiding a flash of the control, and automatic vs manual triggering.
Assignment endpoint The app proxy request that assigns a visitor to a variant and returns the decision the API acts on.
Data and consent What the storefront reads and stamps, the anonymous visitor id, and how opt-out consent affects the API.

Prerequisite: enable the app embed

The entire storefront API is delivered by the AB Test app embed (a theme app extension). Nothing on this page exists on your pages until the embed is enabled. Before you write any code:

  1. Open Online Store > Themes > Customize in your Shopify admin.
  2. Go to App embeds and turn on AB Test.
  3. Keep the Web Pixel enabled so views, conversions, and revenue are recorded.
  4. Save the theme.

With the embed enabled, the app writes its window.__ABTEST__ config onto the page and exposes window.abtest. Without it, window.abtest is undefined and no assignment happens.

If window.abtest is missing on your storefront, the app embed is not enabled on the active theme. Check App embeds before debugging your own code.

A first look

The one call you will use most is isHypothesisActive(). It takes a variant id from the app and returns a boolean for the current visitor, so you can branch your rendering. Use the ready queue so your code runs after the API is available.

<script>
  window.abtest = window.abtest || {};
  (window.abtest.q = window.abtest.q || []).push(function () {
    if (window.abtest.isHypothesisActive("VARIANT_ID_FROM_APP")) {
      // Visitor is in this variant — render your version.
      document.querySelector(".hero__title").textContent =
        "Free shipping on every order";
    }
    // Otherwise leave the original (control) in place.
  });
</script>

Assignment is stable for a visitor, so repeated calls with the same variant id return the same answer throughout their visit. The JavaScript API reference covers the full signatures and the ready queue in detail.

How assignment and attribution fit together

When the API needs a decision it calls the assignment endpoint through the app proxy. The endpoint applies your targeting rules, picks a variant, and keeps that choice stable. The app embed also stamps an anonymous visitor id (_ab_vid) as a Shopify cart attribute, which rides to the order so revenue attribution credits the right variant — even when checkout happens on Shop Pay or through a third-party checkout. The API never reads customer name, email, phone, or address; see Data and consent for exactly what is read and how opt-out consent is respected.

Where to go next