Key ideas
The words used everywhere in the API and the events. They are the same for every value chain: a coffee mill, a tea factory, a juice plant and a soap maker all follow them.
The journey of raw material
your system the factory (Prodaksha)
----------- -----------------------
delivery leaves ── consignment ──▶ expected (pending_intake)
weighed in: intake ──▶ lot(s) consignment.received
processed: run (work order) run.completed
charged: toll statement statement.issued
or bought: purchase invoice invoice.issued
sold on your behalf: proceeds sale.proceeds
paid payment.recorded
| Word | Meaning |
|---|---|
| Company | One factory business on Prodaksha (a tenant). A token belongs to exactly one. |
| Item | Anything the factory stocks: raw material (raw), products (finished), intermediates (semi), packaging (pack), consumables. Each has a code, a base unit and other units (bag60 = 60 kg). |
| Grade | The quality class of a product: AA, AB, PB for coffee; BP1, PF1 for tea. The factory keeps one item per grade (CLEAN-AA), and events carry the grade separately. |
| Consignment | A delivery on its way, declared by the sender with its own reference_no. |
| Intake | The weighing-in of a delivery at the gate: received, rejected and accepted weight, moisture, quality. It creates a lot. |
| Variance | The difference between the declared and the received weight. Outside the factory's tolerance, it waits for the sender to approve or dispute. |
| Lot | A traceable quantity: what came in on one delivery, or what one run made. Lots link back to their inputs, so any bag can be traced to the farm deliveries in it. |
| Run (work order) | Processing: inputs go in, outputs come out by a recipe. |
| Recipe outputs | Each output has a role: main (the product), co_product (another product, such as another grade), by_product (sold, such as husks or cake), waste, and evaporation (water lost in drying or boiling). |
| Yield | Output weight as a share of input weight. Each value chain page shows the usual ranges. |
Toll or purchase
The same delivery can go two ways. The sender says which with mode.
Toll ("mode": "toll") |
Purchase (no mode, or "purchase") |
|
|---|---|---|
| Who owns the goods | The sender (society, farmer group, estate) | The factory, once received |
| What the factory earns | A fee: tariffs per kg or per bag, plus charges such as gunny bags or an export fee | Its own margin when it sells |
| What the sender gets | A toll statement to approve, then the products back, or the money from selling them (proceeds) | A self-billed purchase invoice, then payments |
| Events | statement.issued, then toll.dispatched or sale.proceeds and payment.recorded (kind: proceeds) |
invoice.issued, payment.recorded |
For toll work the factory must first set the sender up as a toll client, linked to the sender's id in your system.
Numbers and ids
reference_nois yours. It is your delivery or batch number (FPOBox usesCMB-26-41for a coffee milling batch andVAB-26-7for any other value-addition batch). The factory echoes it in every event about that delivery, even after the lots were processed several times (cherry → parchment → clean coffee).- The factory's own numbers travel in their own fields:
intake_ticket_no,work_order_ref,statement_no,invoice_no,proceeds_no,dispatch_no. - Ids are strings. The factory's ids are ULIDs (
01JD3…); treat every id as an opaque string. - Your sender id:
sender.external_systemnames your system andsender.society_idthe society or supplier in it. Together they tell the factory who is sending.
Times, quantities and money
- Times are ISO 8601 with a time zone offset:
2026-11-15T08:10:00+03:00. The factory works in its own time zone (GET /company→timezone). - Quantities always come with a
unitcode. Weights are in kg unless the unit says otherwise. - Money comes with a
currency(KES, UGX, TZS, RWF or USD). Amounts are decimals, never in cents.
