# Overview
JavaScript API tests execute custom code in your theme to change what visitors see or experience on your store. Unlike template tests and theme tests (which swap layouts or entire themes), an API test uses developer-written JavaScript to make targeted behavior changes, add dynamic elements, or integrate with third-party tools.
{% hint style="info" %}
API tests require developer involvement. Most merchants will need their developer or agency to write the JavaScript and (for manual API tests) implement the trigger logic.
{% endhint %}
### When to use an API test
Use an API test when the change you want to make can't be accomplished by editing a template or swapping a theme. API tests are ideal for:
* **Adding dynamic elements**: notification bars, banners, popups, countdown timers, or chat widgets
* **Modifying global UI with JavaScript**: changing button text, hiding or showing elements, or adding badges across multiple pages
* **Testing third-party script variations**: comparing different recommendation engine configs, chat widget setups, or review display formats
* **Custom trigger logic**: running a test only after a specific visitor action (scrolling, hovering, spending time on page)
* **Third-party system integration**: triggering test behavior based on data from another platform
* **Complex targeting scenarios**: when Shoplift's built-in audience rules don't cover the exact conditions you need
### How API tests work
{% hint style="info" %}
This article covers basic usage of the JavaScript API for API testing purposes. For a full API reference, see [Reference](/api-reference/reference/window.shoplift.md).
{% endhint %}
When you run an API test, Shoplift assigns each visitor to either the control group or the variant group, just like any other test type. But instead of switching a template or theme, Shoplift executes your custom JavaScript for visitors assigned to the variant by calling the `isHypothesisActive()` method in our API.
### Interfacing with the API
#### **The window\.shoplift Object**
The `window.shoplift` object is the entry point for the Shoplift JavaScript API. It's automatically set up on every page of your Shopify store and exposes the `isHypothesisActive()` method.
The object is available after Shoplift's script has loaded and initialized. It is attached to the global `window` scope.
```typescript
// 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
}
```
#### isHypothesisActive()
The `isHypothesisActive()` method is the core of the Shoplift JavaScript API. It determines whether the current visitor is assigned to the variant (B) or control (A) group of your A/B test.
The `hypothesisId` is found in Shoplift when creating an API test:
#### Method Signature
```typescript
isHypothesisActive(hypothesisId: string): Promise
```
#### Parameters
Parameter
Type
Required
Description
hypothesisId
string
Yes
The unique identifier for your test variant. Found in Shoplift when creating a JavaScript API test.
#### Returns
`Promise` — resolves to:
| Value | Meaning |
| ------- | ----------------------------------------------- |
| `true` | Visitor is assigned to this specific hypothesis |
| `false` | Visitor is not assigned to this hypothesis |
The promise may **reject** if an error occurs during visitor assignment (e.g., a network failure during splitting). See [Error Handling](https://docs.shoplift.ai/api-reference/reference/ishypothesisactive#error-handling) in our [API Reference](https://docs.shoplift.ai/api-reference/reference/ishypothesisactive) for the recommended pattern.
### Basic Usage
Most implementations only need `isHypothesisActive()`:
```typescript
// Basic test implementation
const isVariant = await window.shoplift.isHypothesisActive('hypothesis-id');
if (isVariant) {
// Show variant experience
} else {
// Show control experience
}
```
### API test triggers
There are two sub-types of API test, and they differ in *when* the code runs:
* **Automatic trigger**: your code runs automatically on every page load for assigned visitors. Shoplift handles execution during initialization, before the page becomes visible. No additional coding is needed beyond the variant script itself.
* **Manual trigger**: Shoplift reserves a test assignment for the visitor, but your code only runs when a developer explicitly triggers it using the `isHypothesisActive()` method. This gives you full control over when and where the test activates.
The trigger type is set in Shoplift when creating an API test:
{% hint style="info" %}
For more information about API test triggers, see [JavaScript API Tests](/api-reference/guides/javascript-api-tests.md#test-triggers)
{% endhint %}
#### **Automatic Trigger**
With automatic triggers, visitors enter the test immediately when the page loads, before any JavaScript API calls.
How it works:
```typescript
// Visitor is ALREADY in the test before this code runs
const isActive = await window.shoplift.isHypothesisActive('hypothesis-id');
// This just checks their assignment
```
#### **Manual Trigger**
With manual triggers, visitors only enter the test when your code calls isHypothesisActive() for the first time.
How it works:
```typescript
// No test participation yet
button.addEventListener('click', async () => {
// Test participation triggered NOW, on first call
const isActive = await window.shoplift.isHypothesisActive('hypothesis-id');
// Visitor is now permanently assigned to a variant
});
```
**Start with an automatic trigger** if your change should apply to every page and doesn't need special trigger conditions. **Choose a manual trigger** if you need control over exactly when and where the code executes.
---
# 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/test/javascript-api/overview.md?ask=
```
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.