List Customers
Retrieve a paginated list of customers with optional filters.
GET
https://api.zenpayz.com/merchant/api/v1/customersBearer · API key
Request
Headers
| Header | Description |
|---|---|
Authorization REQUIRED | Bearer {api_key} |
X-Signature REQUIRED | HMAC-SHA256 signature |
X-Timestamp REQUIRED | ISO 8601 timestamp |
X-Secret-Salt REQUIRED | Secret salt for HMAC validation |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
page OPTIONAL | integer1 | Page number |
limit OPTIONAL | integer10 | Items per page (max 100) |
search OPTIONAL | string- | Search by email, name, or customer ID (alias for searchTerm) |
searchTerm OPTIONAL | string- | Search by email, name, or customer ID |
status OPTIONAL | string- | Filter by status (active, inactive, blocked, suspended) |
riskLevel OPTIONAL | string- | Filter by risk level (low, medium, high, warning, critical, risky, vip) |
currency OPTIONAL | string- | Filter by transaction currency |
sortBy OPTIONAL | stringcreatedAt | Sort field (createdAt, updatedAt, riskScore, totalAmount, lastTransactionDate) |
sortOrder OPTIONAL | stringDESC | Sort direction (ASC, DESC) |
Response
Success (200 OK)
{
"success": true,
"data": {
"customers": [
{
"customerId": "cust_a1b2c3d4e5f6g7h8",
"email": "john@example.com",
"firstName": "John",
"lastName": "Doe",
"phone": "+1234567890",
"country": "US",
"status": "active",
"riskLevel": "low",
"riskScore": 10,
"totalTransactions": 15,
"totalSpent": 25000,
"lastPurchase": "2024-01-14T15:30:00.000Z",
"createdAt": "2024-01-01T10:00:00.000Z"
}
],
"total": 150,
"page": 1,
"limit": 10,
"hasMore": true
},
"message": "Customers retrieved successfully",
"error": null,
"meta": {
"request_id": "req_xxxxx",
"timestamp": "2024-01-15T10:30:00.000Z",
"processing_time_ms": 85,
"api_version": "v1",
"endpoint": "GET /customers",
"user_type": "merchant"
}
}
Examples
- cURL
- SDK
curl -X GET "https://api.zenpayz.com/merchant/api/v1/customers?status=active&limit=50" \
-H "Authorization: Bearer zp_test_xxxxx" \
-H "X-Timestamp: 2024-01-15T10:30:00.000Z" \
-H "X-Signature: a1b2c3d4e5f6..." \
-H "X-Secret-Salt: your_secret_salt"
const { data } = await zenpays.customers.list({
status: 'active',
limit: 50,
});
console.log(`Found ${data.total} customers`);