# Payouts

Every tracked video carries a `payouts` field: **an estimate of what the creator earned for that video.** This page explains how it's worked out, so you can predict it without running the maths yourself.

The short version:

> **If you set an eCPM, payouts grow with views — up to a ceiling. If you didn't, payouts are simply your budget.**

## The two inputs

Payouts is derived from two fields you set yourself:

| Field | What it means |
|---|---|
| `ecpm` | What you agreed to pay the creator **per 1,000 views**. Example: `2.50` means $2.50 per 1,000 views. |
| `budget` | The **maximum** you'll pay for this video, regardless of how well it performs. |

Set either one on [`POST /v1/videos/track`](./track) when you start tracking, or later with [`PATCH /v1/videos/by-external-id/{external_video_id}`](./by-external-id-patch).

> **Any currency.** These are plain numbers — the API doesn't convert or interpret them. Pick your organization's currency under **Settings → Currency** in the dashboard and enter your `ecpm` and `budget` as amounts in it. Every figure in this page uses `$` purely as a stand-in symbol.

## How it's calculated

```text
payouts = min(views × ecpm ÷ 1000, budget)     ← when you set an eCPM
payouts = budget                                 ← when you didn't
```

That's the whole rule. Two cases, decided by whether you set an `ecpm`.

### Case 1 — you set an `ecpm`

Payouts grows as views come in, but **never passes your budget.**

```text
views × ecpm ÷ 1000   ← what the views are worth
payouts = the smaller of that and your budget
```

**Example.** `ecpm = 2.50`, `budget = 100`, and the video has 10,000 views:

```text
10,000 × 2.50 ÷ 1000  =  $25.00
budget                =  $100.00
payouts               =  $25.00     ← under the cap
```

At 60,000 views it crosses the cap and stops:

```text
60,000 × 2.50 ÷ 1000  =  $150.00
budget                =  $100.00
payouts               =  $100.00    ← capped
```

### Case 2 — you didn't set an `ecpm`

Payouts is just your `budget`, regardless of views.

This is the **flat-budget** arrangement: the creator is paid a fixed fee, however the video performs. Views don't change the number at all.

**Example.** No `ecpm`, `budget = 250`. The video gets 50 views or 5 million — `payouts` stays `250`.

> **Watch out:** if you set `ecpm` to `0`, it counts as "not set" and you get the flat-budget behaviour. Use `null` to clear the field instead — `0` and `null` mean different things here.

### No budget set

With no `budget`, `payouts` is `null`. It doesn't mean "paid nothing" — it means **no payout has been set up for this video.**

## Reading the value

`payouts` comes back as a **number** on every video response — [`GET /v1/videos/stats`](./stats), [`GET /v1/videos/by-id/{id}`](./by-id), and [`GET /v1/videos/by-external-id/{id}`](./by-external-id).

```json
{
  "video_id": "77168374-dd2c-496a-b1ae-3d4944f48ccb",
  "views": 60000,
  "budget": 100,
  "ecpm": 2.5,
  "payouts": 100
}
```

A few things worth knowing:

- **It's an estimate, not an invoice.** It's recalculated from the latest view count each time you call the API, so it moves as views move. It's not a payment record.
- **`0` and `null` mean different things.** `null` = no payout set. `0` = a real, deliberate zero (for example a `budget` of `0`).
- **It's capped by `budget` by design.** A breakout video won't cost more than you agreed to pay.

## The `cpm` field

The same response includes `cpm`, the **effective** cost per 1,000 views actually paid:

```text
cpm = payouts ÷ views × 1000
```

Where `ecpm` is what you *agreed* to pay per 1,000 views, `cpm` is what you *ended up* paying per 1,000 views. When a video is under its budget cap, `cpm` will be **lower** than `ecpm` — you got more views than the agreement assumed, so your effective rate went down.

For the example above: 100 ÷ 60,000 × 1000 = **$1.67 per 1,000 views**, against an agreed `ecpm` of $2.50.

`cpm` is `null` when a video has no views yet.