For developers

Put a business’s items on its own website

The ChuruzaPOS Catalogue API gives a business’s website everything it sells, with prices, photos and what is in stock, and webhooks tell the website within about a minute when anything changes. Items are managed in ChuruzaPOS; the website only reads them.

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 (product or menu_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 product for a shop’s, pharmacy’s or salon’s goods and services; menu_item for a bar’s or restaurant’s menu.
  • kind goods, service, membership, package, combo or menu.
  • price The branch’s selling price, VAT included as at the till. null means 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, or always for a service. quantity is 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.item is the item.
  • item.updated Something the site would show changed. data.item is 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.item has 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.

Updated 2026-11-13

Frequently asked questions

Can a website change prices or stock through the API?

No. The Catalogue API is read only: items, prices, photos and stock are managed in ChuruzaPOS, and the website follows them.

Does it work for bars and restaurants?

Yes. A bar or restaurant branch gives its menu items with today’s prices, the sizes a drink is served in and whether a dish is sold out.

Can the website show exact stock?

Only if the business switches it on for that website. Otherwise each item says in stock, low or out of stock.

How quickly does the website hear of a change?

Within about a minute: ChuruzaPOS looks for changes once a minute and calls the webhook address for each item that changed.

Where do I get an API key?

From the business: in ChuruzaPOS, Settings, Your website, Connect a website. The key is shown once.

Let’s talk about your business.

Call or write to us for a demonstration on your own kind of business.