Cancel Subscription (Customer)

This is the customer-token call path of the same endpoint described in Cancel Subscription (Merchant API Key). Behavior and response shape are identical — the customer path additionally accepts the optional cancellation-reason fields below, and only the auth surface and the call site differ.

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

Authentication: Session Token — see Customer Endpoints (customer or customer role)

The orderId must belong to the customer that the session token was minted for. Tokens minted for one customer cannot cancel another customer’s subscription.

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

Cancelling a pending plan-change subscription voids that change: the new subscription becomes canceled directly and its PSP cancellation is dispatched right away, so nothing activates or is charged at the planned switch time. The original subscription is not put back into service — it stays canceling and moves one way to canceled, and Reactivate Subscription refuses it with 400. To keep paying, the customer places a new order.

A pending order that ends on its own while the cancellation is in flight — for example the PSP closes one of two plan-change candidates created concurrently for the same subscription — is treated as already canceled: the request returns 200 with the current terminal status (e.g. closed), any discount reservation still held is released once, and no cancellation reason is stored. If the order was changed concurrently but has not ended, the request returns 409 with the current status; re-read the order and retry.

Cancelling a past_due subscription takes effect immediately rather than at period end, and sends no “cancellation scheduled, access until X” email — the billing period has already lapsed. Such a cancellation cannot be reverted with Reactivate Subscription: any subscription that had an unpaid charge at the moment cancellation was requested is refused with 400.

Request Body

Field	Type	Required	Description
`orderId`	string	Yes	Subscription order ID (Short ID format `ORD_xxx`)
`cancelReason`	string	No	Cancellation reason code chosen by the customer. `snake_case`, at most 64 characters. The value set is not constrained — any well-formed code is accepted, so adding or removing reasons needs no API release
`cancelComment`	string	No	Free-text comment from the customer, at most 500 characters. Stored only when the cancellation produces a record

The reason is stored only for buyer-side credentials and only once the cancellation actually succeeds — one row per cancellation action, so cancel → reactivate → cancel leaves two. Storing the reason is a side path: if it fails the cancellation still succeeds and the response is unchanged; a failed cancellation (400 / 409 / 500 / 502), or one that converges on an order that already ended, stores nothing. Merchants read the stored reasons through GraphQL. What happens when cancelReason is omitted depends on which credential made the call:

Credential	`cancelReason` omitted	Meaning
Customer session token (this page)	No record is stored	Merchant-built integration: the request body carries only `orderId`, so an absent field means the buyer was never asked
Buyer session token	One row is stored with `reason_code` = `not_provided`	The buyer portal’s cancellation dialog always asks, so an absent field means the buyer saw it and skipped
Merchant JWT / API key	No record is stored	The merchant cancelled on the buyer’s behalf

The two channels deliberately do not share the sentinel: folding “never asked” and “asked but declined” into one value would make the not_provided share unreadable for merchants. If your integration also offers reason options and you want skips counted in the denominator, submit cancelReason explicitly (the value set is open, e.g. not_provided).

Example Request

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

const client = new WaffoPancake({
  sessionToken: window.WAFFO_SESSION_TOKEN, // injected by the merchant's 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" or "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"

Success Response (200)

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

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 required field: orderId`	`orderId` is missing, empty, or not a string	Fix the body, resubmit
400	`Invalid JSON body`	Request body is not valid JSON	Fix the body, resubmit
400	`Expected format: ORD_xxx, got "..."`	`orderId` Short ID could not be decoded	Fix the `orderId` format, resubmit
400	`cancelReason must not be empty` / `cancelReason must be snake_case` / `cancelReason must be at most 64 characters`	`cancelReason` is blank or not a well-formed code	Send a non-blank `snake_case` code of at most 64 characters, or omit the field
400	`cancelComment must be at most 500 characters`	`cancelComment` exceeds the length limit	Truncate the comment to 500 characters
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`	Session token invalid, expired, or malformed	Re-mint the session token via Issue Session Token
403	`Order does not belong to user`	The token’s customer is not the order owner	Mint a token for the correct customer
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

Cancel Subscription (Customer)

Cancellation Behavior

Request Body

Example Request

Success Response (200)

Response Fields

Errors

​Cancellation Behavior

​Request Body

​Example Request

​Success Response (200)

​Response Fields

​Errors

Cancellation Behavior

Request Body

Example Request

Success Response (200)

Response Fields

Errors