> ## Documentation Index
> Fetch the complete documentation index at: https://docs.abconvert.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Experiments — ABConvert API

> Create price, content, shipping, redirect, template, theme, and checkout experiments using type-specific endpoints with dedicated request bodies.

<Note>
  **Preview — this page is an early draft.** We're still verifying the API reference against the current endpoints. Fields, response shapes, and examples may change before this section is marked stable. Follow [PRO-1459](https://linear.app/abconvert/issue/PRO-1459) or ask in `#abconvert-dev` if you're integrating against this today.
</Note>

ABConvert provides a dedicated creation endpoint for each experiment type. This design lets each endpoint validate and process the parameters that make sense for that type. All creation endpoints are session endpoints and require Shopify authentication.

The price experiment endpoints are the most complex because they involve Shopify variant management. The sections below document their request bodies in full. Other experiment types follow a similar pattern.

***

## Price experiments

ABConvert offers two strategies for price testing, each with its own endpoint.

### v1 — Duplicate variant strategy

Creates a price experiment by duplicating existing product variants and assigning the new price to the duplicate. Compatible with all Shopify plans.

```
POST /api/price-experiments/v1/create
```

#### Request body

<ParamField body="name" type="string" required>
  A descriptive name for the experiment, shown in the ABConvert dashboard.
</ParamField>

<ParamField body="products" type="array" required>
  One or more products to enroll in the experiment.

  <Expandable title="products[]">
    <ParamField body="productId" type="string" required>
      The Shopify product ID (numeric, without the `gid://` prefix).
    </ParamField>

    <ParamField body="variants" type="array" required>
      Variants to test with new prices.

      <Expandable title="variants[]">
        <ParamField body="variantId" type="string" required>
          The Shopify variant ID.
        </ParamField>

        <ParamField body="price" type="string" required>
          The test price as a decimal string, e.g. `"24.99"`.
        </ParamField>

        <ParamField body="compareAtPrice" type="string">
          Optional compare-at price shown as a strikethrough, e.g. `"39.99"`.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="testGroups" type="array" required>
  Traffic split configuration. Weights must sum to 100.

  <Expandable title="testGroups[]">
    <ParamField body="name" type="string" required>
      Group label, e.g. `"Control"` or `"Variant A"`.
    </ParamField>

    <ParamField body="weight" type="number" required>
      Percentage of traffic to assign to this group.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="settings" type="object">
  Optional experiment settings such as start date, end date, and targeting rules.
</ParamField>

#### Example request

```bash theme={null}
curl -X POST "https://app.abconvert.io/api/price-experiments/v1/create" \
  -H "Authorization: Bearer <shopi...en>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Blue Shirt Price Test",
    "products": [
      {
        "productId": "7654321098765",
        "variants": [
          {
            "variantId": "43210987654321",
            "price": "24.99",
            "compareAtPrice": "39.99"
          }
        ]
      }
    ],
    "testGroups": [
      { "name": "Control", "weight": 50 },
      { "name": "Variant A", "weight": 50 }
    ],
    "settings": {
      "startDate": "2024-02-01T00:00:00.000Z"
    }
  }'
```

***

### v2 — Cart transform strategy (Shopify Plus)

Creates a price experiment using Shopify Functions cart transforms to apply price changes at checkout. Requires Shopify Plus.

```
POST /api/price-experiments/v2/create
```

#### Request body

<ParamField body="name" type="string" required>
  A descriptive name for the experiment.
</ParamField>

<ParamField body="products" type="array" required>
  Products to enroll. Same structure as v1 without variant-level pricing — the price change is computed from `priceChangeType` and `priceChange`.
</ParamField>

<ParamField body="priceChangeType" type="string" required>
  How to compute the price change. Either `"PERCENTAGE"` or `"FIXED"`.
</ParamField>

<ParamField body="priceChange" type="number" required>
  The magnitude of the price change. For `PERCENTAGE`, provide a value like `10` for a 10% reduction. For `FIXED`, provide the monetary amount.
</ParamField>

<ParamField body="testGroups" type="array" required>
  Traffic split configuration — same structure as v1.
</ParamField>

#### Example request

```bash theme={null}
curl -X POST "https://app.abconvert.io/api/price-experiments/v2/create" \
  -H "Authorization: Bearer <shopi...en>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "10% Off Cart Transform Test",
    "products": [
      { "productId": "7654321098765" }
    ],
    "priceChangeType": "PERCENTAGE",
    "priceChange": 10,
    "testGroups": [
      { "name": "Control", "weight": 50 },
      { "name": "Variant A", "weight": 50 }
    ]
  }'
```

<Note>
  Cart transform experiments (v2) require Shopify Plus and an active `cart-transformer` Shopify Function extension. ABConvert handles function deployment automatically.
</Note>

***

## Other experiment types

Each experiment type below has its own creation endpoint. They all accept a `name`, `testGroups`, and `settings` field at minimum, plus type-specific parameters.

<CodeGroup>
  ```bash Content experiment theme={null}
  curl -X POST "https://app.abconvert.io/api/content-experiments/create" \
    -H "Authorization: Bearer <shopi...en>" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Product Image A/B Test",
      "products": [{ "productId": "7654321098765" }],
      "testGroups": [
        { "name": "Control", "weight": 50 },
        { "name": "Variant A", "weight": 50 }
      ]
    }'
  ```

  ```bash Shipping experiment theme={null}
  curl -X POST "https://app.abconvert.io/api/shipping-experiments/create" \
    -H "Authorization: Bearer <shopi...en>" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Free Shipping Threshold Test",
      "testGroups": [
        { "name": "Control", "weight": 50 },
        { "name": "Free Shipping", "weight": 50 }
      ]
    }'
  ```

  ```bash Redirect experiment theme={null}
  curl -X POST "https://app.abconvert.io/api/redirect-experiments/create" \
    -H "Authorization: Bearer <shopi...en>" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Landing Page Redirect Test",
      "testGroups": [
        { "name": "Control", "weight": 50 },
        { "name": "New Landing Page", "weight": 50 }
      ]
    }'
  ```

  ```bash Template experiment theme={null}
  curl -X POST "https://app.abconvert.io/api/template-experiments/create" \
    -H "Authorization: Bearer <shopi...en>" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Product Page Template Test",
      "testGroups": [
        { "name": "Control", "weight": 50 },
        { "name": "Alternative Template", "weight": 50 }
      ]
    }'
  ```

  ```bash Theme experiment theme={null}
  curl -X POST "https://app.abconvert.io/api/theme-experiments/create" \
    -H "Authorization: Bearer <shopi...en>" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Theme Comparison Test",
      "testGroups": [
        { "name": "Current Theme", "weight": 50 },
        { "name": "New Theme", "weight": 50 }
      ]
    }'
  ```

  ```bash Checkout experiment theme={null}
  curl -X POST "https://app.abconvert.io/api/checkout-experiments/create" \
    -H "Authorization: Bearer <shopi...en>" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Checkout UI Button Test",
      "testGroups": [
        { "name": "Control", "weight": 50 },
        { "name": "New Button Label", "weight": 50 }
      ]
    }'
  ```
</CodeGroup>

### Creation endpoints reference

| Experiment type              | Endpoint                                |
| ---------------------------- | --------------------------------------- |
| Price (duplicate variant)    | `POST /api/price-experiments/v1/create` |
| Price (cart transform, Plus) | `POST /api/price-experiments/v2/create` |
| Content / image              | `POST /api/content-experiments/create`  |
| Shipping rate                | `POST /api/shipping-experiments/create` |
| URL redirect                 | `POST /api/redirect-experiments/create` |
| Page template                | `POST /api/template-experiments/create` |
| Theme                        | `POST /api/theme-experiments/create`    |
| Checkout UI                  | `POST /api/checkout-experiments/create` |

### Responses

All creation endpoints return `"success"` on success, or a standard error envelope on failure.

```json theme={null}
"success"
```

```json theme={null}
{
  "status": "error",
  "message": "Product not found"
}
```