Demo TerraHarvest Foods: an agribusiness and cold-chain day

Demo TerraHarvest Foods buys mangoes, coffee, and fresh vegetables from 4,800 growers across India, Kenya, and Tanzania. It operates collection centres, packhouses, refrigerated warehouses, a processing plant, and export offices. Produce arrives with variable weight and quality, is graded into saleable lots, converted into juice or frozen packs, and sold to retailers and distributors in several currencies. OSERP connects grower contracts, weighbridge tickets, quality deductions, inventory, production, cold-chain costs, export documentation, settlements, and the general ledger.

1. Create companies, farms, sites, and operating dimensions

Create a legal company for each tax jurisdiction, then branches for collection centres, packhouses, plant, cold stores, and sales offices. Configure functional currency, reporting currency, tax profile, fiscal calendar, warehouses, bins, temperature zones, cost centres, and product families. A farm or grower is a supplier party with agronomic attributes; it is not a warehouse.

Setup field	Demo value	Impact
Company	TerraHarvest Kenya Ltd	Local statutory ledger
Site	Kisumu Collection Centre	Intake ownership and logistics
Grower group	THG-042 Lake Victoria	Settlement and traceability
Crop	Export mango - Kent	Grade, season, and price rules
Cold store	KSM-FRZ-01	Temperature and custody
Currency	KES	Grower and local cost books
Reporting currency	USD	Group and export margin
Cost centre	CC-PACK-KSM	Packhouse accountability

Company setup stores legal name, registration number, address, timezone, tax registrations, numbering series, rounding precision, default accounts, and period status. User scope includes company, site, warehouse, and role. A collection-centre clerk can receive fruit but cannot change the grade tariff or approve a settlement override.

2. Register growers and season contracts

Grower profiles store legal name, grower code, farm locations, bank or mobile-money details, tax status, certification, cooperative, currency, language, and active status. A grower can have multiple farms and crops. Identity and bank changes require verification and an audit event because a settlement destination is a high-risk field.

The seasonal contract stores grower, crop, variety, expected quantity, harvest window, quality bands, price formula, premium or penalty, delivery site, payment terms, advance, certification, currency, and approval. Contract versions preserve changes to quantity or tariff. A grower advance is tracked as a recoverable balance and is deducted from approved deliveries; it is never treated as purchase cost twice.

Example: THG-042 delivers Kent mangoes under a KES price of 78 per kilogram for Grade A, 54 for Grade B, and 22 for processing. A sustainability premium of KES 4 applies to certified lots. The accepted grade and premium are stored on each intake ticket so a later tariff change cannot rewrite historical settlements.

3. Capture weighbridge intake and quality grading

The intake header stores ticket number, grower, farm, crop, vehicle, driver, site, arrival time, gross weight, tare weight, net weight, container, and status. Detail rows store lot, variety, harvest date, field, quantity, UoM, grade, moisture, foreign matter, maturity, damage, pesticide test, certification, and disposition.

Intake field	Demo value	Why it matters
Ticket	KSM-INT-260917-0042	Permanent trace key
Gross weight	2,840 kg	Weighbridge evidence
Tare	640 kg	Removes vehicle/container mass
Net weight	2,200 kg	Purchase quantity before deductions
Grade	A 1,540 kg / B 520 kg / process 140 kg	Price and yield rule
Temperature	11.8 °C	Cold-chain acceptance control
Rejection	0 kg	Keeps supplier and waste history

The quality engine validates that grade quantities equal accepted net weight and applies configurable deductions. A temperature above the threshold routes the lot to inspection or rejection. A rejected lot remains traceable to the ticket and supplier notice; staff must not delete it or silently reduce weight.

4. Settle growers fairly and transparently

The grower settlement statement groups approved intake tickets by contract and period. It shows grade quantity, tariff, premium, deduction, gross amount, advance recovery, packaging charge, transport recovery, withholding tax, mobile-money fee, and net payable. Each row links to ticket, lot, quality result, and approval.

For THG-042, Grade A is KES 120,120, Grade B KES 28,080, and processing KES 3,080. A KES 10,000 advance recovery and KES 1,200 packaging recovery produce KES 140,080 before withholding. The statement records the calculation, not only the final amount. A duplicate ticket or bank/mobile reference is rejected idempotently.

Settlement statuses are Draft → Quality approved → Finance reviewed → Approved → Paid, with controlled Disputed, Held, and Reversed. A dispute stores reason, evidence, owner, due date, and resolution. A reversed payment references the original settlement and new correction; history remains immutable.

5. Move lots through collection, packhouse, and cold store

Lot records store crop, variety, source farm, harvest date, grade, quantity, UoM, ownership, cost, bin, temperature zone, expiry or best-before date, certification, and status. Transfers record source site, destination, vehicle, dispatch time, receipt time, quantity, temperature readings, loss, and receiving user.

The cold-store log records room, lot, entry/exit, temperature minimum and maximum, humidity, alarm, corrective action, and supervisor. A temperature excursion creates a quality hold and prevents sale or production consumption until disposition. Shrinkage is classified as handling loss, spoilage, measurement variance, or unexplained variance, each with a reason and approval.

6. Process, pack, and track yield and by-products

A production order stores product, recipe or bill of materials, plant, line, batch, planned quantity, expected yield, start/end, labour, energy, and quality plan. Consumption rows issue raw lots; output rows create finished lots, co-products, and by-products. Every output retains source lots for recall.

Example: 1,000 kg of Grade B mango produces 620 kg of puree, 280 kg of peel and seed by-product, and 100 kg of process loss. The production record explains the yield, allocates conversion cost by configured method, and routes abnormal loss to an exception. A finished puree batch cannot be released until pH, brix, microbiology, packaging, and label checks are complete.

Packaging items use UoM conversion, lot, expiry, supplier, and specification. A label change is versioned. A recall can search finished batch, raw lot, customer invoice, shipment container, and grower tickets in either direction.

7. Buy packaging, fertiliser, and cold-chain services

Purchase requests store site, cost centre, item, specification, required date, quantity, budget, and supplier. Purchase orders preserve currency, tax, incoterm, delivery schedule, inspection, and contract. Receipts capture accepted and rejected quantity, lot, expiry, temperature, and condition. Supplier invoices match against order and receipt.

Imported cartons priced in EUR record freight, insurance, duty, port charges, and local valuation. Refrigerated transport invoices store route, vehicle, pallet count, temperature report, fuel surcharge, currency, and service period. A three-way mismatch or missing temperature evidence routes to review instead of forced payment.

8. Sell locally and export with traceable lots

Customer profiles store legal identity, tax, country, credit limit, currency, incoterm, bank, and delivery locations. Sales orders store product, grade, lot requirement, quantity, price basis, currency, delivery window, packing, tax, and quality certificate requirement. Allocation reserves lots by FEFO and certification.

An export shipment stores booking, container, seal, vessel, port, origin, destination, bill of lading, certificate of origin, phytosanitary certificate, insurance, freight, and status. Partial shipment reduces open quantity and preserves the remaining commitment. A customer claim references invoice, lot, survey, temperature history, quantity, amount, currency, reserve, and resolution.

Invoices retain order, delivery, lot, tax, currency, rate, payment terms, and revenue account. A USD customer payment against a KES cost base records applied rate and realised FX. The invoice amount is never edited to make FX disappear.

9. Allocate landed cost and calculate margin

Cost allocation separates grower purchase, packaging, collection transport, cold storage, processing labour, energy, quality testing, export freight, insurance, duty, financing, and FX. Allocation rules can use weight, quantity, value, pallet, or container. The rule and basis are stored on the cost document.

The margin dashboard shows physical received, accepted, processed, saleable yield, loss, committed sales, shipped, billed, collected, cold-storage days, cost per kilogram, gross margin, and contribution by crop, grower group, site, customer, and currency. A product can be profitable in USD but appear negative in KES after revaluation; both views remain visible.

10. Close the season and reconcile custody

Close reconciles grower contracts to intake tickets, quality grades to settlements, lots to bin balances, production consumption to output, cold-store statements to book stock, customer shipments to invoices, supplier bills to receipts, advances, claims, tax, payroll, assets, FX, and intercompany transfers. Seasonal inventory is reviewed for expiry, slow movement, and net realisable value.

Each close task stores owner, expected balance, actual balance, variance, evidence, reviewer, and sign-off. Period lock blocks backdated intake or grade changes. An approved correction creates a linked adjustment with reason and authorisation. Intercompany transfers between Kenya, Tanzania, and India use mirrored documents and matching due-to/due-from accounts.

KPI	Before OSERP discipline	After OSERP discipline	Improvement
Grower settlement cycle	14 days	3 days	79% faster
Grade-to-payment disputes	9.6%	2.4%	75% lower
Cold-chain traceability	86%	99.5%	+13.5 points
Finished-yield variance	8.1%	3.0%	63% lower
Export claim resolution	24 days	8 days	67% faster
Seasonal close	22 days	8 days	64% faster

Practice challenge

Create the Kenya company, collection site, grower contract, weighbridge ticket, grade results, seasonal settlement, cold-store transfer, temperature excursion, production order with yield and by-products, imported packaging receipt, export sales order, lot allocation, shipment documents, customer claim, multi-currency receipt, landed-cost allocation, and seasonal close. For every field, explain its type, length or precision, source, permission, validation, accounting impact, tax result, API identifier, exception path, and audit event.

Related: Inventory field guide, Procure-to-pay lab, AR Invoice field guide, AP Invoice field guide, GL mapping guide, Multi-currency lab, Warehouse replenishment, and API cookbook.