Retrieve a paginated list of customers from your Checkout Page account. Customer records are identity and profile data only — no purchase history, no transaction amounts, no subscription status.

Use this tool when you need profile data (company, phone, address, tax ID) or when you need a customer ID for filtering. The two-step pattern (search here → take id → filter transaction tools with customerId) is useful when:

• You need to fan out across transaction tools with one consistent ID

• The customer has multiple email addresses (searching by customerId catches all transactions regardless of email)

• You need profile fields that don't exist on transaction records

The top-level address field is the billing address. The shipping.address field is the shipping address. These are separate and often don't match — a customer may have a billing address but no shipping address, or vice versa. When the question doesn't specify which address, present both clearly labelled (e.g. "Billing address: … / Shipping address: …"). Don't return only one when both exist, and don't return the billing address in response to a shipping address question.

For modification requests, show what's currently stored, then use update_customer with the customer's id once the merchant confirms the change. Data deletion and GDPR/privacy requests require human intervention in the dashboard.

No email delivery data in this tool. No tool in the MCP exposes email delivery information — not on customer records, not on payments, bookings, or subscriptions. You can confirm a purchase exists (via transaction tools) but cannot check email delivery status through this tool. Emails can be resent and email delivery can be verified in the Checkout Page dashboard.

What this tool cannot do:

• No purchase history — customer records contain no transaction data. To see what a customer bought, use their id as customerId on the transaction tools (see cross-tool routing below).

• No aggregation — cannot count customers by country, company, etc. server-side.

• companyName is not searchable — search: "Acme Corp" returns 0 even if a customer has that companyName. To find customers by company, you must paginate and inspect records.

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.

Customers 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:

Customer records do NOT contain purchase data. To build a complete customer picture, combine this tool with the transaction tools:

• list_payments(customerId: "...") — one-time purchases, digital products, physical goods, invoices.

• list_bookings(customerId: "...") — event tickets and registrations.

• list_subscriptions(customerId: "...") — recurring billing, active and canceled subscriptions.

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

If a merchant gives you an order number rather than a customer name or email, do NOT use this tool — try the transaction tools with the orderId filter directly.

Example uses:

• "How many customers do I have?" → call with limit: 1, read total

• "How many new customers this month?" → use createdAfter with the first of the month, limit: 1, read total

• "Find customer jane@example.com" → use search

• "Show me customers named Sarah" → use search (matches name field). Verify the returned records match on name, not just email.

• "What has John Smith ordered?" → search here by name, get id, then query transaction tools with customerId

• "Find my customer Acme Corp" → search won't match companyName; paginate and inspect companyName field

Example customer support uses:

• "Customer asking what information is stored about them — email is jane@example.com" → search to find the customer record. Return all stored profile fields (name, email, phone, addresses, company, tax ID). Note: customer records only contain profile data — for a complete picture of what's stored, also query the transaction tools (list_payments, list_bookings, list_subscriptions) with the customerId to show their purchase history.

• "Customer wants to update their email address" → look up the customer to confirm current email, then call update_customer with their id and the new email once the merchant confirms it. The customer can also change their own email through the customer portal.

• "Customer says they didn't get their confirmation email" → find customer, then check transaction tools for recent purchases. Confirm the purchase exists but explain that email delivery status cannot be checked through this tool. Email delivery can be verified and emails can be resent from the Checkout Page dashboard.

• "Customer wants a full history of what they've bought" → find customer by email/name, then query all transaction tools with customerId to compile full purchase history.

• "Customer requesting deletion of their personal data" → GDPR/privacy request. Show what's stored and explain that data deletion requires human intervention in the Checkout Page dashboard.