Update a test
Updates a test in place. Send only the fields you want to change: a field you leave out stays as it is.
Serves every creatable test type: price, shipping, theme,
template, url_redirect, checkout, and offer. Types authored
only in the ABConvert admin still answer 501 not_implemented.
Read-only fields, such as an offer’s has_widgets and a checkout
customization’s has_conditions, are accepted and ignored when you
send them back, so you can amend a change you just read without
stripping them out of it first. A test group still needs its index,
which says which group you are patching; it isn’t a field you read
back.
A test group can also carry content authored in the checkout editor:
display conditions, or a checkout block. Rewriting that test group’s
changes returns 409 editor_owned_content instead of erasing that
content. Edit that test group in the ABConvert admin.
How arrays merge
- An array without a key replaces the stored array.
- An array whose entries have a key merges by that key, at every
level. A test
group’s
changesmerge bytype, except checkout changes: a test group can carry more than onecheckoutchange, so sending itschangesreplaces that test group’s complete customization list. Pricepricesentries merge byproduct_variant_id, thecountry_pricesinside one entry merge bycountry, and URL redirectdestinationsmerge byrule_key. - To delete a keyed price entry, send it with
remove: true. URL redirect destinations don’t support item-level deletion; send the complete destination list when removing one.
What you can change after launch
Launching a test locks it. After launch, only these accept updates:
name,hypothesis, andprimary_metric- each test group’s
nameandsplit - the schedule’s
end_at
Any other field returns 409 locked_field. Sending a locked field
with its current value is safe: locked_field fires only when the
value you send differs from the stored one.
Changing a split succeeds and returns a new assignment_version,
along with the warning finding split_changed: visitors already
in the test keep their test group, so the traffic already recorded
still reflects the old split.
Authorizations
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
The test's numeric ID as a string, for example "3021".
^[0-9]+$"3021"
Body
The request body for
PATCH /experiments/{id}.
Every field is
optional: leave one out and it stays unchanged.
On a launched test, only name, hypothesis, primary_metric,
each test group's name and split, and the schedule's end_at
are accepted. Any other field returns 409 locked_field when the
value you send differs from the stored one; sending it unchanged is
safe, so a read-modify-write round trip still works.
255The metric the test is judged on.
revenue_per_visitor, average_order_value, conversion_rate, profit_per_visitor, add_to_cart_rate, reached_checkout_rate "revenue_per_visitor"
1 <= x <= 100The PATCH counterpart of SharedConfig. Same keys and field shapes,
but nothing is required: send only the fields that change. An absent
combines_with flag stays unchanged, and create-time defaults do
not re-apply. See SharedConfig for what each field does.
Sparse: entries merge into the stored test groups by index, and
the test groups you leave out stay unchanged. Before launch, the
next unused index adds a test group, and remove: true deletes
one. Deleting renumbers the test groups after it, so re-read the
test before sending further index-keyed edits.
The window the scheduler runs the test in. Send at least one bound.
After launch, only end_at is editable.
Send null to turn targeting off.
Response
The updated test. May carry warnings.
"experiment"The test's numeric ID as a string.
"3021"
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.
price, shipping, theme, template, url_redirect, checkout, offer, visual_editor, combined 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.
draft, preview, active, paused, ended, failed, archived The metric the test is judged on.
revenue_per_visitor, average_order_value, conversion_rate, profit_per_visitor, add_to_cart_rate, reached_checkout_rate "revenue_per_visitor"
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.
The window the scheduler runs the test in. Send at least one bound.
After launch, only end_at is editable.
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.
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.
Increments whenever visitors are reassigned to test groups, for example after a split change.
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.
Present only with ?include=results_summary. Null when no
snapshot has been computed for the test yet.
Non-blocking findings. Absent when the request raised none.