list_subscription_payments

Retrieve a paginated list of subscription payment records for your Checkout Page account. Each record represents one per-Stripe-invoice charge against a subscription — a billing cycle payment, renewal, or failed attempt. Subscriptions rarely accumulate more than 24–36 payment records (2–3 years of monthly billing), so limit: 100 typically retrieves the full history for a single subscription in one call.

Pass livemode: false to read test-mode records.

Cross-tool routing:

Per-payment subscription history → this tool (list_subscription_payments)
Parent subscription record (status, plan, trial, coupon) → list_subscriptions
One-time payment charges → list_payments
Event/booking charges → list_bookings

Records do NOT overlap between tools — a transaction only appears in one tool. No risk of double-counting when combining results.

This tool is read-only. You cannot process refunds, cancel subscriptions, update payment methods, or retry failed payments. For these actions, explain what is currently on file. The merchant can manage subscription payments in the Checkout Page dashboard. The customer can update their payment method through the customer portal.

Name	Required	Description
`paid`	No	Filter by whether the invoice was fully collected. `true` = invoice paid in full, `false` = unpaid (use for "show me unpaid invoices"). Convenience field — an invoice can be `paid: true` even after a failed attempt followed by a successful retry.
`limit`	No	Number of records per page (integer, max 100, default 10).
`pageId`	No	Filter subscription payments by page ID.
`livemode`	No	Set to false to read test-mode records (created while a page was in test mode). Defaults to live records.
`refunded`	No	Filter by whether the payment was refunded. Combine with `createdAfter` to scope to a time window (e.g. "show me refunded subscription payments this month").
`customerId`	No	Filter subscription payments by customer ID.
`createdAfter`	No	Filter by lower bound of `createdAt`. Use a UTC ISO 8601 timestamp with the `Z` suffix (e.g. `2026-03-01T00:00:00Z`). Never use local timezone offsets — dates are stored and compared in UTC.
`billingReason`	No	Filter by reason the invoice was generated. Valid values: manual, subscription_create, subscription_cycle, subscription_threshold, subscription_update, upcoming. `subscription_create`: first payment when the subscription is created and activated; the customer's initial charge. `subscription_cycle`: standard renewal at the end of a billing period. `subscription_update`: charge from a plan change or proration; can explain an unexpected charge after switching plans. `subscription_threshold`: metered billing usage threshold trigger. `manual`: manually triggered by the merchant. `upcoming`: preview of an upcoming invoice; not yet charged.
`createdBefore`	No	Filter by upper bound of `createdAt`. Use a UTC ISO 8601 timestamp with the `Z` suffix (e.g. `2026-03-31T23:59:59Z`). Never use local timezone offsets — dates are stored and compared in UTC.
`ending_before`	No	Cursor-based pagination. Pass a record `id` to return results before it. Cannot be used with `starting_after`.
`paymentStatus`	No	Filter by status of the underlying Stripe charge or payment intent. Valid values: succeeded, pending, failed, incomplete. Use `failed` to find failed attempts (e.g. "show me failed subscription payments"). Note: a record can have `paymentStatus: 'failed'` while the invoice is still `open` — if a later retry succeeded, both `paymentStatus` and `paid` reflect success. For overall invoice lifecycle use the `invoiceStatus` field on the response; for a simple "was this paid?" check use `paid`.
`starting_after`	No	Cursor-based pagination. Pass a record `id` to return results after it. Cannot be used with `ending_before`.
`subscriptionId`	No	Filter by parent subscription ID. Use to retrieve the full per-cycle payment history for one subscription (e.g. "show me payments for subscription X" or "when was subscription X last charged?"). Results are newest-first by default, so the first record is the most recent payment.

Name

Required

Description

Default

paid

Filter by whether the invoice was fully collected. `true` = invoice paid in full, `false` = unpaid (use for "show me unpaid invoices"). Convenience field — an invoice can be `paid: true` even after a failed attempt followed by a successful retry.

limit

Number of records per page (integer, max 100, default 10).

pageId

Filter subscription payments by page ID.

livemode

Set to false to read test-mode records (created while a page was in test mode). Defaults to live records.

refunded

Filter by whether the payment was refunded. Combine with `createdAfter` to scope to a time window (e.g. "show me refunded subscription payments this month").

customerId

Filter subscription payments by customer ID.

createdAfter

Filter by lower bound of `createdAt`. Use a UTC ISO 8601 timestamp with the `Z` suffix (e.g. `2026-03-01T00:00:00Z`). Never use local timezone offsets — dates are stored and compared in UTC.

billingReason

Filter by reason the invoice was generated. Valid values: manual, subscription_create, subscription_cycle, subscription_threshold, subscription_update, upcoming. `subscription_create`: first payment when the subscription is created and activated; the customer's initial charge. `subscription_cycle`: standard renewal at the end of a billing period. `subscription_update`: charge from a plan change or proration; can explain an unexpected charge after switching plans. `subscription_threshold`: metered billing usage threshold trigger. `manual`: manually triggered by the merchant. `upcoming`: preview of an upcoming invoice; not yet charged.

createdBefore

Filter by upper bound of `createdAt`. Use a UTC ISO 8601 timestamp with the `Z` suffix (e.g. `2026-03-31T23:59:59Z`). Never use local timezone offsets — dates are stored and compared in UTC.

ending_before

Cursor-based pagination. Pass a record `id` to return results before it. Cannot be used with `starting_after`.

paymentStatus

Filter by status of the underlying Stripe charge or payment intent. Valid values: succeeded, pending, failed, incomplete. Use `failed` to find failed attempts (e.g. "show me failed subscription payments"). Note: a record can have `paymentStatus: 'failed'` while the invoice is still `open` — if a later retry succeeded, both `paymentStatus` and `paid` reflect success. For overall invoice lifecycle use the `invoiceStatus` field on the response; for a simple "was this paid?" check use `paid`.

starting_after

Cursor-based pagination. Pass a record `id` to return results after it. Cannot be used with `ending_before`.

subscriptionId

Filter by parent subscription ID. Use to retrieve the full per-cycle payment history for one subscription (e.g. "show me payments for subscription X" or "when was subscription X last charged?"). Results are newest-first by default, so the first record is the most recent payment.

Name	Required	Description
`data`	Yes
`total`	Yes	Total number of records matching the query across all pages.
`has_more`	Yes	Whether more records exist beyond the current page.

Name

Required

Description

Default

data

Yes

total

Yes

Total number of records matching the query across all pages.

has_more

Yes

Whether more records exist beyond the current page.

Checkout Page

Input Schema

Output Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources