跳转到主要内容
创建支持多币种定价的一次性购买商品。 
POST /v1/actions/onetime-product/create-product
认证方式： API Key

​
请求体

字段类型必需说明
storeIdstring是Store ID（Short ID 格式 STO_xxx）
namestring是商品名称（≤ 64 字符）
descriptionstring | null否商品描述（支持 Markdown；传 null 或 "" 清空）
pricesobject是多币种定价映射（见下方）
mediaarray否商品图片/视频（见下方）
successUrlstring | null否购买成功后的跳转 URL（≤ 512 字符，必须为合法 http(s) URL；传 null 或 "" 清空）
metadataobject否自定义键值数据（最多 50 个键）

​
价格对象格式

价格为 ISO 4217 货币代码到价格配置对象的映射。至少需要一个货币。 
{
  "USD": {
    "amount": "29.00",
    "taxIncluded": false,
    "taxCategory": "saas"
  },
  "EUR": {
    "amount": "27.00",
    "taxIncluded": true,
    "taxCategory": "saas"
  }
}
字段类型说明
amountstring显示格式的价格字符串（例如 “29.00” = $29.00）
taxIncludedboolean金额是否已包含税费
taxCategorystring用于税率计算的税务类别
支持的 taxCategory 值：
值说明
digital_goods通用数字商品
saas软件即服务
software可下载软件
ebook电子书
online_course在线课程和教育
consulting咨询服务
professional_service专业服务

​
媒体项格式

{
  "type": "image",
  "url": "https://example.com/product.png",
  "alt": "Product screenshot",
  "thumbnail": "https://example.com/product-thumb.png"
}
字段类型说明
typestringimage 或 video
urlstring媒体 URL
altstring用于无障碍的替代文本
thumbnailstring缩略图 URL（图片可选，视频推荐）

​
请求示例

import { WaffoPancake, 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.onetimeProducts.create({
  storeId: "STO_2aUyqjCzEIiEcYMKj7TZtw",
  name: "Premium Template Pack",
  description: "50 premium design templates for your next project.",
  prices: {
    USD: { amount: "49.00", taxIncluded: false, taxCategory: TaxCategory.DigitalGoods },
    EUR: { amount: "45.00", taxIncluded: true, taxCategory: TaxCategory.DigitalGoods },
  },
  media: [
    { type: "image", url: "https://example.com/templates-preview.png", alt: "Template preview" },
  ],
  successUrl: "https://example.com/thank-you",
  metadata: { category: "design", fileCount: "50" },
});

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

​
响应字段

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

​
错误响应

重试策略：4xx 一律不要重试 — 修正请求后重发。5xx 指数退避重试（起步 5s，最多 3 次）。
状态码errors[0].message含义推荐处理
400Missing required field: storeId未提供 storeId修正请求体后重发
400Invalid ID format提供的 Short ID 无法解码修正 storeId 格式后重发
400Missing required field: name未提供 name修正请求体后重发
400Prices must have at least one currencyprices 缺失或为空对象至少提供一种货币后重发
400Invalid currency code货币代码必须为 3 位大写字母（ISO 4217，如 USD、EUR、JPY）使用合法 ISO 4217 代码后重发
400Invalid amount金额必须为正数字符串（如 "9.99"、"100"）使用正数字符串后重发
404Store not found门店不存在或不可访问验证 storeId 是否属于当前商户
500Internal server error服务端意外失败指数退避重试（起步 5s，最多 3 次）