A/B Tests
Update A/B Test
Update campaign or sequence A/B test settings
PATCH
Update A/B Test
Update an A/B test’s effective settings. Campaign and sequence tests use
different selection models:
- Campaign tests use
testPercentage,testDurationMinutes, andwinnerCriteria. - Sequence tests use
testType,winnerThreshold,winnerCriteria, andautoSelectWinner.
confirmLiveChange: true.
Campaign tests support settings changes while draft or testing. During testing,
your campaign must be sending or paused. Duration is the total time from
testStartedAt, not extra time from now. A deadline in the past requests winner
selection immediately; paused campaigns stay paused.
Live audience changes use an integer percentage of the original full audience.
Already committed recipients keep their variant, including pending and ambiguous
send attempts. The worker waits for published sample jobs to settle and validates
again before applying your request. It can reject a shrink if sends increased
meanwhile. Legacy tests without a verifiable sample plan cannot resize.
Request
string
required
A/B test ID.
string
Updated test name.
number
Campaign-only share of the audience used for testing, from 5 to 50.
number
Campaign-only duration before winner selection, from 15 to 1440 minutes.
string
Winner metric for either test kind:
open_rate or click_rate. You cannot
change this metric after campaign testing starts.string
Sequence-only variant strategy:
subject or content. When winnerCriteria
is omitted, subject defaults to open_rate and content defaults to
click_rate.number
Sequence-only number of recipients before selecting a winner, from 10 to 1000.
After the threshold, the variant with the highest open or click rate wins,
excluding bot opens and clicks. Recipients keep being split across variants
while no variant has engagement for
winnerCriteria or the leaders are tied.
The leader is rechecked every 5 minutes. If tracking for winnerCriteria is
off, select the winner manually.boolean
Sequence-only.
true (the default) picks the leading variant once
winnerThreshold is reached. false keeps splitting contacts until you
choose a winner with Select A/B Test Winner. Resume A/B
Test sets it to false. Turning it back on can pick a winner on
the next send when the threshold is already reached.string
Optional campaign revision from your last GET, as an ISO timestamp. A stale
revision returns 409. Omit it for existing unconditional update behavior.
boolean
default:"false"
Discard a failed campaign sample request. Send this without
testPercentage.
It clears pending intent, not emails or recipients already committed.boolean
Required as
true when changing selection settings for an active sequence
test or one with recorded activity.Response
The response includeskind and an effective settings object. Use
settings when copying a test. The legacy testPercentage: 100 and
testDurationMinutes: 0 fields on sequence tests are retained for backwards
compatibility and are not sequence runtime settings.
Live request recovery
A successful update returns currentprogress and pendingSampleUpdate.
testPercentage stays at the last applied value until the worker publishes the
new sample. Poll Get A/B Test until pendingSampleUpdate becomes null.
Omitted settings remain unchanged. Request settings do not accept null.
Repeat the same testPercentage to repair an interrupted enqueue or worker run;
the request keeps its ID. A different pending target returns 409. When error
is present you can retry or send cancelSampleUpdate: true. Active requests
cannot be discarded. A retry uses deterministic jobs and preserves committed
recipient assignments. Winner selection waits while a sample request is pending.
400 covers invalid limits, unavailable start/audience information, an immutable
winning metric, or a shrink below committed sends. 401/403 cover authentication,
scopes or role restrictions; 404 covers missing or inaccessible tests. A 500 may
occur after saving settings if queue publication fails: GET the current state
and retry the same settings. ab_tests:write remains sufficient for campaign
settings updates; finishing early requires campaigns:send as well.
When reducing a campaign sample, only queue jobs whose sends have never started and that have no committed recipients can be withdrawn. Active jobs and pending transport retries finish first, so the minimum can rise before the change applies. Retrying preserves the request; discarding a failed change keeps work already performed, including withdrawn sample jobs. Recipients without committed sends remain eligible for the eventual winner.