isHypothesisActive()

Check whether the current visitor is assigned to a specific test variant.

isHypothesisActive()

The primary method for running A/B tests with the Shoplift JavaScript API. Determines whether the current visitor is assigned to the variant (B) or control (A) group for a given hypothesis.

Signature

window.shoplift.isHypothesisActive(hypothesisId: string): Promise<boolean>

Parameters

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

Returns

Promise<boolean> — resolves to:

Value	Meaning
true	Visitor is assigned to the variant (B)
false	Visitor is assigned to control (A), or the test is not active

Basic Usage

const isVariant = await window.shoplift.isHypothesisActive(
  'aa800953-3e22-4335-a53b-50f61db17538'
);

if (isVariant) {
  showVariantExperience();
} else {
  showControlExperience();
}

Behavior by Trigger Type

The method's side effects depend on how you configured the test's trigger in the Shoplift dashboard.

Automatic Trigger

The visitor is assigned to a variant on page load, before your code calls isHypothesisActive(). Calling the method simply reads the existing assignment.

// Visitor is ALREADY assigned by the time this runs
document.addEventListener('DOMContentLoaded', async () => {
  const isActive = await window.shoplift.isHypothesisActive('hypothesis-id');
  // isActive reflects the assignment that happened at page load
});

Manual Trigger

The visitor is assigned to a variant on the first call to isHypothesisActive(). Subsequent calls return the cached assignment.

// No assignment yet — visitor is not in the test

button.addEventListener('click', async () => {
  // FIRST CALL: assigns the visitor and returns the result
  const isActive = await window.shoplift.isHypothesisActive('hypothesis-id');

  // SUBSEQUENT CALLS: return the cached assignment (no re-assignment)
  const stillActive = await window.shoplift.isHypothesisActive('hypothesis-id');
  // isActive === stillActive (always)
});

This is useful when you only want to include visitors who perform a specific action (e.g., opening a cart or clicking a tab) in the test. See Test Triggers for a detailed comparison.

Return Value Scenarios

Returns true when:

• The visitor is assigned to the variant (B) through normal random assignment

• The URL contains ?slVariant=<hypothesisId> matching this hypothesis

• The URL contains ?slVariant=true (forces all hypotheses to return true)

Returns false when:

• The visitor is assigned to control (A)

• The test is inactive or paused

• The visitor doesn't meet the test's targeting criteria

• The hypothesisId is invalid or not found

• An error occurs (fails safe to control)

Error Handling

The method returns a Promise, so errors should be caught. On failure, the method defaults to false (control), ensuring visitors always see a valid experience.

try {
  const isVariant = await window.shoplift.isHypothesisActive('hypothesis-id');
  if (isVariant) {
    showVariantExperience();
  } else {
    showControlExperience();
  }
} catch (error) {
  console.error('Shoplift test check failed:', error);
  showControlExperience(); // Always fall back to control
}

Caching

After the first call for a given hypothesisId, the result is cached for the remainder of the page session. Subsequent calls resolve immediately without network requests. Assignments persist across page loads for the same visitor via Shoplift's visitor tracking.

URL Parameter Overrides

For testing and QA, you can force specific outcomes using URL parameters:

Parameter	Effect
?slVariant=<hypothesisId>	Forces isHypothesisActive() to return true for the matching hypothesis ID
?slVariant=true	Forces isHypothesisActive() to return true for all hypotheses
?isShopliftMerchant=true	Disables all Shoplift functionality (useful for debugging without test interference)

https://yourstore.com/products/example?slVariant=aa800953-3e22-4335-a53b-50f61db17538