> ## Documentation Index > Fetch the complete documentation index at: https://docs.ionicfi.com/llms.txt > Use this file to discover all available pages before exploring further. # List customers > Returns a paginated list of customers, newest first. Each item includes a lifetime payment summary, the customer's default payment method, and their most recent payment. The `payment_methods` and `recent_payments` arrays are not returned for list items; use the retrieve endpoint to fetch those. Supports offset pagination (`limit` + `offset`) and cursor pagination (`starting_after`). When `has_more` is true, the response includes `next_cursor` — the last returned customer's id; pass it as `starting_after` to fetch the next page. The two forms cannot be combined in one request. ## OpenAPI ````yaml /openapi/customers.yaml get /customers openapi: 3.0.3 info: title: Ionic Customers API version: '2026-05-01' description: | Customer profiles — the anchor for payment methods, invoices, and subscriptions. A customer (`cus_…`) represents a single payer stored under your merchant account. It holds contact information (email, name, phone), optional billing and shipping addresses, and a link to a default payment method. Invoices and subscriptions reference customers by id; payment methods are attached to customers and become available for off-session charges. All timestamps are Unix epoch seconds. Identifiers are opaque, prefixed strings. Authentication uses a merchant secret key (`sk_…`) as a bearer token. Read endpoints require the `customers:read` permission; write endpoints require `customers:write`. The mode of the key (test or live) scopes which customers it can see and mutate. Customers support soft-delete: a deleted customer has `deleted: true` and cannot be modified until restored. Write endpoints that target a deleted customer return `422`. To undo a deletion, call the restore endpoint. Errors are returned as `{ "error": { "code": "...", "message": "..." } }`. servers: - url: '{baseUrl}/v1' variables: baseUrl: default: https://api.ionicfi.com description: API base URL for your environment. security: - secretKey: [] tags: - name: Customers description: Create, retrieve, update, and manage customer profiles. paths: /customers: get: tags: - Customers summary: List customers description: | Returns a paginated list of customers, newest first. Each item includes a lifetime payment summary, the customer's default payment method, and their most recent payment. The `payment_methods` and `recent_payments` arrays are not returned for list items; use the retrieve endpoint to fetch those. Supports offset pagination (`limit` + `offset`) and cursor pagination (`starting_after`). When `has_more` is true, the response includes `next_cursor` — the last returned customer's id; pass it as `starting_after` to fetch the next page. The two forms cannot be combined in one request. operationId: customers_list parameters: - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Offset' - name: search in: query description: Filter customers by email or name prefix. schema: type: string - name: created_gte in: query description: Return customers created at or after this time (RFC 3339). schema: type: string - name: created_lte in: query description: Return customers created at or before this time (RFC 3339). schema: type: string - name: starting_after in: query description: >- Cursor: a customer id (typically the previous response's `next_cursor`). Returns results strictly after it, newest first. Cannot be combined with `offset`. schema: type: string - name: include_deleted in: query description: When true, soft-deleted customers are included in results. schema: type: boolean default: false responses: '200': description: A paginated list of customers, newest first. content: application/json: schema: $ref: '#/components/schemas/CustomerList' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' security: - secretKey: - customers:read components: parameters: Limit: name: limit in: query description: Page size (default 20, max 100). schema: type: integer minimum: 1 maximum: 100 default: 20 Offset: name: offset in: query description: Number of records to skip. schema: type: integer minimum: 0 default: 0 schemas: CustomerList: type: object required: - data - has_more properties: data: type: array items: $ref: '#/components/schemas/CustomerDashboard' has_more: type: boolean description: True when more records exist beyond this page. next_cursor: type: string description: >- Present when `has_more` is true: the last returned customer's id. Pass it as `starting_after` on the next request. CustomerDashboard: description: | A customer enriched with payment summary data. The list endpoint returns `summary`, `default_payment_method`, and `last_payment` for each item. The retrieve endpoint additionally returns the full `payment_methods` and `recent_payments` arrays. allOf: - $ref: '#/components/schemas/Customer' - type: object properties: summary: allOf: - $ref: '#/components/schemas/CustomerSummary' description: Lifetime payment statistics for this customer. default_payment_method: allOf: - $ref: '#/components/schemas/PaymentMethodSummary' description: The customer's default payment method; absent when none is set. last_payment: allOf: - $ref: '#/components/schemas/PaymentSummary' description: The customer's most recent payment; absent when there are none. payment_methods: type: array items: $ref: '#/components/schemas/PaymentMethodSummary' description: >- All payment methods on file. Only returned by the retrieve endpoint. recent_payments: type: array items: $ref: '#/components/schemas/PaymentSummary' description: Recent payments. Only returned by the retrieve endpoint. Error: type: object properties: error: type: object properties: code: type: string description: A stable, machine-readable error code. message: type: string Customer: type: object required: - billing_address - created_at - creation_source - deleted - email - first_name - id - last_name - livemode - merchant_id - metadata - object - payment_settings - phone - shipping - updated_at properties: id: type: string description: Unique customer identifier (`cus_…`). object: type: string enum: - customer merchant_id: type: string livemode: type: boolean description: >- Whether this customer was created with a live (`true`) or test (`false`) key. email: type: string first_name: type: string description: Empty string when not set. last_name: type: string description: Empty string when not set. phone: type: string description: Empty string when not set. billing_address: allOf: - $ref: '#/components/schemas/Address' nullable: true description: Billing address; null when not set. shipping: allOf: - $ref: '#/components/schemas/ShippingDetails' nullable: true description: Shipping details; null when not set. creation_source: type: string enum: - api - checkout - import - dashboard - platform description: How the customer was created (for example `api`). payment_settings: $ref: '#/components/schemas/PaymentSettings' metadata: type: object additionalProperties: type: string deleted: type: boolean description: True when the customer has been soft-deleted. created_at: type: integer description: Unix epoch seconds. updated_at: type: integer CustomerSummary: type: object description: Lifetime payment statistics computed for a customer. properties: payment_count: type: integer description: Total number of payment intents (all statuses). succeeded_payment_count: type: integer failed_payment_count: type: integer refunded_payment_count: type: integer payment_methods_count: type: integer description: Total payment methods on file. active_payment_methods_count: type: integer first_paid_at: type: integer description: >- Unix epoch seconds of the customer's first successful payment; absent when there are none. last_paid_at: type: integer description: >- Unix epoch seconds of the customer's most recent successful payment; absent when there are none. net_spend_by_currency: type: object additionalProperties: type: integer description: >- Net spend (succeeded minus refunded) in minor units, keyed by ISO currency code. gross_spend_by_currency: type: object additionalProperties: type: integer description: >- Total of all successful payment amounts in minor units, keyed by ISO currency code. refunded_by_currency: type: object additionalProperties: type: integer description: Total refunded amount in minor units, keyed by ISO currency code. largest_payment_by_currency: type: object additionalProperties: type: integer description: Largest single payment in minor units, keyed by ISO currency code. PaymentMethodSummary: type: object description: A condensed view of a payment method attached to this customer. properties: id: type: string description: Payment method id (`pm_…`). type: type: string description: Payment method type (for example `card`). usage: type: string description: >- Usage classification (for example `reusable`); absent when not known. status: type: string description: Current status (for example `active`); absent when not known. brand: type: string description: >- Card brand (for example `visa`, `mastercard`); absent for non-card methods. last4: type: string description: Last four digits of the card number; absent for non-card methods. exp_month: type: integer description: Card expiration month (1–12); absent for non-card methods. exp_year: type: integer description: Card expiration year (four digits); absent for non-card methods. bin: type: string description: Bank Identification Number; absent when not available. funding_type: type: string description: Funding type (for example `credit`, `debit`); absent when not known. issuer: type: string description: Card issuer name; absent when not known. country: type: string description: Country of issuance (ISO 3166-1 alpha-2); absent when not known. fingerprint: type: string description: >- Stable per-PAN fingerprint for duplicate detection; absent when not available. billing_name: type: string description: Cardholder name; absent when not stored. billing_email: type: string description: Billing email; absent when not stored. billing_phone: type: string description: Billing phone; absent when not stored. billing_address: allOf: - $ref: '#/components/schemas/PaymentMethodBillingAddress' description: Billing address on the payment method; absent when not stored. chargeable: type: boolean description: Whether this saved method can be used for a new card-on-file charge. created_at: type: integer description: Unix epoch seconds. updated_at: type: integer PaymentSummary: type: object description: A condensed view of a payment intent recorded for this customer. properties: id: type: string description: Payment intent id (`pi_…`). description: type: string amount: type: integer description: Amount in minor units. currency: type: string status: type: string description: >- Payment intent status (for example `succeeded`, `requires_payment_method`). charge_id: type: string description: >- Associated charge id (`ch_…`); absent when no charge has been created. payment_method_id: type: string description: Associated payment method id (`pm_…`); absent when not known. card_brand: type: string description: Card brand used for the payment; absent for non-card payments. last4: type: string description: Last four digits of the card used; absent for non-card payments. created_at: type: integer description: Unix epoch seconds. Address: type: object required: - city - country - line1 - postal_code - state properties: line1: type: string line2: type: string description: Second address line; absent when not set. city: type: string state: type: string postal_code: type: string country: type: string description: ISO 3166-1 alpha-2 country code. ShippingDetails: type: object required: - address - name - phone properties: name: type: string description: Recipient name. phone: type: string description: Recipient phone number. address: $ref: '#/components/schemas/Address' PaymentSettings: type: object description: Payment configuration stored for the customer. properties: default_payment_method: type: string description: The default payment method id (`pm_…`); absent when none is set. PaymentMethodBillingAddress: type: object properties: line1: type: string line2: type: string description: Second address line; absent when not set. city: type: string state: type: string postal_code: type: string country: type: string responses: BadRequest: description: The request was malformed or failed validation. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INVALID_REQUEST message: invalid request body Unauthorized: description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: The key lacks the required permission, or the merchant is not active. content: application/json: schema: $ref: '#/components/schemas/Error' RateLimited: description: Too many requests. Honour the `Retry-After` header before retrying. content: application/json: schema: $ref: '#/components/schemas/Error' InternalError: description: | The API could not return a successful response. For a mutating request, retrieve the resource before retrying because the operation may have completed. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: secretKey: type: http scheme: bearer description: 'A merchant secret key (`sk_…`) sent as `Authorization: Bearer `.' ````