Conversion Events

Conversion events drive the core of Siren’s attribution pipeline. They cover the full lifecycle of a conversion, from the initial trigger through award, approval or rejection, and renewal. These events are defined in Siren\Conversions\Core\Events and are the primary mechanism through which the system creates conversions, issues obligations, and handles recurring payments.

The creation flow

The conversion creation flow begins with ConversionInitialized and ends with ConversionsAwarded. These two events represent the entry and exit of the BuildConversions listener, which is responsible for matching an opportunity to qualifying programs and creating conversion records.

ConversionInitialized is the main entry point for the conversion pipeline. It fires when a commerce event is detected and an opportunity exists to attribute it. The event carries opportunity, transaction, and optional external binding data that the BuildConversions listener uses to evaluate qualifying programs.

ConversionsAwarded fires after BuildConversions has successfully created conversion records for a specific program. It carries the full incentive context, including the conversions themselves, the matching program, and the resolver used to calculate rewards. This is the branching point for obligation creation, engagement completion, and other downstream effects.

The review flow

After conversions are created, they go through a review process. The two events here represent the two possible outcomes of that review.

ConversionApproved fires when a conversion passes review, either through auto-approval or manual admin action. Its primary downstream effect is transitioning the conversion’s associated obligation from draft to pending status, making it eligible for the next fulfillment run.

ConversionRejected fires when a conversion is denied, typically because of a refund or manual rejection by an admin. It triggers obligation cleanup for the rejected conversion.

Renewal events

Renewal events handle recurring payments such as subscription renewals. They parallel the creation flow but start from existing engagements rather than live opportunities.

ConversionRenewed fires when a subscription renewal payment is detected. Unlike ConversionInitialized, which works from an opportunity, this event works from the original engagement records created during the initial sale. The engagement reuse preserves the original attribution, so the collaborator who was credited with the initial sale continues to receive credit for renewals without needing a new opportunity or engagement cycle. After renewal conversions are built, a RenewedConversionsAwarded event fires with the same shape as ConversionsAwarded, carrying the full incentive context for downstream listeners.

Program group resolution

ProgramGroupConversionTriggered fires when a conversion involves programs that belong to a program group. Program groups enforce mutual exclusivity: only one program in the group can award a conversion for a given opportunity. The event identifies the winning program (determined by the group’s resolution strategy) and the losing programs, allowing listeners to clean up engagements on the losers and ensure only the winner proceeds through the conversion flow.

Manual attribution

ManualAttributionRequested fires when an admin manually attributes a conversion to a specific collaborator. This bypasses the normal engagement-based attribution flow entirely. The event provides the collaborator, transaction, and opportunity needed to create conversions without relying on tracked engagements. See Manually Attribute a Transaction for a user-level overview of when and how to use this feature.