Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

JavaScript API

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

No

Quick Start

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

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:

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

PreviousAPI Reference
Nextwindow.shoplift

Last updated

Was this helpful?