Checkout Page

prepare_subscription_cancellation

Read-only

This tool does not cancel the subscription. Cancellation happens only in the Checkout Page dashboard. The tool fetches the subscription, works out whether it can be canceled and what canceling changes, and returns the dashboard URL where a person performs the cancellation.

Returns:

The full subscription record (status, customer, amount, interval, current period dates).
guidance.eligible - whether cancellation can proceed (false for already-canceled or expired subscriptions).
guidance.options.timing - available timing choices (immediately, at_period_end, custom_date). Fixed-term plans (planIterations > 0) only support immediately.
guidance.options.currentPeriodEnd - the end of the current billing period, useful when choosing at_period_end.
guidance.sideEffects - plain-language consequences of canceling (the Stripe subscription ends and no further invoices generate; whether a cancellation is already scheduled).

Use list_subscriptions first to find a subscription ID, or get_subscription to view the full record without the cancellation guidance overlay.

Example uses:

"I want to cancel this customer's subscription - what should I know first?"
"Can subscription 6812fe6e9f39b6760576f01c still be canceled at the end of the period?"
"What changes if I cancel this subscription now?"

Input Schema

Name	Required	Description	Default
`subscriptionId`	Yes	The ID of the subscription you intend to cancel. This tool returns eligibility, side effects, and a dashboard link — it does NOT perform the cancellation.

Output Schema

Name	Required	Description	Default
`data`	Yes
`guidance`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 27, 2026

changedOutput schema / properties / data / properties / couponSnapshot / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "amountOff": {
-        "name": "The fixed amount to subtract from the total. Cannot be combined with `percentOff` for the same coupon.",
-        "type": [
-          "number",
-          "null"
-        ]
-      },
-      "appliesToSetupFee": {
-        "description": "Whether the coupon discount applies to the setup fee, if any.",
-        "type": [
-          "boolean",
-          "null"
-        ]
-      },
-      "code": {
-        "name": "The coupon code that the customer entered to receive the discount. E.g. `BLACKFRIDAY`.",
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "currency": {
-        "name": "The currency code for the coupon. Must match the subscription currency. Required if `amountOff` is set.",
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "deleted": {
-        "name": "Whether the coupon is deleted.",
-        "type": [
-          "boolean",
-          "null"
-        ]
-      },
-      "duration": {
-        "anyOf": [
-          {
-            "enum": [
-              "once",
-              "repeating",
-              "forever"
-            ],
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "name": "The duration of the coupon discount. `once` means the discount applies to the first invoice only. `repeating` means the discount applies for a fixed number of billing periods, as specified by `durationInMonths`. `forever` means the discount applies to all invoices until the subscription is canceled."
-      },
-      "durationInMonths": {
-        "name": "If `duration` is `repeating`, the number of billing periods that the discount applies for.",
-        "type": [
-          "number",
-          "null"
-        ]
-      },
-      "label": {
-        "name": "Label for the coupon, such as \"20% off\" or \"$10 off\". This is the label displayed in the dashboard. Not seen by customers.",
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "maxRedemptions": {
-        "name": "The maximum number of times the coupon can be redeemed. A coupon can be redeemed by the same customer multiple times.",
-        "type": [
-          "number",
-          "null"
-        ]
-      },
-      "pageIds": {
-        "anyOf": [
-          {
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "name": "The list of page IDs to which the coupon applies."
-      },
-      "percentOff": {
-        "name": "The percentage to subtract from the total. Cannot be combined with `amountOff` for the same coupon.",
-        "type": [
-          "number",
-          "null"
-        ]
-      },
-      "redeemBy": {
-        "anyOf": [
-          {
-            "format": "date-time",
-            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$",
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "name": "The date and time when the coupon expires."
-      },
-      "timesRedeemed": {
-        "name": "The number of times the coupon has been redeemed.",
-        "type": [
-          "number",
-          "null"
-        ]
-      }
-    },
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "amountOff": {
+        "name": "The fixed amount to subtract from the total. Cannot be combined with `percentOff` for the same coupon.",
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "appliesToSetupFee": {
+        "description": "Whether the coupon discount applies to the setup fee, if any.",
+        "type": [
+          "boolean",
+          "null"
+        ]
+      },
+      "code": {
+        "name": "The coupon code that the customer entered to receive the discount. E.g. `BLACKFRIDAY`.",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "currency": {
+        "name": "The currency code for the coupon. Must match the subscription currency. Required if `amountOff` is set.",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "deleted": {
+        "name": "Whether the coupon is deleted.",
+        "type": [
+          "boolean",
+          "null"
+        ]
+      },
+      "duration": {
+        "anyOf": [
+          {
+            "enum": [
+              "once",
+              "repeating",
+              "forever"
+            ],
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "name": "The duration of the coupon discount. `once` means the discount applies to the first invoice only. `repeating` means the discount applies for a fixed number of billing periods, as specified by `durationInMonths`. `forever` means the discount applies to all invoices until the subscription is canceled."
+      },
+      "durationInMonths": {
+        "name": "If `duration` is `repeating`, the number of billing periods that the discount applies for.",
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "label": {
+        "name": "Label for the coupon, such as \"20% off\" or \"$10 off\". This is the label displayed in the dashboard. Not seen by customers.",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "maxRedemptions": {
+        "name": "The maximum number of times the coupon can be redeemed. A coupon can be redeemed by the same customer multiple times.",
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "pageIds": {
+        "anyOf": [
+          {
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "deprecated": true,
+        "description": "Deprecated: what a coupon covers is now its `rules`; read them from the coupon (`couponId`). The pages the coupon was limited to when the subscription was bought.",
+        "name": "The list of page IDs to which the coupon applies."
+      },
+      "percentOff": {
+        "name": "The percentage to subtract from the total. Cannot be combined with `amountOff` for the same coupon.",
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "redeemBy": {
+        "anyOf": [
+          {
+            "format": "date-time",
+            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$",
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "name": "The date and time when the coupon expires."
+      },
+      "timesRedeemed": {
+        "name": "The number of times the coupon has been redeemed.",
+        "type": [
+          "number",
+          "null"
+        ]
+      }
+    },
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

Changed2 schema fields changedOct 20, 2026

changedOutput schema / properties / data / properties / amount / description

Previous value: -"Recurring charge amount per billing period, in the smallest currency unit: the recurring price plus any processing fee contribution the customer chose to add to each renewal. It does not reflect coupon discounts; subtract any `couponSnapshot` discount to determine the actual charge."New value: +"Recurring charge amount per billing period, in the smallest currency unit. Includes recurring fees and any processing fee contribution the customer chose to add to each renewal (`processingFeeContribution.renewalAmount`). It does not reflect coupon discounts; subtract any `couponSnapshot` discount to determine the actual charge."

changedOutput schema / properties / data / properties / amountUsd / description

Previous value: -"USD-converted recurring amount for multi-currency accounts. Coupon discounts are applied in the subscription currency, so do not subtract `amountOff` from `amountUsd`."New value: +"`amount` converted to USD for multi-currency accounts, so it also includes recurring fees and the renewal processing fee contribution. Coupon discounts are applied in the subscription currency, so do not subtract `amountOff` from `amountUsd`."

Changed1 schema field changedOct 20, 2026

changedOutput schema / properties / data / properties / amount / description

Previous value: -"Recurring charge amount per billing period, in the smallest currency unit. This is the base recurring price and does not reflect coupon discounts; subtract any `couponSnapshot` discount to determine the actual charge."New value: +"Recurring charge amount per billing period, in the smallest currency unit: the recurring price plus any processing fee contribution the customer chose to add to each renewal. It does not reflect coupon discounts; subtract any `couponSnapshot` discount to determine the actual charge."

Changed2 schema fields changedOct 19, 2026

changedOutput schema / properties / data / properties / fees / anyOf

Previous value: -[
-  {
-    "items": {
-      "additionalProperties": false,
-      "properties": {
-        "amount": {
-          "description": "Fixed fee amount. Cannot be combined with `percentage` for the same fee.",
-          "type": [
-            "number",
-            "null"
-          ]
-        },
-        "name": {
-          "description": "Name or label for the fee. E.g. `processing fee`.",
-          "type": [
-            "string",
-            "null"
-          ]
-        },
-        "percentage": {
-          "description": "Percentage fee amount. Cannot be combined with `amount` for the same fee.",
-          "type": [
-            "number",
-            "null"
-          ]
-        },
-        "stripeProductId": {
-          "type": [
-            "string",
-            "null"
-          ]
-        }
-      },
-      "type": "object"
-    },
-    "type": "array"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "items": {
+      "additionalProperties": false,
+      "properties": {
+        "amount": {
+          "description": "Fee amount billed each period, in the smallest currency unit. For a fee with both a percentage and a fixed amount, the sum of `percentageAmount` and `fixedAmount`.",
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "fixedAmount": {
+          "description": "The fixed part of `amount`, in the smallest currency unit, already multiplied by quantity or tickets when the fee multiplies. Only set on a fee with both a percentage and a fixed amount.",
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "name": {
+          "description": "Name or label for the fee. E.g. `processing fee`.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "percentage": {
+          "description": "Fee percentage, when the fee has one.",
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "percentageAmount": {
+          "description": "The part of `amount` from the percentage, in the smallest currency unit. Only set on a fee with both a percentage and a fixed amount. Can be 0, e.g. when a 100% coupon leaves nothing for the percentage to apply to.",
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "stripeProductId": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      },
+      "type": "object"
+    },
+    "type": "array"
+  },
+  {
+    "type": "null"
+  }
+]

changedOutput schema / properties / data / properties / setupFeeFees / anyOf

Previous value: -[
-  {
-    "items": {
-      "additionalProperties": false,
-      "properties": {
-        "amount": {
-          "description": "Fixed fee amount. Cannot be combined with `percentage` for the same fee.",
-          "type": [
-            "number",
-            "null"
-          ]
-        },
-        "name": {
-          "type": [
-            "string",
-            "null"
-          ]
-        },
-        "percentage": {
-          "description": "Percentage fee amount. Cannot be combined with `amount` for the same fee.",
-          "type": [
-            "number",
-            "null"
-          ]
-        },
-        "stripeInvoiceItemId": {
-          "type": [
-            "string",
-            "null"
-          ]
-        }
-      },
-      "type": "object"
-    },
-    "type": "array"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "items": {
+      "additionalProperties": false,
+      "properties": {
+        "amount": {
+          "description": "Fee amount charged on the setup fee, in the smallest currency unit.",
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "name": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "percentage": {
+          "description": "Fee percentage applied to the setup fee.",
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "stripeInvoiceItemId": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      },
+      "type": "object"
+    },
+    "type": "array"
+  },
+  {
+    "type": "null"
+  }
+]

First observedOct 15, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Fully consistent with readOnlyHint=true and destructiveHint=false, and it adds substantive context annotations cannot express: the actual mutation happens outside the API in the Checkout Page dashboard, the tool returns a side-effects narrative, and fixed-term plans (`planIterations > 0`) only allow `immediately`. That is real behavioral disclosure, not restatement.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the most important fact in bold, then structures returns, alternatives, and examples in scannable blocks. It is somewhat long, and the enumerated return-value list plus three examples overlap with the existing output schema and could be trimmed without losing guidance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter read tool with an output schema, the definition covers everything an agent needs: the surprising non-mutating semantics, eligibility rules, timing option constraints, and where cancellation actually occurs. No gaps remain that would cause a misinvocation or a wrong expectation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only one parameter and schema coverage is 100%, with the schema description already carrying the key caveat about non-cancellation. The description adds essentially nothing about the `subscriptionId` beyond that (format, where to source it is handled by the `list_subscriptions` pointer, which is usage rather than parameter semantics). Baseline 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with an explicit negation of what the name implies ("This tool does not cancel the subscription") and then states precisely what it does: fetch, evaluate eligibility and side effects, return a dashboard URL. It also names the two sibling tools it is not (`get_subscription`, `list_subscriptions`), so an agent can disambiguate without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit routing: use `list_subscriptions` first to obtain an ID, or `get_subscription` if the cancellation guidance overlay is unnecessary. Three concrete example utterances map real user intents onto the tool, leaving little to infer about when this is the right call.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Checkout Page tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?