DocsCustomers
Customers API
Access customer data, order history, and RFM analytics through the Customers API.
Endpoints Overview
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/customers | List all customers (paginated) |
| GET | /api/customers/:id | Get customer by ID |
| GET | /api/customers/:id/orders | Get customer orders |
| GET | /api/customers/:id/analytics | Get customer analytics |
List Customers
Retrieve a paginated list of customers for a store.
Request
GET /api/customers?store_id={storeId}&page=1&limit=25
Authorization: Bearer {token}Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
store_id | string | Yes | Store UUID |
page | number | No | Page number (default: 1) |
limit | number | No | Items per page (default: 25, max: 100) |
search | string | No | Search by name, email, or mobile |
segment | string | No | Filter by RFM segment name |
Response
{
"data": [
{
"id": "uuid",
"salla_id": 123456,
"first_name": "Ahmed",
"last_name": "Mohammed",
"email": "ahmed@example.com",
"mobile": "+966501234567",
"city": "Riyadh",
"country": "SA",
"orders_count": 5,
"orders_amount": 1500.00,
"created_at": "2024-01-15T10:30:00Z",
"analytics": {
"recency_score": 4,
"frequency_score": 3,
"monetary_score": 4,
"segment": "Loyal Customers",
"cltv": 2500.00,
"churn_risk_score": 0.15
}
}
],
"meta": {
"total": 1250,
"page": 1,
"limit": 25,
"total_pages": 50
}
}Get Customer
Retrieve a single customer by ID with full details.
Request
GET /api/customers/{customerId}?store_id={storeId}
Authorization: Bearer {token}Response
{
"id": "uuid",
"salla_id": 123456,
"first_name": "Ahmed",
"last_name": "Mohammed",
"email": "ahmed@example.com",
"mobile": "+966501234567",
"mobile_code": "+966",
"birthday": "1990-05-15",
"gender": "male",
"city": "Riyadh",
"country": "SA",
"lang": "ar",
"orders_count": 5,
"orders_amount": 1500.00,
"orders_average": 300.00,
"total_points": 150,
"wallet_balance": 50.00,
"is_blocked": false,
"is_inactive": false,
"salla_created_at": "2023-06-01T08:00:00Z",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-20T15:45:00Z",
"analytics": {
"recency_score": 4,
"frequency_score": 3,
"monetary_score": 4,
"segment": "Loyal Customers",
"recency_days": 15,
"frequency": 5,
"monetary": 1500.00,
"aov": 300.00,
"cltv": 2500.00,
"churn_risk_score": 0.15,
"first_order_date": "2023-06-15T12:00:00Z",
"last_order_date": "2024-01-05T18:30:00Z"
},
"groups": [
{ "id": 1, "name": "VIP" }
]
}Get Customer Orders
Retrieve order history for a specific customer.
Request
GET /api/customers/{customerId}/orders?store_id={storeId}&page=1&limit=10
Authorization: Bearer {token}Response
{
"data": [
{
"id": "uuid",
"salla_id": 987654,
"reference_id": "ORD-12345",
"status": "completed",
"total": 299.99,
"currency": "SAR",
"items_count": 3,
"payment_method": "credit_card",
"order_date": "2024-01-05T18:30:00Z",
"items": [
{
"product_id": "uuid",
"product_name": "Product Name",
"quantity": 2,
"price": 99.99
}
]
}
],
"meta": {
"total": 5,
"page": 1,
"limit": 10,
"total_pages": 1
}
}Customer Object
Full customer object field reference:
| Field | Type | Description |
|---|---|---|
id | string | Syncaty UUID |
salla_id | number | Salla customer ID |
first_name | string | Customer first name |
last_name | string | Customer last name |
email | string | Email address |
mobile | string | Full phone number |
orders_count | number | Total order count |
orders_amount | number | Total spent amount |
analytics | object | RFM scores and predictions |