Hook System

For usage patterns and examples, see the Use Hooks guide. For checkout pipeline details, see the Hook Pipeline explanation.

Hook types

BeforeHook

type BeforeHook<TData> = (args: {
  data: TData;
  operation: HookOperation;
  context: HookContext;
}) => Promise<TData> | TData;

Before hooks receive the incoming data, may mutate or replace it, and return the (possibly modified) data. Throwing aborts the operation.

AfterHook

type AfterHook<TData> = (args: {
  data: TData | null;
  result: TData;
  operation: HookOperation;
  context: HookContext;
}) => Promise<void> | void;

After hooks receive both the original input (data) and the operation result. They cannot alter the result. Throwing does not roll back the operation unless executed inside a transaction.

HookOperation

type HookOperation =
  | "create"
  | "update"
  | "delete"
  | "read"
  | "list"
  | "statusChange"
  | "addItem"
  | "removeItem"
  | "custom";

HookOrigin

type HookOrigin = "rest" | "local";

---

HookContext

interface HookContext {
  actor: Actor | null;
  tx: unknown;
  logger: Logger;
  services: ServiceContainer;
  context: Record<string, unknown>;
  requestId: string;
  origin: HookOrigin;
  jobs: JobsAdapter;
  db: PluginDb;
  kernel: unknown;
}

| Field | Type | Description | |-------|------|-------------| | actor | Actor \| null | The authenticated user or API key. null for anonymous operations. | | tx | unknown | Current database transaction handle. Cast to TxContext at usage sites. | | logger | Logger | Scoped Pino logger with info, warn, error methods. | | services | ServiceContainer | All registered service instances (catalog, orders, inventory, etc.). | | context | Record<string, unknown> | Mutable bag for passing data between hooks within the same operation. | | requestId | string | Unique identifier for the current request. Same value across all hooks in one request. | | origin | HookOrigin | "rest" (HTTP request) or "local" (direct kernel call). | | jobs | JobsAdapter | Adapter for enqueueing background jobs. | | db | PluginDb | Drizzle database instance. Typed — use directly without casting. | | kernel | unknown | The kernel singleton. Cast to Kernel to access kernel.services, kernel.database.db, kernel.hooks. |

Actor

interface Actor {
  type: "user" | "api_key";
  userId: string;
  email: string | null;
  name: string;
  vendorId: string | null;
  organizationId: string | null;
  role: string;
  permissions: string[];
}

---

Available hook keys

Entity hooks

Registered in config.entities[slug].hooks.

| Key | Type | Operation | |-----|------|-----------| | beforeCreate | BeforeHook | create | | afterCreate | AfterHook | create | | beforeUpdate | BeforeHook | update | | afterUpdate | AfterHook | update | | beforeDelete | BeforeHook | delete | | afterDelete | AfterHook | delete | | beforeRead | BeforeHook | read | | afterRead | AfterHook | read | | beforeList | BeforeHook | list | | afterList | AfterHook | list |

Cart hooks

Registered in config.cart.hooks.

| Key | Type | Operation | |-----|------|-----------| | beforeAddItem | BeforeHook | addItem | | afterAddItem | AfterHook | addItem | | beforeRemoveItem | BeforeHook | removeItem | | afterRemoveItem | AfterHook | removeItem | | beforeUpdateQuantity | BeforeHook | update | | afterUpdateQuantity | AfterHook | update |

Checkout hooks

Registered in config.checkout.hooks or via plugin hooks with key prefix checkout..

| Key | Type | Pipeline position | |-----|------|-------------------| | beforePayment | BeforeHook<CheckoutData> | After calculateShipping, before validatePaymentMethod. Apply gift card deductions, loyalty redemptions, or other balance-based reductions here. | | beforeCreate | BeforeHook<CheckoutData> | After authorizePayment, before order creation | | afterCreate | AfterHook<OrderResult> | After order creation |

Order hooks

Registered in config.orders.hooks.

| Key | Type | Operation | |-----|------|-----------| | beforeCreate | BeforeHook | create | | afterCreate | AfterHook | create | | beforeStatusChange | BeforeHook | statusChange | | afterStatusChange | AfterHook | statusChange | | beforeDelete | BeforeHook | delete |

Inventory hooks

Registered in config.inventory.hooks.

| Key | Type | Operation | |-----|------|-----------| | afterAdjust | AfterHook | custom |

System-registered hooks (read-only)

These are registered by the kernel in the appended slot at boot. They always run after user-defined and plugin hooks and cannot be disabled or reordered.

• Webhook delivery — fires on 14 after-hooks; enqueues async delivery jobs
• Audit logging — fires on 11 after-hooks; writes to commerce_audit_log
• Search index sync — fires on catalog.afterCreate and catalog.afterUpdate
• Order status email — fires on orders.afterStatusChange

---

Checkout pipeline execution order

Before hooks (pre-order creation)

Executed sequentially on CheckoutData:

| Step | Function | Purpose | |------|----------|---------| | 1 | validateCartNotEmpty | Loads cart, verifies line items, enriches with entity title and type | | 2 | resolveCurrentPrices | Resolves live prices and computes subtotal | | 3 | checkInventoryAvailability | Verifies sufficient stock for every line item | | 4 | applyPromotionCodes | Applies automatic and code-based promotions | | 5 | calculateTax | Computes tax via the tax adapter | | 6 | calculateShipping | Computes shipping cost | | 7 | Plugin checkout.beforePayment hooks | Gift cards, loyalty redemptions, balance-based reductions | | 8 | validatePaymentMethod | Asserts a payment method ID is present | | 9 | authorizePayment | Authorizes payment. Stores paymentIntentId in context. |

After hooks (post-order creation, compensation chain)

| Step | Function | Compensatable | Purpose | |------|----------|---------------|---------| | 1 | reserveInventoryStep | Yes | Reserves inventory. Released if a later step fails. | | 2 | capturePaymentStep | Yes | Captures the authorized payment. Reversed if a later step fails. | | 3 | initiateFulfillmentStep | No (best-effort) | Triggers fulfillment | | 4 | sendConfirmationStep | No (best-effort) | Sends order confirmation email |

If the compensation chain fails, order status is set to cancelled.

---

Three-slot execution order

Every hook key has three execution slots. When a hook fires, all handlers run sequentially:

prepended → configured → appended

| Slot | Written by | Purpose | |------|-----------|---------| | prepended | System internals, plugins | Validation guards, system checks — run before user hooks | | configured | User config (commerce.config.ts) | Your hooks | | appended | System internals, plugins | Webhook delivery, audit logging, search sync — run after user hooks |

If any handler throws, execution stops and the error propagates.

---

Registration methods

Three mechanisms register hooks:

1. Config hooks — directly in the config object under the relevant module key (e.g., config.checkout.hooks.beforeCreate)
2. Entity hooks — per entity type in config.entities[slug].hooks
3. Plugin hooks — via defineCommercePlugin({ hooks: () => [...] }), merged into config.hooks

See the Use Hooks guide for code examples of all three methods.