Skip to main content
Glama
Sign In

Checkout Page

by com.checkoutpage
OverviewDiscussionsAdmin

list_subscriptions

Read-only

Retrieve a paginated list of subscriptions processed through your Checkout Page account. Pass livemode: false to read test-mode records.

For questions about a customer's full purchase history query the other transaction tools.

Example uses:

  • "Show me recent subscriptions" — use no filters or narrow with createdAfter

  • "Find the subscription for order ORD-9182" — filter by orderId

  • "Show me subscriptions for checkout page X" — filter by pageId

  • "Find subscriptions for jane@example.com" — use search (contains match on email)

  • "Find subscriptions for Jane Smith" — use search: "Jane Smith" (matches customerName)

  • "Show me Galactic Coffee subscriptions" — use search: "Galactic Coffee" (matches productTitle)

  • "How many active subscriptions do I have?" — filter by status: "active", read total. Note: also query status: "past_due" separately — past_due subscriptions are still active but at risk (see status guidance below).

  • "Show me canceled subscriptions" — filter by status: "canceled"

  • "What's my MRR?" — Tell the merchant they can see their MRR in the Checkout Page dashboard.

  • "Show me abandoned subscription checkouts" — use abandonmentStatus: "abandoned"

Money amounts: All monetary amounts are returned in the smallest currency unit (for example, 10661 USD = $106.61, 299 EUR = €2.99, 500 JPY = ¥500). Divide by 100 before displaying amounts to merchants or customers, noting that some currencies such as JPY do not use decimal minor units.

Example customer support uses:

  • Customer asking if their subscription is active — search by email or orderId lookup. Check status: if active, the subscription is healthy. If past_due, the subscription is still active but the payment method is failing — tell the customer to update their payment method through the customer portal. If canceled, report when it was canceled (canceledAt).

  • Customer asking when their next payment is — check currentPeriodEnd for the next billing date, amount for the charge amount, interval and intervalCount for the billing frequency (e.g. interval: "year", intervalCount: 1 = annual billing). Note: if the subscription has a coupon, the actual charge may be less than amount — check couponSnapshot for discount details.

  • Customer saying their payment keeps failing — search by email. Check status for past_due or failed. Check the paymentError field for a specific error message. Note: the troubleshooting depends on context — if this is the first payment to activate the subscription, the customer may need to retry with a different payment method. If it's a recurring payment failing, the customer should update their payment method through the customer portal. If the customer has multiple subscriptions, only some may be failing — distinguish them clearly.

  • Customer wanting to cancel — orderId or email lookup, confirm what's on file (status, billing details, current period end). Subscription cancellation can be done by the merchant in the Checkout Page dashboard or by the customer through the customer portal.

  • Customer claiming they cancelled but are still being charged - check status and canceledAt. If status: "canceled" and canceledAt is set, the subscription was indeed canceled on that date. The currentPeriodEnd may still be in the future (the customer paid for the period). For the individual charges, use list_subscription_payments(subscriptionId: ...).

  • Customer asking for a refund on their subscription — confirm the subscription details (status, amount, how long active). If a refund has already been issued, report lastRefundAt (date), lastRefundReason (reason code), and lastRefundReasonNote (merchant notes). Refunds can be processed by the merchant in the Checkout Page dashboard.

  • Customer asking what plan they're on — check productTitle (human-readable product name, e.g. "Galactic Coffee Subscription"), amount, interval, and intervalCount. If the subscription has a coupon, also report the discount. Present the plan name with amount and billing frequency (e.g. "Galactic Coffee Subscription — $100/month").

  • Customer asking about their trial — check trialStart, trialEnd, and status. If status is trialing or scheduled and trialEnd is in the future, the trial is still active (trialing = free trial; scheduled = setup fee paid, billing starts later). If trialEnd is in the past, the trial has ended (billing should have started at startDate).

  • Customer asking about their total payments - this tool reports the current recurring charge (amount), billing frequency (interval + intervalCount), and how long the subscription has been active (from createdAt). For what was actually charged each cycle, use list_subscription_payments(subscriptionId: ...) and add up the payments.

  • Customer asking about a discount on their subscription — check couponSnapshot for the coupon code, label, and discount amount (amountOff or percentOff). Check couponSnapshot.duration to see how long the discount lasts (forever, repeating with durationInMonths, or once). Setup fee discounts are visible in setupFeeDiscountAmount.

  • Customer saying the name on their subscription is wrong — check customerName, billing.name (from the payment card), shipping.name, and the fields array for customer_name (from the checkout form). These often don't match. The merchant can update the name in the Checkout Page dashboard; the customer can update it through the portal.

Data limitations for common support questions:

  • Charge/payment history: For per-payment history of a subscription (when each charge happened, amount per cycle, refund details), use list_subscription_payments(subscriptionId: ...).

  • Refund details: lastRefundAt, lastRefundReason, lastRefundReasonNote available but only reflect the most recent refund. Per-refund history requires the dashboard.

  • Historical refund limitation: for records created before 2026-04-09T08:47:59.000Z, full subscription refund transaction history may be incomplete. A subscription can still show refund-related fields or a refunded state while older refund history is incomplete or missing. When reviewing older subscription records, only quote exact refund timing or refund details when the record explicitly includes them.

  • Email delivery: No email delivery data available through this tool. Email delivery can be verified and emails can be resent from the Checkout Page dashboard.

  • Access/entitlement: No content access or login status data.

  • Payment method updates: The merchant can update in the dashboard; the customer can update through the portal.

  • Cancellation metadata: canceledAt present on canceled records. canceledBy and reason are optional.

Date filters: Always use UTC timestamps with the Z suffix (e.g. 2026-03-01T00:00:00Z). Never use local timezone offsets — dates are stored and compared in UTC.

Limit and large response handling:

Use the right limit for the task:

  • Single-record lookups (order lookup, customer search): use limit: 10 or less.

Tips for common questions:

  • For count questions, use the status filter and read total. Remember: past_due subscriptions are still active — include them in "active" counts.

  • For single-customer lookups, use search with email or orderId.

  • A customer may have multiple subscription records (e.g. a failed attempt followed by a successful signup). Always check all returned records, not just the first one.

Subscriptions are returned sorted newest-first. Use cursor-based pagination (starting_after / ending_before) to page through large result sets. starting_after and ending_before cannot be used simultaneously. Max limit is 100, default is 10.

Cross-tool routing:

Records do NOT overlap between tools — a transaction only appears in one tool. Payments, bookings, and subscriptions are separate record sets. No risk of double-counting when combining results.

Order lookup: If "look up order 12345" returns 0 results here, try list_payments(orderId: "12345") and list_bookings(orderId: "12345").

Full customer history: For "show me everything this customer has bought," query list_payments and list_bookings tools with the same customerId or search email and combine results.

Customer profile: For profile data (company, phone, billing email, tax ID), use list_customers or get_customer — subscription records have customerName, customerId, customerEmail, billing.name, and shipping.name but not the full profile fields.

This tool is read-only. You cannot cancel subscriptions, process refunds, update payment methods, change billing details, pause/resume billing, or switch plans. For these actions, explain what's currently on file. The merchant can manage subscriptions in the Checkout Page dashboard by navigating to the subscription record. The customer can manage their subscription through the customer portal.

Input Schema

NameRequiredDescriptionDefault
limitNoNumber of records per page (integer, max 100, default 10).
pageIdNoFilter subscriptions by page ID.
searchNoSearch by customerEmail, customerName, productTitle, or orderId. Contains match.
statusNoFilter by subscription lifecycle status. Valid values: draft, draft_expired, incomplete, incomplete_expired, trialing, paused, scheduled, active, past_due, canceled, unpaid, failed, completed.
orderIdNoFilter by exact order ID.
livemodeNoSet to false to read test-mode records (created while a page was in test mode). Defaults to live records.
customerIdNoFilter subscriptions by customer ID.
createdAfterNoFilter by lower bound of createdAt.
createdBeforeNoFilter by upper bound of createdAt.
ending_beforeNoCursor-based pagination. Pass a record `id` to return results before it. Cannot be used with `starting_after`.
starting_afterNoCursor-based pagination. Pass a record `id` to return results after it. Cannot be used with `ending_before`.
abandonmentStatusNoFilter by `abandoned` or `recovered` subscriptions.

Output Schema

NameRequiredDescriptionDefault
dataYes
totalYesTotal number of records matching the query across all pages.
has_moreYesWhether more records exist beyond the current page.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / properties / data / items / 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"
+  }
+]
  2. Changed2 schema fields changed
    • changedOutput schema / properties / data / items / 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 / items / 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`."
  3. Changed1 schema field changed
    • changedOutput schema / properties / data / items / 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."
  4. Changed2 schema fields changed
    • changedOutput schema / properties / data / items / 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 / items / 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"
+  }
+]
  5. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Beyond the annotations (readOnlyHint, destructiveHint false, openWorldHint false), it discloses real behavioral traits: default live vs test-mode records, UTC-only date handling, newest-first ordering, max/default limits, cursor exclusivity, a historical refund-data gap before 2026-04-09, and the absence of email delivery and access/entitlement data. That is unusually rich disclosure for a read-only list tool.

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

Conciseness2/5

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

The opening sentence and cross-tool routing are well front-loaded, but the body is roughly a thousand words of support playbooks that mostly help interpret results rather than invoke the tool. Status semantics (past_due still active) are restated three times, the MRR bullet is filler, and the useful routing facts are buried under repeated examples.

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?

Given 12 optional filters, enum-heavy status handling, and the fact that an output schema exists, the description covers everything an agent needs: selection criteria, pagination contract, permission boundaries, data-availability caveats, and cross-tool fallbacks when a lookup returns zero results.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description exceeds it by explaining semantics the schema does not: past_due being counted as still active, search's contains-match fields, livemode false meaning test-mode, and UTC Z-suffix formatting. A few parameters (customerId, createdBefore, abandonmentStatus) get nothing beyond the schema, and 'recovered' is never defined, which keeps it short of a 5.

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?

States a specific verb and resource ('Retrieve a paginated list of subscriptions') plus the account scope (Checkout Page), and the cross-tool routing section makes clear how this differs from list_payments, list_bookings, and list_customers. An agent can select it correctly without opening the schema.

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?

The description gives explicit when-to-use guidance through worked example queries ('Find the subscription for order ORD-9182' → orderId; 'Jane Smith' → search), names alternatives such as list_subscription_payments for per-charge history, and states what the tool cannot do (cancel, refund, pause). Alternatives and exclusions are both present.

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

All Checkout Page toolsInspect
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