跳转到主要内容
将商品从测试环境发布到生产环境。这是一个单向、仅限首次发布的操作，将当前测试版本复制到生产环境。 
POST /v1/actions/onetime-product/publish-product
认证方式： API Key
此端点不要包含 X-Environment 请求头。发布始终是从 test 到 production 的单向操作。

​
请求体

字段类型必需说明
idstring是商品 ID（Short ID 格式 PROD_xxx）

​
请求示例

const { product } = await client.onetimeProducts.publish({
  id: "PROD_3kF9mNpQrStUvWxYz1A2bC",
});

​
成功响应 (200)

{
  "data": {
    "product": {
      "id": "PROD_3kF9mNpQrStUvWxYz1A2bC",
      "storeId": "STO_2aUyqjCzEIiEcYMKj7TZtw",
      "name": "Premium Template Pack",
      "description": "50 premium design templates for your next project.",
      "prices": {
        "USD": { "amount": "49.00", "taxCategory": "digital_goods" },
        "EUR": { "amount": "45.00", "taxCategory": "digital_goods" }
      },
      "media": [
        { "type": "image", "url": "https://example.com/templates-preview.png", "alt": "Template preview" }
      ],
      "successUrl": "https://example.com/thank-you",
      "metadata": { "category": "design", "fileCount": "50" },
      "status": "active",
      "createdAt": "2026-01-15T10:30:00.000Z",
      "updatedAt": "2026-01-15T12:00:00.000Z"
    }
  }
}

​
响应字段

与 创建商品响应 相同。
仅支持首次发布。商品拥有生产版本后，此端点不能再对同一商品使用。首次发布后如需更新生产版本，请使用 更新商品 端点并携带 X-Environment: prod 请求头。

​
错误响应

重试策略：4xx 一律不要重试 — 修正请求后重发。5xx 指数退避重试（起步 5s，最多 3 次）。
状态码errors[0].message含义推荐处理
400Missing required field: id未提供 id修正请求体后重发
400Invalid ID format提供的 Short ID 无法解码修正 id 格式后重发
400No test version found商品在测试环境尚无版本先通过 Create Product 创建商品
400Test version is not active当前测试版本状态为 inactive先通过 Update Status 激活测试版本
400Already published to production商品已存在生产版本后续变更使用 Update Product 并附带 X-Environment: prod
404Product not found商品不存在或不可访问验证 id 是否属于当前商户
500Internal server error服务端意外失败指数退避重试（起步 5s，最多 3 次）