What a website gets
Every item one branch sells, as that branch sells it. A supermarket, shop, wholesaler, pharmacy or salon branch gives its products and services at the branch’s own prices, with whether each is in stock. A bar or restaurant branch gives its menu at today’s prices, with the sizes a drink is poured in and whether a dish is sold out.
Prices, names, groups and photos are changed in ChuruzaPOS, by the business, and the website follows. Nothing is written back: the API has no way to change an item, take an order or see sales.
Get a key
The business owner or manager connects the website in ChuruzaPOS: Settings → Your website → Connect a website. They choose the branch the site shows, and may give the address the site wants to be told of changes at. ChuruzaPOS then shows the site’s API key, and the webhook signing secret, once. Ask the business for both.
A key can be replaced (the old one stops at once) or the website disconnected from the same screen. Exact quantities are hidden unless the business switches them on for that site; otherwise each item says in stock, low or out of stock.
Calling the API
Send the key on every call, as Authorization: Bearer chz_… or as X-Api-Key: chz_…. Call it from your server where you can: a key in a web page can be read by anyone, though it only shows the same catalogue the site already shows. Browsers may call it too: every origin is allowed, without cookies.
- GET /catalog The business, the branch and how many items it has.
- GET /catalog/groups The groups the items are in (Dairy, Spirits, Hair), with how many items each.
- GET /catalog/items The items, a page at a time. Filters:
q(name, code or barcode),group(a group id),type(productormenu_item),available=true(leaves out what is out of stock),page,page_size(up to 500, 100 if not said). - GET /catalog/items/{id} One item.
The items, a page at a time
curl https://api.churuzapos.com/api/v1/catalog/items?page=1&page_size=100 \
-H "Authorization: Bearer chz_your_key"
{
"data": [ { …item… }, { …item… } ],
"page": 1,
"page_size": 100,
"pages": 4,
"total": 362
}
An item
One item from GET /catalog/items
{
"id": "5f89f797-5343-492c-8e12-5d8a6a359419",
"type": "product",
"kind": "goods",
"code": "DM-001",
"name": "Inyange Fresh Milk 500ml",
"description": null,
"group": { "id": "0c1d…", "name": "Dairy" },
"outlet": null,
"parent": null,
"variant": null,
"price": 700,
"currency": "RWF",
"unit": "PCS",
"pack": { "name": "CRATE", "size": 12, "price": 8000 },
"options": [],
"barcodes": ["6009880780013"],
"image_url": "https://api.churuzapos.com/api/v1/catalog/images/product/5f89f797-…?v=425871a178",
"availability": "in_stock",
"prescription_only": false
}
- type
productfor a shop’s, pharmacy’s or salon’s goods and services;menu_itemfor a bar’s or restaurant’s menu. - kind
goods,service,membership,package,comboormenu. - price The branch’s selling price, VAT included as at the till.
nullmeans the price is given at the counter: a product with no price yet, or a service priced at each sale. - pack The pack it is also sold in (a crate of 12), with the pack’s own price when it has one.
- options For a drink, the sizes it is served in, each with its price (a tot, a glass, a bottle).
- parent and variant A size or colour of a style: the style is not listed itself, each of its variants is, naming it.
- availability
in_stock,low(at or under the branch’s minimum),out_of_stock, oralwaysfor a service.quantityis added only when the business shows quantities to this site. - outlet For a menu item, the bar or restaurant whose menu it is on.
- prescription_only A pharmacy’s medicine that needs a prescription.
Photos
Each item can have one photo, added by the business on the item’s form. image_url is a public address: put it straight in an <img src>, no key needed. It sends the browser on to the stored picture. The part after ?v= changes when the photo changes, so a cached copy never stays old. image_url is null when there is no photo.
Webhooks: being told of changes
When the business gives a webhook address, ChuruzaPOS looks at the site’s items about once a minute and calls the address for each item that changed since the site was last told: a new item, a price, a name, a photo, a group, stock running out or coming back, a dish sold out. Whatever changed it, a sale at the till, a delivery or an import, the call is the same. Read the whole catalogue once through the API when the site is connected: the first look records what is there and sends nothing.
- item.created An item the site does not have yet.
data.itemis the item. - item.updated Something the site would show changed.
data.itemis the item as it is now: replace yours. - item.deleted No longer sold here (taken off sale, off this branch’s list, or off the menu).
data.itemhas only the id. - ping The Test button in ChuruzaPOS.
A call to the website
POST https://your-site.example/churuza-webhook
Content-Type: application/json
User-Agent: ChuruzaPOS-Webhooks/1.0
X-Churuza-Event: item.updated
X-Churuza-Delivery: 5181fca9-da65-41e1-9852-d5c17c4ef1bf
X-Churuza-Signature: t=1763060000,v1=6f1c…
{
"id": "5181fca9-da65-41e1-9852-d5c17c4ef1bf",
"event": "item.updated",
"created_at": "2026-11-13T18:04:20.000Z",
"business_id": "c50040cd-…",
"branch_id": "b6d627fd-…",
"data": { "item": { …the item as the API gives it… } }
}
Answer with any 2xx status within 10 seconds, and do the work afterwards. Any other answer, or none, is tried again after 1, 2, 5, 10, 30, 60, 120, 360 and 720 minutes, then given up; the business sees each call and its answer under Settings → Your website. A call can arrive twice or out of order: id is the same on every try of one call, and an item’s latest state is always what the API gives.
Checking a call came from ChuruzaPOS
Each call is signed with the website’s secret. X-Churuza-Signature is t=<unix seconds>,v1=<hex>, where v1 is the HMAC-SHA256 of the time, a full stop and the body exactly as it was sent. Refuse a call whose signature does not match, or whose time is more than a few minutes old.
Node.js
import crypto from 'node:crypto'
// rawBody: the request body exactly as received, before any JSON parsing.
export function fromChuruza(rawBody, header, secret) {
const [, t, v1] = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header ?? '') ?? []
if (!t) return false
if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false // older than 5 minutes
const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex')
return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1))
}
PHP
<?php
$raw = file_get_contents('php://input');
$header = $_SERVER['HTTP_X_CHURUZA_SIGNATURE'] ?? '';
$secret = getenv('CHURUZA_WEBHOOK_SECRET');
if (!preg_match('/^t=(\d+),v1=([0-9a-f]{64})$/', $header, $m) || abs(time() - (int)$m[1]) > 300) {
http_response_code(400); exit;
}
$expected = hash_hmac('sha256', $m[1] . '.' . $raw, $secret);
if (!hash_equals($expected, $m[2])) { http_response_code(400); exit; }
$event = json_decode($raw, true);
// Save $event['data']['item'] (or remove it on item.deleted), then answer quickly:
http_response_code(200);
Errors
- 401 No key, a key that was replaced, or a website that was disconnected.
- 404 No such item on this website (it may have been taken off sale), or no photo.
- 429 Over 120 calls in a minute. Keep a copy of the catalogue on your side and use the webhook for changes.
Errors come as JSON with a message in plain words. For help call 0788 816 277 or write to team@churuzapos.com.