# Analytics Metric Catalogue

- Status: Draft — definitions are approved individually
- Version: 0.1.0
- Last updated: 2026-08-20

Every merchant-facing number must identify its grain, formula, source fields, filters, time basis, unit, missing-data behavior, trace path, and definition version.

## Confirmed successful sessions

- Canonical id: `confirmed_successful_sessions`
- Grain: distinct payment session
- Formula: count payment sessions where source `session_status = 'Verified'`
- Unit: sessions
- Time attribution: session `created_at`, converted to `Asia/Tehran` local reporting date
- Missing behavior: `session_status` is required; unknown values are not counted and trigger quality evidence
- Traceability: drill down to eligible session identifiers and their attempt histories within the authenticated merchant
- Approved decision: `Paid` is not included; it remains a separate state until ZarinPal provides an authoritative definition

## Paid but not confirmed as verified

- Canonical id: `paid_unverified_sessions`
- Grain: distinct payment session
- Formula: count payment sessions where source `session_status = 'Paid'`
- Unit: sessions
- Presentation: separate operational state; never label as confirmed success or failure
- Traceability: same merchant-scoped session/attempt drill-down

## Open definitions

- Success-rate denominator and treatment of `Failed`/`Reversed`/`Paid`
- Amount metric inclusion by session status
- Retry and recovery definitions
- Timing percentile definitions and missing coverage
- Fee-ratio terminology for obfuscated `adjusted_fee`
- Merchant-weighted versus transaction-weighted peer comparisons