> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paylead.fr/llms.txt
> Use this file to discover all available pages before exploring further.
# The Offer catalog
> What an Offer is, how it funds your Program, and how to fetch, filter, and display the catalog through the Paylead API.
An [Offer](/glossary#offer) is the unit of value at the heart of Paylead: a published promotion that defines the conditions a [Consumer](/glossary#consumer) transaction must meet to earn a [Reward](/glossary#reward). It is **what the Consumer actually sees** in the bank app, and what funds your [Program](/glossary#program). This page covers what an Offer is, how it funds your Program, and how to surface the catalog through the [Paylead API](/program/user-journey/quickstart).
## From Campaign to Offer
An Offer is never created in a vacuum. It is the published outcome of a Paylead proposal for a partner merchant that the [Program Manager](/glossary#program-manager) has reviewed and accepted.
Paylead submits a [Campaign](/glossary#campaign): a raw, unpublished commercial proposal carrying its conditions: eligible [Brand](/glossary#brand), duration, [playground](/glossary#playground) range, channel, and targeting rules.
The Program Manager reviews each Campaign in [Shift](/glossary#shift) and either publishes it as an Offer or rejects it. This is where the Program Manager sets how the [playground](/glossary#playground) is split between its own commission and the [Cashback](/glossary#cashback) returned to the Consumer.
Once published, the Offer enters the Program catalog and starts surfacing to eligible Consumers.
A **Campaign** is Paylead's draft proposal; an **Offer** is the curated, published promotion the Consumer sees. Only the Program Manager turns one into the other.
## How an Offer funds the Program
Offers are not a cost: they are the revenue mechanism. When a Consumer transaction matches an active Offer (a [Commissioned Transaction](/glossary#commissioned-transaction)):
* Paylead returns a [**playground**](/glossary#playground) to your Program for that transaction.
* The playground splits (per Offer, as the Program Manager decided at publication) between the **Program Manager's commission** and the **Consumer's [Cashback](/glossary#cashback)**.
This is why curating Offers is a Program Manager lever, not just a catalog task: each Offer's split shapes both Consumer value and Program economics.
## Offer types and states
An Offer's `type` sets how the Consumer earns; its state reflects where the Offer is in its life.
| Type | What it is |
| -------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| **Cashback** | Rewards a share of each qualifying purchase, credited to the Consumer's [pool](/glossary#pool). |
| **Voucher** | A [Voucher](/glossary#voucher) bought up front, below face value or with the discount credited back. |
| **[Loyalty Offer](/glossary#loyalty-offer)** | Rewards only after a defined number of qualifying purchases. |
| State | What it means |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Boosted** | The Offer carries two rates, a baseline and a higher current rate while a boost is active. The contrast drives conversion. |
| **Consumed** | The Offer's per-Consumer Cashback cap has been reached. Keep it visible in a dimmed "already claimed" state rather than hiding it. |
A single Brand can publish multiple Offers to the same Consumer simultaneously, for example a default 3% Offer and a boosted 7% Offer. Aggregate them at the Brand level for the catalog index, and expand to individual Offers on tap.
## What an Offer carries
Every Offer defines the terms a transaction must satisfy to be rewarded:
* **Eligible Brand**: where the purchase must happen.
* **A rate**: the share of the [playground](/glossary#playground) returned to the Consumer.
* **Validity period**: the window during which the Offer is active.
* **Channel**: the transactional channel through which the purchase is rewarded: online, in-store, or both.
* **Specific conditions**: minimum and maximum amounts, capping, targeting.
The full Offer payload groups these fields as follows. Most are read-only; some are type-specific (the rate fields apply to `CASHBACK` Offers, the voucher fields to `VOUCHER` Offers).
**Identity and display**
| Field | Description |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `id` | Unique identifier of the Offer (UUID). |
| `name` | Display name shown to the Consumer. |
| `reference` | Human-readable reference built from the Brand name, creation date, and an increment (for example `MYBRAND-20180220-001`). |
| `description` | Consumer-facing description of the Offer. |
| `picture` | Offer illustration. |
| `highlight_level` | Editorial prominence for contextual displays such as banners or carousels: `HIGHEST`, `HIGH`, or `NORMAL`. |
| `is_favorite` | Whether the Consumer has liked the Offer. |
**Lifecycle and status**
| Field | Description |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| `type` | Offer mechanism: `CASHBACK`, `LBS_CASHBACK`, `VOUCHER`, `UNIQUE_COUPON`, or `GENERIC_COUPON`. |
| `status` | `ACTIVE` (available now), `PUBLISHED` (visible but not yet active, for teasing), or `COMPLETED` (budget spent or all coupons burnt). |
| `publication_date` | When the Offer becomes visible. Can precede the start date for teasing. |
| `start_date` | First date a transaction can qualify (inclusive). |
| `end_date` | Last date a transaction can qualify (inclusive). |
**Reward and rate** (`CASHBACK` Offers)
| Field | Description |
| ----------------------- | -------------------------------------------------------------------------------------------- |
| `cashback_rate` | Current effective rate used to compute the [Cashback](/glossary#cashback) amount (0 to 100). |
| `default_cashback_rate` | Baseline rate, shown alongside `cashback_rate` when a boost is active. |
| `is_boosted` | Whether a boost is currently active (current rate above baseline). |
**Eligibility conditions**
| Field | Description |
| ------------------------------ | --------------------------------------------------------------------------------------- |
| `application_channel` | Where the Offer applies: `ONLINE`, `OFFLINE`, or `BOTH`. |
| `application_url` | URL to reach the Offer when the channel is `ONLINE` or `BOTH`. |
| `min_amount` | Minimum transaction amount required to generate a Reward. |
| `max_amount` | Maximum transaction amount counted: the maximum Reward is `max_amount × cashback_rate`. |
| `max_limit_transaction_amount` | Hard ceiling. A transaction above this amount generates no Reward at all. |
| `source_transaction` | When `true`, only transactions from the Program's default bank qualify. |
| `segments` | The [Segments](/glossary#segment) the Offer is scoped to. |
**Capping and frequency**
| Field | Description |
| ---------------------------- | ------------------------------------------------------------------------------------------- |
| `max_cashbacks_per_consumer` | Maximum number of Rewards a single Consumer can earn on the Offer (`null` means unlimited). |
| `capping_period` | Reset window for the cap: `NO_RESET`, `WEEKLY`, `MONTHLY`, `QUARTERLY`, or `BIANNUAL`. |
| `frequency` | Number of qualifying purchases before a Reward is granted (loyalty Offers). |
| `frequency_counter` | Qualifying purchases the Consumer has made so far toward `frequency`. |
| `is_consumed` | Whether the Consumer has reached the Offer's per-Consumer cap. |
**Legal**
| Field | Description |
| ------------- | -------------------------------------------------------- |
| `legal_terms` | Legal terms attached to the Offer. Mandatory to display. |
**Brand**
| Field | Description |
| ------- | ----------------------------------------------------------------------------------------------------------- |
| `brand` | The [Brand](/glossary#brand) the Offer belongs to: identity, logo, website, and [Stores](/glossary#stores). |
**Voucher-specific** (`VOUCHER` Offers)
| Field | Description |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `min_value` / `max_value` | Range of face values the Consumer can buy. |
| `max_discount_rate` | Best price-to-value ratio across the Offer's vouchers. |
| `value` | Nominal face value of a purchased voucher. |
| `price` | Amount the Consumer paid for the voucher. |
| `codes` | Redeemable codes, each with an optional `activation_code` (PIN), `value`, and `validity_date`. |
| `status` | Voucher state: `RESERVED`, `CONFIRMED`, `READY`, `CANCELLED`, `REFUNDING`, `REFUNDED`, or `REFUND_REJECTED`. |
| `reservation_date` / `reservation_expired_date` | When the voucher was reserved, and when an unconfirmed reservation auto-cancels. |
## Fetch the catalog
The Paylead API exposes three entry points. Pick the one that matches your UI.
Return one entry per Brand the Consumer is eligible for, with aggregated Offer statistics. Use this for the catalog index screen.
**Code examples coming soon.** The Paylead API (v2) is still under construction. Request and response examples for this section will be published once the contract is finalized. In the meantime, contact your Paylead account manager for early-access details.
Each entry returns the Brand identity, the maximum Cashback rate available, and flags such as `is_boosted` and `is_consumed`.
Return every Offer the Consumer is eligible for, sorted by [Offer Smart Ranking](/glossary#offer-smart-ranking).
**Code examples coming soon.** The Paylead API (v2) is still under construction. Request and response examples for this section will be published once the contract is finalized. In the meantime, contact your Paylead account manager for early-access details.
**Common filters**
* `is_consumed=false`: hide Offers the Consumer has already maxed out.
* `is_boosted=true`: return only Offers with an active boost.
Return the full Offer payload: legal terms, application channel, validity window, Cashback rate. Required for the detail screen.
**Code examples coming soon.** The Paylead API (v2) is still under construction. Request and response examples for this section will be published once the contract is finalized. In the meantime, contact your Paylead account manager for early-access details.
A separate endpoint returns every Offer for a specific Brand.
Every Offer display **must** show at minimum: the Brand logo, the application channel (online / in-store / both), the website, the legal terms, and the Cashback rate. Skipping any of these breaks the Paylead contract.
## Personalization: Offer Smart Ranking
Consumers do not see the catalog in a fixed order. [Offer Smart Ranking](/glossary#offer-smart-ranking) personalizes the order of Offers per Consumer, using purchase habits, location, Brand power, and editorial spotlight. It improves catalog relevance and conversion, and requires the Consumer's explicit consent to perform best.
## Display and filter behaviors
Three behaviors shape how you render and filter the catalog. The underlying fields are listed in [What an Offer carries](#what-an-offer-carries).
* **Boosted Offers**: show both `default_cashback_rate` (baseline) and `cashback_rate` (current) so the contrast is visible. Filter with `is_boosted=true` to surface only active boosts.
* **[Loyalty Offers](/glossary#loyalty-offer)**: filter with `loyalty_frequency__isnull=false`, then show progress with `frequency_counter` against `frequency`.
* **Consumed Offers**: flagged `is_consumed=true` once the per-Consumer cap is reached. Don't hide them. Display a dimmed "Already claimed" state, and use `is_consumed=false` only on dedicated "available now" screens.
**Code examples coming soon.** The Paylead API (v2) is still under construction. Request and response examples for this section will be published once the contract is finalized. In the meantime, contact your Paylead account manager for early-access details.
## What's next
Track Rewards generated when Consumers transact on an Offer.
How a Consumer redeems an Offer to earn a Reward.
Surface public Offers to prospects who are not Consumers yet.