跳转到主要内容
更新订阅商品的内容。如果内容有变化，将自动创建一个新的不可变版本。如果内容与当前版本一致，则不会创建新版本。 
POST /v1/actions/subscription-product/update-product
认证方式： API Key

​
请求体

字段类型必需说明
idstring是商品 ID（PROD_xxx 格式）
namestring否更新后的商品名称（≤ 64 字符）
billingPeriodstring否weekly、monthly、quarterly 或 yearly
pricesobject否更新后的多币种定价
descriptionstring | null否更新后的描述（传 null 或 "" 清空）
mediaarray否更新后的媒体
successUrlstring | null否更新后的跳转 URL（≤ 512 字符，必须为合法 http(s) URL；传 null 或 "" 清空）
metadataobject否更新后的元数据（可包含 trialDays）

​
请求示例

const { product } = await client.subscriptionProducts.update({
  id: "PROD_3F7H2J5L8N1Q4S6U",
  name: "Pro Plan v2",
  billingPeriod: BillingPeriod.Monthly,
  prices: {
    USD: { amount: "39.00", taxIncluded: false, taxCategory: TaxCategory.SaaS },
    EUR: { amount: "36.00", taxIncluded: false, taxCategory: TaxCategory.SaaS },
  },
  metadata: { trialDays: 7 },
});

​
成功响应 (200)

{
  "data": {
    "product": {
      "id": "PROD_3F7H2J5L8N1Q4S6U",
      "storeId": "STO_2D5F8G3H1K4M6N9P",
      "name": "Pro Plan v2",
      "description": null,
      "billingPeriod": "monthly",
      "prices": {
        "USD": { "amount": "39.00", "taxCategory": "saas" },
        "EUR": { "amount": "36.00", "taxCategory": "saas" }
      },
      "media": [],
      "successUrl": null,
      "metadata": { "trialDays": 7 },
      "status": "active",
      "createdAt": "2026-03-30T10:30:00.000Z",
      "updatedAt": "2026-03-30T11:00:00.000Z"
    }
  }
}

​
响应字段

与 创建订阅商品响应 相同。
商品更新会创建新的不可变版本。现有订阅保留其原始版本。新注册使用最新版本。如果提交的内容与当前版本一致，则不会创建新版本。

​
错误响应

重试策略：4xx 一律不要重试 — 修正请求后重发。5xx 指数退避重试（起步 5s，最多 3 次）。
状态码errors[0].message含义推荐处理
400Missing header: x-context-merchant-id商户上下文 header 未透传修正 SDK 配置
400Missing or invalid header: x-context-environment环境 header 缺失或不是 test / prod把 X-Environment 设为 test 或 prod
400Missing required field: id请求体缺少 id补齐 id 后重发
400Expected format: PROD_xxx, got "X"id 不是合法 Short ID使用 PROD_ 前缀的 Short ID
400Field name must be a non-empty string提供了空字符串的 name不传 name 保留原值，或传非空字符串
400Invalid billingPeriodbillingPeriod 不在 weekly / monthly / quarterly / yearly 集合改为四个允许值之一
400Field prices must be a non-empty object传了空 prices不传 prices 保留原值，或至少包含一种货币
400Invalid currency code: "X". Must be 3 uppercase letters (e.g., "USD", "EUR", "JPY")prices 的 key 不是合法 ISO 4217 代码改为 3 位大写字母
400Invalid amount for X: "Y". Must be a positive number string (e.g., "9.99", "1000")金额字符串无法解析改为正数十进制字符串
400消息包含 has no version目标环境（test 或 prod）尚无版本先在该环境创建版本（从 test 发布，或在 test 创建）
401Unauthorized认证失败检查 API Key、时间戳与签名
404Product not found / Current version not foundproduct ID 不存在（或当前版本缺失）确认 product ID
500Internal server error瞬时下游故障指数退避重试（起步 5s，最多 3 次）