> 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/recommendation-object.md).

# Recommendation Object

## Recommendation Object

| Field                            | Type             | Description                                                                                                          |
| -------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------- |
| `uuid`                           | String           | Recommendation UUID.                                                                                                 |
| `type`                           | String           | `free` or `paid`.                                                                                                    |
| `status`                         | String           | Recommendation status (e.g. `active`, `awaiting_approval`, `archived`).                                              |
| `name`                           | String           | Display name of the recommended publication.                                                                         |
| `last_30_days_confirmation_rate` | Number           | Referral confirmation rate over the last 30 days.                                                                    |
| `role`                           | String           | *Free only.* `sending` or `receiving`, relative to the publication in the path.                                      |
| `recommended_publication`        | String \| Object | The recommended publication's UUID; the full **Publication Object** with `expand=recommended_publication`.           |
| `recommending_publication`       | String \| Object | *Free only.* The sending publication's UUID; the full **Publication Object** with `expand=recommending_publication`. |
| `commission`                     | Number           | *Paid only.* Commission earned per referral.                                                                         |
| `max_payout`                     | Number \| null   | *Paid only.* Per-cycle payout cap.                                                                                   |
| `partner_program_uuid`           | String \| null   | *Paid only.* The backing partner program.                                                                            |
| `stats`                          | Object           | Date-ranged performance. Present only with `expand=stats`.                                                           |

{% hint style="info" %}
Free recommendations omit `commission`, `max_payout`, and `partner_program_uuid`, and their `stats` contain only the `referrals` block (no `earnings`). They include `role` and `recommending_publication`. Paid recommendations omit `role` and `recommending_publication`.
{% endhint %}

**`stats`** (only with `expand=stats`)

| Field       | Type   | Description                                                        |
| ----------- | ------ | ------------------------------------------------------------------ |
| `referrals` | Object | `confirmed`, `pending`, `total` referral counts.                   |
| `earnings`  | Object | *Paid only.* `confirmed`, `estimated_pending`, `total` in dollars. |

**Example (paid, `expand=recommended_publication,stats`)**

```json
{
  "uuid": "rec_a6224cd65cf3",
  "type": "paid",
  "status": "active",
  "name": "The Morning Brew",
  "last_30_days_confirmation_rate": 62.5,
  "recommended_publication": {
    "uuid": "pub_9ac1f2",
    "name": "The Morning Brew",
    "description": "Business news you'll actually enjoy.",
    "logo_url": "https://assets.sparkloop.app/logos/pub_9ac1f2.png",
    "url": "https://morningbrew.com"
  },
  "commission": 2.0,
  "max_payout": 500.0,
  "partner_program_uuid": "pp_abcdef123",
  "stats": {
    "referrals": { "confirmed": 120, "pending": 30, "total": 150 },
    "earnings": { "confirmed": 240.0, "estimated_pending": 37.5, "total": 277.5 }
  }
}
```

**Example (free, receiving)**

```json
{
  "uuid": "rec_b7135de76dg4",
  "type": "free",
  "status": "active",
  "name": "The Daily Brief",
  "role": "receiving",
  "last_30_days_confirmation_rate": 54.0,
  "recommended_publication": "pub_thisone",
  "recommending_publication": "pub_partner"
}
```