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

Orders API Segments API