UpdateSingleActivityProduct - 新增、更新或删除单个商品卡片--企业直播-火山引擎

文档中心

立即注册

导航

UpdateSingleActivityProduct - 新增、更新或删除单个商品卡片

最近更新时间：2025.09.26 16:04:09首次发布时间：2025.07.16 11:47:52

调用 UpdateSingleActivityProduct 接口，在指定直播间中新增、更新或删除指定商品卡片菜单下的单个商品卡片。

说明

启用商品卡片菜单后，配置信息才会在观看页生效。您可通过调用 ModifyActivityMenus 接口，启用商品卡片菜单。

注意事项

请求频率：单用户请求频率限制为 10 次/秒。
数量限制：单个商品卡片菜单下，最多支持配置 500 个商品卡片。
前提条件：确保您拥有火山引擎主账号或具备直播间的菜单管理 > 可编辑权限的子账号。有关如何添加子账号，详见子账号管理。

请求说明

请求方式：POST
请求地址：https://livesaas.volcengineapi.com/?Action=UpdateSingleActivityProduct&Version=2023-08-01

调试

API Explorer

您可以通过 API Explorer 在线发起调用，无需关注签名生成过程，快速获取调用结果。

去调试

请求参数

下表仅列出该接口特有的请求参数和部分公共参数。更多信息详见公共参数。

Query

参数	类型	是否必选	示例值	描述
Action	String	是	`UpdateSingleActivityProduct`	接口名称。当前 API 的名称为 `UpdateSingleActivityProduct`。
Version	String	是	`2023-08-01`	接口版本。当前 API 的版本为 `2023-08-01`。

Body

参数	类型	是否必选	示例值	描述
ActivityId	Long	是	`177985****487296`	直播间 ID。您可通过调用 ListActivityAPI 接口获取 ID。说明使用子账号调用接口时，确保该直播间对子账号可见。有关如何配置子账号的可见范围，详见子账号管理。
ProductConfigId	Long	是	`111723`	商品卡片菜单 ID。您可调用 GetActivityProducts 接口，根据返回参数 `Id`获取 ID。
Action	Integer	是	`1`	操作类型。取值如下： `1`: 新增商品卡片 `2`: 更新商品卡片配置信息 `3`: 删除商品卡片
ReorderIndex	Boolean	否	`false`	新增或更新商品卡片时，如果商品卡片的序号（`Index` 取值）与当前商品卡片菜单下已有的商品卡片序号相同，是否重新排序菜单下的商品卡片。默认值为 `false`。取值如下： `true`：重新排序商品卡片，将已有的商品卡片的序号向后顺延。例如，当前商品卡片菜单下存在商品卡片 A、B 和 C，序号分别为 1、2 和 3，当新增一个序号为 2 的商品卡片，则商品卡片 A 的序号为 1，新增商品卡片的序号为 2，商品卡片 B 的序号为 3，商品卡片 C 的序号为 4。 `false`：不重新排序商品卡片，可能存在相同序号的商品卡片。相同序号的商品卡片排序随机。
Product	Object of Product	是	`-`	商品卡片的配置信息。说明当 `Action` 取值为 `2` 时，为保证商品卡片配置信息的参数值不被清空或替换为默认值，即便参数在该接口中为非必选，也必须传入对应的参数值。您可调用 GetActivityProducts 接口，通过返回参数 `Product` 获取商品卡片配置信息。当 `Action` 取值为 `3` 时，商品卡片配置信息中，仅 `Id` 参数生效。

Product

参数	类型	是否必选	示例值	描述
Id	Long	否	`105472`	商品卡片 ID。调用 GetActivityProducts 接口，根据返回参数 `Id` 获取商品卡片 ID。说明仅在 `Action` 取值为 `2` 或 `3` 时，该参数必选且生效。
Index	Integer	否	`0`	商品卡片的序号。默认值为 `0`。取值范围为 [0,499] 的整数。序号越小，在商品卡片菜单中的位置越靠前。同一菜单下的商品卡片，建议序号唯一。如果无法保证序号唯一，建议将 `ReorderIndex` 取值设置为 `true`。
IntroduceImage	String	否	`https://p.example.org/***.png`	商品图的 URL，需包含协议头。支持上传 JPG、GIF、PNG、BMP 格式的图片。
PromotionTagType	Integer	否	`1`	活动标签类型。默认值为 `0`。取值如下： `0`：无 `1`：自定义 `2`：超值购 `3`：惊喜特惠 `4`：低价秒杀
PromotionTagUrl	String	否	`https://p.example.org/***.png`	活动标签的 URL，需包含协议头。说明当 `PromotionTagType` 取值为 `1` 时，该参数必选且生效。
Title	String	是	`玫瑰慕斯蛋糕（小）`	商品名称。长度为 1 到 100 个字符。
Remark	String	否	`超级好吃的玫瑰慕斯蛋糕`	商品介绍。长度为 1 到 15 个字符。
Highlight	String	否	`¥15`	商品的售卖价，即当前价格。长度为 1 到 20 个字符。
Strikethrough	String	否	`¥30`	商品的参考价，即原价。长度为 1 到 8 个字符。
SellingPointTag	String	否	`买二赠一；满50减20`	卖点标签。最多支持 3 个卖点，卖点间以分号（；）相隔。每个卖点建议不要超过 6 个字符。
RedirectImage	String	否	`https://p.example.org/***.png`	跳转图的 URL，需包含协议头。默认使用系统默认跳转图。支持上传 JPG、GIF、PNG、BMP 格式的图片。
DirectUrls	Array of String	否	`["https://example.com","https://example2.com" ]`	直达链接，需包含协议头。当观众在环境 UA 匹配成功的移动端平台上点击商品卡片时，即可跳转至该链接。说明该参数仅在商品卡片菜单开启直达链接功能后生效。您可调用 UpdateActivityProduct 接口，将 `EnableUA` 参数取值设置为 `true`，开启直达链接功能。请按照所配置的环境名称和环境 UA 的顺序，配置对应的直达链接。最多支持配置 5 个直达链接。
MiniAppDirectUrl	String	否	`https://example.com`	微信小程序链接，需包含协议头。当观众在移动端微信环境点击商品卡片时，即可跳转至该微信小程序。说明该参数仅在商品卡片菜单开启微信小程序跳转功能后生效。您可调用 UpdateActivityProduct 接口，将 `EnableMiniApp` 参数取值设置为 `true`，开启微信小程序跳转功能。
RedirectUrl	String	否	`https://example.com`	跳转链接，即商品详情页的链接，需包含协议头。如果观众无法跳转至直达链接或微信小程序，则会跳转至该链接。
ReminderType	Integer	否	`1`	在商品讲解期间的浮窗商品卡片和商品卡片菜单中，动效展示的提醒类型。默认值为 `0`。取值如下： `0`：无 `1`：热卖 `2`：库存当参数取值为 `1` 或 `2` 时，为确保观看页能够展示热卖或库存提醒，必须同时满足以下条件：调用 ModifyActivityMenus 接口，启用商品卡片菜单。将当前接口的 `EnableStatus` 参数值设置为 `1`，上架商品卡片。调用 ExplainProduct 接口，将 `ExplainStatus` 或 `FloatingStatus` 的参数值设置为 `1`，对商品卡片标记商品讲解。将当前接口的 `OutOfStock` 和 `PriceHidden` 参数值均设置为 `0`，确保商品未售罄且价格为显示状态。
HotSale	String	否	`1000`	热卖提醒数量。长度为 1 到 5 个字符。说明当 `ReminderType` 取值为 `1` 时，该参数必选且生效。
Stock	String	否	`50`	库存提醒数量。长度为 1 到 5 个字符。说明当 `ReminderType` 取值为 `2` 时，该参数必选且生效。
EnableStatus	Integer	否	`1`	是否上架商品。默认值为 `0`。取值如下： `0`：下架 `1`：上架
IsOrderMsgEnable	Integer	否	`1`	是否开启下单消息。默认值为 `0`。取值如下： `0`：关闭 `1`：开启。您需调用 UpdateActivityCommentConfig 接口，同步开启聊天互动菜单的查看商品消息或下单购买消息，从而在聊天区域展示查看商品消息或下单购买消息。
OutOfStock	Integer	否	`0`	是否售罄商品。商品售罄后，观看页的商品图和跳转图将展示“已抢光”的文案。取值如下： `0`：未售罄 `1`：已售罄注意若商品价格为隐藏状态，则不支持售罄商品。即当 `PriceHidden` 为 `1` 时，不支持将该参数设为 `1`。
PriceHidden	Integer	否	`0`	是否隐藏商品售卖价格。商品价格隐藏后，观看页的商品售卖价将以“待开价￥???”的文案展示。取值如下： `0`：不隐藏价格 `1`：隐藏价格注意若商品为售罄状态，则不支持隐藏商品的售卖价格。即当 `OutOfStock` 为 `1` 时，不支持将该参数设为 `1`。

返回参数

参数	类型	示例值	描述
Product	Object of Product	`-`	本次接口调用新增、更新或删除的商品卡片。说明删除的商品卡片仅返回 `Id` 参数。
ConfigProducts	Array of ConfigProducts	`-`	商品卡片菜单下的商品卡片列表。

Product

参数	类型	示例值	描述
Id	Long	`105472`	商品卡片 ID。
Index	Integer	`0`	商品卡片的序号。取值范围为 [0,499]。
IntroduceImage	String	`https://p.example.org/***.png`	商品图的 URL，包含协议头。
PromotionTagType	Integer	`1`	活动标签类型。取值如下： `0`：无 `1`：自定义 `2`：超值购 `3`：惊喜特惠 `4`：低价秒杀
PromotionTagUrl	String	`https://p.example.org/***.png`	活动标签的 URL，包含协议头。
Title	String	`玫瑰慕斯蛋糕（小）`	商品名称。
Remark	String	`超级好吃的玫瑰慕斯蛋糕`	商品介绍。
Highlight	String	`¥15`	商品的售卖价，即当前价格。
Strikethrough	String	`¥30`	商品的参考价，即原价。
SellingPointTag	String	`买二赠一；满50减20`	卖点标签。卖点间以分号（；）相隔。
RedirectImage	String	`https://p.example.org/***.png`	跳转图的 URL，包含协议头。
DirectUrls	Array of String	`["https://example.com","https://example2.com"]`	直达链接，包含协议头。当观众在环境 UA 匹配成功的移动端平台上点击商品卡片时，即可跳转至该链接。说明该参数仅在商品卡片菜单开启直达链接功能后生效。您可调用 UpdateActivityProduct 接口，将 `EnableUA` 参数取值设置为 `true`，开启直达链接功能。
MiniAppDirectUrl	String	`https://example.com`	微信小程序链接，包含协议头。当观众在移动端微信环境点击商品卡片时，即可跳转至该微信小程序。说明该参数仅在商品卡片菜单开启微信小程序跳转功能后生效。您可调用 UpdateActivityProduct 接口，将 `EnableMiniApp` 参数取值设置为 `true`，开启微信小程序跳转功能。
RedirectUrl	String	`https://example.com`	跳转链接，即商品详情页的链接，包含协议头。如果观众无法跳转至直达链接或微信小程序，则会跳转至该链接。
ReminderType	Integer	`1`	在商品讲解期间的浮窗商品卡片和商品卡片菜单中，动效展示的提醒类型。取值如下： `0`：无 `1`：热卖 `2`：库存
HotSale	String	`1000`	热卖提醒数量。说明该参数仅在 `ReminderType` 取值为 `1` 时生效。
Stock	String	`50`	库存提醒数量。说明该参数仅在 `ReminderType` 取值为 `2` 时生效。
EnableStatus	Integer	`1`	是否上架商品。取值如下： `0`：下架 `1`：上架
IsOrderMsgEnable	Integer	`1`	是否开启下单消息。取值如下： `0`：关闭 `1`：开启
ExplainStatus	Integer	`0`	商品讲解状态。取值如下： `0`：未讲解 `1`：讲解中 `2`：讲解结束说明仅在开启直播时移功能时，该参数生效。更多有关直播时移的信息，详见直播时移。
ExplainTime	Long	`0`	最近一次修改商品讲解状态的时间。Unix 时间戳，单位为秒。取值为 `0` 表示未修改过商品讲解状态。
FloatingStatus	Integer	`1`	是否浮窗展示商品卡片。取值如下： `1`：浮窗展示 `其他值`：非浮窗展示说明仅在未开启直播时移功能时，该参数生效。
FloatingTime	Long	`1742873573`	最近一次浮窗展示商品卡片的时间。Unix 时间戳，单位为秒。取值为 `0` 表示商品卡片从未浮窗展示过。
OutOfStock	Integer	`0`	商品是否售罄。商品售罄后，观看页的商品图和跳转图将展示“已抢光”的文案。取值如下： `0`：未售罄 `1`：已售罄
PriceHidden	Integer	`0`	商品售卖价格是否为隐藏状态。商品价格隐藏后，观看页的商品售卖价将以“待开价￥???”的文案展示。取值如下： `0`：未隐藏 `1`：已隐藏

ConfigProducts

参数	类型	示例值	描述
Id	Long	`105472`	商品卡片 ID。
Index	Integer	`0`	商品卡片的序号。取值范围为 [0,499]。
IntroduceImage	String	`https://p.example.org/***.png`	商品图的 URL，包含协议头。
PromotionTagType	Integer	`1`	活动标签类型。取值如下： `0`：无 `1`：自定义 `2`：超值购 `3`：惊喜特惠 `4`：低价秒杀
PromotionTagUrl	String	`https://p.example.org/***.png`	活动标签的 URL，包含协议头。
Title	String	`玫瑰慕斯蛋糕（小）`	商品名称。
Remark	String	`超级好吃的玫瑰慕斯蛋糕`	商品介绍。
Highlight	String	`¥15`	商品的售卖价，即当前价格。
Strikethrough	String	`¥30`	商品的参考价，即原价。
SellingPointTag	String	`买二赠一；满50减20`	卖点标签。卖点间以分号（；）相隔。
RedirectImage	String	`https://p.example.org/***.png`	跳转图的 URL，包含协议头。
DirectUrls	Array of String	`["https://example.com","https://example2.com"]`	直达链接，包含协议头。当观众在环境 UA 匹配成功的移动端平台上点击商品卡片时，即可跳转至该链接。说明该参数仅在商品卡片菜单开启直达链接功能后生效。您可调用 UpdateActivityProduct 接口，将 `EnableUA` 参数取值设置为 `true`，开启直达链接功能。
MiniAppDirectUrl	String	`https://example.com`	微信小程序链接，包含协议头。当观众在移动端微信环境点击商品卡片时，即可跳转至该微信小程序。说明该参数仅在商品卡片菜单开启微信小程序跳转功能后生效。您可调用 UpdateActivityProduct 接口，将 `EnableMiniApp` 参数取值设置为 `true`，开启微信小程序跳转功能。
RedirectUrl	String	`https://example.com`	跳转链接，即商品详情页的链接，包含协议头。如果观众无法跳转至直达链接或微信小程序，则会跳转至该链接。
ReminderType	Integer	`1`	在商品讲解期间的浮窗商品卡片和商品卡片菜单中，动效展示的提醒类型。取值如下： `0`：无 `1`：热卖 `2`：库存
HotSale	String	`1000`	热卖提醒数量。说明该参数仅在 `ReminderType` 取值为 `1` 时生效。
Stock	String	`50`	库存提醒数量。说明该参数仅在 `ReminderType` 取值为 `2` 时生效。
EnableStatus	Integer	`1`	是否上架商品。取值如下： `0`：下架 `1`：上架
IsOrderMsgEnable	Integer	`1`	是否开启下单消息。取值如下： `0`：关闭 `1`：开启
ExplainStatus	Integer	`0`	商品讲解状态。取值如下： `0`：未讲解 `1`：讲解中 `2`：讲解结束说明仅在开启直播时移功能时，该参数生效。更多有关直播时移的信息，详见直播时移。
ExplainTime	Long	`0`	最近一次修改商品讲解状态的时间。Unix 时间戳，单位为秒。取值为 `0` 表示未修改过商品讲解状态。
FloatingStatus	Integer	`1`	是否浮窗展示商品卡片。取值如下： `1`：浮窗展示 `其他值`：非浮窗展示说明仅在未开启直播时移功能时，该参数生效。
FloatingTime	Long	`1742873573`	最近一次浮窗展示商品卡片的时间。Unix 时间戳，单位为秒。取值为 `0` 表示商品卡片从未浮窗展示过。
OutOfStock	Integer	`0`	商品是否售罄。商品售罄后，观看页的商品图和跳转图将展示“已抢光”的文案。取值如下： `0`：未售罄 `1`：已售罄
PriceHidden	Integer	`0`	商品售卖价格是否为隐藏状态。商品价格隐藏后，观看页的商品售卖价将以“待开价￥???”的文案展示。取值如下： `0`：未隐藏 `1`：已隐藏

请求示例

POST https://livesaas.volcengineapi.com/?Action=UpdateSingleActivityProduct&Version=2023-08-01
{
    "ActivityId": 177985****487296,
    "ProductConfigId": 111723,
    "Action": 1,
    "Product": {
        "Id": 105472,
        "Title": "玫瑰慕斯蛋糕（小）",
        "Remark": "超级好吃的玫瑰慕斯蛋糕",
        "Strikethrough": "¥30",
        "MiniAppDirectUrl": "https://example.com",
        "DirectUrls": [
            "https://example.com",
            "https://example2.com"
        ],
        "EnableStatus": 1,
        "Index": 0,
        "RedirectUrl": "https://example.com",
        "RedirectImage": "https://p.example.org/***.png",
        "IntroduceImage": "https://p.example.org/***.png",
        "Highlight": "¥15",
        "SellingPointTag": "买二赠一；满50减20",
        "ReminderType": 1,
        "PromotionTagUrl": "https://p.example.org/***.png",
        "PromotionTagType": 1,
        "IsOrderMsgEnable": 1,
        "HotSale": "1000",
        "Stock": "50",
        "PriceHidden": 0,
        "OutOfStock": 0
    },
    "ReorderIndex": false
}

返回示例

{
    "ResponseMetadata": {
        "RequestId": "20230604110420****100232280022D31",
        "Action": "UpdateSingleActivityProduct",
        "Version": "2023-08-01",
        "Service": "livesaas",
        "Region": "cn-north-1",
        "SystemTime": 1697446406
    },
    "Result": {
        "Product": {
            "Id": 105472,
            "Title": "玫瑰慕斯蛋糕（小）",
            "Remark": "超级好吃的玫瑰慕斯蛋糕",
            "Strikethrough": "¥30",
            "MiniAppDirectUrl": "https://example.com",
            "DirectUrls": [
                "https://example.com",
                "https://example2.com"
            ],
            "EnableStatus": 1,
            "Index": 0,
            "RedirectUrl": "https://example.com",
            "RedirectImage": "https://p.example.org/***.png",
            "IntroduceImage": "https://p.example.org/***.png",
            "Highlight": "¥15",
            "SellingPointTag": "买二赠一；满50减20",
            "ReminderType": 1,
            "PromotionTagUrl": "https://p.example.org/***.png",
            "PromotionTagType": 1,
            "IsOrderMsgEnable": 1,
            "HotSale": "1000",
            "Stock": "50",
            "ExplainStatus": 0,
            "ExplainTime": 0,
            "FloatingStatus": 1,
            "FloatingTime": 1742873573,
            "OutOfStock": 0,
            "PriceHidden": 0
        },
        "ConfigProducts": [
            {
                "Id": 105472,
                "Title": "玫瑰慕斯蛋糕（小）",
                "Remark": "超级好吃的玫瑰慕斯蛋糕",
                "Strikethrough": "¥30",
                "MiniAppDirectUrl": "https://example.com",
                "DirectUrls": [
                    "https://example.com",
                    "https://example2.com"
                ],
                "EnableStatus": 1,
                "Index": 0,
                "RedirectUrl": "https://example.com",
                "RedirectImage": "https://p.example.org/***.png",
                "IntroduceImage": "https://p.example.org/***.png",
                "Highlight": "¥15",
                "SellingPointTag": "买二赠一；满50减20",
                "ReminderType": 1,
                "PromotionTagUrl": "https://p.example.org/***.png",
                "PromotionTagType": 1,
                "IsOrderMsgEnable": 1,
                "HotSale": "1000",
                "Stock": "50",
                "ExplainStatus": 0,
                "ExplainTime": 0,
                "FloatingStatus": 1,
                "FloatingTime": 1742873573,
                "OutOfStock": 0,
                "PriceHidden": 0
            }
        ]
    }
}

错误码

访问公共错误码和错误码获取详细信息。