# Marketing Metrics API
> Digital-marketing metrics maths as an API, computed locally and deterministically. The ads endpoint computes campaign KPIs from any two of the spend, impressions, clicks and conversions: the CPM (cost per thousand impressions), the CPC (cost per click), the CTR (click-through rate), the conversion rate and the CPA (cost per acquisition). The roas endpoint computes the return on ad spend, ROAS = revenue ÷ spend, the ROI percentage and the gross profit, and — given a gross margin — the break-even ROAS of 1 ÷ margin. The ltv endpoint computes the customer lifetime value, average order value × purchase frequency × lifespan × gross margin, and, with the marketing spend and number of new customers, the customer acquisition cost, the all-important LTV:CAC ratio and the CAC payback period in months. Everything is computed locally and deterministically, so it is instant and private. Ideal for marketing, advertising, e-commerce and growth app developers, campaign dashboards and reporting tools, and agency calculators. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is marketing-metrics maths; for percentage maths use a percentage API and for currency conversion use a currency API.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/marketing-api/..."
```

## Pricing
- **Free** (Free) — 2,000 calls/Mo, 2 req/s
- **Starter** ($14/Mo) — 30,000 calls/Mo, 6 req/s
- **Pro** ($39/Mo) — 200,000 calls/Mo, 15 req/s
- **Mega** ($119/Mo) — 1,524,000 calls/Mo, 40 req/s

## Endpoints

### Marketing

#### `GET /v1/ads` — Campaign metrics

**Parameters:**
- `spend` (query, optional, string) — Ad spend Example: `1000`
- `impressions` (query, optional, string) — Impressions Example: `100000`
- `clicks` (query, optional, string) — Clicks Example: `2000`
- `conversions` (query, optional, string) — Conversions Example: `100`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/marketing-api/v1/ads?spend=1000&impressions=100000&clicks=2000&conversions=100"
```

**Response:**
```json
{
    "data": {
        "cpa": 10,
        "cpc": 0.5,
        "cpm": 10,
        "note": "CPM = spend/impressions·1000, CPC = spend/clicks, CTR = clicks/impressions, conversion = conversions/clicks, CPA = spend/conversions.",
        "inputs": {
            "spend": 1000,
            "clicks": 2000,
            "conversions": 100,
            "impressions": 100000
        },
        "ctr_percent": 2,
        "conversion_rate_percent": 5
    },
    "meta": {
        "timestamp": "2026-06-04T18:38:15.311Z",
        "request_id": "5e858240-e06d-4d86-9880-16ff632451b7"
    },
    "status": "ok",
    "message": "Campaign metrics",
    "success": true
}
```

#### `GET /v1/ltv` — LTV & CAC

**Parameters:**
- `average_order_value` (query, required, string) — Average order value Example: `50`
- `purchase_frequency` (query, required, string) — Purchases per year Example: `4`
- `lifespan_years` (query, required, string) — Customer lifespan (years) Example: `3`
- `gross_margin` (query, optional, string) — Gross margin fraction (default 1) Example: `0.6`
- `marketing_spend` (query, optional, string) — Marketing spend for CAC Example: `5000`
- `new_customers` (query, optional, string) — New customers acquired Example: `100`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/marketing-api/v1/ltv?average_order_value=50&purchase_frequency=4&lifespan_years=3&gross_margin=0.6&marketing_spend=5000&new_customers=100"
```

**Response:**
```json
{
    "data": {
        "cac": 50,
        "note": "LTV = AOV × frequency × lifespan × margin. A healthy LTV:CAC ratio is around 3 or higher.",
        "inputs": {
            "gross_margin": 0.6,
            "lifespan_years": 3,
            "purchase_frequency": 4,
            "average_order_value": 50
        },
        "annual_value": 120,
        "ltv_cac_ratio": 7.2,
        "cac_payback_months": 5,
        "customer_lifetime_value": 360
    },
    "meta": {
        "timestamp": "2026-06-04T18:38:15.404Z",
        "request_id": "15b84371-f9ae-4f1d-a475-beeeab3ceee7"
    },
    "status": "ok",
    "message": "LTV & CAC",
    "success": true
}
```

#### `GET /v1/roas` — ROAS / ROI

**Parameters:**
- `revenue` (query, required, string) — Revenue from ads Example: `5000`
- `spend` (query, required, string) — Ad spend Example: `1000`
- `gross_margin` (query, optional, string) — Gross margin fraction (0–1, default 1) Example: `0.5`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/marketing-api/v1/roas?revenue=5000&spend=1000&gross_margin=0.5"
```

**Response:**
```json
{
    "data": {
        "note": "ROAS = revenue/spend. ROI% = (revenue − spend)/spend. With a gross margin, the campaign breaks even at ROAS = 1/margin.",
        "roas": 5,
        "inputs": {
            "spend": 1000,
            "revenue": 5000,
            "gross_margin": 0.5
        },
        "roi_percent": 400,
        "gross_profit": 1500,
        "break_even_roas": 2
    },
    "meta": {
        "timestamp": "2026-06-04T18:38:15.489Z",
        "request_id": "6927e309-d02c-448a-b925-eb8c9f3653d0"
    },
    "status": "ok",
    "message": "ROAS / ROI",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Spec

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/marketing-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "notes": "Money in any currency, rates as percentages. Frequency is purchases per year; gross margin is a fraction (0–1). Marketing estimates, not guarantees.",
        "service": "marketing-api",
        "formulae": {
            "cpm": "spend/impressions × 1000",
            "ctr": "clicks/impressions × 100",
            "ltv": "AOV × frequency × lifespan × margin",
            "roas": "revenue/spend"
        },
        "endpoints": {
            "GET /v1/ads": "Campaign metrics from any two of spend, impressions, clicks and conversions.",
            "GET /v1/ltv": "Customer lifetime value, CAC and the LTV:CAC ratio with payback period.",
            "GET /v1/meta": "This document.",
            "GET /v1/roas": "Return on ad spend, ROI and break-even ROAS."
        },
        "description": "Digital-marketing metrics calculator: ad-campaign KPIs (CPM, CPC, CTR, conversion, CPA), ROAS/ROI, and customer LTV with the LTV:CAC ratio."
    },
    "meta": {
        "timestamp": "2026-06-04T18:38:15.569Z",
        "request_id": "7b65bc12-3aa2-4b29-acce-618a78932102"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/marketing-api
OpenAPI spec: https://www.oanor.com/api/marketing-api/openapi.json