Developers

PLUX API & webhooks

Connect your own website, accounting or other tools to your business on PLUX. Read your price list, place and follow orders, and get told the moment something happens.

Keys

The business owner creates keys in Settings → Developers. A key is shown once; PLUX keeps only a fingerprint of it. Send it on every request:

curl https://plux.africa/api/v1/me \
  -H "Authorization: Bearer plux_live_..."

• Live keys (plux_live_…) work with real business data.
• Test keys (plux_test_…) can read the price list and try out orders: the order is priced and checked for real, then discarded (livemode: false). They never read orders, customers, payments or stock.
• Each key carries only the scopes it was given. Keep keys on your server — never in a web page or mobile app.
• Revoke a key in Settings and it stops working at once.

Requests and answers

• JSON in and out, over https. Money is whole kobo (250000 = ₦2,500). Times are ISO 8601 in UTC.
• Lists return { data, has_more, next_after }. Ask for the next page with ?after= the next_after value; limit is 1–100 (25 by default).
• Errors return { error, code } with status 401 (bad key), 403 (missing scope, or a test key on live data), 404, 422 (invalid input) or 429.
• Each key may make 120 requests a minute.

Endpoints

Placing orders

Send product ids and quantities. PLUX works out the prices, charges and total from your price list — a price in the request is ignored. The order then follows the business's own rules, exactly like an online order: it is sent on automatically or waits for staff, and large orders can wait for a manager.

curl -X POST https://plux.africa/api/v1/orders \
  -H "Authorization: Bearer plux_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "idempotency_key": "web-order-20481",
    "customer": { "name": "Chidi Okafor", "phone": "08030001111" },
    "lines": [ { "product_id": "PRODUCT_ID", "quantity": 2, "option_ids": [] } ],
    "notes": "Call on arrival"
  }'

• idempotency_key (8–80 characters) is required. Sending the same key again returns the same order instead of creating another, so a retry after a timeout is safe.
• Optional: branch_id (the first branch otherwise) and service_type (takeaway, dine_in or delivery).
• Order status is one of new, confirmed, queued, in_progress, ready, handed_over, completed, cancelled; stage gives the business's own step name.

Webhooks

Add an https URL in Settings → Developers and choose the events you want. PLUX POSTs each event to it as JSON within a few seconds. Answer with any 2xx status within 8 seconds.

{
  "id": "evt_cmg1x...",
  "type": "order.ready",
  "created_at": "2026-10-02T11:04:31.512Z",
  "business_id": "...",
  "branch_id": "...",
  "entity": { "type": "order", "id": "..." },
  "order_id": "...",
  "payment_id": null,
  "channel": "WEB",
  "amount_kobo": null,
  "reason": null,
  "actor": { "kind": "staff", "role": "MANAGER" },
  "data": {}
}

Check the signature

Every delivery carries PLUX-Signature: t=<unix seconds>,v1=<hex>. Compute HMAC-SHA256 of `${t}.${rawBody}` with your signing secret and compare. Reject anything older than five minutes.

import { createHmac, timingSafeEqual } from "node:crypto";

function fromPlux(rawBody, header, secret) {
  const [t, v1] = header.split(",").map((p) => p.split("=")[1]);
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const mine = createHmac("sha256", secret).update(t + "." + rawBody).digest("hex");
  return mine.length === v1.length && timingSafeEqual(Buffer.from(mine), Buffer.from(v1));
}

• A failed delivery is retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours. After that it is marked failed and can be sent again from Settings.
• The same event can arrive more than once and not always in order: use id to ignore repeats and created_at to order.
• After 15 failed attempts in a row PLUX switches the webhook off and flags it on the owner's dashboard. Switch it back on in Settings.
• Redirects are not followed. Use “Send test” to receive a webhook.test event.
• Missed something? GET /api/v1/events?after=evt_… returns the same events in order.

Events

Event names never change once published. New fields may be added to an event; ignore the ones you don't use.