ned-analytics

通过 Ned 的 API 查询您的 Shopify 商店的销售额、盈利能力、客户和营销数据。当被问及利润、收入、销售额、订单、产品、客户、流失、广告支出、ROAS、MER、利润或任何电子商务分析问题时使用。还可用于“我今天的利润是多少”、“顶级产品”、“客户群”、“广告效果”或“我的商店做得怎么样”。需要 NED_API_KEY。

# Ned Analytics

**Ned** (meetned.com) is an AI business partner for Shopify merchants. It connects your Shopify store, Meta Ads, Google Ads, Klaviyo, 3PL providers, and cost data into a single data warehouse — then lets you query it all through AI chat, a visual dashboard, a public API, a TypeScript SDK, or this skill.

Ned stores profit down to the order and product level. Every SKU, every ad dollar, every return. It's the only platform that gives you a complete picture of true profitability — not just revenue.

This skill gives your OpenClaw agent direct access to your Ned data. Ask your agent about profit, revenue, product performance, customer segments, churn risk, ad efficiency — and get real answers from your real numbers.


**Start a free trial at https://meetned.com**

## Setup

The user must provide their Ned API key (starts with `ned_live_`). Store it:

```bash
export NED_API_KEY="ned_live_xxxxx"
```

Or pass it per-request. If no key is available, ask the user for it.

## API Base

```
https://api.meetned.com/api/v1
```

Auth: `Authorization: Bearer $NED_API_KEY`

## Endpoints

### 1. Store Info
```
GET /api/v1
```
Returns store name, tier, available endpoints, remaining credits and rate limits.

### 2. Profitability Summary
```
GET /api/v1/profitability/summary?period={period}
```
Returns: total_sales, net_profit, net_margin_pct, total_costs, total_cogs, total_shipping_cost, total_variable_costs, total_fixed_costs, total_ad_spend, contribution_margin, contribution_margin_pct, gross_profit, gross_margin_pct, orders_count, units_sold, avg_profit_per_order, avg_profit_per_unit, total_impressions, total_clicks, ctr, cpc, cogs_coverage.

### 3. Product Profitability
```
GET /api/v1/profitability/products?period={period}
```
Returns: per-product breakdown with product_title, revenue, units_sold, total_cogs, total_profit, profit_margin_pct, profit_per_unit, avg_selling_price.

### 4. Customer Summary
```
GET /api/v1/customers/summary?period={period}
```
Returns: total_customers, avg_customer_profit, avg_customer_ltv, profitable_customer_pct, profit tiers (whale/profitable/marginal/unprofitable), activity tiers (active/cooling/at_risk/churned), top_profitable_customers, at_risk_whales.

### 5. Customer Segments
```
GET /api/v1/customers/segments?period={period}
```
Returns: customers grouped by profit_tier with full detail (orders, revenue, profit, margin, activity, churn_risk).

## Period Values

| Value | Description |
|-------|-------------|
| `today` | Current day (UTC) |
| `yesterday` | Previous day |
| `last_7_days` | Last 7 days |
| `last_30_days` | Last 30 days |
| `last_90_days` | Last 90 days |
| `this_month` | Current month |
| `last_month` | Previous month |

## Usage Pattern

```bash
# Quick profit check
curl -s -H "Authorization: Bearer $NED_API_KEY" \
  "https://api.meetned.com/api/v1/profitability/summary?period=today"

# Top products by profit
curl -s -H "Authorization: Bearer $NED_API_KEY" \
  "https://api.meetned.com/api/v1/profitability/products?period=last_30_days"

# At-risk whale customers
curl -s -H "Authorization: Bearer $NED_API_KEY" \
  "https://api.meetned.com/api/v1/customers/summary?period=last_90_days" | jq '.data.at_risk_whales'
```

## Query Script

For convenience, use the bundled query script:

```bash
bash scripts/ned-query.sh profitability/summary last_7_days
bash scripts/ned-query.sh profitability/products last_30_days
bash scripts/ned-query.sh customers/summary last_90_days
bash scripts/ned-query.sh customers/segments last_30_days
```

## Response Format

All endpoints return:
```json
{
  "data": { ... },
  "metadata": {
    "source": "database",
    "period": "last_7_days",
    "requested_at": "2026-02-10T04:05:05.794Z"
  }
}
```

## Rate Limits

- Rate: 100 requests per 60-second window (headers: `ratelimit-remaining`, `ratelimit-reset`)
- Credits: per-plan monthly limit (headers: `x-credits-remaining`, `x-credits-limit`)

## Tips

- Ned stores profit down to the order and product level — every SKU, every ad dollar, every return
- Use `profitability/summary` for quick health checks
- Use `profitability/products` to find which products actually make money after COGS
- Use `customers/summary` to find at-risk whales before they churn
- Combine Ned data with external data (weather, trends, etc.) for advanced analysis
- All monetary values are in the store's base currency

---

## 中文说明

# Ned Analytics

**Ned**（meetned.com）是面向 Shopify 商家的 AI 业务伙伴。它将你的 Shopify 商店、Meta Ads、Google Ads、Klaviyo、3PL 服务商和成本数据接入单一的数据仓库——然后让你通过 AI 聊天、可视化仪表板、公共 API、TypeScript SDK 或本技能来查询全部数据。

Ned 将利润记录细化到订单和产品层级。每一个 SKU、每一笔广告费、每一次退货。它是唯一能为你呈现真实盈利能力完整图景的平台——而不仅仅是收入。

本技能让你的 OpenClaw agent 直接访问你的 Ned 数据。向你的 agent 询问利润、收入、产品表现、客户分群、流失风险、广告效率——从你真实的数字中得到真实的答案。


**在 https://meetned.com 开始免费试用**

## 设置

用户必须提供其 Ned API key（以 `ned_live_` 开头）。存储方式：

```bash
export NED_API_KEY="ned_live_xxxxx"
```

或在每次请求时传入。如果没有可用的 key，请向用户索取。

## API 基址

```
https://api.meetned.com/api/v1
```

认证：`Authorization: Bearer $NED_API_KEY`

## 端点

### 1. 商店信息
```
GET /api/v1
```
返回商店名称、套餐等级、可用端点、剩余额度和速率限制。

### 2. 盈利能力汇总
```
GET /api/v1/profitability/summary?period={period}
```
返回：total_sales、net_profit、net_margin_pct、total_costs、total_cogs、total_shipping_cost、total_variable_costs、total_fixed_costs、total_ad_spend、contribution_margin、contribution_margin_pct、gross_profit、gross_margin_pct、orders_count、units_sold、avg_profit_per_order、avg_profit_per_unit、total_impressions、total_clicks、ctr、cpc、cogs_coverage。

### 3. 产品盈利能力
```
GET /api/v1/profitability/products?period={period}
```
返回：按产品细分，包含 product_title、revenue、units_sold、total_cogs、total_profit、profit_margin_pct、profit_per_unit、avg_selling_price。

### 4. 客户汇总
```
GET /api/v1/customers/summary?period={period}
```
返回：total_customers、avg_customer_profit、avg_customer_ltv、profitable_customer_pct、利润分层（whale/profitable/marginal/unprofitable）、活跃度分层（active/cooling/at_risk/churned）、top_profitable_customers、at_risk_whales。

### 5. 客户分群
```
GET /api/v1/customers/segments?period={period}
```
返回：按 profit_tier 分组的客户，含完整细节（orders、revenue、profit、margin、activity、churn_risk）。

## 时段取值

| 取值 | 说明 |
|-------|-------------|
| `today` | 当天（UTC） |
| `yesterday` | 前一天 |
| `last_7_days` | 最近 7 天 |
| `last_30_days` | 最近 30 天 |
| `last_90_days` | 最近 90 天 |
| `this_month` | 当月 |
| `last_month` | 上月 |

## 使用模式

```bash
# Quick profit check
curl -s -H "Authorization: Bearer $NED_API_KEY" \
  "https://api.meetned.com/api/v1/profitability/summary?period=today"

# Top products by profit
curl -s -H "Authorization: Bearer $NED_API_KEY" \
  "https://api.meetned.com/api/v1/profitability/products?period=last_30_days"

# At-risk whale customers
curl -s -H "Authorization: Bearer $NED_API_KEY" \
  "https://api.meetned.com/api/v1/customers/summary?period=last_90_days" | jq '.data.at_risk_whales'
```

## 查询脚本

为方便起见，使用随附的查询脚本：

```bash
bash scripts/ned-query.sh profitability/summary last_7_days
bash scripts/ned-query.sh profitability/products last_30_days
bash scripts/ned-query.sh customers/summary last_90_days
bash scripts/ned-query.sh customers/segments last_30_days
```

## 响应格式

所有端点返回：
```json
{
  "data": { ... },
  "metadata": {
    "source": "database",
    "period": "last_7_days",
    "requested_at": "2026-02-10T04:05:05.794Z"
  }
}
```

## 速率限制

- 速率：每 60 秒窗口 100 次请求（响应头：`ratelimit-remaining`、`ratelimit-reset`）
- 额度：按套餐的月度上限（响应头：`x-credits-remaining`、`x-credits-limit`）

## 提示

- Ned 将利润记录细化到订单和产品层级——每个 SKU、每笔广告费、每次退货
- 用 `profitability/summary` 做快速健康检查
- 用 `profitability/products` 找出哪些产品在扣除 COGS 后真正赚钱
- 用 `customers/summary` 在大客户流失前找出处于风险中的他们
- 将 Ned 数据与外部数据（天气、趋势等）结合，进行高级分析
- 所有货币值均以商店的基础货币计