list_bookings
Retrieve a paginated list of event bookings 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 customer support uses:
"Customer wants to know if they're registered - email is X" →
searchby email. CheckstatusandorderStatusand present the full picture: a refunded or canceled booking may still appear. Do not useamountPaid > 0as the test for registration - a complimentary booking is registered withamountPaidof 0. Let the merchant interpret whether the registration is still valid."Customer asking how much they paid — order 12345" →
orderIdlookup, reportamountPaidin display currency. IfamountRefunded > 0, also report the refund amount and net."Customer asking about a coupon — order 12345" →
orderIdlookup, checkcouponobject and report the coupon details (code, label, discount amount)."Customer chasing a refund — order 12345" →
orderIdlookup, checkstatusforrefundedorpartial_refund. ReportamountRefunded,lastRefundAt,lastRefundReason, andlastRefundReasonNote. If no refund has been issued, report that and direct to the dashboard."Customer says booking keeps failing" →
searchby email, look forstatus: failed/isAbandoned: truerecords alongside any successful booking.
Example uses:
"Show me recent bookings" → no filters, or narrow with
createdAfter"Show me canceled bookings" → filter by
orderStatus: 'canceled'"Find the booking for order 12345" → filter by
orderId"Show me abandoned event bookings" → filter by
abandonmentStatus: 'abandoned'"Show me complimentary bookings" → filter by
isComplimentary: 'true'"Show me archived bookings" → filter by
archived: 'true'
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.
Two independent status fields:
statusis the payment status (paid, refunded, failed, etc.). Use for financial questions.orderStatusis the booking lifecycle (active, canceled). Archiving is the separatearchivedAtfield. Whether a booking is canceled depends onorderStatus, notstatus.These are independent: a booking can be
status: paid+orderStatus: canceled(paid then canceled, refund may not yet be issued), orstatus: refunded+orderStatus: active(refunded but booking not marked canceled).Questions about "canceled" bookings sometimes mean financially refunded (
status: refunded) rather than lifecycle-canceled (orderStatus: canceled). If the question is ambiguous, check both and explain what you find.isComplimentaryis independent of both: a complimentary booking was issued by the merchant at no charge and is recorded asstatus: paidwithamountandamountPaidof 0, whilecomplimentaryDiscountAmountholds the face value forgone. It is a real, valid registration, not an unpaid or failed one. Filter withisComplimentary: 'true'for comps only,'false'to exclude them.archivedAtis independent of all three: the merchant hid the booking from their default bookings list in the dashboard. Archiving changes nothing else, so an archived booking can still be a valid registration. The list includes archived bookings unless you filter witharchived: 'false'.
Customer name fields. There are four places a name can appear: (1) customerName — the canonical customer name from the customer entity. This is the primary name field. (2) billing.name — from the payment card, may differ from the registration form name. (3) shipping.name — from the shipping details, when provided. (4) fields array — the name entered on the registration form. These may not all match — e.g. a spouse's card used for someone else's registration. For questions about a name on a booking, customerName is the best default; check the other three if there's a discrepancy.
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, registration check, customer search): use
limit: 10or less.
Bookings 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.
Data limitations for common support questions:
Event metadata: Booking records include
eventTitle(human-friendly event name) but do not include the event date, time, location, or description. Event details beyond the name aren't available through this tool — check the event in the Checkout Page dashboard.Refund details:
amountRefunded,lastRefundAt,lastRefundReason, andlastRefundReasonNoteare available on refunded/partial_refund records. Limitation:lastRefundReasonandlastRefundReasonNoteonly reflect the most recent refund action — if multiple partial refunds were issued with different reasons, only the latest is visible. Full refund history (individual refund transactions) requires the Checkout Page dashboard.Historical refund limitation: for records created before
2026-01-22T06:43:28.000Z, some refund metadata may be incomplete. A record can showstatus: refunded,partial_refund, or sometimescanceledwhileamountRefundedremains0or refund detail fields are missing. When reviewing older records, treat the refund status as authoritative but only quote an exact refunded amount if the record explicitly includes it.Cancellation metadata:
canceledByandcanceledReasonare only set when a cancellation is performed from the Checkout Page dashboard. For cancellations from other flows, these fields may be empty or null, so cancellation reason analysis is often unavailable.Email delivery: No tool in the MCP exposes email delivery information — no sent date, no delivery status, no bounce info. A booking can be confirmed (via this tool) but email delivery status cannot be checked. If a customer says they didn't receive a confirmation, verify the email address on file (
customerEmail,billing.email) is correct, confirm the booking exists, and direct to the Checkout Page dashboard where emails can be resent.Address information:
billing.addressandshipping.addressare often empty objects, especially for free or low-cost event registrations.Ticket capacity/inventory: The
capacityandticketGroupCapacityfields on ticket objects are historical snapshots from booking time — they do NOT reflect current remaining availability. If a ticket object'scapacityfield is missing, that ticket type should be treated as unlimited. IfticketGroupCapacityis missing, that ticket group should be treated as unlimited. But an unlimited ticket type can still belong to a ticket group with a limit, and an unlimited ticket group can still sit inside an event with a limit. Total event capacity lives on the event, which is not accessible through any current tool. Do not use booking records alone for inventory calculations. "How many tickets are left?", "Is my event sold out?", and "Can I accept more bookings?" are still unanswerable from this tool alone — you can count tickets sold, but you may not have the governing event or group limit to subtract from. For sold counts, note the inventory logic: canceled bookings release tickets back to inventory, but refunded bookings do not — a refunded ticket still counts against capacity.
Cross-tool routing:
Records do NOT overlap between tools — a transaction only appears in one tool. Payments, bookings, and subscriptions are separate record sets. There is no risk of double-counting when combining results across tools.
Name and event search: search on this tool matches customerName, customerEmail, eventTitle, and orderId. Searching by name (e.g. search: "Nelson") returns all records for customers with that name. Searching by event (e.g. search: "AI Summit") returns all bookings for that event. If you need more customer profile details (company, phone, tax ID), use list_customers or get_customer.
Order lookup: If "look up order 12345" returns 0 results here, try list_payments(orderId: "12345") and list_subscriptions(orderId: "12345") — the order may be a payment or subscription, not a booking.
Full customer history: For "show me everything this customer has bought," query all three transaction tools (list_payments, list_bookings, list_subscriptions) with the same customerId or search email and combine results. Do not present results from one tool alone as a complete history.
Customer profile: For profile data (company, phone, billing email, tax ID), use list_customers or get_customer — booking records only have customerEmail and billing.name.
This tool is read-only. You cannot transfer tickets, change attendee names, cancel bookings, resend confirmations, or issue refunds. For modification requests, show what's currently on file and explain that changes need to be made in the Checkout Page dashboard.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of records per page (integer, max 100, default 10). | |
| pageId | No | Filter by event ID. | |
| search | No | Search by customerEmail, customerName, eventTitle, or orderId. Contains match (e.g. 'jane' matches 'jane@example.com', 'Doe' matches 'Jane Doe', 'Summit' matches 'Future of AI Summit 2026'). | |
| status | No | Filter by payment status. Valid values: created, pending, unpaid, partially_paid, paid, canceled, failed, partial_refund, refunded, draft, draft_expired. | |
| orderId | No | Filter by order ID. | |
| archived | No | Filter by archived bookings. `true` returns only archived bookings, `false` excludes them. Without it the list includes both. | |
| livemode | No | Set to false to read test-mode records (created while a page was in test mode). Defaults to live records. | |
| couponCode | No | Filter by coupon code. | |
| customerId | No | Filter by customer ID. | |
| orderStatus | No | Filter by order status. Valid values: active, canceled. | |
| createdAfter | No | Filter by lower bound of createdAt. | |
| createdBefore | No | Filter by upper bound of createdAt. | |
| 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`. | |
| isComplimentary | No | Filter by complimentary bookings. `true` returns only complimentary bookings, `false` excludes them. | |
| abandonmentStatus | No | Filter by `abandoned` or `recovered` bookings. |
Output 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. |