> For the complete documentation index, see [llms.txt](https://docs.sparkloop.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sparkloop.app/api-v3/objects-schema/earnings-report-object.md).

# Earnings Report Object

## Earnings Report Object

The earnings report echoes the query it was built from and carries the figures under `data`. The shape of `data` depends on `granularity` and `group_by`.

| Field         | Type            | Description                               |
| ------------- | --------------- | ----------------------------------------- |
| `from`        | String          | Start of the window (`YYYY-MM-DD`).       |
| `to`          | String          | End of the window (`YYYY-MM-DD`).         |
| `channel`     | String \| null  | The channel filter applied, or `null`.    |
| `group_by`    | String \| null  | The grouping applied, or `null`.          |
| `granularity` | String          | `total`, `daily`, `weekly`, or `monthly`. |
| `data`        | Object \| Array | The earnings figures (see below).         |

Every earnings figure is an object of `confirmed`, `estimated_pending`, and `total`, in dollars.

* **`granularity=total`, no `group_by`** — `data` is a single earnings object.
* **`granularity=total` with `group_by`** — `data` is an array, one entry per group, ranked highest-first. Each entry carries the earnings figure plus fields naming the group. The two id-based dimensions have the same shape — the group's own uuid plus the promoted thing as an expandable:
  * `recommendation` — `recommendation_uuid`, plus `recommended_publication`: the promoted newsletter as a **Publication Object** expandable (its UUID by default, the full object with `expand=recommended_publication`).
  * `offer` — `offer_recommendation_uuid`, plus `offer`: the promoted offer as an **Offer Object** expandable (its UUID by default, the full object with `expand=offer`).
  * `utm_campaign` — the raw `utm_campaign` string.
* **`granularity=daily`/`weekly`/`monthly`** — `data` is an array, one entry per time bucket, each with a `date`.

**Example (overall total)**

```json
{
  "from": "2026-06-01",
  "to": "2026-06-30",
  "channel": null,
  "group_by": null,
  "granularity": "total",
  "data": { "confirmed": 240.0, "estimated_pending": 37.5, "total": 277.5 }
}
```

**Example (grouped by recommendation)**

By default a recommendation row identifies the promoted newsletter only by `recommended_publication`'s UUID; the `recommendation_uuid` itself is an opaque `partner_campaign_…` id.

```json
{
  "from": "2026-06-01",
  "to": "2026-06-30",
  "channel": null,
  "group_by": "recommendation",
  "granularity": "total",
  "data": [
    { "recommendation_uuid": "partner_campaign_a6224cd65cf3", "recommended_publication": "pub_9a8b7c6d5e4f", "confirmed": 200.0, "estimated_pending": 30.0, "total": 230.0 }
  ]
}
```

**Example (grouped by recommendation, `expand=recommended_publication`)**

Expanding inlines each promoted newsletter's full **Publication Object** — including its `name` — in place of the UUID.

```json
{
  "recommendation_uuid": "partner_campaign_a6224cd65cf3",
  "recommended_publication": {
    "uuid": "pub_9a8b7c6d5e4f",
    "name": "The Leveraged Coach Newsletter",
    "description": "Build a Better Coaching Business",
    "logo_url": "https://cdn.sparkloop.app/publications/pub_9a8b7c6d5e4f/logo.png",
    "url": "https://theleveragedcoach.com"
  },
  "confirmed": 200.0,
  "estimated_pending": 30.0,
  "total": 230.0
}
```

**Example (grouped by offer)**

An offer row mirrors a recommendation row: the publication's OfferRecommendation uuid (addressable via `/earn/offers/:uuid`) plus the promoted offer as an expandable.

```json
{
  "from": "2026-06-01",
  "to": "2026-06-30",
  "channel": null,
  "group_by": "offer",
  "granularity": "total",
  "data": [
    { "offer_recommendation_uuid": "offer_recommendation_ab12cd34ef56", "offer": "offer_1a2b3c4d5e6f", "confirmed": 120.0, "estimated_pending": 0.0, "total": 120.0 }
  ]
}
```

**Example (grouped by offer, `expand=offer`)**

Expanding inlines each promoted offer's full **Offer Object** in place of the UUID.

```json
{
  "offer_recommendation_uuid": "offer_recommendation_ab12cd34ef56",
  "offer": {
    "uuid": "offer_1a2b3c4d5e6f",
    "headline": "Get 20% off your first order",
    "source": "external-brand",
    "brand": { "name": "Acme Cookware", "logo_url": "https://cdn.sparkloop.app/offers/offer_1a2b3c4d5e6f/logo.png" },
    "max_payout": 500.0
  },
  "confirmed": 120.0,
  "estimated_pending": 0.0,
  "total": 120.0
}
```

**Example (monthly time series)**

```json
{
  "from": "2026-04-01",
  "to": "2026-06-30",
  "channel": "signup_flow",
  "group_by": null,
  "granularity": "monthly",
  "data": [
    { "date": "2026-04-01", "confirmed": 180.0, "estimated_pending": 20.0, "total": 200.0 },
    { "date": "2026-05-01", "confirmed": 210.0, "estimated_pending": 25.0, "total": 235.0 },
    { "date": "2026-06-01", "confirmed": 240.0, "estimated_pending": 37.5, "total": 277.5 }
  ]
}
```