Skip to main content

Create Experiment

POST 

/api/advertising/experiments

Creates a holdout experiment and assigns products to treatment and control arms. Returns 201.

Required scope: advertising:write

Grant 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, goal or rule.
  • 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 of spend and/or category, 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​

Created

Response Headers
    Content-Type