.webp)
Build a Commera plugin
A Commera plugin is a Frappe app that adds behaviour to a Commera store. Your plugin can react to orders, change checkout, and add screens to the Commera dashboard at /commera. You do not change Commera's code, and Commera upgrades do not overwrite your work.
What your plugin can do
| Part | What it does | Reference |
|---|---|---|
| Events | Run your code in a background job after something happens: an order is placed, paid, shipped, refunded, or a product or its stock changes | Events |
| Hooks | Refuse a cart, add a fee, hide or reprice a delivery option, or hide a payment method, while the shopper waits | Hooks |
| Dashboard entries | Add pages, cards, actions, palette commands and a Settings tab to /commera |
Dashboard entries |
| SDK | Read orders, catalog items and the cart, and record a shipment, through a stable Python API | SDK |
How it works
flowchart TD
A[Shopper checks out] --> B[Hooks run]
B -->|cart refused| A
B --> C[Commera places the order and commits]
C --> D[Commera records order_placed and order_paid]
D --> E[Your event handler runs in a background job]
E --> F[Your plugin calls the SDK, for example record_shipment]
F --> G[Order status changes]
G --> D
H[Staff open /commera] --> I[Your pages, cards and actions]
I --> J[Your whitelisted methods]
- The hooks run inside the shopper's request. They can stop or change the checkout.
- After the order commits, Commera records an event and queues one delivery for each plugin that handles it.
- Your handler runs in a background job. It cannot stop the action that caused the event.
- Your dashboard entries call whitelisted methods in your plugin. Commera draws the frame around them.
Handlers go in two dicts in hooks.py:
commera_api_version = [1]
commera_events = {"order_paid": ["my_app.orders.on_order_paid"]}
commera_hooks = {"validate_cart": ["my_app.cart.get_cart_refusal"]}
Where dashboard entries show
The folder of an index.vue under your plugin's commera/ folder decides where it shows: a page, a card or an action on an order, product or customer, a palette command, or a Settings tab. All other folders under commera/ are your own code, for example commera/shared/. Where your plugin shows up has a screenshot and the folder for each place.
Install a plugin
Install a Commera plugin like any Frappe app. The plugin must list commera in required_apps.
bench get-app https://github.com/<owner>/<app>
bench --site <site> install-app <app>
bench build --app <app>
bench --site <site> migrate
After migrate, Commera checks every plugin that has a commera_ hook. It prints a warning, and writes an Error Log, when a plugin does not support this Commera API version or adds Custom Fields without its app name as the prefix. See Compatibility.
To see working plugins, read the public example repositories, for example commera_gift_wrap and commera_loyalty.
Build your own
The tutorial builds a complete plugin step by step: a settings tab, a hook, an order handler, drop-ship Purchase Orders, an order card and actions, a status sync, a dashboard page and a palette command.