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.
