---
title: "Create Price Experiment"
method: POST
path: "/api/v1/playbooks/{playbook_id}/price-experiments"
tags: ["playbook-pricing"]
---

# Create Price Experiment

`POST /api/v1/playbooks/{playbook_id}/price-experiments`

## Request

- Base URL: `https://api.badgeia.com`
- URL: `https://api.badgeia.com/api/v1/playbooks/{playbook_id}/price-experiments`
- Auth: none declared

Create a new draft experiment (FR-06).

Validations beyond the schema:
  - Caller owns the playbook.
  - Variants span ≤ 5x range (PRD-008 FR-06).
  - No active running experiment on this playbook.
  - No active introductory pricing window (ADR-009 Q-04 — 409 Conflict).

## Path parameters

- `playbook_id` string, uuid, required

## Request body

- PriceExperimentCreate: Creator-side: create a new draft price experiment. Variants must: - have between 2 and 4 entries (PRD-008 FR-06). - have unique labels. - have traffic_pct summing to exactly 100. - span ≤ 5x range (PRD-008 FR-06; service helper does the math). Validation that depends on referenced rows (intro-pricing overlap, single- running-experiment-per-playbook) lives in the endpoint where it has DB access.
  - `variants` ExperimentVariant[], required
    - `label` string, required
    - `price_cents` integer, required
    - `traffic_pct` integer, required
  - `min_sample_per_variant` integer
  - `notes` string, nullable

## Response `201`

Successful Response

- PriceExperimentRead: Full experiment row + computed-on-read fields.
  - `id` string, uuid, required
  - `playbook_id` string, uuid, required
  - `creator_user_id` string, uuid, nullable, required
  - `variants_json` object[], required
  - `status` string, required
  - `started_at` string, date-time, nullable, required
  - `ends_at` string, date-time, nullable, required
  - `min_sample_per_variant` integer, required
  - `winner_variant_label` string, nullable, required
  - `notes` string, nullable, required
  - `created_at` string, date-time, required
  - `concluded_at` string, date-time, nullable, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/badgeia/apis/badge.md) · [All operations](https://skmtc.dev/badgeia/apis/badge/llms.txt) · [OpenAPI document](https://skmtc.dev/badgeia/apis/badge/revisions/7e7f7fee8b77?raw)