window.shoplift

The global Shoplift API object and entry point for all client-side functionality.

window.shoplift

The window.shoplift object is the entry point for the Shoplift JavaScript API. It's automatically injected into every page of your Shopify store and exposes three methods for interacting with A/B tests.

Availability

The object is available after Shoplift's script has loaded and initialized. It is attached to the global window scope — no imports or module resolution is required.

// 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
}

Object Shape

interface ShopliftAPI {
  /**
   * Check if the current visitor is assigned to a specific test variant.
   * Returns true for variant (B), false for control (A).
   */
  isHypothesisActive(hypothesisId: string): Promise<boolean>;

  /**
   * Manually set visitor analytics consent.
   * Only needed for custom consent management platforms.
   */
  setAnalyticsConsent(consent: boolean): Promise<void>;

  /**
   * Retrieve visitor information and test assignments.
   * Synchronous — returns data immediately.
   */
  getVisitorData(): VisitorData;
}

Methods

Method

Description

Async

Details

isHypothesisActive(id)

Returns whether the visitor is in the variant group for a given hypothesis

Yes

Reference →

setAnalyticsConsent(consent)

Sets the visitor's analytics consent state

Yes

Reference →

getVisitorData()

Returns visitor info and all test assignments

Reference →

Loading Behavior

Shoplift's script is injected into the <head> of your theme and loads with the following characteristics:

Automatic injection — Shoplift installs and maintains the script tag. You never need to add it manually.
Early loading — The script loads before most other third-party scripts to reduce flicker when applying variant changes.
Automatic updates — When Shoplift releases improvements, the script updates without any action on your part.
No dependencies — The script is self-contained and doesn't require jQuery, React, or any other library.

Waiting for the Object

If your code runs before Shoplift's script has loaded, window.shoplift will be undefined. Use one of these patterns to wait:

Polling (recommended)

function onShopliftReady(callback, interval = 100, maxAttempts = 50) {
  let attempts = 0;
  const timer = setInterval(() => {
    if (window.shoplift) {
      clearInterval(timer);
      callback(window.shoplift);
    } else if (++attempts >= maxAttempts) {
      clearInterval(timer);
      console.warn('Shoplift: script did not load.');
    }
  }, interval);
}

onShopliftReady(async (shoplift) => {
  const isActive = await shoplift.isHypothesisActive('hypothesis-id');
  // ...
});

Inline Guard

For one-off checks where you don't need to wait:

if (window.shoplift) {
  const data = window.shoplift.getVisitorData();
}

Error Handling

All async methods (isHypothesisActive, setAnalyticsConsent) return Promises that may reject. Always wrap calls in try/catch:

try {
  const isVariant = await window.shoplift.isHypothesisActive('hypothesis-id');
  // Apply variant
} catch (error) {
  console.error('Shoplift error:', error);
  // Fall back to control experience
}

The synchronous getVisitorData() method will not throw, but may return { visitor: null, visitorTests: [] } if data isn't available yet.

Browser Compatibility

The Shoplift script works in all modern browsers (Chrome, Firefox, Safari, Edge). It uses Promises, so environments must support ES6+ or have a polyfill loaded.

TypeScript

Add these declarations to your project to get type-checking:

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

interface VisitorData {
  visitor: Visitor | null;
  visitorTests: TestRelation[];
}

interface Visitor {
  id: string;
  shopifyAnalyticsId: string | null;
  device: 'desktop' | 'mobile';
  country: string | null;
  createdAt: Date;
  storedAt: Date;
  utmSource: string;
  utmMedium: string;
  utmCampaign: string;
  utmContent: string;
  referrer: string;
}

interface TestRelation {
  testId: string;
  hypothesisId: string;
  isThemeTest: boolean;
  themeId?: number;
  createdAt: Date;
  isSaved: boolean;
}

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

PreviousAPI Overview NextisHypothesisActive()

Last updated 2 hours ago

Was this helpful?

hashtagwindow.shoplift

hashtagAvailability

hashtagObject Shape

hashtagMethods

hashtagLoading Behavior

hashtagWaiting for the Object

hashtagPolling (recommended)

hashtagInline Guard

hashtagError Handling

hashtagBrowser Compatibility

hashtagTypeScript

window.shoplift

Availability

Object Shape

Methods

Loading Behavior

Waiting for the Object

Polling (recommended)

Inline Guard

Error Handling

Browser Compatibility

TypeScript