获取 GMV Max 推广系列列表

您可以使用本接口获取广告账户中的 GMV Max 推广系列列表。

请求

地址 https://business-api.tiktok.com/open_api/v1.3/gmv_max/campaign/get/

方法 GET

Header

|字段{35%}|类型{15%}|描述{50%}|
|---|---|---|
|Access-Token {必填}|string|授权访问令牌。<br>可以通过[获取访问令牌](1738373164380162.html)接口获取。|

参数

|字段{35%}|类型{15%}|描述{50%}|
|---|---|---|
|advertiser_id {必填}|string|广告主 ID。|
|fields|string[]|希望返回的字段集合。<br><br>不传入本字段时，默认返回所有字段。<br><br>枚举值参见返回中`list`下包含的字段。|
|filtering {必填}|object|筛选条件。<br><br>示例： `filtering=&#123;"gmv_max_promotion_types":["PRODUCT_GMV_MAX"]&#125;`。|
#|gmv_max_promotion_types {必填}|string[]|GMV Max 推广系列类型。<br><br>枚举值：<ul><li>`PRODUCT_GMV_MAX`: [商品 GMV Max 推广系列](1822009220448257.html)。</li><li>`LIVE_GMV_MAX`: [直播 GMV Max 推广系列](1822009242546258.html)。</li></ul>|
#|store_ids|string[]|TikTok Shop ID 列表。<br><br>最大数量：10。<br><br>若想获取可用于 GMV Max 推广系列的 TikTok Shop，可使用 [/gmv_max/store/list/](1822001044479041.html) 并确认返回的 `is_gmv_max_available` 为 `true`。|
#|campaign_ids|string[]|推广系列 ID 列表。<br><br>最大数量：100。|
#|campaign_name|string|推广系列名称。|
#|primary_status|string|一级状态。<br><br>枚举值：<ul><li>`STATUS_DELIVERY_OK`: 已生效。</li><li>`STATUS_DISABLE`: 已暂停。</li><li>`STATUS_DELETE`: 已删除。</li></ul>|
#|creation_filter_start_time|string|推广系列最早创建时间，格式为 `YYYY-MM-DD HH:MM:SS` (UTC 时区)。将返回创建时间晚于此时间的推广系列。<br><br>示例： `2025-01-01 00:00:01`。<br><br>若 `creation_filter_start_time` 和 `creation_filter_end_time` 不传入，将返回任意时间创建的所有 GMV Max 推广系列。<br><br><p><span style="color:darkred"><b>注意</b></span>：为确保任务成功执行及任务速度不受影响，创建时间的范围建议在6个月以内。|
#|creation_filter_end_time|string|推广系列最晚创建时间，格式为 `YYYY-MM-DD HH:MM:SS` (UTC 时区)。将返回创建时间先于此时间的推广系列。<br><br>示例： `2025-02-01 00:00:01`。<br><br>若 `creation_filter_start_time` 和 `creation_filter_end_time` 不传入，将返回任意时间创建的所有 GMV Max 推广系列。<br><br><p><span style="color:darkred"><b>注意</b></span>：为确保任务成功执行及任务速度不受影响，创建时间的筛选范围建议在6个月以内。|
|page|integer|当前页数。<br><br>取值范围：≥ 1。<br>默认值: 1。|
|page_size|integer|分页大小。<br><br>取值范围：1-100。<br>默认值: 10。|

示例

获取商品 GMV Max 推广系列列表

(code curl http)
curl --location  --request GET 'https://business-api.tiktok.com/open_api/v1.3/gmv_max/campaign/get/?advertiser_id={{advertiser_id}}&filtering={"gmv_max_promotion_types": ["PRODUCT_GMV_MAX"]}' \
--header 'Access-Token: {{Access-Token}}'
(/code)

获取直播 GMV Max 推广系列列表

(code curl http)
curl --location  --request GET 'https://business-api.tiktok.com/open_api/v1.3/gmv_max/campaign/get/?advertiser_id={{advertiser_id}}&filtering={"gmv_max_promotion_types": ["LIVE_GMV_MAX"]}' \
--header 'Access-Token: {{Access-Token}}'
(/code)

|字段{35%}|类型{15%}|描述{50%}|
|---|---|---|
|code |number| 返回码。完整返回码列表及描述，参见[附录 - 返回码](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097)。|
|message |string| 返回信息。更多信息参见[附录 - 返回码](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097)。 |
|request_id |string| 请求的日志 ID，唯一标识一个请求。 |
|data |object| 返回数据。 |
#|list|object[]|推广系列列表。<br><br>返回字段基于请求中的`fields`字段，默认返回所有字段。|
##|advertiser_id|string|广告主 ID。|
##|campaign_id|string|推广系列 ID。|
##|campaign_name|string|推广系列名称。|
##|operation_status|string|推广系列的开/关状态。<br><br>枚举值：<ul><li>`ENABLE`: 处于“开”状态。</li><li>`DISABLE`: 处于“关”状态。</li></ul>|
##|create_time|string|推广系列的创建时间，格式为 `YYYY-MM-DD HH:MM:SS` (UTC 时区)。<br><br>示例： `2025-01-01 00:00:01`。|
##|modify_time|string|推广系列的最近修改时间，格式为 `YYYY-MM-DD HH:MM:SS` (UTC 时区)。<br><br>示例： `2025-01-01 00:00:01`。|
##|objective_type|string|推广目标。<br><br>枚举值：`PRODUCT_SALES`（商品销量）。|
##|secondary_status|string|二级状态。<br><br>枚举值参见 [GMV Max 推广系列支持的推广系列二级状态](https://business-api.tiktok.com/portal/docs?id=1757239620352002#item-link-GMV%20Max%20%E6%8E%A8%E5%B9%BF%E7%B3%BB%E5%88%97)。|
##|roi_protection_compensation_status|string|该推广系列的 ROI（投资回报率）保障状态。<br>投资回报率保障功能在您遵循 GMV Max 指南和最佳实践且推广系列的投资回报率仍低于特定阈值的情况下，自动向您发放广告赠款。若想了解 ROI 保障功能的符合资格及不符合的场景，请查看[关于 GMV Max 推广系列的 ROI 保障功能](https://ads.tiktok.com/help/article/about-roi-protection-for-gmv-max-campaigns)。<br><br>枚举值： <ul><li>`IN_EFFECT`：符合 ROI 保障资格。如果您的广告在 24 小时内促成 20 次以上转化，但 ROI 结果低于目标的 90%，此推广系列有资格获得广告费用赠款。为确保推广系列持续符合 ROI 保障资格，请勿修改 ROI、暂停广告投放或启用最大投放量优化模式。推广系列资格每 24 小时重置一次。</li><li>`NOT_ELIGIBLE`：不符合 ROI 保障资格。如果因为修改了 ROI、暂停了推广系列、启用了最大投放量优化模式，或者您的店铺、广告账号、直播或商品存在问题，导致没有达成目标 ROI，那么此推广系列不符合广告费用赠款资格。推广系列资格每 24 小时重置一次。</li></ul>|
#|page_info|object|分页信息。|
##|page|integer|当前页数。|
##|page_size|integer|分页大小。|
##|total_number|integer|总结果数。|
##|total_page|integer|总页数。|

示例

(code Success-Response http)
HTTPS/1.1 200 OK
{
    "code": 0,
    "message": "OK",
    "request_id": "{{request_id}}",
    "data": {
        "list": [
            {
                "campaign_name": "{{campaign_name}}",
                "advertiser_id": "{{advertiser_id}}",
                "objective_type": "PRODUCT_SALES",
                "modify_time": "{{modify_time}}",
                "secondary_status": "CAMPAIGN_STATUS_DISABLE",
                "campaign_id": "{{campaign_id}}",
                "create_time": "{{create_time}}",
                "operation_status": "DISABLE"
            },
            {
                "campaign_name": "{{campaign_name}}",
                "advertiser_id": "{{advertiser_id}}",
                "objective_type": "PRODUCT_SALES",
                "modify_time": "{{modify_time}}",
                "secondary_status": "CAMPAIGN_STATUS_DISABLE",
                "campaign_id": "{{campaign_id}}",
                "create_time": "{{create_time}}",
                "operation_status": "DISABLE"
            }
        ],
        "page_info": {
            "page": 1,
            "page_size": 10,
            "total_page": 1,
            "total_number": 2
        }
    }
}
(/code)