---
name: trueprofit
description: >
  TrueProfit profit analytics expert. Use this skill whenever working with TrueProfit MCP tools
  to analyze store performance, query profit data, orders, products, ad costs, or customer metrics.
  Trigger automatically when the user asks about profit, ROAS, COGS, net margin, orders, revenue,
  ad spend, shipping costs, or any e-commerce analytics question involving their TrueProfit store.
  Also use when the user connects a new MCP server at mcp.trueprofit.io.
---

# TrueProfit MCP — Usage Guide

TrueProfit is a profit analytics platform for e-commerce merchants (Shopify, etc.). This skill
teaches you how to use TrueProfit MCP tools effectively to answer business analytics questions.

## Key Business Concepts

### Profit Metrics
- **Revenue**: Gross sales before any deductions
- **Net Revenue**: Revenue after refunds and discounts
- **COGS (Cost of Goods Sold)**: Product cost per unit — must be set manually or imported
- **Gross Profit** = Net Revenue − COGS
- **Net Profit** = Gross Profit − Ad Costs − Shipping − Transaction Fees − Custom Costs − Taxes
- **Net Margin** = Net Profit / Net Revenue × 100%
- **Contribution Margin** = Revenue − Variable Costs (excludes fixed overhead)

### Advertising Metrics
- **Ad Spend**: Total spend across all connected platforms (Facebook, Google, TikTok, etc.)
- **ROAS** = Revenue / Ad Spend (per channel)
- **Blended ROAS** = Total Revenue / Total Ad Spend (all channels combined)
- **MER (Marketing Efficiency Ratio)** = Revenue / Total Marketing Cost

### Key Ratios
- **AOV (Average Order Value)** = Revenue / Number of Orders
- **Refund Rate** = Refunded Amount / Gross Revenue × 100%
- **CAC (Customer Acquisition Cost)** = Total Ad Spend / New Customers
- **LTV (Lifetime Value)** = AOV × Purchase Frequency × Customer Lifespan
- **Break-even ROAS** = 1 / (1 − COGS%) where COGS% = COGS / Revenue

## Workflow Patterns

### Step 1: Always establish shop context

Most tools require a `shop_id`. Start every session with:
```
list_shops → identify the right shop → use shop_id for all subsequent calls
```

Single-shop users: `list_shops` returns one item — use its `shop_id` directly.
Multi-shop / agency users: confirm with the user which shop before proceeding, or loop across all shops.

### Step 2: Use the correct date range format

All dates use `YYYY-MM-DD` format in the shop's local timezone.

| User says | date_from | date_to |
|-----------|-----------|---------|
| "today" | today | today |
| "this month" | first day of current month | yesterday |
| "last month" | first day of previous month | last day of previous month |
| "last 30 days" | yesterday − 29 | yesterday |
| "last 7 days" | yesterday − 6 | yesterday |
| "yesterday" | yesterday | yesterday |
| "Q1 2025" | 2025-01-01 | 2025-03-31 |

Check the shop's timezone via `get_shop_details` if date precision matters.

### Step 3: Pick the right tool

| User question | Tool |
|---------------|------|
| "What's my profit this month?" | `get_profit_summary` |
| "Show daily profit trend / chart" | `get_profit_by_date` |
| "Which products make the most profit?" | `get_profit_by_product` |
| "Show my recent orders" | `list_orders` |
| "Find order #1234 / search orders" | `list_orders` with `search` param |
| "Details on a specific order" | `get_order_insights` |
| "Orders summary / total count" | `get_orders_summary` |
| "How much did I spend on ads?" | `get_ad_costs` |
| "ROAS by UTM / campaign / source" | `get_revenue_by_utm` |
| "What custom costs do I have?" | `get_custom_costs` |
| "Show my products and COGS" | `list_products` |
| "Details on a specific product" | `get_product` |
| "Customer retention / total customers" | `get_customer_overview` |
| "Details on a specific customer" | `get_customer_details` |
| "Shipping cost for specific orders" | `get_shipping_cost` |
| "Which ad platforms are connected?" | `get_connected_platforms` |
| "What shop am I looking at?" | `get_shop_details` |
| "Report a bug / request a feature" | `submit_feedback` |

## Important Tool Parameters

These non-obvious parameters unlock significant functionality:

**`list_orders`**
- `financial_status`: filter by `paid`, `pending`, `refunded`, `partially_refunded`, `authorized`, `partially_paid`, `unpaid`, `voided` (comma-separated for multiple)
- `search`: find orders by name or number (e.g., `"#1234"`)
- `order_by`: sort by `created_at`, `total_price`, or `profit`
- `page` / `page_size`: paginate large result sets (default page_size=20)

**`list_products`**
- `search`: filter by product title
- `page` / `page_size`: paginate large catalogs

**`get_shipping_cost`**
- Requires specific **order IDs** (not a date range) — get them from `list_orders` first
- Max 100 order IDs per request

**`get_customer_details`**
- Requires a Shopify **customer ID** (numeric) — not name or email
- Get customer IDs from order data in `list_orders` or `get_order_insights`

**`submit_feedback`**
- `category`: one of `bug`, `feature_request`, `question`, `complaint`, `praise`, `other`
- `subject`: short summary (max 200 chars)
- `message`: detailed feedback (max 5000 chars)
- `shop_id`: optional, include for shop-specific bugs or requests

## Common Workflows

### "How was my performance last month?"
1. `list_shops` → get `shop_id`
2. `get_profit_summary` with last month's date range
3. `get_ad_costs` for ad spend breakdown by platform
4. Present as: Revenue, Net Profit, Net Margin %, ROAS, AOV — with period-over-period change if available

### "Which products should I focus on?"
1. `get_profit_by_product` for a meaningful date range (e.g., last 30 days)
2. Sort by **net profit** (not revenue) — high-revenue products can have negative profit
3. Flag products with COGS = 0 — profit data is unreliable until COGS is set
4. Recommend: double down on high-margin, investigate high-volume low-margin

### "Find a specific order"
1. `list_orders` with `search="#1234"` (order name/number) and a date range
2. Or filter by `financial_status="refunded"` to find refunded orders
3. Then `get_order_insights` with the order ID for full line-item breakdown

### "Why did my profit drop this week?"
1. `get_profit_by_date` → find which specific day(s) caused the drop
2. `get_ad_costs` → check for ad spend spike or platform attribution issues
3. `list_orders` with `financial_status="refunded"` → look for refund spike
4. `get_connected_platforms` → verify all ad platforms still connected

### "Show shipping costs for my orders"
1. `list_orders` → get order IDs for the date range (up to 100 at a time)
2. Extract the order IDs
3. `get_shipping_cost` with the order ID list

### "Compare my shops" (multi-shop / agency)
1. `list_shops` → get all shop IDs
2. For each shop: `get_profit_summary` with same date range
3. Build comparison: Revenue, Net Profit, Net Margin, ROAS per shop
4. Note: currencies may differ — confirm before converting

### "How many customers do I have?"
- `get_customer_overview` → total customers, new customers (no date range needed — shop-level metric)
- For individual customer history: need their Shopify customer ID from order data

## Presenting Results to Users

When sharing analytics data, lead with the most actionable insight:

- **Profit summary**: Revenue → Net Profit → Net Margin % → ROAS → AOV (in that order)
- **Product analysis**: present as a ranked table with Revenue, Profit, Margin columns
- **Date trends**: describe the trend direction first, then call out notable peaks/drops
- **Ad costs**: show spend by platform + total ROAS, flag platforms with low ROAS
- **COGS gaps**: prominently warn if products have COGS = 0 before showing profit numbers

## Formulas Reference

```
Net Profit = Revenue - COGS - Ad Spend - Shipping - Transaction Fees - Refunds - Custom Costs
ROAS = Ad Revenue / Ad Spend
Blended ROAS = Total Revenue / Total Ad Spend
Net Margin % = (Net Profit / Revenue) × 100
AOV = Revenue / Number of Orders
CAC = Total Ad Spend / New Customers
LTV = AOV × Purchase Frequency × Customer Lifespan
Refund Rate = Refunded Amount / Gross Revenue × 100
Break-even ROAS = 1 / (1 - COGS%) where COGS% = COGS / Revenue
```

## Tips & Gotchas

1. **COGS = 0 means unreliable profit**: If any products lack COGS, net profit is overstated for
   those products. Always warn the user before presenting profit data.

2. **Ad platform reporting lag**: Facebook, Google, and TikTok can have 1–3 day attribution delay.
   For very recent dates, ad costs may appear lower than actual spend.

3. **Currency per shop**: Each shop reports in its own currency. Never mix currencies across shops
   without explicit user confirmation and conversion.

4. **UTM data is incomplete by nature**: `get_revenue_by_utm` only captures orders where UTM
   parameters were tracked. Direct/organic traffic won't appear — always note this caveat.

5. **`get_customer_overview` has no date range**: It returns shop-level lifetime totals, not
   a filtered period. Don't pass date params to this tool.

6. **`get_shipping_cost` needs order IDs, not dates**: First use `list_orders` to get IDs,
   then pass them to `get_shipping_cost` (max 100 per call).

8. **Auth is automatic**: This MCP uses Account-level OAuth. The server automatically exchanges
   it for a Shop token when needed — don't try to manage tokens manually.

9. **Refunds inflate cost ratios**: A refund spike makes ad spend look higher as % of revenue.
   Check `list_orders` with `financial_status="refunded"` to assess refund impact.

## Connected Ad Platforms

Check which platforms are active via `get_connected_platforms`:

| Platform | Notes |
|----------|-------|
| Facebook Ads | Most common, 1-3 day attribution delay |
| Google Ads | Includes Shopping, Search, YouTube |
| TikTok Ads | |
| Snapchat Ads | |
| Pinterest Ads | |

Disconnected platforms = spend tracked as custom costs, or not tracked at all.

## Keeping the Skill Up to Date

TrueProfit MCP is actively developed — new tools and workflows are added regularly. To get the
latest version of this skill, call the `get_skill` tool from the TrueProfit MCP server:

```
get_skill → copy the returned SKILL.md content → overwrite ~/.claude/skills/trueprofit/SKILL.md
```

Do this periodically (e.g., once a month) or whenever you notice a tool behaving differently
than documented here.

## MCP Server Info

- **Server URL**: https://mcp.trueprofit.io/mcp
- **Auth**: OAuth 2.0 — sign in with your TrueProfit Account at app.trueprofit.io
- **Tools**: 20 tools covering profit, orders, products, ads, customers, shipping, feedback
- **Download skill**: https://mcp.trueprofit.io/skill