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 examplerwd_01jcx7m4q9v2k8t5r3n6w0ha1b. Use it to get, approve or decline a reward. It’s also returned in therewardsarray of transactions and of thetransaction.createdwebhook, and by Add reward. - Reward key: the
keyof 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_periodordeclined. - 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:
trueonce 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 nopartner field. Instead:
customerholds the ID of the partner who earned the reward.referred_customerholds 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
/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:- Set the commission review period to Until manually approved under Settings → Commission. New commissions then stay in review until you approve them.
- Find commissions waiting for review with List rewards and
payout_status=in_review, or store the rewardidfrom therewardsarray of the transaction response or thetransaction.createdwebhook. - When your system confirms the sale, call Approve reward. If it falls through, call Decline reward.
