Skip to main content
GET
/
customers
Find customers
curl --request GET \
  --url https://sandbox-api.paynext.com/customers \
  --header 'X-API-Version: <x-api-version>'
{
  "object": "customers",
  "url": "/v1/customers",
  "has_more": false,
  "next_page": null,
  "data": [
    {
      "id": "cus_b8d0fe7e-3a7f-4b5f-a68b-d31358b49c3f",
      "email": "alice.johnson@example.com",
      "external_id": "ext_001",
      "full_name": "Alice Johnson",
      "phone": "+1-555-123-4567",
      "address": {
        "city": "San Francisco",
        "country": "US",
        "line1": "123 Market Street",
        "line2": "Suite 400",
        "postal_code": "94105",
        "state": "CA"
      },
      "payment_methods": [
        {
          "type": "CARD",
          "billing_address": {
            "city": "San Francisco",
            "country": "US",
            "line1": "123 Market Street",
            "line2": "Suite 400",
            "postal_code": "94105",
            "state": "CA"
          },
          "details": {
            "bin": "411111",
            "last4": "1111",
            "exp_month": 12,
            "exp_year": 2028,
            "is_network_tokenized": true,
            "number": "4111111111111111",
            "bin_data": {
              "brand": "visa",
              "country": "US",
              "currency_code": "USD",
              "description": "Chase Sapphire Preferred",
              "funding": "credit",
              "issuer": "Chase Bank",
              "type": "consumer"
            }
          }
        },
        {
          "type": "PAYPAL",
          "details": {
            "payer_info": {
              "email": "alice.johnson@example.com",
              "first_name": "Alice",
              "last_name": "Johnson",
              "payer_id": "PAYER12345",
              "tenant": "Tenant"
            },
            "processor_customer_email": "alice.johnson@example.com",
            "processor_customer_id": "cus_pp_1234567890",
            "processor_payment_method_id": "pm_pp_1234567890"
          }
        },
        {
          "type": "VENMO",
          "details": {
            "processor_payment_method_id": "pm_venmo_1234567890"
          }
        },
        {
          "type": "CASHAPP",
          "details": {
            "processor_customer_id": "cus_ca_1234567890",
            "processor_payment_method_id": "pm_ca_1234567890"
          }
        },
        {
          "type": "APPLEPAY",
          "billing_address": {
            "city": "San Francisco",
            "country": "US",
            "line1": "123 Market Street",
            "line2": "Suite 400",
            "postal_code": "94105",
            "state": "CA"
          },
          "details": {
            "token": "ap_token_12345678",
            "token_exp_month": 12,
            "token_exp_year": 2028,
            "token_service_provider": "APPLE"
          }
        },
        {
          "type": "GPAY",
          "billing_address": {
            "city": "San Francisco",
            "country": "US",
            "line1": "123 Market Street",
            "line2": "Suite 400",
            "postal_code": "94105",
            "state": "CA"
          },
          "details": {
            "token": "gp_token_12345678",
            "token_exp_month": 12,
            "token_exp_year": 2028,
            "token_service_provider": "GOOGLE"
          }
        }
      ],
      "subscriptions": [
        {
          "id": "sub_123e4567-e89b-12d3-a456-426614174000",
          "status": "active",
          "current_period_start": "2025-05-26T10:00:00Z",
          "current_period_end": "2025-06-26T10:00:00Z",
          "next_billing_date": "2025-06-26T12:00:00Z",
          "past_due": {
            "attempt_count": 0,
            "max_attempts_count": 7
          },
          "plan": {
            "id": "price_1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
            "name": "Pro Plan",
            "type": "recurring",
            "interval": "months",
            "interval_count": 1,
            "trial_interval": "days",
            "trial_interval_count": 14,
            "price": {
              "amount": 1999,
              "currency": "USD"
            },
            "trial_price": {
              "amount": 0,
              "currency": "USD"
            },
            "tax": {
              "collect_tax": "DEFAULT"
            }
          },
          "metadata": {
            "key": "value"
          },
          "created_at": "2025-05-26T10:00:00Z",
          "updated_at": "2025-05-27T10:00:00Z"
        }
      ],
      "metadata": {
        "tier": "premium"
      },
      "created_at": "2025-05-28T14:00:00Z",
      "updated_at": "2025-05-28T14:05:00Z"
    }
  ]
}

Headers

​
X-API-Version
enum<string>
required

Specifies the version of the API to use

Available options:
2.0.0

Query Parameters

​
query
string
required

The search query string. Uses PayNext's Search Query Language. Supports exact match (:), substring match (~), numeric comparisons (>, >=, <, <=), negation (-), logical operators (AND, OR), and nested field access (dot notation). Field names use dotted paths (for example payment_status, customer.email, payment_method.details.last4); short aliases are not accepted. See the endpoint description for the full list of searchable fields and their types. String values must be quoted. Maximum 10 clauses per query.

​
limit
integer
default:10

A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.

Required range: 1 <= x <= 100
​
page
string

A cursor for pagination across multiple pages of results. Don't include this parameter on the first call. Use the next_page value returned in a previous response to request subsequent results.

Response

A dictionary with a data property that contains an array of up to limit customers. If no customers match the query, the resulting array will be empty.

​
object
enum<string>

String representing the object's type. Value is always customers.

Available options:
customers
Example:

"customers"

​
total_count
integer

The accurate total number of records matching the query (not capped at 10,000). Returned alongside the cursor pagination fields.

Example:

142

​
url
string

The URL for accessing this list.

Example:

"/v1/customers"

​
data
object[]

An array of up to limit customers that match the query. Each entry in the array is a separate customer object. If no customers match the query, the resulting array will be empty.

​
has_more
boolean

Whether or not there are more elements available after this set. If false, this set comprises the end of the list.

Example:

false

​
next_page
string | null

A cursor for use in pagination. If has_more is true, you can pass the value of next_page to a subsequent call to fetch the next page of results.

Example:

null