サブスクリプションのキャンセル

保留中・有効・支払い遅延中のサブスクリプションをキャンセルします。動作は現在のサブスクリプションステータスによって異なります。

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

認証： API Key（merchant、owner ロール）

このエンドポイントには customer 側の session-token フローもあります：サブスクリプションのキャンセル（Customer）を参照。

キャンセル動作

現在のステータス	アクション	結果ステータス
`pending`（新規購入）	即時キャンセル、PSP 呼び出しなし	`canceled`
`pending`（プラン変更の新サブスクリプション）	即時キャンセル、PSP キャンセルは即時送信	`canceled`
`active`	期間終了時にキャンセル（PSP 経由）	`canceling` -> 期間終了時に `canceled`
`past_due`	即時キャンセル（PSP 経由）	`canceling` -> PSP の確認後に `canceled`

pending: 直接キャンセルされ、ステータスは canceled になります（canceling を経由しません）
pending のプラン変更サブスクリプション: 同じく直接 canceled になりますが、その予約済みサブスクリプションに対する PSP キャンセルが即時送信されるため、予定の切替時刻に有効化も課金もされません。元のサブスクリプションは一切変更されず、canceling のままで active には戻りません
キャンセル中に終了済み（冪等な収束）: 読み取り時は pending だった注文が、キャンセルの書き込み前に終了状態になった場合 —— 例えば同じサブスクリプションに対してプラン変更候補が 2 件同時に作成され、PSP が譲った側をクローズして先にクローズ通知を返した場合や、並行する別のキャンセルが先に反映された場合 —— はキャンセル済みとして収束します。まだ保持されている割引の予約を解放し（解放済みのものを二重に解放することはありません）、200 と現在の終了状態（例: closed）を返します。この場合キャンセル理由は保存されません
active: PSP キャンセルがトリガーされます（請求期間の終了時に有効）。ローカルステータスは canceling になり、期間終了時に Webhook 経由で canceled に更新されます
past_due: PSP キャンセルは期間終了を待たず即時に送信されます。ローカルステータスは canceling になり、PSP の確認後に Webhook 経由で canceled に更新されます。請求期間は既に終了しているため、この経路では「キャンセル予定・X 日まで利用可能」のメールは送信されません

canceling のサブスクリプションは通常サブスクリプションの再開で取り消せますが、キャンセル要求時点で未払いの請求があるサブスクリプションは取り消せず、当該エンドポイントは 400 を返します。past_due のキャンセルは必ずこれに該当します。

確定済みのプラン変更によって canceling になったサブスクリプションは決して取り消せません。保留中の新サブスクリプションをキャンセルして変更を無効化した後も同様です。決済チャネルは変更を確定した時点で元のサブスクリプションをキャンセル待ちにし、戻す手段を提供しません。このサブスクリプションは一方向に canceled へ進みます。買い手の支払いを継続させたい場合は新規注文を作成してください。

リクエストボディ

フィールド	型	必須	説明
`orderId`	string	Yes	サブスクリプション注文 ID（Short ID フォーマット `ORD_xxx`）

リクエスト例

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

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

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

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

// Assumes callApi() is defined as shown in the Authentication guide
const result = await callApi("POST", "/v1/actions/subscription-order/cancel-order", {
  orderId: "ORD_2aUyqjCzEIiEcYMKj7TZtw",
});

// Assumes callApi() is defined as shown in the Authentication guide
String result = callApi("POST", "/v1/actions/subscription-order/cancel-order",
    "{\"orderId\":\"ORD_2aUyqjCzEIiEcYMKj7TZtw\"}");

# Assumes call_api() is defined as shown in the Authentication guide
result = call_api("POST", "/v1/actions/subscription-order/cancel-order", {
    "orderId": "ORD_2aUyqjCzEIiEcYMKj7TZtw",
})

// Assumes callAPI() is defined as shown in the Authentication guide
result, err := callAPI("POST", "/v1/actions/subscription-order/cancel-order",
    `{"orderId":"ORD_2aUyqjCzEIiEcYMKj7TZtw"}`)

// Assumes call_api() is defined as shown in the Authentication guide
let result = call_api("POST", "/v1/actions/subscription-order/cancel-order",
    r#"{"orderId":"ORD_2aUyqjCzEIiEcYMKj7TZtw"}"#
).await?;

// Assumes call_api() is defined as shown in the Authentication guide
call_api("/v1/actions/subscription-order/cancel-order",
    "{\"orderId\":\"ORD_2aUyqjCzEIiEcYMKj7TZtw\"}");

// Assumes call_api() is defined as shown in the Authentication guide
auto result = call_api("/v1/actions/subscription-order/cancel-order",
    R"({"orderId":"ORD_2aUyqjCzEIiEcYMKj7TZtw"})");

MERCHANT_ID="MER_2aUyqjCzEIiEcYMKj7TZtw"
TIMESTAMP=$(date +%s)
BODY='{"orderId":"ORD_2aUyqjCzEIiEcYMKj7TZtw"}'
BODY_HASH=$(echo -n "$BODY" | openssl dgst -sha256 -binary | base64 | tr -d '\n')
CANONICAL="POST
/v1/actions/subscription-order/cancel-order
$TIMESTAMP
$BODY_HASH"

SIGNATURE=$(echo -n "$CANONICAL" | openssl dgst -sha256 -sign private_key.pem | base64 | tr -d '\n')

curl -X POST "https://api.waffo.ai/v1/actions/subscription-order/cancel-order" \
  -H "Content-Type: application/json" \
  -H "X-Merchant-Id: $MERCHANT_ID" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Signature: $SIGNATURE" \
  -d "$BODY"

MERCHANT_ID="MER_2aUyqjCzEIiEcYMKj7TZtw"
TIMESTAMP=$(date +%s)
BODY='{"orderId":"ORD_2aUyqjCzEIiEcYMKj7TZtw"}'
BODY_HASH=$(echo -n "$BODY" | openssl dgst -sha256 -binary | base64 | tr -d '\n')
CANONICAL="POST
/v1/actions/subscription-order/cancel-order
$TIMESTAMP
$BODY_HASH"

SIGNATURE=$(echo -n "$CANONICAL" | openssl dgst -sha256 -sign private_key.pem | base64 | tr -d '\n')

wget -qO- --post-data="$BODY" \
  --header="Content-Type: application/json" \
  --header="X-Merchant-Id: $MERCHANT_ID" \
  --header="X-Timestamp: $TIMESTAMP" \
  --header="X-Signature: $SIGNATURE" \
  "https://api.waffo.ai/v1/actions/subscription-order/cancel-order"

成功レスポンス (200) — 有効なサブスクリプション

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

成功レスポンス (200) — 保留中のサブスクリプション

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

レスポンスフィールド

フィールド	型	説明
`orderId`	string	注文 ID（Short ID）
`status`	string	新しい注文ステータス（`canceling` または `canceled`。キャンセル中に注文がすでに終了状態となり、キャンセル済みとして収束した場合は現在の終了状態 `canceled` / `closed` / `expired`）

エラー

リトライポリシー：4xx は一切リトライしない — リクエストを修正してから再送信。5xx は指数バックオフでリトライ（5s 開始、最大 3 回）。

ステータス	`errors[0].message`	意味	推奨処理
400	`Missing X-Context-Merchant-Id header`	API Key 認証下で merchant コンテキストが欠落	認証パイプラインを確認
400	`Missing required field: orderId`	`orderId` が欠落・空・文字列以外	リクエストボディを修正してから再送信
400	`Invalid JSON body`	リクエストボディが正しい JSON ではない	リクエストボディを修正してから再送信
400	`Expected format: ORD_xxx, got "..."`	`orderId` Short ID のデコード失敗	`orderId` のフォーマットを修正してから再送信
400	`Subscription cannot be canceled, current status: X`	注文ステータスが `pending`、`active`、`past_due` のいずれでもない（`canceled`、`canceling`、`closed`、`expired` など）	サブスクリプションはキャンセル不可
401	`Authentication failed`	API Key 署名が無効	認証ヘッダーを確認
403	`Order does not belong to user`	所有権チェック失敗	呼び出し元が注文を所有しているか確認
404	`Order not found`	注文が存在しない	order ID を確認
409	`Subscription order changed during cancellation, current status: X`	`pending` の注文がキャンセル中に並行して更新され、終了状態になっていない —— バージョン競合、またはキャンセルが反映される前に切替時刻で有効化されたプラン変更サブスクリプション	注文を再読み込みし、まだ `pending` ならキャンセルをリトライする（冪等）。有効化済みで PSP キャンセルが受理済みのプラン変更サブスクリプションは手動での照合が必要
500	`Internal server error`	サーバ側の予期しない障害	指数バックオフでリトライ（5s 開始、最大 3 回）
502	`Failed to cancel subscription`	PSP キャンセルが失敗し、注文が終了状態になっていない	指数バックオフでリトライ（5s 開始、最大 3 回）

概要

認証

マーチャント API（API Key）

Customer Portal API（Session Token）

GraphQL

サブスクリプションのキャンセル

キャンセル動作

リクエストボディ

リクエスト例

成功レスポンス (200) — 有効なサブスクリプション

成功レスポンス (200) — 保留中のサブスクリプション

レスポンスフィールド

エラー

​キャンセル動作

​リクエストボディ

​リクエスト例

​成功レスポンス (200) — 有効なサブスクリプション

​成功レスポンス (200) — 保留中のサブスクリプション

​レスポンスフィールド

​エラー

キャンセル動作

リクエストボディ

リクエスト例

成功レスポンス (200) — 有効なサブスクリプション

成功レスポンス (200) — 保留中のサブスクリプション

レスポンスフィールド

エラー