> ## Documentation Index
> Fetch the complete documentation index at: https://helium-mintlify-create-navigation-structure-42614.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Experiments

> Run A/B tests to optimize conversion rates

An **experiment** is an A/B test that compares two or more paywall variants to determine which one performs best. Experiments live within a workflow and can be scoped to specific audiences and locales, allowing you to test different monetization strategies on different user segments simultaneously.

***

### **Anatomy of an Experiment**

| Field                   | Description                                                                                               |
| :---------------------- | :-------------------------------------------------------------------------------------------------------- |
| **Experiment Name**     | A human-readable label for the test (e.g., "Annual vs Monthly Q1 2025").                                  |
| **Hypothesis**          | An optional description of what you're testing and why.                                                   |
| **Experiment Type**     | The test methodology: abcd (standard A/B/C/D test), aa (validation test), or bandit (multi-armed bandit). |
| **Status**              | The current state: running, scheduled, or stopped.                                                        |
| **Paywall Variants**    | Two or more paywalls being tested, each with a traffic allocation percentage.                             |
| **Allocations**         | The percentage of traffic routed to each variant (must total 100%).                                       |
| **Control & Treatment** | Exactly one variant is marked as the **control** (your baseline). All others are **treatments**.          |
| **Locale**              | An optional locale scope (e.g., en\_US). A global experiment applies to all locales.                      |
| **Start / End Date**    | When the experiment begins and when it's scheduled to end.                                                |

***

### **Variants and Allocations**

Each experiment contains two or more **variants** — paywall designs you're comparing. Every variant has:

* A **paywall** — the actual paywall UI shown to users in that variant
* A **percentage allocation** — the share of eligible traffic this variant receives
* A **variant type** — either control (the baseline) or treatment (the challenger)

Allocations must total exactly **100%**. When a user qualifies for the experiment, they're randomly assigned to a variant based on these percentages and consistently see that same variant on subsequent triggers.

You can **update allocations on a running experiment**. When you do, Helium creates an **experiment version** — a snapshot of the allocation state. This lets you ramp up a promising treatment or wind down an underperformer without stopping the test entirely.

***

### **Lifecycle of an Experiment**

<Steps>
  <Step title="Create">
    Experiments are created from within a workflow's detail page. The creation flow has four steps:

    1. **Basic Info** — Name your experiment and state your hypothesis.
    2. **Target Audience** — Choose which audience this experiment applies to. You can select "All Users," pick an existing audience, or create a new one.
    3. **Paywalls & Allocations** — Select the paywall variants, mark one as control, and set traffic percentages.
    4. **Review** — Confirm your configuration before launching.

    Experiments start **immediately** upon creation — there is no draft state.
  </Step>

  <Step title="Running">
    While an experiment is running:

    * Users are **allocated to variants** based on the configured percentages.
    * Each user is **consistently bucketed** — they see the same variant every time the trigger fires.
    * You can **view results** on the experiment detail page, including per-variant metrics.
    * You can **adjust allocations** on the fly. Changing allocations creates a new experiment version for clean cohort tracking.
    * You can **add or remove paywall variants** from a running experiment.
  </Step>

  <Step title="Stop">
    When you stop an experiment, you decide what happens to the audience that was enrolled:

    | Option                            | Behavior                                                                                                                 |
    | :-------------------------------- | :----------------------------------------------------------------------------------------------------------------------- |
    | **Route to a specific paywall**   | Replace the experiment with a static paywall for that audience. Typically used to lock in the winner.                    |
    | **Fall through to next audience** | Remove the audience's targeting rule entirely, letting the user match the next applicable rule (or the control paywall). |

    Stopping an experiment updates the workflow's targeting criteria automatically. The experiment's status changes to stopped and a stopped\_at timestamp is recorded.
  </Step>

  <Step title="Analyze">
    Stopped experiments and their data remain available for analysis. You can filter and group metrics by experiment to compare variant performance across revenue, conversion rate, and other metrics.
  </Step>

  <Step title="Delete">
    Deleting an experiment removes it and its locale associations. A database constraint prevents deleting a **running** experiment — you must stop it first. Deletion is permanent.
  </Step>
</Steps>

***

### **Overlap and Conflict Rules**

The database enforces several constraints to prevent conflicting experiments:

* **One running experiment per workflow + locale.** You can't have two active experiments competing for the same locale within the same workflow.
* **Global experiments block all others.** A global experiment cannot overlap in time with any other experiment, regardless of locale or workflow.
* **Same-locale overlap protection.** Two experiments in the same workflow and locale cannot have overlapping date ranges if both are running or scheduled.

If you try to create an experiment that violates these rules, you'll see an overlap conflict error.

***

### **Audience Scoping**

Experiments are connected to audiences through the workflow's **targeting criteria**. When you create an experiment and select an audience:

* Helium adds a targeting rule to the parent workflow: "For this audience, run this experiment."
* Only users who match the audience see the experiment.
* Users outside the audience follow the workflow's other rules (or fall through to the control paywall).

If you select **All Users**, Helium creates (or reuses) a system "All Users" audience and maps it to the experiment.

Audiences that are already mapped to another experiment in the same workflow are excluded from selection, preventing double-enrollment.

***

### **Experiment Versions**

Every time you change an experiment's allocations, Helium creates an **experiment version** — an immutable snapshot of the allocation state at that point in time. This enables:

* Clean cohort analysis (users allocated under version 1 vs. version 2)
* Allocation change history
* Accurate attribution even when you ramp traffic mid-experiment

***

### **Stripe Paywall Constraints**

If any paywall variant in your experiment uses Stripe products, additional rules apply:

* **Stripe paywalls cannot be the control variant.** Stripe paywalls only work for a subset of users (Apple Pay enabled, US store), so using one as the control would bias results.
* **Audience must have Stripe-compatible targeting.** If you include a Stripe paywall, the experiment's audience must be configured to target only eligible users.

These constraints are validated during experiment creation and will block you if not satisfied.

***

### **Key Rules**

* Experiments start **immediately** — there is no draft state.
* Allocations must total exactly **100%**.
* Exactly **one variant** must be marked as the control.
* Only **published paywalls** can be used as variants.
* **Running experiments cannot be deleted** — stop them first.
* Only **one running experiment per workflow + locale** is allowed at a time.
* **Global experiments** cannot overlap with any other experiment.
* Changes to allocations are **versioned** for clean cohort tracking.
* Stopping an experiment automatically updates the parent workflow's targeting criteria.

***

### **Common Patterns**

| Pattern                  | Description                                                                                                   |
| :----------------------- | :------------------------------------------------------------------------------------------------------------ |
| **Simple A/B test**      | Two paywalls (control vs. treatment), 50/50 split, scoped to all users. The classic test.                     |
| **Multi-variant test**   | Three or more paywalls with custom allocations (e.g., 40% control, 30% treatment A, 30% treatment B).         |
| **Audience-scoped test** | Run an experiment only for a specific user segment, like "users on day 3+" or "users in the US."              |
| **Ramp-up**              | Start with 90/10 control/treatment, then gradually increase the treatment allocation as confidence grows.     |
| **Locale-specific test** | Run different experiments per locale — test annual pricing in the US while testing monthly pricing in Europe. |
| **AA test**              | Show the same paywall to both groups to validate your instrumentation and statistical methodology.            |

***