Plugin Developer Guide
Plugins let you hook into key moments in the order lifecycle — when an order is placed, when payment is confirmed, when a refund is requested — and run your own logic without modifying the core codebase.
Overview
A plugin is a small Node.js module with two files: an extension.js (your logic)
and a config.json (your settings). Drop it into the extension/
directory, register it in the database, and it runs automatically at the execution points
you specify.
How it works
When a significant event happens in the POS (an order is created, a payment is confirmed,
a refund is requested), the core code calls a function called runExtensions().
That function:
- Fetches all active plugins for the current store (host).
- Filters to those registered at the current execution point.
- For each one, verifies
extension.jsexists on disk and loads it. - Calls the plugin's
work(parameters, context)function. - Feeds the plugin's return value into the next plugin in the chain.
- Returns the final result to the caller.
Here's the execution chain in visual form:
PIPELINE ┌─────────────────┐
│ POS Event │ e.g. order.approved
└────────┬────────┘
▼
┌─────────────────────────────┐
│ runExtensions("order.approved") │
└────────┬────────────────────┘
▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ fraudguard │ → │ loyaltypoints│ → │ receiptsender│
└──────────────┘ └──────────────┘ └──────────────┘
│ │ │
▼ ▼ ▼
{ order, { order, { order,
fraudCheck } fraudCheck, fraudCheck,
loyalty } loyalty,
receipt }
Plugin anatomy
At runtime a plugin is just two files. To list it on POS GROVE you ship four more (see Upload to POS GROVE):
| File | Purpose | Required? |
|---|---|---|
extension.js |
Your logic. Must export a function that takes (parameters, context). |
Yes |
config.json |
Settings your plugin reads (API keys, thresholds, toggles). | Yes for uploads (may be {}) |
manifest.json |
Name, slug, version, author, description (shown on the website) and execution points. | Yes for uploads |
screenshot.png |
Picture of the plugin's settings or result. Becomes the plugin's image on the website. | Yes for uploads |
logo.png |
Square logo. | Optional |
README.txt |
Plain-text instructions for store owners. | Optional |
Structure
Folder layout
All plugins live inside the extension/ folder at your project root. Each plugin gets its own subfolder, named after its slug:
LAYOUTyour-project/
├── extension/
│ ├── receiptsender/
│ │ ├── extension.js
│ │ ├── config.json
│ │ ├── manifest.json
│ │ ├── screenshot.png
│ │ ├── logo.png (optional)
│ │ └── README.txt (optional)
│ ├── loyaltypoints/
│ │ ├── extension.js
│ │ └── config.json
│ └── fraudguard/
│ ├── extension.js
│ └── config.json
├── src/
│ └── ...your app code
└── package.json
slug field
in the database registration exactly. Slugs may only contain letters, digits,
dots, dashes, and underscores: /^[a-zA-Z0-9_\-\.]+$/.
Path traversal characters (../, /) are rejected.
config.json
Settings file. Any JSON is valid — you decide the schema. It's read once when the plugin
is first loaded and passed to your work() function via context.config.
JSON{
"enabled": true,
"apiKey": "sk-abc123...",
"threshold": 5000,
"notifyEmails": ["ops@example.com", "alerts@example.com"]
}
Registering your plugin
Once your files are on disk, register the plugin in the pos_settings collection
for the store(s) that should use it. Each entry in the plugins array looks like
this:
JAVASCRIPT{
id: "PLG-UNIQUE-ID", // any unique string
kind: "plugin", // must be "plugin"
name: "My Plugin", // display name
slug: "myplugin", // must match folder name
description: "What it does",
category: "general",
compatibility: ">=1.0.0",
executionPoints: "order.approved", // string OR array of strings
version: "1.0.0",
latestVersion: "1.0.0",
price: 1500,
currency: "NGN",
active: true, // ← toggle on/off
published: true, // ← must be true
purchaseCount: 0,
createdAt: new Date(),
updatedAt: new Date(),
availablelocal: true
}
kind === "plugin", active === true, published !== false,
and slug is set.
Setting executionPoints
You can register a plugin for a single point or multiple points:
JAVASCRIPT// Single point
executionPoints: "order.approved"
// Multiple points
executionPoints: ["order.placed", "order.approved", "order.shipped"]
Upload to POS GROVE
To offer your plugin to other stores, upload it from Account → Plugin uploads. Zip the plugin's files (not the folder) so they sit at the top level of the ZIP:
| File | Required | Limit |
|---|---|---|
manifest.json | Yes | 1 MB |
extension.js | Yes | 1 MB |
config.json | Yes | 1 MB |
screenshot.png | Yes | 2 MB, PNG, up to 6000 × 6000 px |
logo.png | Optional | 2 MB, PNG |
README.txt | Optional | 1 MB |
The ZIP may be at most 6 MB and may not contain folders or any other file.
manifest.json{
"name": "Fraud Guard",
"slug": "fraudguard",
"version": "1.0.0",
"author": "Your name",
"description": "Flags risky orders before they are saved.",
"executionPoints": ["order.placed"]
}
- On the upload form, tick every execution point your plugin runs at (at least one).
- The
descriptionfrommanifest.jsonbecomes the plugin's description on the website, andscreenshot.pngbecomes its picture. - We review each upload. Once approved it is registered as a plugin automatically and appears in the plugin catalogue when published. Your files are never run on our servers.
- Uploading a new
versionwith the sameslugadds a new version to your existing plugin.
Execution Points
Execution points are the "hooks" where your plugin can attach. Each one fires at a specific moment in the order lifecycle and delivers a specific payload to your plugin.
Available now LIVE
| Point | Fires when | Payload shape |
|---|---|---|
order.placed |
A new order is created (before it's saved to the DB). | { order, action: "order_placed" } |
payment.confirmed |
Payment is marked as paid on an order. |
{ order, payment, action: "payment_confirmed" } |
order.approved |
An order is confirmed/approved (also fires after createorder saves). |
{ order, action: "order_approved" } |
order.cancelled |
An order is cancelled. | { order, action: "cancelled" } |
refund.requested |
A refund is initiated (before processing). | { order, reason, action: "refund_requested" } |
refund.approved |
A refund is approved and processed. | { order, refund, action: "refund_approved" } |
order.ready |
Kitchen marks an order as ready for pickup/delivery. | { order, action: "kitchen_ready" } |
order.shipped |
An order is sent out for delivery. | { order, action: "sent_for_delivery" } |
discount.applied |
Discounts are computed but before the order is saved. | { cartItems, cartSubtotal, couponDiscount, automaticDiscount, couponDetails, automaticDiscountDetails, action: "discount_applied" } |
user.registered |
A customer or staff account is created. | { user, source: "customer" | "staff" } |
product.uploaded |
A product (or product variants) is created in the catalogue. | { product, variants, uploadedBy } |
Plugin API
The work() function
Your extension.js must export a function. This is the entry point the
runtime calls. It can be synchronous or async — both are supported.
JAVASCRIPTfunction work(parameters, context) {
// your logic here
return parameters;
}
module.exports = work;
Arguments
| Name | Type | Description |
|---|---|---|
parameters |
Object | The data being processed at this execution point. Its shape depends on the point (see the execution points table above). Contains the previous plugin's return value if plugins are chained. |
context |
Object | Metadata about the current execution (see below). |
The context object
| Field | Type | Description |
|---|---|---|
context.req | Object | The Express request object (req.headers, req.user, etc.). Read-only — don't mutate. |
context.point | string | The execution point that triggered this run, e.g. "order.approved". |
context.plugin | Object | Your plugin's registration record: { id, name, slug, version }. |
context.config | Object | Contents of your config.json. |
context.orderId | string | undefined | The order ID, when applicable (not set for order.placed since the order isn't saved yet). |
context.host | string | The store hostname (req.headers.host). |
Return value
Whatever you return replaces the parameters object for
the next plugin in the chain, and (if you're the last plugin) becomes the final
result handed back to the caller.
| Return value | Effect |
|---|---|
undefined or null | Payload passes through unchanged. |
| An object | Payload is replaced with your returned object. |
| An object with extra keys | Your keys are merged in for callers that merge (see note below). |
createorder, the return value is merged
on top of the original order data:
finalOrderData = { ...orderData, ...transformed.order }. In other hooks,
the returned object is passed as-is to the next plugin and then to the caller.
Error handling
Throwing is safe. If your plugin throws (or its promise rejects), the runtime catches the error, logs it, and continues to the next plugin in the chain. The rest of the request is never affected.
JAVASCRIPTfunction work(parameters, context) {
// This throw will NOT break the request.
// It's logged as: [plugins] Error executing "myplugin" at order.approved: boom
throw new Error("boom");
// Execution continues with the next registered plugin.
}
parameters unchanged.
Sample Extension
A complete, working plugin that fires on order.approved, sends a receipt
email (simulated), and attaches a receipt object to the payload.
Create the folder
SHELLmkdir -p extension/receiptsender
Add config.json
extension/receiptsender/config.json{
"alowuser": true,
"senderName": "Store Receipts",
"senderEmail": "receipts@example.com",
"replyTo": "support@example.com",
"logoUrl": "https://example.com/logo.png",
"footerNote": "Thank you for your business!",
"currencyFormat": "NGN",
"maxRetries": 3
}
Add extension.js
extension/receiptsender/extension.js'use strict';
const config = require('./config.json');
/**
* receiptsender
* Execution point: order.approved
*
* Receives { order, action } and returns a payload with a `receipt`
* object describing the receipt that was (or would be) sent.
*/
function work(parameters = {}, context = {}) {
const order = parameters.order || {};
const updateparameters = { ...parameters };
// Config-driven kill switch
updateparameters.alowuser = config.alowuser;
if (config.alowuser !== true) {
updateparameters.receipt = {
sent: false,
reason: 'Plugin disabled via config.alowuser'
};
return updateparameters;
}
// Build the receipt payload
const orderNumber = order.orderNumber || 'UNKNOWN';
const customer = order.customer || {};
const items = Array.isArray(order.items) ? order.items : [];
const total = order.total?.amount || 0;
const currency = order.total?.currency || config.currencyFormat || 'USD';
const lineItems = items.map(it => ({
name: it.name,
qty: it.quantity,
unit: it.unitPrice?.amount || 0,
lineTotal: it.totalPrice?.amount || 0,
variant: it.variantName || null
}));
const receipt = {
to: customer.email || null,
from: `${config.senderName} <${config.senderEmail}>`,
replyTo: config.replyTo,
subject: `Receipt for Order ${orderNumber}`,
orderNumber,
customerName: customer.name || 'Guest',
currency,
subtotal: order.subtotal?.amount || 0,
discount: order.discount?.amount || 0,
tax: order.tax?.amount || 0,
total,
lineItems,
logoUrl: config.logoUrl,
footerNote: config.footerNote,
generatedAt: new Date().toISOString(),
sent: false,
attempts: 0,
maxRetries: config.maxRetries
};
// Attempt to send (stubbed — swap for real transport)
if (!receipt.to) {
receipt.reason = 'No customer email on file';
} else {
try {
console.log(
`[receiptsender] Would send receipt for ${orderNumber} ` +
`to ${receipt.to} (${currency} ${Number(total).toFixed(2)})`
);
receipt.sent = true;
receipt.attempts = 1;
receipt.sentAt = new Date().toISOString();
} catch (err) {
receipt.sent = false;
receipt.reason = err.message;
receipt.attempts = 1;
}
}
updateparameters.receipt = receipt;
updateparameters.persist = false;
return updateparameters;
}
module.exports = work;
Register the plugin
Add the following entry to the plugins array on your store's pos_settings document:
JAVASCRIPT{
id: "PLG-RECEIPT001",
kind: "plugin",
name: "receiptsender",
slug: "receiptsender",
description: "Emails a receipt when an order is approved",
category: "notifications",
compatibility: ">=1.0.0",
executionPoints: "order.approved",
version: "1.0.0",
latestVersion: "1.0.0",
price: 1500,
currency: "NGN",
active: true,
published: true,
purchaseCount: 0,
createdAt: new Date(),
updatedAt: new Date(),
availablelocal: true
}
Testing your plugin
Once registered and active, the plugin will fire on the next order.approved
event. Watch your server logs for the [receiptsender] prefix.
You can also trigger it manually via the admin test endpoint:
HTTPPOST /runextensiontest
Content-Type: application/json
{
"point": "order.approved",
"parameters": {
"order": {
"orderNumber": "TEST-001",
"customer": { "name": "Jane", "email": "jane@example.com" },
"items": [{ "name": "Widget", "quantity": 2 }],
"total": { "amount": 5000, "currency": "NGN" }
}
}
}
Patterns
Multi-hook plugins
One plugin can listen to multiple execution points. Just register multiple points in
the executionPoints array, then branch inside work() using
context.point:
JAVASCRIPTfunction work(parameters, context) {
switch (context.point) {
case 'order.placed':
return handlePlaced(parameters, context);
case 'order.approved':
return handleApproved(parameters, context);
case 'order.cancelled':
return handleCancelled(parameters, context);
default:
return parameters;
}
}
module.exports = work;
Pipeline chaining
Because each plugin's return value is fed to the next plugin, you can build composed
behavior naturally. Say you have three plugins all on order.approved —
they run in alphabetical order and share state through the payload:
JAVASCRIPT// Plugin 1: fraudguard
return { ...parameters, fraudCheck: { status: 'clean' } };
// Plugin 2: loyaltypoints (receives plugin 1's output)
function work(params, ctx) {
console.log(params.fraudCheck.status); // "clean"
return { ...params, loyalty: { points: 100 } };
}
// Plugin 3: receiptsender (receives plugin 2's output)
function work(params, ctx) {
console.log(params.loyalty.points); // 100
return { ...params, receipt: { sent: true } };
}
name.
To force a specific order, prefix names (01_fraudguard,
02_loyaltypoints, 03_receiptsender) or add a
priority field to the registration and sort on that.
Best practices
Always use safe accessors
Never assume a field exists. The payload shape can vary between execution points and between versions:
JAVASCRIPT// Bad
const name = order.customer.name;
// Good
const name = order.customer?.name || 'Guest';
Never throw for control flow
If you want to "skip" a plugin, return parameters unchanged. Reserve
throw for genuine bugs or unrecoverable errors.
Keep plugins side-effect-free when possible
Plugins run inside the request lifecycle, so a slow plugin slows the user. If you need to do heavy work (send an email, call an API), consider firing off a background job rather than awaiting it inline.
Version your config
Include a "configVersion" key in your config.json so you can
migrate settings safely as your plugin evolves:
JSON{
"configVersion": 2,
"enabled": true
}
Log with a prefix
Use a consistent prefix like [yourplugin] so logs are greppable:
JAVASCRIPTconsole.log('[fraudguard] order flagged:', reason);
console.error('[fraudguard] lookup failed:', err.message);
Don't mutate context.req
context.req is the live Express request. Reading it is fine (headers,
user), but mutating it can have surprising effects on downstream code.
FAQ
Can I run multiple plugins at the same execution point?
Yes. All active plugins registered for a given point run in sequence, and each one's return value is passed to the next.
What happens if my plugin's extension.js doesn't exist?
The runtime logs a warning and silently skips it. No exception reaches the caller.
Do I need to restart the server after editing my plugin?
Yes for changes to extension.js (Node's require cache is
busted on load, but the file is only re-read when it's first needed after the cache
is cleared). Config-only changes are picked up on the next request because the
active-plugins cache has a 30-second TTL.
Can I access the database directly from a plugin?
Not through the plugin API. The plugin receives the request context, but not the
database. If you need DB access, either:
(a) pass the data you need in parameters from the caller, or
(b) require your models directly inside extension.js — this works because
plugins run in the same Node process, but it couples the plugin to the host schema.
What does parameters.alowuser do?
Nothing — it's a convention from the sample extension that just echoes
config.alowuser back into the payload. You can use whatever keys you want.
Can I return a Promise?
Yes. async function work(params, ctx) { ... } is fully supported. The
runtime does await Promise.resolve(mod.work(...)), so sync and async
are interchangeable.
What is context.host for?
Multi-tenant stores. Each store has its own hostname, its own plugins list, and its own config. Use it if your plugin needs to behave differently per store.
How do I disable my plugin temporarily?
Two options:
(1) set active: false in the database registration, or
(2) add a "enabled": false flag in config.json and check it
at the top of work(). The sample above uses alowuser for
the same purpose.
What's the difference between order.placed and order.approved?
order.placed fires before the order is saved to the database,
so context.orderId isn't available yet. order.approved fires
after the order is saved, so you have access to the real _id
and orderNumber.