取消订阅（Customer）

本页是取消订阅（Merchant API Key）同一端点的 customer-token 调用视图。行为与响应结构完全一致 — customer 路径额外接受下方两个可选的取消原因字段，其余只有认证方式和调用方位置不同。

POST /v1/actions/subscription-order/cancel-order

认证方式： Session Token — 见 Customer Endpoints（customer 或 customer 角色）

orderId 必须属于该 session token 所绑定的 customer。为某 customer mint 的 token 不能取消另一 customer 的订阅。

取消行为

当前状态	操作	结果状态
`pending`（新购）	立即取消，不调用 PSP	`canceled`
`pending`（换方案新订阅）	立即取消，PSP 取消按发起时刻投递	`canceled`
`active`	在周期结束时取消（通过 PSP）	`canceling` → 周期结束时变为 `canceled`
`past_due`	立即取消（通过 PSP）	`canceling` → PSP 确认后变为 `canceled`

取消待生效的换方案新订阅会作废那笔变更：新订阅直接变为 canceled，其 PSP 取消按发起时刻投递，因此原定切换时刻既不激活也不扣款。原订阅不会被放回生效 —— 它保持 canceling 并单向走向 canceled，恢复订阅对它返回 400。买家想继续付费，请重新下单。

取消 past_due 订阅立即生效而非周期末生效，且不发送「取消中，可用至 X 日」邮件 —— 计费周期已经结束。此类取消不可撤回：恢复订阅对「发起取消时存在未结清扣款」的订阅一律返回 400。

请求体

字段	类型	必需	说明
`orderId`	string	是	订阅订单 ID（Short ID 格式 `ORD_xxx`）
`cancelReason`	string	否	customer 选定的取消原因码。`snake_case`，最长 64 字符。值域不做限定 —— 任意合法形态都被接受，增删原因项不需要 API 发版
`cancelComment`	string	否	customer 的自由文本留言，最长 500 字符。仅在该次取消产生记录时一并落库

取消原因只在买家侧凭证发起、且取消动作真实成功后留存 —— 一次取消动作一行，因此取消 → 恢复 → 再取消会留下两行。原因写入是旁路：写入失败时取消照常成功、响应体不变；取消失败（400 / 500 / 502）时不产生记录。商户通过 GraphQL 读取已留存的原因。不传 cancelReason 时的行为，取决于本次调用使用的凭证：

凭证	省略 `cancelReason`	含义
Customer session token（本页）	不产生记录	商户自建集成：请求体本就只有 `orderId`，字段缺失表示从未询问过买家
Buyer session token	记录一行，`reason_code` 为 `not_provided`	买家门户的取消弹窗一定会问，字段缺失表示买家看过但选择跳过
Merchant JWT / API key	不产生记录	商户代买家取消

两个渠道刻意不共用这个哨兵码：把「从未询问」与「问过但拒答」混进同一个值，会让商户无法解读 not_provided 的占比。若你的集成也向买家展示原因选项、并希望「跳过」被计入分母，请显式提交 cancelReason（值域开放，例如 not_provided）。

请求示例

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

const client = new WaffoPancake({
  sessionToken: window.WAFFO_SESSION_TOKEN, // 由商户 portal 注入
  environment: "prod",
});

const result = await client.orders.cancelSubscription({
  orderId: "ORD_2aUyqjCzEIiEcYMKj7TZtw",
  cancelReason: "too_expensive",
});

console.log(result.orderId); // "ORD_2aUyqjCzEIiEcYMKj7TZtw"
console.log(result.status);  // "canceling" 或 "canceled"

const result = await fetch("https://api.waffo.ai/v1/actions/subscription-order/cancel-order", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${SESSION_TOKEN}`,
    "Content-Type": "application/json",
    "X-Environment": "prod",
  },
  body: JSON.stringify({
    orderId: "ORD_2aUyqjCzEIiEcYMKj7TZtw",
    cancelReason: "too_expensive",
  }),
}).then(r => r.json());

curl -X POST "https://api.waffo.ai/v1/actions/subscription-order/cancel-order" \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Environment: prod" \
  -d '{"orderId":"ORD_2aUyqjCzEIiEcYMKj7TZtw","cancelReason":"too_expensive"}'

wget -qO- \
  --header="Authorization: Bearer $SESSION_TOKEN" \
  --header="Content-Type: application/json" \
  --header="X-Environment: prod" \
  --post-data='{"orderId":"ORD_2aUyqjCzEIiEcYMKj7TZtw","cancelReason":"too_expensive"}' \
  "https://api.waffo.ai/v1/actions/subscription-order/cancel-order"

成功响应 (200)

{
  "data": {
    "orderId": "ORD_2aUyqjCzEIiEcYMKj7TZtw",
    "status": "canceling"
  }
}

响应字段

字段	类型	说明
`orderId`	string	订单 ID（Short ID）
`status`	string	新的订单状态（`canceling` 或 `canceled`）

错误响应

重试策略：4xx 一律不要重试 — 修正请求后重发。5xx 指数退避重试（起步 5s，最多 3 次）。

状态码	`errors[0].message`	含义	推荐处理
400	`Missing required field: orderId`	`orderId` 缺失、为空或不是字符串	修正请求体后重新提交
400	`Invalid JSON body`	请求体不是合法 JSON	修正请求体后重新提交
400	`Expected format: ORD_xxx, got "..."`	`orderId` Short ID 解码失败	修正 `orderId` 格式后重新提交
400	`cancelReason must not be empty` / `cancelReason must be snake_case` / `cancelReason must be at most 64 characters`	`cancelReason` 为空白或形态不合法	改为非空、最长 64 字符的 `snake_case` 码，或省略该字段
400	`cancelComment must be at most 500 characters`	`cancelComment` 超长	将留言截断到 500 字符
400	`Subscription cannot be canceled, current status: X`	订单状态非 `pending`、`active` 或 `past_due`（如已 `canceled`、`canceling`、`closed`、`expired`）	该订阅已不可取消
401	`Authentication failed`	Session token 无效、过期或格式错误	通过 Issue Session Token 重新签发
403	`Order does not belong to user`	Token 绑定的 customer 不是订单所有者	为正确的 customer mint 一个 token
404	`Order not found`	订单不存在	验证 order ID
500	`Failed to cancel subscription`	本地写入未落地 —— 版本冲突，或换方案新订阅的 PSP 取消已受理而本地写入失败（两侧已分叉）	重试前先重新读取订单；已分叉的换方案取消需要人工核对
500	`Internal server error`	服务端意外失败	指数退避重试（起步 5s，最多 3 次）
502	`Failed to cancel subscription`	本地更新或 PSP 取消失败	指数退避重试（起步 5s，最多 3 次）

概览

认证

商户 API（API Key）

Customer Portal API（Session Token）

GraphQL

取消订阅（Customer）

取消行为

请求体

请求示例

成功响应 (200)

响应字段

错误响应

​取消行为

​请求体

​请求示例

​成功响应 (200)

​响应字段

​错误响应

取消行为

请求体

请求示例

成功响应 (200)

响应字段

错误响应