跳转到主要内容
POST /v1/actions/subscription-product/create-product
认证方式： API Key

​
请求体

字段类型必需说明
storeIdstring是Store ID（STO_xxx 格式）
namestring是商品名称（≤ 64 字符）
billingPeriodstring是weekly、monthly、quarterly 或 yearly
pricesobject是多币种定价（参见 价格格式）
descriptionstring | null否商品描述（支持 Markdown；传 null 或 "" 清空）
mediaarray否商品图片/视频（参见 媒体格式）
successUrlstring | null否成功订阅后的跳转 URL（≤ 512 字符，必须为合法 http(s) URL；传 null 或 "" 清空）
metadataobject否自定义键值数据。可包含 trialDays（整数，1-365）以提供免费试用期

​
请求示例

import { WaffoPancake, BillingPeriod, TaxCategory } from "@waffo/pancake-ts";

const client = new WaffoPancake({
  merchantId: process.env.WAFFO_MERCHANT_ID!,
  privateKey: process.env.WAFFO_PRIVATE_KEY!,
});

const { product } = await client.subscriptionProducts.create({
  storeId: "STO_2D5F8G3H1K4M6N9P",
  name: "Pro Plan",
  billingPeriod: BillingPeriod.Monthly,
  prices: {
    USD: { amount: "29.00", taxIncluded: false, taxCategory: TaxCategory.SaaS },
    EUR: { amount: "27.00", taxIncluded: false, taxCategory: TaxCategory.SaaS },
  },
  description: "Full access to all Pro features.",
  successUrl: "https://example.com/welcome",
  metadata: { trialDays: 14 },
});

​
成功响应 (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-30T10:30:00.000Z"
    }
  }
}

​
响应字段

响应包裹在 data.product 中。商品对象是合并了商品和版本字段的扁平化详情视图。
字段类型说明
idstring商品 ID（PROD_xxx）
storeIdstringStore ID（STO_xxx）
namestring商品名称（来自当前版本）
descriptionstring | null商品描述（来自当前版本）
billingPeriodstring计费周期：weekly、monthly、quarterly 或 yearly
pricesobject多币种定价映射（见下方）
mediaarray媒体项（来自当前版本）
successUrlstring | null成功跳转 URL（来自当前版本）
metadataobject自定义元数据（来自当前版本，可包含 trialDays）
statusstring当前环境中的状态：active 或 inactive
createdAtstring商品创建时间戳（ISO 8601）
updatedAtstring商品最后更新时间戳（ISO 8601）
响应价格对象（每个货币）：
字段类型说明
amountstring显示格式的价格字符串（例如 “29.00”）
taxCategorystring用于税率计算的税务类别

​
错误响应

重试策略：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: storeId / Missing required field: name / Missing required field: prices (must have at least one currency)必填字段缺失补齐字段后重发
400Expected format: STO_xxx, got "X"storeId 不是合法 Short ID使用 STO_ 前缀的 Short ID
400Invalid or missing billingPeriodbillingPeriod 不在 weekly / monthly / quarterly / yearly 集合改为四个允许值之一
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")金额字符串无法解析改为正数十进制字符串
401Unauthorized认证失败检查 API Key、时间戳与签名
404Store not found解码后的 storeId 不存在（外键约束）确认门店归属于当前商户
500Internal server error瞬时下游故障指数退避重试（起步 5s，最多 3 次）