Launch a test

curl --request POST \
  --url https://api.abconvert.io/v1/experiments/{id}/start \
  --header 'Authorization: Bearer <token>'

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.abconvert.io/v1/experiments/{id}/start', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.abconvert.io/v1/experiments/{id}/start",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.abconvert.io/v1/experiments/{id}/start"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.abconvert.io/v1/experiments/{id}/start")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "object": "experiment",
  "id": "3021",
  "type": "price",
  "status": "draft",
  "name": "<string>",
  "test_groups": [
    {
      "name": "Variant A",
      "control": false,
      "split": 50,
      "changes": [
        {
          "type": "price",
          "adjustment": {
            "unit": "percentage",
            "value": 0
          },
          "prices": [
            {
              "product_variant_id": "gid://shopify/ProductVariant/45678",
              "price": {
                "amount": "17.99",
                "currency": "USD"
              },
              "compare_at_price": {
                "amount": "24.99",
                "currency": "USD"
              },
              "country_prices": [
                {
                  "country": "AU",
                  "price": {
                    "amount": "27.99",
                    "currency": "AUD"
                  }
                }
              ]
            }
          ]
        }
      ],
      "template_preview_url": "<string>"
    }
  ],
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "hypothesis": "<string>",
  "primary_metric": "revenue_per_visitor",
  "traffic_allocation": 123,
  "shared": {
    "price": {
      "product_ids": [
        "gid://shopify/Product/8123456789"
      ],
      "markets": [
        {
          "id": "gid://shopify/Market/13762560",
          "countries": [
            "<string>"
          ]
        }
      ]
    },
    "shipping": {
      "zone_ids": [
        "gid://shopify/DeliveryZone/282141261"
      ]
    },
    "theme": {
      "path_rules": {
        "mode": "include",
        "rules": [
          {
            "match_type": "exact",
            "match_value": "/collections/sale",
            "subject": "path"
          }
        ]
      }
    },
    "template": {
      "theme_id": "gid://shopify/OnlineStoreTheme/123456789",
      "template_type": "product",
      "path_rules": {
        "mode": "include",
        "rules": [
          {
            "match_type": "exact",
            "match_value": "/collections/sale",
            "subject": "path"
          }
        ]
      }
    },
    "url_redirect": {
      "rules": [
        {
          "key": "<string>",
          "match_type": "exact",
          "match_value": "/products/old-pdp",
          "subject": "path"
        }
      ],
      "redirect": {
        "mode": "always",
        "preserve_query_string": true
      }
    },
    "offer": {
      "combines_with": {
        "product_discounts": true,
        "order_discounts": true,
        "shipping_discounts": true
      }
    }
  },
  "schedule": {
    "start_at": "2023-11-07T05:31:56Z",
    "end_at": "2023-11-07T05:31:56Z"
  },
  "audience": {
    "filter_groups": [
      {
        "filters": [
          {
            "type": "device",
            "operator": "equals",
            "value": "mobile"
          }
        ]
      },
      {
        "filters": [
          {
            "type": "visitor_type",
            "operator": "equals",
            "value": "new"
          }
        ]
      }
    ]
  },
  "has_force_assign_rules": true,
  "assignment_version": 123,
  "product_group": {
    "id": "66c1f0a2e4b0a1d2c3e4f5a6",
    "name": "Bestsellers"
  },
  "results_summary": {
    "computed_at": "2023-11-07T05:31:56Z",
    "test_groups": [
      {
        "test_group_index": 1,
        "sample_size": 5231,
        "session_count": 6816,
        "conversion_rate": 0.034,
        "revenue_per_visitor": {
          "amount": "17.99",
          "currency": "USD"
        },
        "average_order_value": {
          "amount": "17.99",
          "currency": "USD"
        },
        "profit_per_visitor": {
          "amount": "17.99",
          "currency": "USD"
        },
        "add_to_cart_rate": 0.081,
        "reached_checkout_rate": 0.052
      }
    ],
    "outcome": "winner",
    "winning_test_group_index": 123,
    "srm_status": "ok"
  },
  "started_at": "2023-11-07T05:31:56Z",
  "ended_at": "2023-11-07T05:31:56Z"
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "details": {},
    "findings": [
      {
        "severity": "error",
        "code": "product_not_found",
        "message": "<string>",
        "param": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "details": {},
    "findings": [
      {
        "severity": "error",
        "code": "product_not_found",
        "message": "<string>",
        "param": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "details": {},
    "findings": [
      {
        "severity": "error",
        "code": "product_not_found",
        "message": "<string>",
        "param": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "details": {},
    "findings": [
      {
        "severity": "error",
        "code": "product_not_found",
        "message": "<string>",
        "param": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "details": {},
    "findings": [
      {
        "severity": "error",
        "code": "product_not_found",
        "message": "<string>",
        "param": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "details": {},
    "findings": [
      {
        "severity": "error",
        "code": "product_not_found",
        "message": "<string>",
        "param": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "details": {},
    "findings": [
      {
        "severity": "error",
        "code": "product_not_found",
        "message": "<string>",
        "param": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "details": {},
    "findings": [
      {
        "severity": "error",
        "code": "product_not_found",
        "message": "<string>",
        "param": "<string>"
      }
    ]
  }
}

Lifecycle

Launch a test

Launches a test. Use the same call from draft or from preview.

Before launching, ABConvert checks the test against the rest of your store. Any error finding returns 422 and the test stays where it was. These checks include cross-test rules:

A running theme test blocks shipping, template, and URL redirect tests, plus any combined test that carries one of those changes, and a second theme test. Each returns the finding theme_test_running. A visual editor test returns visual_editor_conflict. Price, offer, and checkout tests can launch while a theme test runs.
Two price tests cannot share a product, and two shipping tests cannot share a delivery zone. Either case returns the finding resource_claimed, naming the test that already has it.
A theme test in preview occupies the store just as a running one does, so previewing a theme test blocks the same launches. Products and delivery zones are claimed only while a test is active.

Two other outcomes:

While platform checks are still running on the test, start returns 409 checks_pending. Retry once they finish; the response lists what you can do meanwhile in details.allowed_actions.
On a test that is already active, start returns 200 and the unchanged test.

POST

experiments

{id}

start

Launch a test

curl --request POST \
  --url https://api.abconvert.io/v1/experiments/{id}/start \
  --header 'Authorization: Bearer <token>'

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.abconvert.io/v1/experiments/{id}/start', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.abconvert.io/v1/experiments/{id}/start",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.abconvert.io/v1/experiments/{id}/start"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.abconvert.io/v1/experiments/{id}/start")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "object": "experiment",
  "id": "3021",
  "type": "price",
  "status": "draft",
  "name": "<string>",
  "test_groups": [
    {
      "name": "Variant A",
      "control": false,
      "split": 50,
      "changes": [
        {
          "type": "price",
          "adjustment": {
            "unit": "percentage",
            "value": 0
          },
          "prices": [
            {
              "product_variant_id": "gid://shopify/ProductVariant/45678",
              "price": {
                "amount": "17.99",
                "currency": "USD"
              },
              "compare_at_price": {
                "amount": "24.99",
                "currency": "USD"
              },
              "country_prices": [
                {
                  "country": "AU",
                  "price": {
                    "amount": "27.99",
                    "currency": "AUD"
                  }
                }
              ]
            }
          ]
        }
      ],
      "template_preview_url": "<string>"
    }
  ],
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "hypothesis": "<string>",
  "primary_metric": "revenue_per_visitor",
  "traffic_allocation": 123,
  "shared": {
    "price": {
      "product_ids": [
        "gid://shopify/Product/8123456789"
      ],
      "markets": [
        {
          "id": "gid://shopify/Market/13762560",
          "countries": [
            "<string>"
          ]
        }
      ]
    },
    "shipping": {
      "zone_ids": [
        "gid://shopify/DeliveryZone/282141261"
      ]
    },
    "theme": {
      "path_rules": {
        "mode": "include",
        "rules": [
          {
            "match_type": "exact",
            "match_value": "/collections/sale",
            "subject": "path"
          }
        ]
      }
    },
    "template": {
      "theme_id": "gid://shopify/OnlineStoreTheme/123456789",
      "template_type": "product",
      "path_rules": {
        "mode": "include",
        "rules": [
          {
            "match_type": "exact",
            "match_value": "/collections/sale",
            "subject": "path"
          }
        ]
      }
    },
    "url_redirect": {
      "rules": [
        {
          "key": "<string>",
          "match_type": "exact",
          "match_value": "/products/old-pdp",
          "subject": "path"
        }
      ],
      "redirect": {
        "mode": "always",
        "preserve_query_string": true
      }
    },
    "offer": {
      "combines_with": {
        "product_discounts": true,
        "order_discounts": true,
        "shipping_discounts": true
      }
    }
  },
  "schedule": {
    "start_at": "2023-11-07T05:31:56Z",
    "end_at": "2023-11-07T05:31:56Z"
  },
  "audience": {
    "filter_groups": [
      {
        "filters": [
          {
            "type": "device",
            "operator": "equals",
            "value": "mobile"
          }
        ]
      },
      {
        "filters": [
          {
            "type": "visitor_type",
            "operator": "equals",
            "value": "new"
          }
        ]
      }
    ]
  },
  "has_force_assign_rules": true,
  "assignment_version": 123,
  "product_group": {
    "id": "66c1f0a2e4b0a1d2c3e4f5a6",
    "name": "Bestsellers"
  },
  "results_summary": {
    "computed_at": "2023-11-07T05:31:56Z",
    "test_groups": [
      {
        "test_group_index": 1,
        "sample_size": 5231,
        "session_count": 6816,
        "conversion_rate": 0.034,
        "revenue_per_visitor": {
          "amount": "17.99",
          "currency": "USD"
        },
        "average_order_value": {
          "amount": "17.99",
          "currency": "USD"
        },
        "profit_per_visitor": {
          "amount": "17.99",
          "currency": "USD"
        },
        "add_to_cart_rate": 0.081,
        "reached_checkout_rate": 0.052
      }
    ],
    "outcome": "winner",
    "winning_test_group_index": 123,
    "srm_status": "ok"
  },
  "started_at": "2023-11-07T05:31:56Z",
  "ended_at": "2023-11-07T05:31:56Z"
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "details": {},
    "findings": [
      {
        "severity": "error",
        "code": "product_not_found",
        "message": "<string>",
        "param": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "details": {},
    "findings": [
      {
        "severity": "error",
        "code": "product_not_found",
        "message": "<string>",
        "param": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "details": {},
    "findings": [
      {
        "severity": "error",
        "code": "product_not_found",
        "message": "<string>",
        "param": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "details": {},
    "findings": [
      {
        "severity": "error",
        "code": "product_not_found",
        "message": "<string>",
        "param": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "details": {},
    "findings": [
      {
        "severity": "error",
        "code": "product_not_found",
        "message": "<string>",
        "param": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "details": {},
    "findings": [
      {
        "severity": "error",
        "code": "product_not_found",
        "message": "<string>",
        "param": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "details": {},
    "findings": [
      {
        "severity": "error",
        "code": "product_not_found",
        "message": "<string>",
        "param": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "details": {},
    "findings": [
      {
        "severity": "error",
        "code": "product_not_found",
        "message": "<string>",
        "param": "<string>"
      }
    ]
  }
}

Authorizations

Authorization

string

header

required

Bearer tokens created in the ABConvert admin under Settings → MCP & API Access. Scopes: read_experiments and write_experiments (write implies read; the default is read). See Authentication for which scope each request needs.

Path Parameters

string

required

The test's numeric ID as a string, for example "3021".

Pattern: ^[0-9]+$

Example:

"3021"

Response

The updated test. A test that already had the target status also returns 200, unchanged.

object

string

required

Allowed value: "experiment"

string

required

The test's numeric ID as a string.

Example:

"3021"

type

enum<string>

required

What the test changes: product prices, shipping rates, the theme a visitor sees, a page template, the URL a visitor lands on, checkout delivery and payment methods, or a cart offer. visual_editor is a storefront edit: custom CSS and JavaScript, which you can write here, alongside DOM changes authored in the ABConvert visual editor. combined bundles more than one change type in one test. See CreatableExperimentType for the ones you can create here.

Available options:

price,

shipping,

theme,

template,

url_redirect,

checkout,

offer,

visual_editor,

combined

status

enum<string>

required

The test's current status. The ABConvert admin labels ended as Closed; the wire value stays ended. Scheduling isn't a status: a scheduled test is a draft or preview with a schedule.

Available options:

draft,

preview,

active,

paused,

ended,

failed,

archived

name

string

required

test_groups

object[]

required

Show child attributes

created_at

string<date-time>

required

updated_at

string<date-time>

required

hypothesis

string | null

primary_metric

enum<string> | null

The metric the test is judged on.

Available options:

revenue_per_visitor,

average_order_value,

conversion_rate,

profit_per_visitor,

add_to_cart_rate,

reached_checkout_rate

Example:

"revenue_per_visitor"

traffic_allocation

integer

shared

object

Configuration shared by every test group in the test, keyed by change type. Send exactly the key that matches the test's type. A combined test carries one key per change type it bundles.

Show child attributes

schedule

object | null

The window the scheduler runs the test in. Send at least one bound. After launch, only end_at is editable.

Show child attributes

audience

object | null

Limits the test to visitors who match your filters. Without an audience, every visitor is eligible. In PATCH, audience: null turns targeting off.

Filter groups combine with AND: a visitor must match every filter group to enter the test. Filters inside one filter group combine with OR: one match is enough.

To require two filters at once, put each one in its own filter group. The example below enters visitors who are on mobile and new. Putting the same two filters in one filter group would enter visitors who are on mobile or new instead.

A test whose targeting you turn off in the ABConvert admin reads back with no audience.

Show child attributes

Example:

{
  "filter_groups": [
    {
      "filters": [
        {
          "type": "device",
          "operator": "equals",
          "value": "mobile"
        }
      ]
    },
    {
      "filters": [
        {
          "type": "visitor_type",
          "operator": "equals",
          "value": "new"
        }
      ]
    }
  ]
}

has_force_assign_rules

boolean

read-only

True when the test has force-assign rules, which you author in the ABConvert admin. ABConvert evaluates them only for visitors who already match audience, and applies the first rule whose filters all match: that rule either puts the visitor in the test group it names or keeps them out of the test, in place of the random split.

assignment_version

integer

read-only

Increments whenever visitors are reassigned to test groups, for example after a split change.

product_group

object | null

read-only

The product group attached to this test, or null. Its id is what product_group_id takes on a custom result query. No product-group endpoint exists, so read it here.

Show child attributes

results_summary

object | null

Present only with ?include=results_summary. Null when no snapshot has been computed for the test yet.

Show child attributes

started_at

string<date-time> | null

ended_at

string<date-time> | null

⌘I

Overview

Tests

Lifecycle

Schedule

Results

Exports

Launch a test

Authorizations

Path Parameters

Response