# Margin Intelligence Data Contract

Companion to **AI Margin Intelligence Agent: Which eCommerce Products Are Actually Profitable?**

**Revenue ≠ profit.** This contract lists **inputs**. It does not compute a FactualMinds client margin. If a cost field is missing, the agent returns `unknown` — it does not invent COGS.

```text
Contribution-ish view (only if all inputs exist) =
  Selling price
  − Discounts
  − Product cost
  − Shipping (merchant-borne)
  − Returns cost (allocated)
  − Advertising (allocated, method named)
  − Marketplace fees (if relevant)
```

If any term is missing, **do not publish a ranking presented as truth**.

## Required fields (per SKU / period)

| Field | Source system | If missing |
| ----- | ------------- | ---------- |
| `sku` | PIM / storefront | Stop |
| `units_sold` | OMS | Stop |
| `net_revenue` | OMS / finance | Stop |
| `product_cost` | ERP / costing | `unknown` — no rank |
| `discount_amount` | OMS / promo | Assume 0 only if promo engine confirms none |
| `shipping_cost_merchant` | 3PL / finance | `unknown` |
| `return_cost_allocated` | RMA + finance | `unknown` or exclude from rank |
| `ad_cost_allocated` | Ads + your attribution rule | `unknown` — name the rule or skip |
| `marketplace_fees` | Channel | 0 if D2C-only and confirmed |

## Agent answers

- “Which products are generating **profitable** growth?” — only with the contract filled
- “Which products grew **revenue**?” — allowed with OMS only; label it revenue, not profit

## Writes

Live price, markdown, and vendor cost edits are **HITL**. This agent is read + recommend.

## Related

- Excess inventory (not margin): [`excess-inventory-action-matrix.md`](excess-inventory-action-matrix.md)
- Pricing governance: [`pricing-recommendation-governance.md`](pricing-recommendation-governance.md)