> ## Documentation Index
> Fetch the complete documentation index at: https://docs.partnero.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rewards API overview

> List the commissions your partners have earned, see which are in review, available or paid, and approve or decline commissions in review.

A reward is the commission a partner earns from a referred transaction, or a reward you [added manually](https://docs.partnero.com/api-reference/partners/add-reward.md). Partnero creates rewards automatically from your commission rules. The Rewards API lets you read them and settle the ones that are waiting for review.

> [!NOTE]
>
> The Rewards API is only available for affiliate programs. In newsletter and refer-a-friend programs every `/v1/rewards` endpoint returns `428` with `Rewards are not valid for this program type. They are only available for affiliate programs.`

## Key concepts

* **Reward ID**: the reward's unique identifier (`id`), for example `rwd_01jcx7m4q9v2k8t5r3n6w0ha1b`. Use it to get, approve or decline a reward. It's also returned in the `rewards` array of [transactions](https://docs.partnero.com/api-reference/transactions/get.md) and of the [`transaction.created` webhook](https://docs.partnero.com/guides/webhooks/outgoing-webhooks#event-specific-payloads), and by [Add reward](https://docs.partnero.com/api-reference/partners/add-reward.md).
* **Reward key**: the `key` of the transaction or action that created the reward. It isn't unique: with [multi-tier commissions](https://docs.partnero.com/knowledge-base/commissions-rewards/multi-tier-commission.md) or [additional partners](https://docs.partnero.com/knowledge-base/customers-leads/assigning-additional-partners-to-a-customer.md), one transaction creates several rewards with the same key. Don't use it to look up a reward.
* **Status**: the reward's internal status, for example `ok`, `review_period` or `declined`.
* **Payout status**: where the reward stands for the partner: in review, available to pay out, paid, or not payable. Use it to answer "what do I owe" without decoding every internal status.
* **Paid**: `true` once the reward has been included in a payout marked as paid.

## Payout statuses

Every reward has exactly one payout status. `paid` takes priority over everything else.

| `payout_status` | Meaning |
| - | - |
| `in_review` | Waiting in the [commission review period](https://docs.partnero.com/knowledge-base/commissions-rewards/approve-or-reject-commission-in-review.md). Not payable until approved. |
| `available` | Approved and counted toward the partner's balance, not paid yet. |
| `paid` | Paid out to the partner. |
| `declined` | Declined during review, in the dashboard, the API or the MCP server. Won't be paid. |
| `rejected` | Rejected with a reason, for example from the dashboard. Won't be paid. |
| `fraudulent` | Marked as fraudulent. Won't be paid. |
| `expired` | Outside the commission period or claim period. Won't be paid. |
| `other` | Any other state where the reward isn't payable, for example missing commission settings. |

Rewards of refunded or archived transactions are archived with them and no longer appear in the Rewards API.

## Rewards from sub-partners

With [multi-tier commissions](https://docs.partnero.com/knowledge-base/commissions-rewards/multi-tier-commission.md), a partner also earns a reward when a partner they referred (a sub-partner) makes a sale. These rewards have no `partner` field. Instead:

* `customer` holds the ID of the partner who earned the reward.
* `referred_customer` holds the ID of the sub-partner who made the sale.

## Available endpoints

> [card] [List rewards](https://docs.partnero.com/api-reference/rewards/list.md)
>
> Filter by payout status, partner, customer or transaction

> [card] [Get reward](https://docs.partnero.com/api-reference/rewards/get.md)
>
> Get a single reward by its ID

> [card] [Approve reward](https://docs.partnero.com/api-reference/rewards/approve.md)
>
> Approve a reward that's in review

> [card] [Decline reward](https://docs.partnero.com/api-reference/rewards/decline.md)
>
> Decline a reward that's in review

Rewards can't be created, updated or deleted through `/v1/rewards`. To give a partner a reward, use [Add reward](https://docs.partnero.com/api-reference/partners/add-reward.md).

## Approving commissions from your own system

If commissions should only count once something happens on your side, for example a delivery, a domain transfer or the end of a trial:

1. Set the commission review period to **Until manually approved** under **Settings** → **Commission**. New commissions then stay in review until you approve them.
2. Find commissions waiting for review with [List rewards](https://docs.partnero.com/api-reference/rewards/list.md) and `payout_status=in_review`, or store the reward `id` from the `rewards` array of the [transaction](https://docs.partnero.com/api-reference/transactions/create.md) response or the `transaction.created` webhook.
3. When your system confirms the sale, call [Approve reward](https://docs.partnero.com/api-reference/rewards/approve.md). If it falls through, call [Decline reward](https://docs.partnero.com/api-reference/rewards/decline.md).

A transaction can create more than one reward, for example with multi-tier commissions. Approve or decline each of them.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.