Skip to main content
A reward is the commission a partner earns from a referred transaction, or a reward you added manually. Partnero creates rewards automatically from your commission rules. The Rewards API lets you read them and settle the ones that are waiting for review.
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 and of the transaction.created webhook, and by Add reward.
  • Reward key: the key of the transaction or action that created the reward. It isn’t unique: with multi-tier commissions or additional partners, 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. 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, 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

List rewards

Filter by payout status, partner, customer or transaction

Get reward

Get a single reward by its ID

Approve reward

Approve a reward that’s in review

Decline reward

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.

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 and payout_status=in_review, or store the reward id from the rewards array of the transaction response or the transaction.created webhook.
  3. When your system confirms the sale, call Approve reward. If it falls through, call Decline reward.
A transaction can create more than one reward, for example with multi-tier commissions. Approve or decline each of them.