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

# Offer Object

## Offer Object

The brand/owner view of an offer a publication has created.

| Field              | Type           | Description                                                                                         |
| ------------------ | -------------- | --------------------------------------------------------------------------------------------------- |
| `uuid`             | String         | Offer UUID.                                                                                         |
| `headline`         | String         | Offer headline.                                                                                     |
| `description`      | String \| null | Offer description.                                                                                  |
| `terms`            | String \| null | Offer terms.                                                                                        |
| `conversion_type`  | String         | What counts as a conversion (e.g. `lead`).                                                          |
| `category`         | String \| null | Offer category.                                                                                     |
| `image_url`        | String         | Offer image URL.                                                                                    |
| `commissions`      | Array          | Payout tiers (see below). Empty for internal offers.                                                |
| `geo_restrictions` | Object         | Accepted-referral geography: `allow_worldwide_referrals`, `allowed_countries`, `blocked_countries`. |
| `name`             | String         | Offer name.                                                                                         |
| `status`           | String         | Offer status (e.g. `active`).                                                                       |
| `brand_origin`     | String         | `own` or `external`.                                                                                |
| `visibility`       | String         | `public` or `private`.                                                                              |
| `created_at`       | String         | When the offer was created (ISO 8601).                                                              |
| `budget`           | Object         | `monthly_cap`, `used`, `remaining` in dollars.                                                      |
| `stats`            | Object         | Performance. Present only with `expand=stats`.                                                      |

**`commissions[]`**

| Field         | Type           | Description                               |
| ------------- | -------------- | ----------------------------------------- |
| `type`        | String         | `fixed_amount` (dollars) or `percentage`. |
| `amount`      | Number         | The payout figure, interpreted by `type`. |
| `description` | String \| null | Human description of the tier.            |

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

| Field             | Type    | Description                                             |
| ----------------- | ------- | ------------------------------------------------------- |
| `impressions`     | Integer | Times shown.                                            |
| `claims`          | Integer | Primary conversions (claims).                           |
| `claim_rate`      | Number  | Claims / impressions, as a percentage.                  |
| `conversions`     | Integer | Confirmed conversions.                                  |
| `conversion_rate` | Number  | Confirmed conversions / subscriptions, as a percentage. |

**Example (`expand=stats`)**

```json
{
  "uuid": "offer_1a2b3c",
  "headline": "Get 20% off Acme Pro",
  "description": "Premium productivity tools for newsletter teams.",
  "terms": "New customers only.",
  "conversion_type": "lead",
  "category": "Productivity",
  "image_url": "https://assets.sparkloop.app/offers/offer_1a2b3c.png",
  "commissions": [
    { "type": "fixed_amount", "amount": 2.0, "description": "Per verified lead" }
  ],
  "geo_restrictions": {
    "allow_worldwide_referrals": true,
    "allowed_countries": [],
    "blocked_countries": []
  },
  "name": "Acme Pro",
  "status": "active",
  "brand_origin": "own",
  "visibility": "public",
  "created_at": "2025-05-01T00:00:00.000Z",
  "budget": { "monthly_cap": 1000.0, "used": 250.0, "remaining": 750.0 },
  "stats": {
    "impressions": 5000,
    "claims": 400,
    "claim_rate": 8.0,
    "conversions": 120,
    "conversion_rate": 30.0
  }
}
```