Skip to main content

Rating traceability

This guide defines a repeatable trace method across billing entities for incident response and support evidence.

Trace chain​

  • Event: source fact captured at ingest boundary.
  • Rating: pricing/cost decision snapshot.
  • Rated record: per-meter decomposition of rating.
  • Allocation: funding application and settlement state.
  • Attribution (where available): business ownership mapping for rating.

Join keys and linkage rules​

  • rated_record.rating_id -> rating.rating_id
  • allocation.rating_id -> rating.rating_id
  • allocation.reversal_of_allocation_id -> prior allocation.allocation_id (reversal chain)
  • rating.reversal_of_rating_id -> prior rating.rating_id
  • attribution.rating_id -> rating.rating_id

Use ids above as authoritative joins for incident evidence.

Cardinality expectations​

  • One event can lead to zero, one, or multiple ratings.
  • One rating can contain multiple rated records.
  • One rating can map to multiple allocations (for example split funding or reversals).
  • One rating can have multiple attribution rows.

Query defaults that affect trace outcomes​

  • Ratings list defaults to sort_by=rated_at, sort_order=desc.
  • Rated-records list defaults to sort_by=created_at, sort_order=desc.
  • Allocations list defaults to sort_by=rated_at, sort_order=desc.
  • allocations.expand=rating inlines rating.
  • allocations.expand=rating.rated_records inlines both rating and rated records.
  • ratings.expand=rated_records inlines decomposition records for direct rating inspection.

Investigation playbook​

  1. Start from disputed amount/time/account.
  2. Pull candidate ratings in the chosen time basis.
  3. Expand or fetch rated records to verify meter-level decomposition.
  4. Pull allocations for those ratings and verify funding path: funding_kind, application_status, settlement_state, reversal_of_allocation_id.
  5. For ownership disputes, inspect attribution rows tied to the same rating_id.
  6. Use revenue report as aggregate confirmation only.

Allocation-state checks to always perform​

  • application_status: confirm whether amount was applied, clipped, reversed, quarantined, or failed.
  • settlement_state: confirm settlement progress (pending -> settling -> settled) or failure/void.
  • late_rating: identify ratings applied after the primary usage window.
  • reason_codes: preserve machine-readable reasons in incident notes.

What commonly breaks reasoning​

  • Mixing event time and rating time windows.
  • Assuming one rating always maps to one allocation.
  • Ignoring allocation reversals and reading only latest debit rows.
  • Treating aggregate report output as if it were the settlement ledger itself.
  • event ids (if source-fact dispute)
  • rating id + rated record ids
  • allocation ids and reversal links
  • funding kind + application/settlement statuses
  • exact time basis and query filters
  • request/window context (billing_account_id, from/to, sort basis)

Minimal trace checklist (copy into incident template)​

  1. billing_account_id, time basis, from/to, and sort configuration.
  2. Rating ids and their rated-record ids.
  3. Allocation ids with reversal links.
  4. Funding kind + application/settlement states.
  5. If ownership dispute: attribution ids and attribution kind/id pairs.

Verification checklist​

  • Quantity and amount decomposition in rated records explains the rating.
  • Allocation sums and statuses explain the applied/settled outcome.
  • Any reversal is explicitly tied to prior allocation/rating ids.
  • Ownership conclusions (if used) are backed by attribution rows, not by assumptions.

Next​