Customers API

Access customer analytics and segmentation data.

Get Customer Summary

Returns customer-level profit metrics and statistics.

GET /api/v1/customers/summary

Parameters

Parameter	Type	Required	Description
period	string	No	Time period (default: this_month)

Example Request

curl -H "Authorization: Bearer ned_live_YOUR_KEY" \
  "https://api.meetned.com/api/v1/customers/summary?period=this_month"

Example Response

{
  "data": {
    "summary": {
      "total_customers": 1245,
      "new_customers": 89,
      "returning_customers": 156,
      "average_ltv": 285.50,
      "average_orders_per_customer": 2.3
    },
    "profit_distribution": {
      "profitable_customers": 1120,
      "break_even_customers": 45,
      "unprofitable_customers": 80
    },
    "top_customers": [
      {
        "customer_id": "cust_123",
        "email": "j***@example.com",
        "total_orders": 12,
        "total_revenue": 2450.00,
        "total_profit": 980.00
      }
    ]
  },
  "meta": {
    "period": "this_month",
    "generated_at": "2025-02-04T12:00:00Z"
  }
}

---

Get Customer Segments

Returns customer segmentation analysis (RFM-based).

GET /api/v1/customers/segments

Parameters

Parameter	Type	Required	Description
period	string	No	Time period for analysis (default: last_90_days)

Example Request

curl -H "Authorization: Bearer ned_live_YOUR_KEY" \
  "https://api.meetned.com/api/v1/customers/segments"

Example Response

{
  "data": {
    "segments": [
      {
        "segment": "champions",
        "label": "Champions",
        "description": "Best customers who buy frequently and recently",
        "customer_count": 145,
        "percentage": 11.6,
        "avg_revenue": 520.00,
        "avg_orders": 5.2
      },
      {
        "segment": "loyal",
        "label": "Loyal Customers",
        "description": "Regular buyers with good frequency",
        "customer_count": 280,
        "percentage": 22.5,
        "avg_revenue": 340.00,
        "avg_orders": 3.8
      },
      {
        "segment": "potential_loyalist",
        "label": "Potential Loyalists",
        "description": "Recent customers with potential to become loyal",
        "customer_count": 320,
        "percentage": 25.7,
        "avg_revenue": 185.00,
        "avg_orders": 2.1
      },
      {
        "segment": "at_risk",
        "label": "At Risk",
        "description": "Previously active customers who haven't purchased recently",
        "customer_count": 180,
        "percentage": 14.5,
        "avg_revenue": 290.00,
        "avg_orders": 3.2
      },
      {
        "segment": "hibernating",
        "label": "Hibernating",
        "description": "Inactive customers with low engagement",
        "customer_count": 320,
        "percentage": 25.7,
        "avg_revenue": 120.00,
        "avg_orders": 1.4
      }
    ],
    "total_customers": 1245
  },
  "meta": {
    "period": "last_90_days",
    "generated_at": "2025-02-04T12:00:00Z"
  }
}

Segment Definitions

Customer segments are based on RFM (Recency, Frequency, Monetary) analysis:

Segment	Recency	Frequency	Monetary
Champions	Recent	High	High
Loyal Customers	Recent/Medium	High	Medium-High
Potential Loyalists	Recent	Low-Medium	Low-Medium
At Risk	Not Recent	Medium-High	Medium-High
Hibernating	Not Recent	Low	Low

Using Segments

Segments are useful for:

• Champions: Upsell, cross-sell, loyalty programs
• Loyal: Maintain engagement, referral programs
• Potential Loyalists: Nurture campaigns, early incentives
• At Risk: Win-back campaigns, special offers
• Hibernating: Re-engagement or sunset campaigns