Called when a new OrderEventMessage is created.

add_action( 'shopp_{event}_order_event', [callback] );

@param OrderEventMessage $Event the OrderEventMessage object generating the event


Called when a new OrderEventMessage is created.

The order event system was introduced in Shopp 1.2 to define a flexible messaging protocol for order and payment processing events. Each event has a specific message data structure to track relevant information for the event.

When a new order event is added, the message is broadcast using the WordPress action hook system. This allows any code, anywhere in the system (Shopp, WordPress plugins or custom theme code) to run custom code when the event occurs.

The order event system uses a series of OrderEventMessage class objects to define and manage the message structure. Each event has an internal name defined in the message class to identify the message type. The purchase event, for example, represents the PurchaseOrderEvent class where the purchase message structure is defined.

The PurchaseOrderEvent is the shopper-initiated purchase (sales order) command message. This message is the key message that starts the entire ordering process. As the first step, this event triggers the creation of a new order in the system. In accounting terms this acts as the Sales Order document, and is stored in Shopp as a ShoppPurchase record.

In most cases, after record creation an InvoicedOrderEvent (invoiced) sets up the transactional debit against the purchase total prior to an AuthOrderEvent (auth) request.

The sequence of events from creating the order, to completed order payment, to cancellation is shown in the diagram below.


The typical sequence of events to process an order successfully from creation to capturing the payment funds follows this workflow: purchaseinvoicedauthauthedcapturecaptured.

It is important to note that some events have a transactional role adjusting the order accounting balance. Others are request events starting a request/response process. The remainder are simply a notice event for logging purposes.

Order Events Reference

The following list briefly describes the various events that are built-in to Shopp, what they are for and when they occur.

  • purchasePurchaseOrderEvent is the first request event of the entire ordering process that generates a new order for the store and saves it as ShoppPurchase record.
  • invoicedInvoicedOrderEvent is a transactional event that establishes the order balance, an amount due to be paid, for the order.
  • authAuthOrderEvent is the first payment request event that is fired when a payment request is submitted to initiate payment authorization. This typically happens on or around when the Submit Order button is clicked on the checkout page, though it varies depending on the gateway.
  • authedAuthedOrderEvent is a response event that is usually triggered inside payment gateway code to indicate a successful payment authorization. There are several special features in the authed order event, including the capture parameter which can tell Shopp to immediately fire a capture order event if the gateway detects the funds are immediately captured successfully.
  • auth-failAuthFailOrderEvent is an error notice message that is logged to the order when an error occurs during the auth event request processing. It is used to indicate a failure to authorize a payment, such when the credit card payment is denied by the bank for insufficient funds.
  • captureCaptureOrderEvent is a request event that is triggered when a payment capture request is submitted. This usually happens when clicking the Charge Order button from within the order manager. It submits a payment capture request that the payment gateway code can detect and submit to the remote API to trigger fund capture on a previously authorized transaction.
  • capturedCapturedOrderEvent is a transactional event that credits the payment to the order to balance the debit added to the payment register by the invoiced order event. A payment gateway will issue this event to indicate successful payment capture.
  • capture-failCaptureFailOrderEvent is an error notice message that the payment gateway logs when an error occurs while processing a payment capture request.
  • rebillRebillOrderEvent is a transactional event that adjusts the running balance for an order to accommodate a new recurring payment event. This event debits the order to establish an amount due. The recaptured event can credit a rebill-ed order.
  • recapture-failRecaptureFailOrderEvent a notice event that logs when an error occurs during recapture request processing.
  • recapturedRecapturedOrderEvent a transactional event that credits an order for a successful recpature request payment.
  • refundRefundOrderEvent is a request event that initiates the refund process for an order, submitting a refund request to the payment gateway API.
  • refund-failRefundFailOrderEvent triggered by the gateway to indicate a refund failure.
  • refundedRefundedOrderEvent triggered by the gateway to indicate a successful refund.
  • voidVoidOrderEvent triggered to indicate a voided order.
  • void-failVoidFailOrderEvent triggered to indicate a void failure.
  • voidedVoidedOrderEvent triggered to indicate a successful voided order.
  • decryptDecryptOrderEvent triggered to indicate payment card decryption has taken place, logging the user account that accessed the information.
  • shippedShippedOrderEvent triggered to indicate that an order shipment occurred.
  • downloadDownloadOrderEvent is a notice event that logs when a request has been made to download a digital asset associated with the order.
  • reviewReviewOrderEvent is a notice event to log transaction review information about a payment processing request.
  • noticeNoticeOrderEvent is a generic notice event that logs a notice message in the order history
  • noteNoteOrderEvent is a notice event that logs when a message is sent to the customer on record for the order.
  • unstockUnstockOrderEvent is a request event that allocates items from inventory to fulfill the order. It reduces the stock level of the store’s inventory for the products in the order.

When a new order event is dispatched it fires three different action hooks:

  • A gateway-specific form of the action hook: shopp_{gateway}_{event}
  • An event specific action hook: shopp_{event}_order_event
  • A generic action hook for all order events: shopp_order_event

All three hooks will pass the event object to the callback handler.


add_action('shopp_captured_order_event', 'payment_captured');

// Log the payment to the PHP error log
function payment_captured ( $ShoppOrderEvent ) {
    error_log("Order #{$ShoppOrderEvent->order} was successfully paid.");
add_action('shopp_unstock_order_event', 'notify_dropshipper');

// Log the payment to the PHP error log
function notify_dropshipper ( $UnstockOrderEvent ) {
    $Purchase = $UnstockOrderEvent->order();
    $message = array();
    foreach ( $UnstockOrderEvent->allocated as $PurchaseStockAllocation ) {
        $message[] = "{$PurchaseStockAllocation->sku} x{$PurchaseStockAllocation->quantity}";
    $message[] = "";
    $message[] = "Send to {$Purchase->firstname} {$Purchase->lastname} {$Purchase->address} {$Purchase->city}, {$Purchase->state} {$Purchase->postcode}";
        'New Order to fulfill', 
        join("\n", $message), 
        array('from' => shopp_setting('merchant_email'));

See Also

You must be logged in to post a comment.

© Ingenesis Limited. Shopp™ is a registered trademark of Ingenesis Limited.