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

​
请求体

字段类型必需说明
storeIdstring是门店 ID（Short ID 格式 STO_xxx）
namestring是产品名称
descriptionstring否产品描述（支持 Markdown）
pricesobject是多币种定价映射（见下方）
mediaarray否产品图片/视频（见下方）
successUrlstring否购买成功后的重定向 URL
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": {
    "id": "PROD_3kF9mNpQrStUvWxYz1A2bC",
    "storeId": "STO_2aUyqjCzEIiEcYMKj7TZtw",
    "prodVersionId": null,
    "testVersionId": "PROD_7dG4hJkLmNpQrStUvWxYz1",
    "prodStatus": "inactive",
    "testStatus": "active",
    "createdAt": "2026-01-15T10:30:00.000Z",
    "updatedAt": "2026-01-15T10:30:00.000Z",
    "version": {
      "id": "PROD_7dG4hJkLmNpQrStUvWxYz1",
      "productId": "PROD_3kF9mNpQrStUvWxYz1A2bC",
      "versionNumber": 1,
      "name": "Premium Template Pack",
      "description": "50 premium design templates for your next project.",
      "prices": {
        "USD": { "amount": "49.00", "taxIncluded": false, "taxCategory": "digital_goods" },
        "EUR": { "amount": "45.00", "taxIncluded": true, "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" },
      "createdAt": "2026-01-15T10:30:00.000Z"
    }
  }
}

​
响应字段

字段类型说明
idstring产品 ID（PROD_xxx）
storeIdstring门店 ID（STO_xxx）
prodVersionIdstring | null生产环境活跃版本 ID（PROD_xxx），未发布时为 null
testVersionIdstring | null测试环境活跃版本 ID（PROD_xxx），不在测试环境时为 null
prodStatusstring生产状态：active 或 inactive
testStatusstring测试状态：active 或 inactive
createdAtstring创建时间戳（ISO 8601）
updatedAtstring最后更新时间戳（ISO 8601）
versionobject当前环境中创建或活跃的版本
版本对象：
字段类型说明
idstring版本 ID（PROD_xxx）
productIdstring父产品 ID（PROD_xxx）
versionNumberinteger递增版本号（从 1 开始）
namestring该版本的产品名称
descriptionstring | null该版本的产品描述
pricesobject多币种定价映射
mediaarray该版本的媒体项
successUrlstring | null该版本的成功重定向 URL
metadataobject | null该版本的自定义元数据
createdAtstring版本创建时间戳（ISO 8601）
在测试环境中创建（默认），testStatus 为 active，prodStatus 为 inactive。在生产环境中创建时，值相反。

​
错误响应

状态码错误说明
400Missing required field: storeId未提供 storeId
400Missing required field: name未提供 name
400Prices must not be emptyprices 缺失或为空对象
404Store not found门店不存在或不可访问