ned-analytics

### Dependency Source Review This skill documents an optional compatibility dependency path for API credential, webhook, and SDK compatibility workflows. Treat `scripts/_bootstrap_install.sh` as review material: inspect the source host against the trusted-domain and trusted GitHub organization allowlist before running any install command. It is not required for ordinary integration or webhook requests. # 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