Update an experience variation

put

https://api.convert.com/api/v2/accounts/{account_id}/projects/{project_id}/experiences/{experience_id}/variations/{variation_id}/update

Modifies an existing variation within an experience. This can include changing its name, description, traffic distribution, status (running/stopped), or the actual changes (CSS, JS, HTML modifications) it applies. The Knowledge Base article "How do I edit my variations?" covers the UI aspect.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

account_id

integer

required

ID of the account that owns the retrieved/saved data

project_id

integer

required

ID of the project to which save/retrieved data is connected

experience_id

integer

required

The ID of the updated experience

variation_id

integer

required

The ID of the variation to be updated

Body Params

name

string

length ≤ 200

A user-defined, friendly name for the variation (e.g., "Original Homepage", "Variation B - Green Button", "Personalized Offer for New Users"). This name appears in reports and the Convert UI.

description

string | null

An optional, more detailed explanation of what this variation entails or what changes it implements compared to the original or other variations.

is_baseline

boolean

If true, this variation is considered the baseline (control) against which other variations in the experience are compared for performance. Typically, the "Original" variation is the baseline. Only one variation per experience can be the baseline. Knowledge Base: "What is a Baseline?"

traffic_distribution

number

0 to 100

The percentage of eligible traffic allocated to this specific variation. The sum of traffic_distribution for all active variations within an experience should ideally be 100% of the traffic allocated to the experience itself. For Multi-Armed Bandit (MAB) experiences, this value may be dynamically adjusted by the system. Knowledge Base: "What is an Traffic Distribution?"

key

string

length ≤ 32

A unique, machine-readable key or identifier for this variation within the project. Often auto-generated from the name if not specified, but can be user-defined for easier programmatic reference (e.g., in Full Stack SDKs). Example: "control", "treatment_A".

concurrency_key

string | null

A server-generated hash that represents the object's state at the time of retrieval. When included in an update request, the operation will only succeed if the object hasn't been modified since this key was obtained. If another update has occurred in the meantime, the request will fail with a conflict error, requiring you to fetch the latest version and retry your update with the new concurrency_key. This implements optimistic concurrency control to prevent lost updates in concurrent scenarios.

status

string

enum

Allowed:

changes

array

An array of changes that this variation would apply. Empty array will remove changes.

changes

Responses

200Detailed information for a single experience variation, including its id, name, description, is_baseline status, traffic_distribution, status (running/stopped), and an array of changes it implements.

defaultIndicates an error occurred while processing the request. The code provides an HTTP status code, message offers a human-readable explanation or an array of validation errors, and fields (if present) specifies which input fields were problematic.