DocsSegments
Segments API
Create, manage, and query customer segments through the Segments API.
Endpoints Overview
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/segmentation | List all segments |
| POST | /api/segmentation | Create a new segment |
| GET | /api/segmentation/:id | Get segment by ID |
| PUT | /api/segmentation/:id | Update a segment |
| DELETE | /api/segmentation/:id | Delete a segment |
| POST | /api/segmentation/preview | Preview segment count |
| GET | /api/segmentation/:id/customers | Get segment customers |
| GET | /api/segmentation/:id/export | Export segment to CSV/Excel |
List Segments
Retrieve all segments for a store.
Request
GET /api/segmentation?store_id={storeId}
Authorization: Bearer {token}Response
{
"segments": [
{
"id": "uuid",
"name": "VIP Customers",
"description": "High-value loyal customers",
"rules": {...},
"cached_count": 250,
"count_cached_at": "2024-01-20T10:00:00Z",
"is_active": true,
"created_at": "2024-01-15T08:00:00Z",
"updated_at": "2024-01-20T10:00:00Z"
}
]
}Create Segment
Create a new customer segment with rules.
Request
POST /api/segmentation?store_id={storeId}
Authorization: Bearer {token}
Content-Type: application/json
{
"name": "VIP Customers",
"description": "High-value loyal customers",
"rules": {
"id": "root",
"logic": "AND",
"conditions": [
{
"id": "c1",
"field": "orders_count",
"operator": "greater_than_or_equals",
"value": 5
}
],
"groups": [
{
"id": "g1",
"logic": "OR",
"conditions": [
{
"id": "c2",
"field": "segment",
"operator": "equals",
"value": "Champions"
},
{
"id": "c3",
"field": "segment",
"operator": "equals",
"value": "Loyal Customers"
}
],
"groups": []
}
]
}
}Response
{
"id": "uuid",
"name": "VIP Customers",
"description": "High-value loyal customers",
"rules": {...},
"cached_count": 0,
"is_active": true,
"created_at": "2024-01-20T15:30:00Z"
}Rules Structure
The rules object defines the segment criteria using nested AND/OR logic:
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier for the group |
logic | string | "AND" or "OR" |
conditions | array | Array of condition objects |
groups | array | Nested rule groups |
Condition Object
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier |
field | string | Field to evaluate |
operator | string | Comparison operator |
value | any | Value to compare against |
value2 | any | Second value (for "between") |
Preview Segment
Preview the customer count for rules without saving the segment.
Request
POST /api/segmentation/preview?store_id={storeId}
Authorization: Bearer {token}
Content-Type: application/json
{
"rules": {
"id": "root",
"logic": "AND",
"conditions": [
{
"id": "c1",
"field": "orders_count",
"operator": "greater_than_or_equals",
"value": 3
}
],
"groups": []
}
}Response
{
"count": 450
}Get Segment Customers
Retrieve customers matching a segment with pagination.
Request
GET /api/segmentation/{segmentId}/customers?store_id={storeId}&page=1&limit=25
Authorization: Bearer {token}Response
{
"data": [
{
"id": "uuid",
"first_name": "Ahmed",
"last_name": "Mohammed",
"email": "ahmed@example.com",
"mobile": "+966501234567",
"orders_count": 8,
"orders_amount": 2500.00,
"analytics": {
"segment": "Champions",
"recency_score": 5,
"frequency_score": 5,
"monetary_score": 4,
"cltv": 4500.00
}
}
],
"meta": {
"total": 250,
"page": 1,
"limit": 25,
"total_pages": 10
}
}Export Segment
Export segment customers to CSV or Excel format.
Request
GET /api/segmentation/{segmentId}/export?store_id={storeId}&format=xlsx
Authorization: Bearer {token}Export Parameters
| Parameter | Type | Description |
|---|---|---|
format | string | "csv" or "xlsx" (default: csv) |
Returns a file download with customer data including contact info, order stats, and RFM analytics.