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)

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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)

{
  "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 }
  ]
}