# 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

```typescript
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

```javascript
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.

```javascript
// 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.

```javascript
// 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:

```javascript
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
}
```

{% hint style="info" %}
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.
{% endhint %}

### 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
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.shoplift.ai/api-reference/reference/ishypothesisactive.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.