Commerce services emit typed events after successful state changes. Listen for side effects; do not use listeners to repair core invariants that belong in the transaction.
Create a listener
import { OrderPlaced } from "@adocommercekit/core/events";
export default class SendOrderReceipt {
async handle(event: InstanceType<typeof OrderPlaced>) {
// Dispatch an idempotent mail job keyed by event.orderId.
}
}Register it using the Adonis emitter:
// start/events.ts
import emitter from "@adonisjs/core/services/emitter";
import { OrderPlaced } from "@adocommercekit/core/events";
emitter.on(OrderPlaced.name, [
() => import("#listeners/send_order_receipt"),
"handle",
]);Use the event class’s exported name rather than copying a string from logs when possible.
Inline or outbox delivery
With events.outbox.enabled: false, Adocommerce Kit emits after transaction success in the current process. This is simple but a crash after commit can lose the side effect.
With outbox mode enabled, event envelopes are written in the same transaction as commerce state. DrainEventOutbox claims pending rows, delivers them, and retries with backoff. Consumers must still be idempotent because at-least-once delivery may repeat a handler.
Listener rules
- Use aggregate IDs from the event and reload current state.
- Key jobs and external writes by event identity or aggregate transition.
- Keep listeners small; dispatch slow work through
JobDispatcher. - Never throw to roll back a transaction that has already committed.
- Treat event payloads as public contracts. Add fields compatibly; do not repurpose existing fields.
- Avoid listener chains where event A writes core state solely to trigger event B. Put orchestration in a service or workflow.
For audit or analytics consumers, store the event name, aggregate ID, and observed timestamp. Do not persist raw customer PII unless the downstream system has an explicit retention policy.
Payment and return event names
Core exports PaymentAuthorized, PaymentCaptured, PaymentFailed, PaymentExpired,
PaymentReviewRequired, RefundSucceeded, and RefundFailed. Pending provider refunds
do not emit a terminal refund event; wait for the webhook or operation reconciliation.
Provider adapter event strings such as refund.pending and payment.captured are
normalized webhook input, not the Adonis domain-event names to register here.
RMA consumers can use ReturnRequested, ReturnStateChanged, ReturnRefunded, and
ReturnExchanged. ReturnStateChanged includes returnId, from, and to; reload the
aggregate rather than inferring current state from an event that may be delivered late.
Inventory movement and low-stock events
StockAdjusted(itemId, locationId, delta, reason) covers every movement-ledger mutation:
receipts, sales, return restocks, adjustments, cycle counts, transfer dispatch/receipt,
backorder receipt commits, and payment/shipment compensation. Reservation alone changes
availability but is not an on-hand movement. Consumers should reload the level and use
the signed delta/reason rather than assuming every stock event is an operator adjustment.
StockLevelLow(itemId, available, threshold) uses the inventory level’s reorderPoint,
not an inventory-item-wide threshold. It fires when negative movement or a new reservation
leaves onHand - reserved <= reorderPoint, including reservation-induced low availability.
A null reorder point disables this notification. The payload has no location ID; reload
levels if a consumer needs location-specific decisions.
Return refunds and non-payment tender
The exported constructor is
ReturnRefunded(returnId, refundId: string | null, amount: Money, orderId, paymentAmount: Money, nonPaymentAmount: Money). amount is the complete returned value;
the two tender portions sum to it. A gift-only refund can have refundId: null and zero
paymentAmount. Do not assume this event always corresponds to a provider refund row.
The gift-card provider credits nonPaymentAmount on this event. Its generic
RefundSucceeded listener skips payment refunds with metadata.returnId, preventing
double-crediting the same return. Cancellation releases remaining gift holds and unfulfilled
preorder allocations through OrderCanceled; fulfilled returns do not reopen preorder capacity.
Keep financial listeners idempotent and active when configuring outbox delivery.