API Overview

Get up and running with the Shoplift JavaScript API in minutes.

Getting Started

The Shoplift JavaScript API gives you programmatic control over A/B test variant assignment, 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 ShopliftAPI {
  isHypothesisActive(hypothesisId: string): Promise<boolean>;
  setAnalyticsConsent(consent: boolean): Promise<void>;
  getVisitorData(): VisitorData;
}

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

Method

Purpose

Returns

Async

isHypothesisActive()

Check if visitor is assigned to a test variant

Promise<boolean>

Yes

setAnalyticsConsent()

Set visitor analytics consent

Promise<void>

Yes

getVisitorData()

Retrieve visitor info and test assignments

VisitorData

Quick Start

Most 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 test draft and test report pages when you create tests.

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). 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)
Combine conditions — factor in device type, location, or user behavior before showing a variant
Integrate with third-party tools — pass test data to analytics platforms or interact with other apps programmatically

For simpler use cases, Shoplift's no-code test types (template, theme, and URL tests) are a faster path. See the product documentation for a comparison.

Last updated 23 minutes ago

Was this helpful?

hashtagGetting Started

hashtagHow the Script Loads

hashtagThe window.shoplift Object

hashtagQuick Start

hashtagSafely Checking for Shoplift