---
title: "Create a GMV Max campaign"
method: POST
path: "/gmv-max/campaigns"
tags: ["GMV Max"]
---

# Create a GMV Max campaign

`POST /gmv-max/campaigns`

Create a new GMV Max (TikTok Smart+) campaign on the shop's connected TikTok Business ad account. Requires ``read_write`` scope. Single shop only — set ``x-shop-id`` to the owning shop.

The canonical body is mapped to TikTok's create payload server-side (``daily_budget``→budget, ``target_roas``→ROAS bid, ``product_selection``→ALL / CUSTOMIZED_PRODUCTS, etc.). The shop must already be connected to TikTok Business / GMV Max — an unconnected or incomplete connection returns 400 ``INVALID_REQUEST``.

Idempotent via the ``Idempotency-Key`` header — replays of the same key + same body return the cached 201 without creating a duplicate. ``X-Dry-Run: true`` validates the body + connection and echoes the exact TikTok payload without calling TikTok.

## Headers

- `Idempotency-Key` string, nullable
- `X-Dry-Run` string, nullable
- `X-Created-Via` string, nullable

## Request body

- CreateGmvMaxCampaignRequest — ``POST /public/v1/gmv-max/campaigns`` — create a GMV Max campaign.
  - `campaign_name` string, required — Human-readable campaign name shown in Seller Center / the portal.
  - `campaign_type` 'product' | 'live' — `product` (Product GMV Max) or `live` (LIVE GMV Max). Maps to TikTok `shopping_ads_type` PRODUCT / LIVE.
  - `product_selection` 'all' | 'customized', required — `all` promotes every eligible product; `customized` restricts to the products in `item_group_ids`. Maps to TikTok `product_specific_type` ALL / CUSTOMIZED_PRODUCTS.
  - `item_group_ids` string[], nullable — Product (SPU / item_group_id) IDs to promote. Required and non-empty when `product_selection` is `customized`; must be omitted when `product_selection` is `all`.
  - `target_roas` number, required — Target ROAS. Required — TikTok GMV Max create always needs a target ROI: maps to TikTok `roas_bid` with `deep_bid_type=VO_MIN_ROAS`.
  - `daily_budget` number, required — Daily budget in the shop's currency. Maps to TikTok `budget`.
  - `schedule_type` 'from_now' | 'start_end', required — `from_now` starts immediately with no end (TikTok SCHEDULE_FROM_NOW); `start_end` runs between `schedule_start_time` and `schedule_end_time` (TikTok SCHEDULE_START_END).
  - `schedule_start_time` string, required — Campaign start time, TikTok format `YYYY-MM-DD HH:MM:SS`. Required for both `from_now` and `start_end` (TikTok always requires it).
  - `schedule_end_time` string, nullable — Campaign end time, TikTok format `YYYY-MM-DD HH:MM:SS`. Required when `schedule_type` is `start_end`.
  - `promotion_days` integer, nullable — Optional number of promotion days (LIVE GMV Max scheduling hint).
  - `auto_budget_enabled` boolean, nullable — Optional: let TikTok auto-manage the budget.
  - `affiliate_posts_enabled` boolean, nullable — Optional: allow affiliate creator posts to be used as creatives.

## Response `200`

Dry-run echo (no campaign created).

## Other responses

- `201` — Campaign created.
- `400` — Invalid request / shop not connected to GMV Max.
- `403` — API key lacks `read_write` scope.
- `409` — Idempotency-Key conflict.
- `422` — Validation Error
- `429` — Write rate limit exceeded.
- `502` — TikTok rejected or failed the create.

## Changes

- **2026-09-02** `d4fe3e380424` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/reacherapp/apis/reacher-data-api/changes/gmv-max/campaigns/post.md)

---

[API](https://skmtc.dev/reacherapp/apis/reacher-data-api.md) · [All operations](https://skmtc.dev/reacherapp/apis/reacher-data-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/reacherapp/reacher-data-api/revisions/643422c93bd8/schema)