更新现有门店的名称、状态或配置设置。仅请求体中包含的字段会被更新；省略的字段保持不变。
POST /v1/actions/store/update-store
认证方式： API Key（需要 owner 或 admin 角色）请求体 字段 类型 必需 说明 idstring 是 Store ID（Short ID 格式 STO_xxx） namestring 否 更新后的门店名称（1-48 字符） statusstring 否 active、inactive 或 suspendedlogostring | null 否 门店 logo URL（设为 null 可移除） supportEmailstring | null否 商店客服邮箱（设为 null 以移除） websitestring | null否 商店网站 URL（设为 null 以移除） notificationSettingsobject | null 否 通知偏好设置（设为 null 可移除） checkoutSettingsobject | null 否 收银台主题配置（设为 null 可移除）
通知设置 分两类，写入权限不同：
商户可写 （✅ 通过本端点接受）：字段 类型 默认值 说明 notifyNewOrdersboolean true新订单时通知商户 notifyNewSubscriptionsboolean true新订阅时通知商户 notifySubscriptionCanceledboolean true订阅取消（用户取消，仍在 access 期内）时通知商户 notifySubscriptionEndedboolean true订阅终止时通知商户 notifySubscriptionPastDueboolean true订阅扣款失败（past_due）时通知商户 notifySubscriptionRenewedboolean true订阅续费成功时通知商户 notifySubscriptionUncanceledboolean true订阅取消后恢复时通知商户 notifySubscriptionUpdatedboolean true订阅 plan 变更时通知商户（forward-compat） notifyChargebackboolean true拒付（chargeback）时通知商户（forward-compat） notifyPayoutCompletedboolean true提现完成时通知商户（forward-compat） notifyPayoutFailedboolean true提现失败时通知商户（forward-compat）
平台管理 （🔒 商户 API 只读；由 PANCAKE 平台管理）：字段 类型 默认值 说明 emailOrderConfirmationboolean true订单确认时发送邮件 emailSubscriptionConfirmationboolean true订阅创建时发送邮件 emailSubscriptionCycledboolean true订阅续费时发送邮件 emailSubscriptionCanceledboolean true订阅取消时发送邮件 emailSubscriptionRevokedboolean true订阅撤销时发送邮件 emailSubscriptionPastDueboolean true订阅逾期时发送邮件 emailTrialStartedboolean true试用启动时发送邮件 emailTrialEndingboolean true试用即将结束时发送提醒邮件
若 notificationSettings 入参中包含任何平台管理的 email* 字段，服务端会静默丢弃这些字段，并在 200 响应的 warnings[] 中列出被丢弃的 key。如需修改消费者邮件 toggle，请联系 PANCAKE 平台。
收银台设置 字段 类型 说明 defaultDarkModeboolean 是否默认使用暗色模式 lightobject 亮色主题设置（见下方） darkobject 暗色主题设置（见下方）
收银台主题设置 （适用于 light 和 dark）：字段 类型 说明 checkoutLogostring | null 收银台页面 logo URL checkoutColorPrimarystring 主色（hex） checkoutColorBackgroundstring 背景色（hex） checkoutColorCardstring 卡片/面板颜色（hex） checkoutColorTextstring 文字颜色（hex） checkoutBorderRadiusstring 圆角半径（CSS 值）
部分更新语义 两个 settings 对象均支持部分更新，每个子字段有三种传值语义：
传值 行为 示例 不传（JSON 中省略） 保留现有值 只传 notifyNewOrders，其它通知开关保持不变 null清除该字段 "checkoutLogo": null 移除收银台页面 logo具体值 新增/更新 "checkoutColorPrimary": "#FF6600" 设置新主色
将整个对象设为 null（如 "notificationSettings": null）会清除该设置组的所有字段。
请求示例 SDK
TypeScript (fetch)
Java
Python
Go
Rust
C
C++
cURL
wget
import { WaffoPancake , EntityStatus } 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 . update ({ id: "STO_2aUyqjCzEIiEcYMKj7TZtw" , name: "Updated Store Name" , // 只允许写商户可见的通知 toggle（B 类）； // 消费者邮件 toggle（emailOrderConfirmation 等 A 类）由 PANCAKE 平台管理， // 请勿在此处传入（传了会被静默丢弃 + 200 warning）。 notificationSettings: { notifyNewOrders: true , notifyNewSubscriptions: false , }, });
成功响应 (200) { "data" : { "store" : { "id" : "STO_2aUyqjCzEIiEcYMKj7TZtw" , "name" : "Updated Store Name" , "status" : "active" , "logo" : null , "slug" : "my-digital-store-a1b2c3" , "prodEnabled" : false , "notificationSettings" : { "emailOrderConfirmation" : true , "emailSubscriptionConfirmation" : true , "emailSubscriptionCycled" : true , "emailSubscriptionCanceled" : true , "emailSubscriptionRevoked" : true , "emailSubscriptionPastDue" : true , "emailTrialStarted" : true , "emailTrialEnding" : true , "notifyNewOrders" : true , "notifyNewSubscriptions" : false , "notifySubscriptionCanceled" : true , "notifySubscriptionEnded" : true , "notifySubscriptionPastDue" : true , "notifySubscriptionRenewed" : true , "notifySubscriptionUncanceled" : true , "notifySubscriptionUpdated" : true , "notifyChargeback" : true , "notifyPayoutCompleted" : true , "notifyPayoutFailed" : 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-15T11:00:00.000Z" } } }
响应字段 与 创建门店响应字段 相同。
webhookSettings 兼容性警告 请求体中如出现 webhookSettings 字段，该字段会被静默忽略，响应顶层会包含一个 warnings 数组。data.store 对象不受影响。
{ "data" : { "store" : { "..." : "..." } }, "warnings" : [ { "message" : "webhookSettings is no longer accepted on update-store; the field was ignored." , "layer" : "store" , "aiHint" : "AI assistant: 'webhookSettings' is permanently removed (BREAKING 2026-05). Do not retry with this field. SDK users: upgrade to @waffo/pancake-ts >= 0.6.0 and call client.webhooks.add / update / remove instead of client.stores.update({ webhookSettings }). Direct API users: POST /api/actions/store/add-webhook to create a webhook, /update-webhook to modify, /remove-webhook to delete. Query the webhook list via GraphQL Store.storeWebhooks field, not via this endpoint." } ] }
错误响应
重试策略 ：4xx 一律不要重试 — 修正请求后重发。5xx 指数退避重试（起步 5s，最多 3 次）。
状态码 errors[0].message含义 推荐处理 400 Missing merchantId in request contextAPI Key 未解析出商户上下文 不要重试 。检查 API Key 配置。400 Missing required field: id请求体未传 id 修正输入后重新提交。 400 Expected format: STO_xxx, got "<value>"id 不是有效的 Store Short ID修正 id 后重新提交。 400 Store name cannot be empty or contain only whitespacetrim() 后 name 为空修正 name 后重新提交。 400 Store name cannot exceed 48 charactersname 超过 48 字符缩短 name 后重新提交。 400 Invalid status, must be active, inactive or suspendedstatus 不在枚举内改用 active、inactive 或 suspended。 400 Invalid logo: must be a string or nulllogo 既不是字符串也不是 null传字符串 URL 或 null 以清空。 403 Not authorized to update this store调用方在该门店上的角色不是 owner/admin 不要重试 。改用具备权限的商户。404 Store not found该商户下不存在该门店 ID 不要重试 。校验 id。
