SaleTriggered

SaleTriggered is the primary commerce event for purchases. It fires when an extension determines that an order should be tracked by Siren, and it sets the entire downstream pipeline in motion. Conversions, obligations, and eventually payouts all trace back to this event.

The event ID is sale_triggered, and its fully qualified class is Siren\Commerce\Events\SaleTriggered.

What does this event carry?

The event carries five pieces of data: the opportunity ID that links the sale back to the affiliate referral, an array of transaction details describing the line items (each with a name, description, value, and type), a source string identifying which extension produced the event, and two optional binding fields. The bindingId maps the event to the external platform’s order record, and bindingDataType identifies the kind of external record it maps to.

use Siren\Commerce\Events\SaleTriggered;

$event = new SaleTriggered(
    $opportunityId,       // int: the opportunity that tracked this referral
    $transactionDetails,  // array: line items with name, description, value, type
    'wc',                 // string: source extension identifier
    $orderId,             // ?string: external order ID for mapping
    'wc_order'            // ?string: external type identifier
);

How does the pipeline react?

When SaleTriggered fires, InitializeSaleConversion in the conversions domain picks it up and begins the conversion process.

During initialization, the system fires a separate SaleInitialized event (event ID: sale_initialized). This is an internal coordination point. Listeners that need to act during the initialization phase, before conversions are fully built, subscribe to SaleInitialized rather than to SaleTriggered itself. The two events represent different phases of the same process: SaleTriggered is the entry point from the extension, and SaleInitialized is the internal signal that initialization is underway.

For the full lifecycle of commerce events and how they connect to the rest of the attribution pipeline, see the Commerce Events overview.