将订阅商品从测试环境发布到生产环境。这是一个单向、仅限首次发布的操作。
POST /v1/actions/subscription-product/publish-product
此端点不要包含 X-Environment 请求头。发布始终是从 test 到 production 的单向操作。
请求体
| 字段 | 类型 | 必需 | 说明 |
|---|
id | string | 是 | 商品 ID（PROD_xxx 格式） |
请求示例
await client.subscriptionProducts.publish({
id: "PROD_3F7H2J5L8N1Q4S6U",
});
成功响应 (200)
{
"data": {
"product": {
"id": "PROD_3F7H2J5L8N1Q4S6U",
"storeId": "STO_2D5F8G3H1K4M6N9P",
"name": "Pro Plan",
"description": "Full access to all Pro features.",
"billingPeriod": "monthly",
"prices": {
"USD": { "amount": "29.00", "taxCategory": "saas" },
"EUR": { "amount": "27.00", "taxCategory": "saas" }
},
"media": [],
"successUrl": "https://example.com/welcome",
"metadata": { "trialDays": 14 },
"status": "active",
"createdAt": "2026-03-30T10:30:00.000Z",
"updatedAt": "2026-03-30T12:00:00.000Z"
}
}
}
响应字段
与 创建订阅商品响应 相同。
仅支持首次发布。商品拥有生产版本后，此端点将返回错误。如需更新已发布的商品，请在生产环境中使用 更新商品 端点。 错误响应
重试策略：4xx 一律不要重试 — 修正请求后重发。5xx 指数退避重试（起步 5s，最多 3 次）。
| 状态码 | errors[0].message | 含义 | 推荐处理 |
|---|
| 400 | Missing header: x-context-merchant-id | 商户上下文 header 未透传 | 修正 SDK 配置 |
| 400 | Missing required field: id | 请求体缺少 id | 补齐 id 后重发 |
| 400 | Expected format: PROD_xxx, got "X" | id 不是合法 Short ID | 使用 PROD_ 前缀的 Short ID |
| 400 | No test version found | 该商品在 test 环境无版本可发布 | 先通过 Update Product / Update Status 在 test 创建并激活版本 |
| 400 | Test version is not active | test 版本存在但状态为 inactive | 先通过 Update Status 把 test 版本激活后再发布 |
| 400 | Already published to production | 商品已有 prod 版本（publish 只支持首次发布） | 改在 prod 环境调 Update Product |
| 401 | Unauthorized | 认证失败 | 检查 API Key、时间戳与签名 |
| 404 | Product not found / Source version not found | product ID 不存在（或源版本缺失） | 确认 product ID |
| 500 | Internal server error | 瞬时下游故障 | 指数退避重试（起步 5s，最多 3 次） |
