Getting Started

The Shoplift JavaScript API gives you programmatic control over A/B test entry criteria and experiences, visitor consent, and test data retrieval. Use it to build custom test experiences that go beyond what template, theme, and URL tests offer.

How the Script Loads

Shoplift automatically injects and maintains its script in your theme's <head> section. You don't need to add any script tags — the script is managed for you and:

Loads before other scripts to minimize flicker
Initializes automatically on every page load
Provides the global window.shoplift object
Updates automatically when new versions are released

The `window.shoplift` Object

Once the page loads, three methods are available on the global window.shoplift object:

interface ShopliftPublic {
  isHypothesisActive(hypothesisId: string): Promise<boolean>;
  setAnalyticsConsent(consent: boolean): Promise<void>;
  getVisitorData(): ExternalVisitorData;
}

declare global {
  interface Window {
    shoplift?: ShopliftPublic;
  }
}

Method

Purpose

Returns

Async

isHypothesisActive()

Check if visitor is assigned to a specific test variant

Promise<boolean>

Yes

setAnalyticsConsent()

Sets the visitor's analytics consent state

Promise<void>

Yes

getVisitorData()

Returns visitor info and all test assignments

ExternalVisitorData

Quick Start

Most JavaScript API test implementations only need isHypothesisActive(). Here's the minimal pattern:

// 1. Check that Shoplift is loaded
if (window.shoplift) {

  // 2. Check the visitor's variant assignment
  const isVariant = await window.shoplift.isHypothesisActive('your-hypothesis-id');

  // 3. Render the appropriate experience
  if (isVariant) {
    // Variant (B) experience
  } else {
    // Control (A) experience
  }
}

The hypothesisId is the unique identifier for your test variant. You'll find it in the Shoplift dashboard when you create a JavaScript API test:

Safely Checking for Shoplift

The window.shoplift object may not be available immediately (e.g., if your script runs before Shoplift's script has loaded). You can use a polling pattern to wait for it:

function waitForShoplift(callback, maxAttempts = 50) {
  let attempts = 0;

  function check() {
    if (window.shoplift) {
      callback(window.shoplift);
    } else if (attempts < maxAttempts) {
      attempts++;
      setTimeout(check, 100);
    } else {
      console.warn('Shoplift did not load within the expected time.');
    }
  }

  check();
}

// Usage
waitForShoplift(async (shoplift) => {
  const isVariant = await shoplift.isHypothesisActive('your-hypothesis-id');
  // ...
});

When to Use the JavaScript API

The JavaScript API is the right choice when you need to:

Control trigger timing — assign visitors to tests only when they perform a specific action (open a cart, click a tab, scroll to a section)
Modify dynamic content — elements that load after the initial page render (AJAX carts, React components, lazy-loaded sections)
Set third-party consent management state — if your consent management platform doesn't integrate with Shopify's Customer Privacy API, you can set consent state
Combine targeting conditions — factor in more advanced targeting conditions like cookie presence or user behavior before including a visitor in a test and showing a variant
Integrate with third-party tools — pass test data to analytics platforms or interact with other apps programmatically

Nextwindow.shoplift

Last updated 1 hour ago

Was this helpful?

hashtagHow the Script Loads

hashtagThe window.shoplift Object

hashtagQuick Start

hashtagSafely Checking for Shoplift

hashtagWhen to Use the JavaScript API

How the Script Loads

The `window.shoplift` Object

Quick Start

Safely Checking for Shoplift

When to Use the JavaScript API