List customers

curl --request GET \
  --url https://api.paystack.com/v1/customers \
  --header 'Authorization: Bearer <token>'

{
  "status": true,
  "message": "Customers fetched successfully",
  "code": "ok",
  "data": [
    {
      "id": "cust_01HXYZABC1234567890ABCDEFG",
      "type": "individual",
      "name": "Alice Johnson",
      "email": "alice@example.com",
      "merchant_reference": "ref_01HXYZ4K5ABCDEFGHJKLMNPQRS",
      "country_code": "NG",
      "tier": "tier_0",
      "kyc_status": "not_started",
      "metadata": {
        "source": "checkout"
      },
      "created_at": "2026-04-16T16:14:08.000Z",
      "updated_at": "2026-04-16T16:14:08.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 50,
    "total": 137,
    "has_more": false,
    "request_id": "req_01HXYZ4K5ABCDEFGHJKLMNPQRS",
    "timestamp": "2026-05-14T15:43:55.732Z",
    "version": "1"
  }
}

Customers

List customers

List customers for your merchant. Filter by type and kyc_status to narrow results.

All filters are optional. When no filters are supplied every customer is returned (paginated).

Filter behavior

type — restricts to customers of the given type. One of individual, business.
kyc_status — restricts to customers in the given KYC state. One of not_started, pending, in_progress, approved, rejected, expired.

Pagination

page — 1-indexed page number. Defaults to 1. Must be between 1 and 1,000,000.
per_page — page size. Defaults to 50. Must be between 1 and 200.

The response carries pagination metadata under meta:

"meta": {
  "request_id": "req_...",
  "timestamp": "...",
  "version": "1",
  "page": 1,
  "per_page": 50,
  "total": 21,
  "has_more": false
}

has_more is true when at least one more page is available.

Ordering

Results are sorted by created_at DESC, id DESC (newest first, deterministic on ties).

Example

GET /v1/customers?type=individual&kyc_status=not_started&page=1&per_page=25

GET

customers

List customers

curl --request GET \
  --url https://api.paystack.com/v1/customers \
  --header 'Authorization: Bearer <token>'

{
  "status": true,
  "message": "Customers fetched successfully",
  "code": "ok",
  "data": [
    {
      "id": "cust_01HXYZABC1234567890ABCDEFG",
      "type": "individual",
      "name": "Alice Johnson",
      "email": "alice@example.com",
      "merchant_reference": "ref_01HXYZ4K5ABCDEFGHJKLMNPQRS",
      "country_code": "NG",
      "tier": "tier_0",
      "kyc_status": "not_started",
      "metadata": {
        "source": "checkout"
      },
      "created_at": "2026-04-16T16:14:08.000Z",
      "updated_at": "2026-04-16T16:14:08.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 50,
    "total": 137,
    "has_more": false,
    "request_id": "req_01HXYZ4K5ABCDEFGHJKLMNPQRS",
    "timestamp": "2026-05-14T15:43:55.732Z",
    "version": "1"
  }
}

Authorizations

Authorization

string

header

required

API key issued during merchant onboarding.

Query Parameters

type

string

kyc_status

string

page

string

per_page

string

Response

Customers fetched successfully

status

enum<boolean>

required

Available options:

true

Example:

true

message

string

required

Human-readable summary

Example:

"Customers fetched successfully"

code

enum<string>

required

Available options:

ok

Example:

"ok"

data

object[]

required

Show child attributes