Skip to main content
The Cost Intelligence dashboard combines two deliberately separate financial views:
  • Calculated costs come from the immutable PostgreSQL cost ledger and its rebuildable ClickHouse analytics projection.
  • Finalized revenue comes from finalized or closed billing invoices and fees.
Estimated event revenue is used only for real-time decisions such as /can. It is never added to finalized billing revenue.

​
Report sections

The dashboard provides:
  • Feature profitability: directly attributable finalized usage revenue minus Feature and linked detailed costs.
  • Customer profitability: finalized usage and fixed subscription revenue minus direct and allocated shared costs.
  • Cost Events: individual detailed ledger entries with customer, parent Feature Event, quantity, dimensions, and amount.
  • Shared Costs: allocated Shared Period Cost ledger entries.
  • Uncosted: Feature Events and Cost Events that need a rule, parent, or configuration correction.
  • Conflicts: asynchronously detected identifier reuse where the same identifier arrived with a different payload.
Fixed subscription revenue remains at customer and company level in Version One. Nozle does not invent a Feature allocation for it.

​
Currency rule

Each organization selects one reporting currency for Cost Intelligence. Cost Rules and Shared Costs must use that currency. Values in other currencies are not combined without an immutable conversion rate.

​
Cost report endpoint

GET /cost-intelligence/report needs a secret key; with API key permissions, the key needs analytic:read. It returns the calculated cost portion of the report. It reads aggregated ledger projections from ClickHouse and the authoritative Uncosted queue from PostgreSQL. The dashboard’s GraphQL layer adds finalized billing revenue afterward. The optional from and to query parameters take an RFC3339 timestamp or a YYYY-MM-DD date, in Coordinated Universal Time; from_date and to_date are accepted as aliases. For timestamps, from is inclusive and to is exclusive. A plain date from starts at 00:00 UTC that day, and a plain date to includes that whole day (the range ends at the start of the next day). With neither, the report covers the last month. With only to, it covers the month before to. With only from, it runs from from until now (one month after from if from is not in the past). A value that cannot be parsed, or an end that is not after the start, returns 400 with {"code": "invalid_date_range", "error": "the end of the range must be after its start"}. limit applies independently to each breakdown and detail collection and is capped at 500. A linked Cost Event that remains in pending_parent for 24 hours is moved to uncosted with parent_resolution_deadline_exceeded so it remains visible for review instead of waiting forever.

​
Finalized revenue

The dashboard’s GraphQL layer (nozleCostIntelligenceReport: summary, features and customers) adds finalized revenue to the calculated cost.
  • By service period. A fee counts for the share of its service period that falls inside the report range: the charges period for a usage fee, the fixed charges period for a fixed charge fee, the subscription period for a subscription fee, prorated by time when the period crosses the range. September usage invoiced on October 1 is September revenue, the same range as its cost. A fee without a service period (an add-on or a credit) counts on its invoice’s finalization date. Before, every fee counted on the finalization date.
  • Currency units. Revenue is in major units of the report currency, rounded to its decimals: a 100,000 JPY fee is 100000 and a 12.345 KWD fee is 12.345. Before, every currency was divided by 100.
  • costStatus. Each breakdown row has costStatus, loaded or not_loaded. When the cost query returned only the top limit keys by cost and a key with revenue is not among them, its cost is unknown: cost and finalizedMargin are null, costStatus is not_loaded, and the row sorts after the costed rows. cost and finalizedMargin can therefore be null. Before, such a row showed a cost of 0 and a margin equal to its whole revenue. Raise limit to load them.

​
Recovery

Administrative replay is intentionally narrow:
  • An uncosted Feature Event or an uncosted or pending Cost Event can be rated again after configuration is corrected.
  • A PostgreSQL ledger entry can be requeued for ClickHouse projection.
  • A source that already created ledger entries cannot be replayed as new money.
PostgreSQL remains the financial source of truth. ClickHouse can be rebuilt or replayed without changing the ledger.