{/* Metadata lives in ./layout.tsx */}

# Metrics

The same profit numbers the dashboard shows, for any date range. One request, one JSON object, money as decimal strings. {{ className: 'lead' }}

<Warning>
  Not live yet. Wire contract below is the intended v1 surface.
</Warning>

---

## `GET /v1/metrics`

<Row>
 <Col>

**Auth:** any key with `read` (`pk_plp_` or `sk_plp_`).

Query parameters, both optional:

| Param | Meaning |
| --- | --- |
| `from` | `YYYY-MM-DD`, inclusive |
| `to` | `YYYY-MM-DD`, inclusive |

Defaults to the last 30 days ending today (UTC). Maximum range is 366 days; an inverted or malformed range is rejected.

Response fields, all money in the shop currency:

| Field | Meaning |
| --- | --- |
| `revenue` | Order revenue before refunds, at the order date |
| `refunds` | Money returned to customers, at the refund date |
| `net_revenue` | `revenue` minus `refunds` |
| `orders` | Order count (JSON number; it is a count, not money) |
| `cogs` | Product costs, minus restocked-refund credits |
| `gateway_fees` | Payment gateway fees |
| `ad_spend` | Ad spend in the shop currency |
| `net_profit` | `net_revenue` minus `cogs`, `gateway_fees`, and `ad_spend` |
| `aov` | Average order value; `null` when there are no orders |
| `mer` | `ad_spend / revenue`; `null` when revenue is zero |
| `blended_roas` | `revenue / ad_spend`; `null` when spend is zero |

Ad accounts running a different currency than the shop are excluded until currency conversion lands; when that happens the response carries a `currency_note` explaining what was left out.

 </Col>
 <Col sticky>

 <CodeGroup title="Request">

```sh {{ title: 'curl' }}
curl "https://api.plutoprofit.com/v1/metrics?from=2026-06-15&to=2026-07-14" \
  -H "Authorization: Bearer pk_plp_your_key"
```

 </CodeGroup>

```json {{ title: 'Response' }}
{
  "from": "2026-06-15",
  "to": "2026-07-14",
  "currency": "DKK",
  "revenue": "184230.00",
  "refunds": "9120.50",
  "net_revenue": "175109.50",
  "orders": 412,
  "cogs": "61480.25",
  "gateway_fees": "4972.10",
  "ad_spend": "38400.00",
  "net_profit": "70257.15",
  "aov": "447.16",
  "mer": "0.2084",
  "blended_roas": "4.7977"
}
```

 </Col>
</Row>

---

## `GET /v1/metrics/definitions`

<Row>
 <Col>

**Auth:** any key with `read`.

The metric catalog: what every field above means and the formula behind it. Static per API version, so it is safe to cache. Useful for building tooltips or letting an AI agent explain the numbers.

 </Col>
 <Col sticky>

```json {{ title: 'Response' }}
{
  "metrics": [
    {
      "key": "net_profit",
      "label": "Net profit",
      "formula": "net_revenue - cogs - gateway_fees - ad_spend",
      "description": "What is left after product costs, gateway fees, and ad spend."
    }
  ]
}
```

 </Col>
</Row>