RewardHeldForReview

RewardHeldForReview says that Siren held a collaborator’s rewards from one sale for an admin to review, for example rewards on lines in a currency the program doesn’t pay in. The sale and its rewards are recorded. Each reward waits as a draft with its reason, and a program’s auto-approve setting doesn’t approve it. An admin approves or rejects the reward’s conversion, or the reward, to settle it.

It fires once per collaborator per sale, listing every reward that sale held for them across programs, after the sale’s rewards are issued. A held reward isn’t announced by RewardEarned, since it may never be owed.

The event is identified as reward_held_for_review and lives in Siren\Obligations\Core\Events\RewardHeldForReview.

What does this event carry?

• collaboratorId, the collaborator whose rewards were held.
• obligations, the held rewards as Obligation models. getObligationIds() returns their ids, and getHoldReason() on each says why it waits.
• conversionIds, the conversion behind each reward, keyed by obligation id.
• transactionId and opportunityId, the sale’s transaction and opportunity, when it had them.
• propertyId, on Siren Cloud, the Property every reward came from, or null.

use Siren\Obligations\Core\Events\RewardHeldForReview;

public function handle(Event $event): void
{
    foreach ($event->obligations as $obligation) {
        $reason = $obligation->getHoldReason();
    }
}

When would you use it?

Use it to alert whoever reviews rewards, or to log why a sale’s rewards didn’t count yet. Siren also writes a note about the held rewards. On Siren Cloud, this event also sends the “Reward held for review” email to Admins. Sales in another currency explains the review from the dashboard side.

On a WordPress site connected to Siren Cloud, Siren Cloud does this work, so the site doesn’t raise RewardHeldForReview. No Siren Cloud webhook announces held rewards.