Create Experiment
POST/api/advertising/experiments
Creates a holdout experiment and assigns products to treatment and control arms. Returns 201.
advertising:writeGrant this scope to your token under Settings → Developer → Personal Access Tokens.
Eligible products are advertised products not already in a running experiment of the same treatment type. They are split with a stratified random assignment (by trailing-30-day ad spend band and/or primary category); control_share of them go to control and do not receive the treatment (the guardrail policy, goal or rule) for the run. The experiment is running when it starts today or earlier, otherwise draft until its start date; it completes automatically after weeks.
Body fields:
name(required, string, max 255).treatment_type(required):guardrail_policy,goalorrule.treatment_ref_id(optional integer >= 1): the specific goal or rule being tested.control_share(optional, 0.01-0.5, default 0.1).stratify_by(optional array ofspendand/orcategory, default both).starts_on(optional date-only,m/d/Y, tenant timezone; default today).weeks(optional integer 1-26, default 4).product_ids(optional array of at least 2 product IDs; default all advertised products).
Returns 422 on product_ids when fewer than two eligible products remain.
Requires the advertising.manage permission.
Available only when the tenant has both the advertising and advertising-manager features enabled; otherwise every route here returns 404.
Request
Responses
- 201
- 401
- 403
- 422
- 429
Created
Response Headers
Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.
Forbidden — the token lacks a required scope, the endpoint is not available to API tokens, or the user behind the token lacks the permission. A human must adjust the token scopes or user permissions; do not retry.
Unprocessable Entity
Response Headers
Rate limited — platform limit is 1,000 requests/min; individual tokens may carry lower limits. Honor the Retry-After header before retrying. See the Rate Limits guide.