BI and KPI Expectations

This page defines business-level BI and KPI requirements for the headless stack. It describes what must be measurable and reportable, not how analytics are implemented.

Principles

• Facility-first operations, org-wide rollups for analytics.
• Temporal truth: KPIs tie to as-of inventory, cost, and price snapshots.
• Cross-service traceability: every KPI can drill down to source records and events.
• Sliceability by org, facility, channel, category, and time bucket.
• Near-real-time for operational KPIs; batch is acceptable for deep analysis.
• Default alert thresholds are defined per KPI and governed by org policy; inbox alerts are emitted when thresholds are breached.
• Default alert thresholds can be tuned by vertical (grocery, apparel, hardgoods) and channel (ecom, wholesale, POS).

KPI dictionary

• Formal formulas, inclusion/exclusion rules, and default alert thresholds: /common/bi-kpi-dictionary.html.

Profile selector matrix (onboarding defaults)

• Select a vertical + channel profile, then apply seasonal and regional modifiers from the KPI dictionary.
• If multiple channels are active, choose a primary profile and override per channel as needed.

Vertical	Channel	Suggested profile key	Notes
Grocery	POS	grocery-pos	Strict availability, FEFO focus, high throughput.
Grocery	Ecom	grocery-ecom	Tight SLA, higher substitution tolerance.
Grocery	Wholesale	grocery-wholesale	Large orders, longer lead times.
Apparel	POS	apparel-pos	Fit exchanges, returns sensitivity.
Apparel	Ecom	apparel-ecom	High returns, promo-driven demand.
Apparel	Wholesale	apparel-wholesale	Case packs, longer replenishment cycles.
Hardgoods	POS	hardgoods-pos	Pick accuracy and damage control.
Hardgoods	Ecom	hardgoods-ecom	Carrier damage risk, longer cycle time.
Hardgoods	Wholesale	hardgoods-wholesale	Bulk order cadence and lead time tolerance.

Rebalancing

• Rebalancing policies and guardrails: /common/rebalancing.html.

Core dimensions and time buckets

• Time buckets: hourly, daily, weekly, monthly, seasonal, fiscal.
• Dimensions: org, logical facility, zone/bin, channel, taxonomy, supplier, customer segment, campaign, tender type, and cost centre.
• Filters: region/market, sales channel, procurement channel, and fulfillment method.

KPI catalog (by domain)

Inventory and warehouse (ICS)

• Inventory position: on-hand, available, reserved, allocated, in-transit, quarantine, damaged, consignment-held.
• Inventory accuracy: count variance, shrink rate, adjustment rate.
• Stockout rate, backorder rate, and fill rate.
• Pick/pack/ship cycle time and accuracy.
• Receiving cycle time, over/under receipt rate, and QC hold rate.
• Transfer lead time, on-time transfer rate, and short-ship rate.
• Aging inventory and expiry risk (FIFO/FEFO compliance).
• Space utilization, putaway adherence, and staging congestion.

Sales and fulfillment (SCM)

• GMV, net sales, order count, units, and average order value.
• Margin and GMROI by facility, channel, and category.
• Order cycle time, on-time ship, late delivery, and partial fulfillment rate.
• Cancellation rate, substitution rate, and no-show rate (BOPIS/curbside).
• Return rate, return reasons, refund leakage, and exchange rate.
• Tender mix, gift card usage, store credit usage, and chargeback rate.

Pricing and promotions (PPM)

• Realized price vs list, discount depth, and markdown effectiveness.
• Promo lift, incremental margin, and promotion ROI.
• Override rate, price compliance vs min/max, and approval latency.
• Dynamic/surge pricing activations, guardrail breaches, and exception counts.
• Coupon redemption rate, stacking incidence, and fraud signals.

Procurement (PCM)

• Open-to-buy usage, weeks of supply, and over/under buy flags.
• Vendor lead time mean/variance, fill rate, and on-time delivery.
• PO cycle time, expedite rate, and partial receipt rate.
• Invoice match rate, discrepancy rate, and tolerance breaches.
• Landed cost variance, freight/tariff impact, and FX impact.
• RTV rate and credit recovery time.

CRM and loyalty

• Active customers, retention, churn, repeat rate, and LTV.
• Loyalty liability, earn vs redeem, and breakage.
• Tier distribution, tier migration, and abuse flags.
• Consent coverage and privacy compliance coverage.

Influencer and affiliate

• Attributed revenue, orders, units, and conversion rate.
• Earnings vs payable vs paid, hold rate, and clawback rate.
• ROI by campaign, channel, and influencer tier.
• Fraud and abuse indicators (self-referral, anomalous patterns).

Accounting readiness

• Inventory valuation by facility and channel.
• COGS by category, channel, and time bucket.
• Tax collected vs refunded by jurisdiction.
• Liability balances: gift cards, store credits, loyalty, influencer payouts.
• Traceability coverage: percent of financial events linked to source records.

KPI outputs and governance

• KPIs are org-scoped and facility-aware with role-based access.
• Provide drill-down from KPI to source records.
• Support exception thresholds and alerts for out-of-policy states.
• Preserve historical KPI values for at least 24 months.

KPI query surfaces (IPM)

• Query and record KPIs via IPM:
  • POST /ipm/kpi/query
  • POST /ipm/kpi/record
  • POST /ipm/kpi/alert (records an alert and can deliver to inbox).
• Export contracts aligned to event streams: POST /ipm/export/contract/list.

Related pages

• /common/eventing-auditability.html
• /common/request-context.html
• /common/storage-billing.html