REreacherapp
GMV Max

Create a GMV Max campaign

Changed on

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.). A live campaign needs the one TikTok account that goes LIVE in identity_ids. A product campaign lets TikTok pick posts (post_selection: auto, optionally from identity_ids) or runs only posts (post_selection: custom); each post is looked up on TikTok first. Use gmv_max_identities and gmv_max_posts for both. 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, looks up any identity_ids / posts on TikTok (counted against the live-read cap, so it can return 429 LIVE_READ_CAP_REACHED), and echoes the exact TikTok payload without creating anything.

post/gmv-max/campaigns

Request

  • Base URL
    https://api.reacherapp.com/public/v1
  • URL
    https://api.reacherapp.com/public/v1/gmv-max/campaigns
  • Auth
    API key in header x-api-key and API key in header x-shop-id

Headers

Idempotency-Keystring nullable
X-Dry-Runstring nullable
X-Created-Viastring nullable

Request body

campaign_namestring 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_idsstring[] 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_roasnumber 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_budgetnumber 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_timestring 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_timestring nullable

Campaign end time, TikTok format YYYY-MM-DD HH:MM:SS. Required when schedule_type is start_end.

auto_budget_enabledboolean nullable

Optional: let TikTok raise the budget on days the campaign is near its ROI target and has spent most of its budget.

auto_budget_increase_percentageinteger nullable

Each automatic budget increase, in percent (TikTok default 50).

auto_budget_increase_limitinteger nullable

Most automatic budget increases per day (TikTok default 10).

affiliate_posts_enabledboolean nullable

Optional: allow affiliate creator posts to be used as creatives. Product campaigns with post_selection: auto only.

identity_idsstring[] nullable

TikTok accounts from gmv_max_identities. A live campaign needs exactly one, with live_gmv_max_available; it is the account that goes LIVE. A product campaign with post_selection: auto may name up to 20 with product_gmv_max_available as its post sources; with none, TikTok uses product images.

post_selection'auto' | 'custom'

Product campaigns only. auto lets TikTok pick posts; custom runs only the posts in posts.

Response

Dry-run echo (no campaign created).

Changes

  • 9353ed4982e8Revision changes
    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

  • 17e0890869d5Revision changes
    • breaking

      removed subschema #1 from the request property anyOf list

    • info

      added to the request property anyOf list

    • info

      added to the response property anyOf list for the response status

    • info

      removed subschema #1 from the response property anyOf list for the response status