Attribution Events

Attribution events handle the middle of Siren’s pipeline. They sit between the commerce events that enter the system from e-commerce platforms and the conversion events that generate obligations and payouts. This is where Siren determines which collaborator gets credit for a customer action, creates the engagement records that represent that credit, and signals the conversion system to proceed.

All opportunity events live in Siren\Opportunities\Core\Events. All engagement events live in Siren\Engagements\Core\Events.

Opportunity lifecycle

Opportunities are temporary tracking records that capture a customer’s referral context before a conversion occurs. Two events manage their lifecycle.

OpportunityTriggered fires when a new opportunity is created, such as when a customer visits a site through an affiliate link or uses a coupon. Engagement trigger strategies evaluate this event to decide whether to create engagements.

OpportunityInvalidated fires when an existing opportunity is determined to be invalid, whether from duplicate detection, expired referral links, or other validation failures. Any engagements that were created for the opportunity are marked invalid, preventing them from contributing to conversions.

From opportunity to engagement

Three events manage the process of creating, awarding, and completing engagements. They represent a progression: engagements are triggered (created in bulk), individually awarded (given credit within a program), and then completed (marked as having led to a conversion).

EngagementsTriggered fires when engagement trigger strategies produce new engagement records. A single opportunity can produce multiple engagements if the collaborator participates in multiple programs, so this event always carries an array rather than a single engagement.

EngagementAwarded fires when an individual engagement is awarded credit during the conversion process. This is different from triggering. Triggering creates the engagement record. Awarding happens later, when the conversion system evaluates which engagements should receive credit based on the program’s resolver strategy.

EngagementCompleted fires when engagements for an opportunity finish the conversion process. This signals that the opportunity’s engagements have been fully processed and should transition from active to completed status.

Bridging into the conversion system

Two internal coordination events handle the transition from the attribution layer into the conversion system.

EngagementInitialized (event ID: Engagement_initialized) fires when the engagement system begins processing a sale or lead for conversion. It carries an opportunity ID, line item details from the commerce event, and the engagement type. This event signals the conversion system to prepare for building conversion records.

TransactionTriggered (event ID: transaction_triggered) fires when the attribution system produces the data needed for a transaction record. It carries an opportunity ID and line item details. When this event fires, InitializeSaleEngagement picks it up and begins evaluating which engagement trigger strategies apply. This is the handoff point where financial data from the commerce layer flows into the engagement system’s attribution logic.

These two events are internal plumbing. Most integrations will listen to the five events documented on their individual pages rather than these coordination signals.

The flow from opportunity through engagement to conversion

The attribution events form a clear path through the pipeline. An opportunity is created when a customer interacts with a referral link, and OpportunityTriggered fires. Engagement trigger strategies evaluate the opportunity and create engagement records, producing EngagementsTriggered. When a sale or lead comes in, TransactionTriggered and EngagementInitialized carry the commerce data into the engagement system. The conversion system awards credit to the relevant engagements, producing EngagementAwarded for each one. Finally, EngagementCompleted signals that all engagements for the opportunity have been processed and the conversion is done.

If an opportunity is determined to be invalid at any point, OpportunityInvalidated fires and the associated engagements are invalidated before they can contribute to conversions.

The conversion events that follow this flow (such as ConversionsAwarded and ObligationIssued) are documented separately. They belong to the conversion and obligation domains rather than the attribution layer.