跳转到主要内容
为已认证的商户创建新门店。门店 slug 由名称自动生成，JSONB 配置字段（notificationSettings、checkoutSettings）以默认值初始化。Webhook 通过 add-webhook 单独管理 — 新创建的门店不存在任何 webhook 记录。 
POST /v1/actions/store/create-store
认证方式： API Key

​
请求体

字段类型必需说明
namestring是门店名称（1-48 字符，自动去除首尾空格）

​
请求示例

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

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

const { store } = await client.stores.create({ name: "My Digital Store" });
console.log(store.id);   // => "STO_2aUyqjCzEIiEcYMKj7TZtw"
console.log(store.slug); // => "my-digital-store-a1b2c3"

​
成功响应 (200)

{
  "data": {
    "store": {
      "id": "STO_2aUyqjCzEIiEcYMKj7TZtw",
      "name": "My Digital Store",
      "status": "active",
      "logo": null,
      "supportEmail": null,
      "website": null,
      "slug": "my-digital-store-a1b2c3",
      "prodEnabled": false,
      "notificationSettings": {
        "emailOrderConfirmation": true,
        "emailSubscriptionConfirmation": true,
        "emailSubscriptionCycled": true,
        "emailSubscriptionCanceled": true,
        "emailSubscriptionRevoked": true,
        "emailSubscriptionPastDue": true,
        "notifyNewOrders": true,
        "notifyNewSubscriptions": true
      },
      "checkoutSettings": {
        "defaultDarkMode": false,
        "light": {
          "checkoutLogo": null,
          "checkoutColorPrimary": "#000000",
          "checkoutColorBackground": "#FFFFFF",
          "checkoutColorCard": "#F5F5F5",
          "checkoutColorText": "#1A1A1A",
          "checkoutBorderRadius": "8px"
        },
        "dark": {
          "checkoutLogo": null,
          "checkoutColorPrimary": "#FFFFFF",
          "checkoutColorBackground": "#1A1A1A",
          "checkoutColorCard": "#2A2A2A",
          "checkoutColorText": "#F5F5F5",
          "checkoutBorderRadius": "8px"
        }
      },
      "deletedAt": null,
      "createdAt": "2026-01-15T10:30:00.000Z",
      "updatedAt": "2026-01-15T10:30:00.000Z"
    }
  }
}

​
响应字段

字段类型说明
idstringStore ID（Short ID 格式 STO_xxx）
namestring门店显示名称
statusstring门店状态（active、inactive 或 suspended）
logostring | null门店 logo URL
supportEmailstring | null客服邮箱
websitestring | null门店网站 URL
slugstring | null自动生成的 URL slug
prodEnabledboolean是否已启用生产模式
notificationSettingsobject | null通知偏好设置（参见 通知设置）
checkoutSettingsobject | null收银台页面主题（参见 收银台设置）
deletedAtstring | null软删除时间戳（ISO 8601），活跃时为 null
createdAtstring创建时间戳（ISO 8601）
updatedAtstring最后更新时间戳（ISO 8601）

​
错误响应

重试策略：4xx 一律不要重试 — 修正请求后重发。5xx 指数退避重试（起步 5s，最多 3 次）。
状态码errors[0].message含义推荐处理
400Missing merchantId in request contextAPI Key 未解析出商户上下文不要重试。检查 API Key 配置。
400Missing required field: name请求体未传 name修正输入后重新提交。
400Store name cannot be empty or contain only whitespacetrim() 后 name 为空修正输入后重新提交。
400Store name cannot exceed 48 charactersname 超过 48 字符缩短名称后重新提交。
400Cannot create more stores. Maximum limit of 20 stores per merchant has been reached.商户已拥有 20 个门店不要重试。先删除一个现有门店，或联系支持提升上限。
每个商户最多可创建 20 个门店。门店创建者自动被分配 owner 角色。