isHypothesisActive()

The primary method for running A/B tests with the Shoplift JavaScript API. Determines whether the current visitor is assigned to a specific hypothesis (variant). For manual API tests, the first call also triggers the visitor's test assignment.

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 this specific hypothesis
false	Visitor is not assigned to this hypothesis (assigned to control, a different variant, test is inactive, visitor doesn't qualify, etc.)

The promise may reject if an error occurs during visitor assignment (e.g., a network failure during splitting). See Error Handling for the recommended pattern.

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 during Shoplift's initialization, before your code calls isHypothesisActive(). Calling the method simply reads the existing assignment.

// Visitor is ALREADY assigned by the time this runs
if (window.shoplift) {
  const isActive = await window.shoplift.isHypothesisActive('hypothesis-id');
  // isActive reflects the assignment that happened during initialization
}

Manual Trigger

The visitor is assigned to a variant on the first call to isHypothesisActive(). Subsequent calls return the existing 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 existing 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 this specific hypothesis 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 or a different variant

• The visitor is excluded from the test (hypothesisId is null in the assignment)

• The test is inactive or paused

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

• The hypothesisId is invalid or not found

Error Handling

The method returns a Promise that may reject if an error occurs during visitor assignment (for example, a network failure when splitting a visitor into a manual test). The method does not automatically fall back to false — your code is responsible for handling errors gracefully.

Always wrap calls in try/catch so visitors see a valid experience even if something goes wrong:

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

Errors are only possible on the first call for a manual-trigger test, when the visitor is being assigned. Subsequent calls and all automatic-trigger calls read from local state and will not reject.

Mutual Exclusion

API tests participate in Shoplift's mutual exclusion system. The behavior depends on the trigger type:

• Automatic API tests block all conditional tests (template, URL redirect, manual API) for that visitor. They have the same exclusion scope as theme and price tests.

• Manual API tests block global tests (theme, price, automatic API) for that visitor.

This means a visitor cannot be in both an automatic API test and a manual API test simultaneously.

Assignment Persistence

After a visitor is assigned to a test, the assignment is stored in Shoplift's visitor state and persists across page loads. Subsequent calls to isHypothesisActive() for the same hypothesis read directly from local state without network requests.

URL Parameter Overrides

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

Parameter	Effect
?slVariant=<hypothesisId>	Forces true for the matching hypothesis ID, false for all others
?slVariant=true	Forces 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