डेवलपर गाइड अंग्रेज़ी में हैं।

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.

Zero downtime. Plugins are loaded dynamically at runtime. You can add, update, or disable a plugin without restarting the server or touching core code.

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:

  1. Fetches all active plugins for the current store (host).
  2. Filters to those registered at the current execution point.
  3. For each one, verifies extension.js exists on disk and loads it.
  4. Calls the plugin's work(parameters, context) function.
  5. Feeds the plugin's return value into the next plugin in the chain.
  6. 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):

FilePurposeRequired?
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 rules. The folder name (slug) must match the 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
}
Activation criteria. A plugin only runs when all of these are 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:

FileRequiredLimit
manifest.jsonYes1 MB
extension.jsYes1 MB
config.jsonYes1 MB
screenshot.pngYes2 MB, PNG, up to 6000 × 6000 px
logo.pngOptional2 MB, PNG
README.txtOptional1 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 description from manifest.json becomes the plugin's description on the website, and screenshot.png becomes 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 version with the same slug adds 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

PointFires whenPayload 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

NameTypeDescription
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

FieldTypeDescription
context.reqObjectThe Express request object (req.headers, req.user, etc.). Read-only — don't mutate.
context.pointstringThe execution point that triggered this run, e.g. "order.approved".
context.pluginObjectYour plugin's registration record: { id, name, slug, version }.
context.configObjectContents of your config.json.
context.orderIdstring | undefinedThe order ID, when applicable (not set for order.placed since the order isn't saved yet).
context.hoststringThe 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 valueEffect
undefined or nullPayload passes through unchanged.
An objectPayload is replaced with your returned object.
An object with extra keysYour keys are merged in for callers that merge (see note below).
Merge behavior. In 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.
}
Never rely on the throw for control flow. Use it only for genuine errors. To signal "skip me", return 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.

1

Create the folder

SHELLmkdir -p extension/receiptsender
2

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
}
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;
4

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 } };
}
Deterministic order. Plugins are sorted alphabetically by 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.