Cancel Subscription

Cancel a pending, active, or past-due subscription. The behavior depends on the current subscription status.

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

Authentication: API Key (merchant, owner role)

This endpoint also has a customer-side flow with session-token auth: see Cancel Subscription (Customer).

Cancellation Behavior

Current Status	Action	Result Status
`pending` (new purchase)	Immediate cancel, no PSP call	`canceled`
`pending` (plan-change subscription)	Immediate cancel, PSP cancellation dispatched now	`canceled`
`active`	Cancel at period end (via PSP)	`canceling` -> `canceled` at period end
`past_due`	Cancel immediately (via PSP)	`canceling` -> `canceled` once the PSP confirms

pending: Directly canceled, status becomes canceled — it never passes through canceling
pending plan-change subscription: also becomes canceled directly, but the PSP cancellation for that scheduled subscription is dispatched right away, so it neither activates nor charges at the planned switch time. The original subscription is left untouched: it stays canceling and does not return to active
Already ended while canceling (idempotent): if a pending order reaches a terminal status after it was read but before the cancellation is written — for example two plan-change candidates were created concurrently for the same subscription and the PSP closed the one that yielded, pushing the close notification back first, or a concurrent cancellation landed first — the request converges as canceled: any discount reservation still held is released (an already released one is not released twice), and it returns 200 with the current terminal status (e.g. closed). No cancellation reason is stored in this case
active: PSP cancellation is triggered (takes effect at billing period end). Local status becomes canceling, then updated to canceled via Webhook when the period ends
past_due: PSP cancellation is dispatched immediately, not deferred to period end. Local status becomes canceling, then updated to canceled via Webhook once the PSP confirms. No “cancellation scheduled, access until X” email is sent on this path, because the billing period has already lapsed

A canceling subscription can normally be reverted with Reactivate Subscription, but a subscription that had an unpaid charge at the moment cancellation was requested cannot be reverted and that endpoint returns 400. Cancelling a past_due subscription always falls into this category.

A subscription that is canceling because of a confirmed plan change can never be reverted, not even after that change is voided by cancelling its pending new subscription: the payment channel put the original subscription into pending cancellation when it confirmed the change and offers no way back. It moves one way to canceled; to keep the buyer paying, place a new order.

Request Body

Field	Type	Required	Description
`orderId`	string	Yes	Subscription order ID (Short ID format `ORD_xxx`)

Example Request

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"

Success Response (200) — Active Subscription

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

Success Response (200) — Pending Subscription

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

Response Fields

Field	Type	Description
`orderId`	string	Order ID (Short ID)
`status`	string	New order status (`canceling` or `canceled`; when the cancellation converges on an order that already ended, its current terminal status — `canceled`, `closed`, or `expired`)

Errors

Retry policy: Never retry 4xx — fix the request and resubmit. Retry 5xx with exponential backoff (start 5s, max 3 attempts).

Status	`errors[0].message`	What it means	Recommended handling
400	`Missing X-Context-Merchant-Id header`	Merchant context missing in API Key auth	Verify the auth pipeline
400	`Missing required field: orderId`	`orderId` is missing, empty, or not a string	Fix the request body, then resubmit
400	`Invalid JSON body`	Request body is not valid JSON	Fix the request body, then resubmit
400	`Expected format: ORD_xxx, got "..."`	`orderId` Short ID could not be decoded	Fix the `orderId` format, then resubmit
400	`Subscription cannot be canceled, current status: X`	Order status is not `pending`, `active`, or `past_due` (e.g. already `canceled`, `canceling`, `closed`, `expired`)	The subscription is no longer cancellable
401	`Authentication failed`	Invalid API Key signature	Verify auth headers
403	`Order does not belong to user`	Ownership check failed	Verify the caller owns the order
404	`Order not found`	Order does not exist	Verify the order ID
409	`Subscription order changed during cancellation, current status: X`	A `pending` order was changed concurrently while it was being canceled and has not ended — a version conflict, or a plan-change subscription that was activated at its switch time before the cancellation could apply	Re-read the order; if it is still `pending`, retry the cancellation (it is idempotent). An activated plan-change subscription whose PSP cancellation already went through needs manual reconciliation
500	`Internal server error`	Unexpected server-side failure	Retry with exponential backoff (start 5s, max 3 attempts)
502	`Failed to cancel subscription`	PSP cancellation failed and the order has not ended	Retry with exponential backoff (start 5s, max 3 attempts)

Overview

Auth

Merchant API (API Key)

Customer Portal API (Session Token)

GraphQL

Cancellation Behavior

Request Body

Example Request

Success Response (200) — Active Subscription

Success Response (200) — Pending Subscription

Response Fields

Errors

​Cancellation Behavior

​Request Body

​Example Request

​Success Response (200) — Active Subscription

​Success Response (200) — Pending Subscription

​Response Fields

​Errors

Cancellation Behavior

Request Body

Example Request

Success Response (200) — Active Subscription

Success Response (200) — Pending Subscription

Response Fields

Errors