---
title: "Events and hooks"
space: "Commera"
url: "https://docs.bwh.tech/commera/plugin-reference/events-and-hooks"
updated: "2026-10-09"
---

A plugin declares three entries in `hooks.py`. Together they give 13 handler names.

```python
commera_api_version = [1]

commera_events = {"order_paid": ["my_app.orders.on_order_paid"]}

commera_hooks = {"validate_cart": ["my_app.cart.get_cart_refusal"]}
```

| Hook | What it does | When a handler fails |
| --- | --- | --- |
| `commera_api_version` | Names the Commera API versions that your plugin supports. See [Compatibility](/commera/plugin-reference/compatibility) | Not a handler |
| `commera_events` | Tells your plugin that something happened. Handlers run later, in a background job | Commera retries the delivery |
| `commera_hooks` | Asks your plugin while an action runs. The answer changes the action. Today every hook runs at checkout | The checkout is blocked |

`bench migrate` prints a warning and writes an Error Log for a key that Commera does not know, for example `order_payed`.

## Events

Register them in `commera_events`. Each handler gets a `CommeraEvent`. See [Events](/commera/plugin-reference/events).

| Key | When it fires |
| --- | --- |
| `order_placed` | The shopper places a store order |
| `order_paid` | A store order is paid |
| `order_cancelled` | A store order is cancelled |
| `order_fulfilled` | A store order is shipped, delivered or returned, whichever comes first |
| `order_delivered` | A store order is delivered |
| `order_returned` | A store order is partially or fully returned |
| `order_refunded` | A refund for a store order is submitted |
| `product_updated` | A product on the storefront changes |
| `inventory_changed` | Stock of a product on the storefront changes in the store warehouse |

## Hooks

Register them in `commera_hooks`. Each handler gets the cart `Quotation`. See [Hooks](/commera/plugin-reference/hooks).

| Key | What it can do |
| --- | --- |
| `validate_cart` | Refuse the checkout, with a message for the shopper |
| `cart_fees` | Add a charge row to the cart, which adds to the total |
| `delivery_options` | Hide, reprice or rename delivery options |
| `payment_methods` | Hide payment methods |

No hook changes an item price, gives a discount or sets the cart total directly.

## Other places to extend Commera

These are not Commera hooks:

- **Dashboard pages, cards, actions and settings.** The folder of a file under `commera/` sets where it shows. See [Dashboard entries](/commera/plugin-reference/dashboard-entries).
- **Refuse a cancel.** Use a Sales Order `before_cancel` doc event. See [Hooks](/commera/plugin-reference/hooks#refuse-a-cancel).

## Next steps

- [Events](/commera/plugin-reference/events)
- [Hooks](/commera/plugin-reference/hooks)
- [SDK](/commera/plugin-reference/sdk)