---
title: "Posts usable in a Product GMV Max campaign"
method: POST
path: "/gmv-max/posts"
tags: ["GMV Max"]
---

# Posts usable in a Product GMV Max campaign

`POST /gmv-max/posts`

## Request

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

TikTok's `gmv_max/video/get`, read on the request: the posts (videos) this store can use in a Product GMV Max campaign, with linked products, identity and video details. Filter by products, caption or post ID, and `identity_ids` from `gmv_max_identities`; set `custom_posts_eligible` for videos that can become customized posts for one product. Read-only. Single shop only.

## Request body

- GmvMaxPostsRequest: ``POST /public/v1/gmv-max/posts`` — posts usable in a Product GMV Max campaign, read from TikTok's ``gmv_max/video/get``.
  - `spu_ids` string[], nullable: Only posts linked to these products. With `custom_posts_eligible`, exactly one product.
  - `custom_posts_eligible` boolean: Videos that can become customized posts for one product (`spu_ids` must hold exactly one).
  - `keyword` string, nullable: Caption text (fuzzy), or a post ID of 19+ digits (exact).
  - `identity_ids` string[], nullable: Only posts from these identities of this store (IDs from `gmv_max_identities`; not AUTH_CODE ones).
  - `include_auth_code_posts` boolean: Include posts authorized with video codes. TikTok returns nothing when this is false and no `identity_ids` are given.
  - `sort_field` 'GMV' | 'POST_TIME' | 'VIDEO_VIEWS' | 'VIDEO_LIKES' | 'CLICK_THROUGH_RATE' | 'PRODUCT_CLICKS', nullable: Not with `custom_posts_eligible`.
  - `sort_type` 'ASC' | 'DESC', nullable
  - `page` integer
  - `page_size` integer

## Response `200`

Successful Response

- GmvMaxPostsResponse: POST /gmv-max/posts — posts usable in a Product GMV Max campaign.
  - `shop_id` integer, required
  - `advertiser_id` string, required
  - `store_id` string, required: This shop's TikTok Shop (store) ID.
  - `source` 'live': Always `live`: read from TikTok on the request.
  - `fetched_at` string, nullable, required
  - `data` GmvMaxPost[], required
    - `item_id` string, required: The TikTok post (video) ID.
    - `text` string, nullable: The post caption.
    - `spu_id_list` string[], nullable: Products (SPU IDs) linked to the post.
    - `identity_info` object, nullable
    - `video_info` object, nullable
  - `page_info` GmvMaxPageInfo
    - `page` integer, nullable
    - `page_size` integer, nullable
    - `total_number` integer, nullable
    - `total_page` integer, nullable

## Other responses

- `400`: Invalid request / shop not connected to GMV Max.
- `403`: The shop's TikTok authorization lacks this permission.
- `422`: TikTok rejected the request.
- `429`: TikTok is throttling, or the live-read cap was reached.
- `502`: TikTok failed transiently; safe to retry.
- `503`: Live reads are briefly unavailable; retry in a minute.

## Changes

> 76 revisions in range; 1 not diffed.

- **2026-10-18** `17e0890869d5`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/reacherapp/apis/reacher-data-api/changes/gmv-max/posts/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.dev/reacherapp/apis/reacher-data-api/revisions/63ce74b30b5a?raw)