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
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| 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
TableJSON Schema
| 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. |