> ## Documentation Index
> Fetch the complete documentation index at: https://docs.abconvert.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Experiment Analytics — ABConvert API

> Query product-based and visitor-based analytics for a specific experiment, plus statistical significance timeseries, with flexible date and filter options.

<Note>
  **Preview — this page is an early draft.** We're still verifying the API reference against the current endpoints. Fields, response shapes, and examples may change before this section is marked stable. Follow [PRO-1459](https://linear.app/abconvert/issue/PRO-1459) or ask in `#abconvert-dev` if you're integrating against this today.
</Note>

ABConvert provides four analytics endpoints for a single experiment: two product-based and two visitor-based (v1 and v2). A fifth endpoint returns a timeseries of statistical significance values so you can visualize how confidence builds over the run of an experiment.

All analytics endpoints are session endpoints, require Shopify authentication, and accept the same standard request body described below.

***

## Standard analytics request

All analytics endpoints except the timeseries endpoint accept this request body:

```json theme={null}
{
  "dateStart": "2024-01-01T00:00:00.000Z",
  "dateFinish": "2024-01-31T23:59:59.999Z",
  "filterParams": {
    "countries": ["US", "CA"],
    "productIds": ["123456"]
  },
  "deviceType": "ALL",
  "visitorType": "ALL"
}
```

<ParamField body="dateStart" type="string" required>
  ISO 8601 start of the reporting window, inclusive.
</ParamField>

<ParamField body="dateFinish" type="string" required>
  ISO 8601 end of the reporting window, inclusive.
</ParamField>

<ParamField body="filterParams" type="object">
  Optional filters to narrow the result set.

  <Expandable title="filterParams fields">
    <ParamField body="countries" type="array">
      Array of two-letter ISO country codes. If omitted, all countries are included.
    </ParamField>

    <ParamField body="productIds" type="array">
      Array of Shopify product ID strings. If omitted, all products in the experiment are included.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="deviceType" type="string">
  Filter by device category. One of `"ALL"`, `"DESKTOP"`, `"MOBILE"`, or `"TABLET"`. Defaults to `"ALL"`.
</ParamField>

<ParamField body="visitorType" type="string">
  Filter by visitor type. One of `"ALL"`, `"VISITOR"` (new visitors), or `"CUSTOMER"` (returning customers). Defaults to `"ALL"`.
</ParamField>

***

## Product-based analytics

Returns conversion metrics aggregated at the product level. Use this view when you want to compare raw counts of views, add-to-carts, and revenue across test groups.

```
POST /api/analytics/:experimentId
```

### Path parameters

<ParamField path="experimentId" type="string" required>
  The `_id` of the experiment to query.
</ParamField>

### Example request

```bash theme={null}
curl -X POST "https://app.abconvert.io/api/analytics/64a1f2b3c4d5e6f7a8b9c0d1" \
  -H "Authorization: Bearer <shopi...en>" \
  -H "Content-Type: application/json" \
  -d '{
    "dateStart": "2024-01-01T00:00:00.000Z",
    "dateFinish": "2024-01-31T23:59:59.999Z",
    "filterParams": { "countries": ["US"] },
    "deviceType": "ALL",
    "visitorType": "ALL"
  }'
```

### Response

```json theme={null}
{
  "views": [1200, 1185],
  "addToCarts": [340, 390],
  "revenue": [8500.00, 9750.50],
  "conversionRates": {
    "addToCart": [0.283, 0.329],
    "purchase": [0.071, 0.082]
  }
}
```

<ResponseField name="views" type="array">
  Total product page views per test group. Index 0 is the control group; index 1 is the first variant.
</ResponseField>

<ResponseField name="addToCarts" type="array">
  Total add-to-cart events per test group.
</ResponseField>

<ResponseField name="revenue" type="array">
  Total revenue in store currency per test group.
</ResponseField>

<ResponseField name="conversionRates" type="object">
  Computed conversion rates for add-to-cart and purchase events, indexed by test group.
</ResponseField>

***

## Visitor-based analytics v1

Returns conversion metrics at the unique visitor level rather than per product view. This is the standard analytics view for most experiment types.

```
POST /api/analytics/v1/:experimentId
```

### Path parameters

<ParamField path="experimentId" type="string" required>
  The `_id` of the experiment to query.
</ParamField>

### Example request

```bash theme={null}
curl -X POST "https://app.abconvert.io/api/analytics/v1/64a1f2b3c4d5e6f7a8b9c0d1" \
  -H "Authorization: Bearer <shopi...en>" \
  -H "Content-Type: application/json" \
  -d '{
    "dateStart": "2024-01-01T00:00:00.000Z",
    "dateFinish": "2024-01-31T23:59:59.999Z",
    "deviceType": "DESKTOP",
    "visitorType": "ALL"
  }'
```

### Response

```json theme={null}
{
  "totalViews": [950, 940],
  "totalAddToCarts": [210, 255],
  "totalOrders": [67, 81],
  "totalRevenue": [6800.00, 8200.00],
  "statisticalSignificance": {
    "pValue": 0.043,
    "tStat": 2.04,
    "confidenceInterval": [0.02, 0.18]
  }
}
```

<ResponseField name="totalViews" type="array">
  Unique visitors who viewed the experiment per test group.
</ResponseField>

<ResponseField name="totalAddToCarts" type="array">
  Unique visitors who added to cart per test group.
</ResponseField>

<ResponseField name="statisticalSignificance" type="object">
  <Expandable title="statisticalSignificance fields">
    <ResponseField name="pValue" type="number">
      The p-value for the primary conversion metric. Values below 0.05 indicate statistical significance at the 95% confidence level.
    </ResponseField>

    <ResponseField name="tStat" type="number">
      The t-statistic for the two-sample test.
    </ResponseField>

    <ResponseField name="confidenceInterval" type="array">
      95% confidence interval for the difference in conversion rates between control and variant.
    </ResponseField>
  </Expandable>
</ResponseField>

***

## Visitor-based analytics v2

An enhanced version of visitor-based analytics that includes journey tracking — how visitors moved through the funnel across multiple sessions. Use v2 when you need more granular attribution.

```
POST /api/analytics/v2/:experimentId
```

### Path parameters

<ParamField path="experimentId" type="string" required>
  The `_id` of the experiment to query.
</ParamField>

### Example request

```bash theme={null}
curl -X POST "https://app.abconvert.io/api/analytics/v2/64a1f2b3c4d5e6f7a8b9c0d1" \
  -H "Authorization: Bearer <shopi...en>" \
  -H "Content-Type: application/json" \
  -d '{
    "dateStart": "2024-01-01T00:00:00.000Z",
    "dateFinish": "2024-01-31T23:59:59.999Z",
    "deviceType": "ALL",
    "visitorType": "ALL"
  }'
```

The response shape is an extension of v1, with additional journey-level breakdown fields included for each test group.

***

## Statistical significance timeseries

Returns a day-by-day (or period-by-period) breakdown of statistical significance over the life of the experiment. Use this to visualize how confidence grows and identify when the experiment reached significance.

```
POST /api/analytics/timeseries/:experimentId
```

### Path parameters

<ParamField path="experimentId" type="string" required>
  The `_id` of the experiment to query.
</ParamField>

### Request body

<ParamField body="dateStart" type="string" required>
  ISO 8601 start of the reporting window.
</ParamField>

<ParamField body="dateFinish" type="string" required>
  ISO 8601 end of the reporting window.
</ParamField>

<ParamField body="totalViews" type="array" required>
  Total cumulative visitor counts per group at the time of the query. Example: `[950, 940]`.
</ParamField>

<ParamField body="type" type="string">
  Metric to use for the significance calculation. Pass `"sales"` to use revenue; omit for the default conversion rate calculation.
</ParamField>

### Example request

```bash theme={null}
curl -X POST "https://app.abconvert.io/api/analytics/timeseries/64a1f2b3c4d5e6f7a8b9c0d1" \
  -H "Authorization: Bearer <shopi...en>" \
  -H "Content-Type: application/json" \
  -d '{
    "dateStart": "2024-01-01T00:00:00.000Z",
    "dateFinish": "2024-01-31T23:59:59.999Z",
    "totalViews": [950, 940],
    "type": "sales"
  }'
```

### Response

```json theme={null}
{
  "timeSeriesData": [
    { "date": "2024-01-01", "significance": 0.12 },
    { "date": "2024-01-07", "significance": 0.31 },
    { "date": "2024-01-14", "significance": 0.67 },
    { "date": "2024-01-21", "significance": 0.89 },
    { "date": "2024-01-31", "significance": 0.96 }
  ],
  "overallSignificance": 0.96
}
```

<ResponseField name="timeSeriesData" type="array">
  Array of date + significance pairs. `significance` ranges from 0 to 1, where values above 0.95 indicate 95% confidence.
</ResponseField>

<ResponseField name="overallSignificance" type="number">
  The aggregate statistical significance for the full date range.
</ResponseField>