Guides
StatusDashboard

Analytics and Observability

Test rules in shadow mode, measure their impact with performance reports and backtesting, and interpret decline results.

Overview

Authorization Rules include several tools for testing and measuring rules before and after they affect live transactions:

  • Shadow mode lets a draft rule observe live transactions without affecting outcomes
  • Performance reports provide daily statistics on how each version of a rule evaluated transactions
  • Backtesting simulates a rule against historical transactions
  • Rule results explain, per transaction, which rules affected the outcome and why

Together these let you validate a rule's behavior before promoting it and continue monitoring it once it is active.

Shadow Mode

When you draft a rule, it runs in shadow mode. The rule evaluates live transactions in real time and logs how it would have affected each one, but it does not change any authorization outcome. This lets you measure a rule's real-world impact before promoting it to active.

Use shadow mode together with performance reports to confirm a rule behaves as intended before it affects live authorizations.

For how to draft, promote, and disable rules, see Authorization Rule Lifecycle.

Performance Reports

Performance reports are generated daily and provide daily statistics for each version of a rule that evaluated transactions during the period, including both the active version and any shadow (draft) version. Retrieve a report with the GET /v2/auth_rules/{auth_rule_token}/report endpoint.

Reports cover recent history and support a maximum interval of 31 days per request. Report data is available through the previous day in UTC; the current day's data is not yet available.

Each day's statistics contain a versions array. Each version reports:

  • version: the rule version number
  • state: the version's evaluation mode during the period (ACTIVE, SHADOW, or INACTIVE)
  • action_counts: a map of action type to the number of times that action was taken by this version. Evaluations where the rule took no action are counted under NO_ACTION
  • examples: example events for the version
{
  "auth_rule_token": "cbab2546-b597-4b17-903e-3e392c10ed64",
  "begin": "2025-11-19",
  "end": "2025-12-18",
  "daily_statistics": [
    {
      "date": "2025-12-11",
      "versions": [
        {
          "version": 2,
          "state": "ACTIVE",
          "action_counts": {
            "DECLINE": 8,
            "NO_ACTION": 1043
          },
          "examples": []
        },
        {
          "version": 3,
          "state": "SHADOW",
          "action_counts": {
            "DECLINE": 21,
            "NO_ACTION": 1030
          },
          "examples": []
        }
      ]
    }
  ]
}

In this example, the active version (2) would decline 8 transactions on the day, while the shadow version (3) would decline 21, letting you compare the impact of a draft change before promoting it.

📘

The examples array is retained for compatibility but is not currently populated, so example events are not returned in performance reports. For the full report schema, see the Performance Report API.

Checking Calculated Feature Values

For Velocity Limit Rules and rules that use transaction-count or other behavioral attributes, you can retrieve the current calculated feature values for a specific card or account using the GET /v2/auth_rules/{auth_rule_token}/features endpoint. This is useful for debugging, for example, to check how much of a card's velocity window has been consumed.

Provide the relevant query parameter:

  • card_token: required for card-scoped velocity limits and transaction-count attributes
  • account_token: required for account-scoped velocity limits

The response includes the current amount and transaction count tracked against each velocity window or count attribute on the rule.

Backtesting

Backtesting simulates a rule against historical transactions to estimate how it would have performed in the past. It is especially useful when making significant changes to a rule, since it provides a data-driven way to evaluate impact before promoting.

📘

Backtesting is part of Lithic Fraud Command. It is available for the supported rule types; velocity-based rules are generally not backtestable. To learn how to initiate backtests, interpret results, and apply best practices, see Backtesting Authorization Rules.

Understanding Rule Results

When a rule blocks a transaction, the Lithic transaction object records this in a rule_results array on the transaction event. This array helps you understand exactly which rules affected the transaction and why.

Each transaction event contains a rule_results array. It is always present and is empty for transactions that no rule affected. An entry is added when a rule affects a transaction, whether the rule is one you configured or a Lithic-configured rule (such as a mandatory bank limit).

"rule_results": [
  {
    "auth_rule_token": "ef49df0c-ed17-44cb-811b-6de1ec0f088a",
    "name": "Block foreign country rule",
    "result": "AUTH_RULE",
    "explanation": "The rule declined the transaction because the COUNTRY value of CAN failed the parameter evaluation of COUNTRY IS_NOT_ONE_OF USA."
  }
]

Each entry contains:

  • auth_rule_token: the token of the rule responsible for the result, or null if the result came from a Lithic-configured rule
  • name: the name of the rule, if one was configured
  • result: the detailed result associated with the rule's decision (for example, AUTH_RULE). For the full set of values, see the transaction object
  • explanation: a human-readable explanation of the rule's decision

Using these values, you can identify which rule caused a decline and the specific evaluation behind it. If the decline was undesirable, look up the rule by its auth_rule_token and adjust its parameters.

Tokenization events also include a rule_results array following the same structure, except the result value is one of APPROVED, DECLINED, REQUIRE_TFA, or ERROR. When a tokenization result comes from a Lithic-configured internal rule rather than a rule you configured, the auth_rule_token is null.

📘

Not every declined transaction has a rule_result. Lithic runs basic security checks before evaluating your rules; a transaction declined during those checks does not produce a rule_result. Any decline caused directly by an Authorization Rule does produce one.

Next Steps

Updated 1 day ago