التوثيقالشرائح
Englishتسجيل الدخولابدأ الآن

Segments API

Create, manage, and query customer segments through the Segments API.

Endpoints Overview

MethodEndpointDescription
GET/api/segmentationList all segments
POST/api/segmentationCreate a new segment
GET/api/segmentation/:idGet segment by ID
PUT/api/segmentation/:idUpdate a segment
DELETE/api/segmentation/:idDelete a segment
POST/api/segmentation/previewPreview segment count
GET/api/segmentation/:id/customersGet segment customers
GET/api/segmentation/:id/exportExport 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:

FieldTypeDescription
idstringUnique identifier for the group
logicstring"AND" or "OR"
conditionsarrayArray of condition objects
groupsarrayNested rule groups

Condition Object

FieldTypeDescription
idstringUnique identifier
fieldstringField to evaluate
operatorstringComparison operator
valueanyValue to compare against
value2anySecond 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

ParameterTypeDescription
formatstring"csv" or "xlsx" (default: csv)

Returns a file download with customer data including contact info, order stats, and RFM analytics.

Segmentation GuideCustomers API