Checkout Page

list_invoices

Read-only

List invoices generated from payments (Charges) on the Checkout Page account. Pass livemode: false to read test-mode records. Each invoice's invoiceUrl links to its hosted PDF, the document customers usually ask for. The link is signed, safe to share with the buyer, and expires 1 hour after the response. Read-only; for full purchase history also query list_payments, list_subscriptions, list_subscription_payments and list_bookings.

Input Schema

Name	Required	Description
`limit`	No	Number of records per page (integer, max 100, default 10).
`search`	No	Case-insensitive search matched against `customerEmail`, `customerName`, `productTitle` and `invoiceNumber`. The query is routed based on input shape: email-like inputs (`jane@example.com`) match `customerEmail` only; identifier-like inputs containing a digit/underscore/hyphen (`2026-000010`) match `invoiceNumber`; multi-word inputs match `customerName` and `productTitle`; any other single bare word falls back to a broad case-insensitive substring match across `customerName`, `customerEmail` and `productTitle`. Best default when the user gives an ambiguous query. A customer may have multiple invoice records — always review all matches, not just the first.
`status`	No	Filter by invoice status. Only one status per call. Valid values: draft, open, paid, uncollectible, refunded, partially_refunded, void. Use "paid" for completed invoices, "open" for outstanding, "refunded" or "partially_refunded" for refund history, "void" for cancelled. Filter by status when counting a category — an unfiltered total includes drafts and voids.
`chargeId`	No	Return invoices for a specific payment (Charge). Use when a customer asks for a copy of their invoice and you already have the originating payment ID. Most charges have one invoice.
`livemode`	No	Set to false to read test-mode records (created while a page was in test mode). Defaults to live records.
`poNumber`	No	Exact match on the invoice PO number. Use for "find the invoice for PO-5678".
`customerId`	No	Return all invoices for a specific customer. Useful when you already have the customer record (e.g. from get_customer or list_customers).
`createdAfter`	No	Inclusive lower bound on invoice createdAt. ISO-8601 UTC datetime with the `Z` suffix (e.g. `2026-01-01T00:00:00Z`). Never use a local timezone offset — invoices are stored and compared in UTC.
`createdBefore`	No	Inclusive upper bound on invoice createdAt. ISO-8601 UTC datetime with the `Z` suffix (e.g. `2026-12-31T23:59:59Z`). Never use a local timezone offset — invoices 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`.
`starting_after`	No	Cursor-based pagination. Pass a record `id` to return results after it. Cannot be used with `ending_before`.

Output Schema

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.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 20, 2026

addedOutput schema / properties / data / items / properties / processingFeeContribution

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": false,
+      "properties": {
+        "amount": {
+          "description": "Contribution in the smallest currency unit.",
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "name": {
+          "description": "Name shown on the invoice, frozen at payment.",
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      },
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "What the customer chose to add to cover the processing fee, added after tax and never taxed. Not one of `fees`."
+}

Changed1 schema field changedOct 19, 2026

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

Previous value: -[
-  {
-    "items": {
-      "additionalProperties": false,
-      "properties": {
-        "amount": {
-          "description": "Fee amount in the smallest currency unit.",
-          "type": [
-            "number",
-            "null"
-          ]
-        },
-        "name": {
-          "description": "Display name for the fee (e.g. \"Shipping\", \"Processing\").",
-          "type": [
-            "string",
-            "null"
-          ]
-        },
-        "percentage": {
-          "description": "Fee as a percentage of the subtotal (0-100), when defined that way.",
-          "type": [
-            "number",
-            "null"
-          ]
-        }
-      },
-      "type": "object"
-    },
-    "type": "array"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "items": {
+      "additionalProperties": false,
+      "properties": {
+        "amount": {
+          "description": "Fee amount 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": "Display name for the fee (e.g. \"Shipping\", \"Processing\").",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "percentage": {
+          "description": "Fee as a percentage of the subtotal (0-100), when defined that way.",
+          "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"
+          ]
+        }
+      },
+      "type": "object"
+    },
+    "type": "array"
+  },
+  {
+    "type": "null"
+  }
+]

First observedOct 15, 2026

TDQS

A4.3/5.0

Behavior4/5

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

Annotations already declare readOnlyHint/destructiveHint=false, but the description adds genuinely useful behavior: the invoiceUrl is a signed hosted-PDF link, safe to share with the buyer, and expires 1 hour after the response. That expiry/shareability detail is exactly the kind of context an agent cannot get from the structured fields, though pagination/limit behavior is left to the schema.

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

Conciseness5/5

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

Four sentences, each carrying distinct information: scope, mode selection, a non-obvious return-value trait, and sibling routing. Purpose is front-loaded and there is no filler or repetition.

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?

With an output schema present, the description need not explain return shapes, and it covers everything else an agent needs: what the tool lists, how to reach test data, what the returned URL means, and which sibling tools round out the picture. No material gap for an 11-parameter read-only list tool.

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?

Schema description coverage is 100%, so all 11 parameters (including the nuanced search routing and status enum) are already documented in the schema. The description restates the livemode:false guidance but adds no parameter semantics beyond what the schema provides, making the baseline 3 appropriate.

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 ('List invoices generated from payments (Charges) on the Checkout Page account'), which pins down both the entity and its origin. It implicitly distinguishes itself from get_invoice (single lookup) and list_payments by naming those siblings as complementary sources for full purchase history.

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

Usage Guidelines4/5

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

Gives explicit routing guidance: pass livemode:false for test records, and query list_payments/list_subscriptions/list_subscription_payments/list_bookings for complete purchase history. It stops short of an explicit when-not rule (e.g. 'use get_invoice when you already have an invoice ID'), so it's clear context rather than a full decision matrix.

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?