ConversionInitialized

The conversion pipeline begins here. When a commerce event is detected and an opportunity exists to attribute it, the system fires ConversionInitialized. This is the moment where a tracked customer interaction becomes a potential conversion, kicking off the evaluation of programs, incentive rules, and ultimately the creation of conversion records.

The event is identified as conversion_initialized and lives in the Siren\Conversions\Core\Events namespace.

What does this event carry?

The event provides the opportunityId that links the conversion back to the customer’s tracked session, a conversionType string that identifies what kind of outcome occurred (a sale, a lead, a subscription payment), and transaction data describing the financial details. The transaction data can be either a Transaction model (if one was already created) or an array of transaction detail arrays that the pipeline will use to create one.

Optional binding fields allow the conversion to be linked to an external record in another system. A WooCommerce order ID or an EDD payment ID, for example, would be passed through bindingId and bindingDataType.

use Siren\Conversions\Core\Events\ConversionInitialized;

public function handle(Event $event): void
{
    $opportunityId = $event->getOpportunityId();
    $type = $event->getConversionType();

    // Transaction data may be a model or a raw details array
    $transaction = $event->getTransaction();
    $details = $event->getTransactionDetails();

    // Optional external binding
    $bindingId = $event->getBindingId();
    $bindingDataType = $event->getBindingDataType();
}

What happens when it fires?

The BuildConversions listener picks up this event. It queries for all active programs that match the opportunity’s engagements, evaluates each program’s incentive rules against the transaction data, and creates conversion records for every qualifying program. Once conversions are built for a program, the listener broadcasts ConversionsAwarded for that program, handing off to the next stage of the pipeline.

This separation matters because it keeps the detection of commerce events completely decoupled from the logic of evaluating programs. The commerce integration only needs to fire ConversionInitialized with the right data. Everything else is handled downstream.

See the Conversion Events overview for how this event fits into the full conversion pipeline.