Skip to main content
POST
Create a test

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.

Headers

​
Idempotency-Key
string

Replaying a request with the same key returns the original response instead of creating a second resource. Reusing a key with a different body returns 409 idempotency_key_in_use, and a key outside 1-255 characters returns 400 invalid_idempotency_key rather than being ignored. See Idempotency.

Required string length: 1 - 255

Body

application/json
​
type
enum<string>
required

The types you can create through the API. A combined test is authored in the ABConvert admin, with read and lifecycle access only.

Available options:
price,
shipping,
theme,
template,
url_redirect,
checkout,
offer,
visual_editor
​
name
string
required
Maximum string length: 255
​
test_groups
object[]
required
Required array length: 2 - 5 elements
​
hypothesis
string

What you expect this test to show, in your own words.

​
primary_metric
enum<string>

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
default:100

The percentage of eligible visitors who enter the test.

Required range: 1 <= x <= 100
​
shared
object

Required on price, shipping, template, and url_redirect tests, which each carry a mandatory key here. Optional on theme, offer, and checkout. Omitting it where it is required returns 422.

​
schedule
object

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

​
audience
object

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.

Example:

Response

The created draft. The response can carry non-blocking warnings.

​
object
string
required
Allowed value: "experiment"
​
id
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
​
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.

​
schedule
object | null

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

​
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.

Example:
​
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.

​
results_summary
object | null

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

​
started_at
string<date-time> | null
​
ended_at
string<date-time> | null
​
warnings
object[]

Non-blocking findings. Absent when the request raised none.