Overview

JavaScript API tests execute custom code in your theme to change what visitors see or experience on your store. Unlike template tests and theme tests (which swap layouts or entire themes), an API test uses developer-written JavaScript to make targeted behavior changes, add dynamic elements, or integrate with third-party tools.

API tests require developer involvement. Most merchants will need their developer or agency to write the JavaScript and (for manual API tests) implement the trigger logic.

When to use an API test

Use an API test when the change you want to make can't be accomplished by editing a template or swapping a theme. API tests are ideal for:

• Adding dynamic elements: notification bars, banners, popups, countdown timers, or chat widgets

• Modifying global UI with JavaScript: changing button text, hiding or showing elements, or adding badges across multiple pages

• Testing third-party script variations: comparing different recommendation engine configs, chat widget setups, or review display formats

• Custom trigger logic: running a test only after a specific visitor action (scrolling, hovering, spending time on page)

• Third-party system integration: triggering test behavior based on data from another platform

• Complex targeting scenarios: when Shoplift's built-in audience rules don't cover the exact conditions you need

How API tests work

This article covers basic usage of the JavaScript API for API testing purposes. For a full API reference, see Reference.

When you run an API test, Shoplift assigns each visitor to either the control group or the variant group, just like any other test type. But instead of switching a template or theme, Shoplift executes your custom JavaScript for visitors assigned to the variant by calling the isHypothesisActive() method in our API.

Interfacing with the API

The window.shoplift Object

The window.shoplift object is the entry point for the Shoplift JavaScript API. It's automatically set up on every page of your Shopify store and exposes the isHypothesisActive() method.

The object is available after Shoplift's script has loaded and initialized. It is attached to the global window scope.

// The object exists on window after script initialization
typeof window.shoplift // 'object' when loaded, 'undefined' before

// Always guard access
if (window.shoplift) {
  // Safe to use
}

isHypothesisActive()

The isHypothesisActive() method is the core of the Shoplift JavaScript API. It determines whether the current visitor is assigned to the variant (B) or control (A) group of your A/B test.

The hypothesisId is found in Shoplift when creating an API test:

Method Signature

isHypothesisActive(hypothesisId: string): Promise<boolean>

Parameters

Parameter	Type	Required	Description
hypothesisId	string	Yes	The unique identifier for your test variant. Found in Shoplift when creating a JavaScript API test.

Returns

Promise<boolean> — resolves to:

Value	Meaning
true	Visitor is assigned to this specific hypothesis
false	Visitor is not assigned to this hypothesis

The promise may reject if an error occurs during visitor assignment (e.g., a network failure during splitting). See Error Handling in our API Reference for the recommended pattern.

Basic Usage

Most implementations only need isHypothesisActive():

// Basic test implementation
const isVariant = await window.shoplift.isHypothesisActive('hypothesis-id');

if (isVariant) {
  // Show variant experience
} else {
  // Show control experience
}

API test triggers

There are two sub-types of API test, and they differ in when the code runs:

• Automatic trigger: your code runs automatically on every page load for assigned visitors. Shoplift handles execution during initialization, before the page becomes visible. No additional coding is needed beyond the variant script itself.

• Manual trigger: Shoplift reserves a test assignment for the visitor, but your code only runs when a developer explicitly triggers it using the isHypothesisActive() method. This gives you full control over when and where the test activates.

The trigger type is set in Shoplift when creating an API test:

For more information about API test triggers, see Test Triggers

Automatic Trigger

With automatic triggers, visitors enter the test immediately when the page loads, before any JavaScript API calls.

How it works:

// Visitor is ALREADY in the test before this code runs
const isActive = await window.shoplift.isHypothesisActive('hypothesis-id');
// This just checks their assignment

Manual Trigger

With manual triggers, visitors only enter the test when your code calls isHypothesisActive() for the first time.

How it works:

// No test participation yet
button.addEventListener('click', async () => {
  // Test participation triggered NOW, on first call
  const isActive = await window.shoplift.isHypothesisActive('hypothesis-id');
  // Visitor is now permanently assigned to a variant
});

Start with an automatic trigger if your change should apply to every page and doesn't need special trigger conditions. Choose a manual trigger if you need control over exactly when and where the code executes.