RewardEarned

RewardEarned says that a collaborator earned rewards. It fires once per collaborator per sale, lead, or renewal, listing every reward that sale gave them across programs, and once per collaborator per completed distribution. A distribution that leaves a collaborator nothing raises nothing for them, and a reward held for review is announced by RewardHeldForReview instead.

The event is identified as reward_earned and lives in Siren\Obligations\Core\Events\RewardEarned. ObligationIssued still fires once for each reward. RewardEarned groups them per collaborator after the work that issued them is done.

What does this event carry?

The event carries ids and the obligations as they stand once the sale or distribution is processed. Each obligation holds its amount, from getValue().

• collaboratorId, the collaborator who earned the rewards.
• obligations, a list of Obligation models. getObligationIds() returns their ids.
• conversionIds, the conversion behind each sale’s reward, keyed by obligation id. It’s empty for a distribution. The program comes from the conversion.
• transactionId and opportunityId, the sale’s transaction and opportunity, when it had them.
• distributionId, the distribution that paid the share, for a distribution.
• propertyId, on Siren Cloud, the Property every reward came from. It’s null when they came from none or from several.

use Siren\Obligations\Core\Events\RewardEarned;

public function handle(Event $event): void
{
    $collaboratorId = $event->collaboratorId;

    foreach ($event->obligations as $obligation) {
        $amount = $obligation->getValue();
    }
}

When would you use it?

Use it for anything that should happen once per collaborator for one sale, such as telling them what they earned. Listening to ObligationIssued instead gives you one call per reward, so a sale that pays a collaborator in three programs calls you three times. On Siren Cloud, this event sends the “Reward earned” email once a merchant switches it on.

On a WordPress site connected to Siren Cloud, Siren Cloud does this work, so the site doesn’t raise RewardEarned. The site does raise ObligationIssued for each reward Siren Cloud sends it, so listen for that there.

See the Payment Events overview for how this event fits into the payment pipeline.