most Checkout Sessions expire unpaid and nobody is told

"""Report the share of Stripe Checkout Sessions that expire unpaid.

Read only. One paginated GET and no writes: give this a RESTRICTED key with read
access to Checkout Sessions. The repair is printed, never performed, because this
script holds a credential to a live payments account.
"""
import argparse
import logging
import os
import sys
import time

import requests

logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
log = logging.getLogger("stripe_checkout_abandonment")

API = "https://api.stripe.com/v1"

HIGH_SHARE = 0.5    # more than half of everything created is thrown away
WATCH_SHARE = 0.25  # worth looking at before it becomes the first number


def verdict(total, expired, lapsed_open=0):
    """Classify one window of Checkout Sessions. Pure, so the thresholds are testable.

    `total` is every session created in the window, `expired` the ones Stripe has
    already marked expired, and `lapsed_open` the ones still marked open whose
    expires_at is in the past. Returns (state, detail).
    """
    if not total:
        return ("no-data", "no Checkout Sessions were created in the window")
    share = expired / float(total)
    pct = 100.0 * share
    if share >= HIGH_SHARE:
        return ("abandoned",
                "%d of %d session(s) expired unpaid (%.1f%%). More than half of "
                "everything created is being discarded." % (expired, total, pct))
    if lapsed_open:
        return ("lapsed",
                "%d open session(s) are already past expires_at and have not been "
                "marked yet; %.1f%% expired so far." % (lapsed_open, pct))
    if share >= WATCH_SHARE:
        return ("elevated",
                "%d of %d session(s) expired unpaid (%.1f%%). Shorten the window "
                "so the lapse is visible in hours." % (expired, total, pct))
    return ("normal",
            "%d of %d session(s) expired unpaid (%.1f%%)." % (expired, total, pct))


def get(session, path, params=None):
    r = session.get(API + path, params=params or {}, timeout=30)
    if r.status_code == 401:
        raise SystemExit("401 from Stripe: the key is wrong, or is for the other mode")
    r.raise_for_status()
    return r.json()


def scan(session, since, cap):
    """Tally status across every session created since `since`.

    Stripe returns newest first; the order does not matter for a tally, but the
    pagination does, because a single page of 100 on a busy account is a sample
    rather than a rate.
    """
    counts = {"open": 0, "complete": 0, "expired": 0}
    total = 0
    lapsed = 0
    now = int(time.time())
    params = {"created[gte]": since, "limit": 100}
    while True:
        page = get(session, "/checkout/sessions", params)
        data = page.get("data", [])
        for cs in data:
            total += 1
            state = cs.get("status") or "unknown"
            counts[state] = counts.get(state, 0) + 1
            expires = cs.get("expires_at")
            if state == "open" and expires is not None and expires < now:
                lapsed += 1
        if not data or not page.get("has_more") or total >= cap:
            break
        params["starting_after"] = data[-1]["id"]
    return total, counts, lapsed


def main():
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("--days", type=int, default=30,
                    help="window to measure, in days (keep it fixed between runs)")
    ap.add_argument("--max-sessions", type=int, default=5000,
                    help="stop paginating after this many sessions")
    args = ap.parse_args()

    key = os.environ.get("STRIPE_API_KEY")
    if not key:
        log.error("set STRIPE_API_KEY (use a restricted, read-only key)")
        return 2

    s = requests.Session()
    s.headers.update({"Authorization": "Bearer " + key})

    since = int(time.time()) - args.days * 86400
    total, counts, lapsed = scan(s, since, args.max_sessions)
    state, detail = verdict(total, counts.get("expired", 0), lapsed)

    log.info("%-11s %s", state, detail)
    log.info("  open %d  complete %d  expired %d  (last %d days)",
             counts.get("open", 0), counts.get("complete", 0),
             counts.get("expired", 0), args.days)
    if state in ("normal", "no-data"):
        return 0

    log.warning("  repair: create sessions with a shorter window so a lapse shows "
                "up in hours rather than a day:")
    log.warning("  POST %s/checkout/sessions -d expires_at=<now+7200>   "
                "(min 30 minutes, max 24 hours)", API)
    log.warning("  and subscribe an event destination to checkout.session.expired "
                "so each lapse is recorded")
    return 1


if __name__ == "__main__":
    sys.exit(main())

/**
 * Report the share of Stripe Checkout Sessions that expire unpaid.
 *
 * Read only. One paginated GET and no writes: give this a RESTRICTED key with
 * read access to Checkout Sessions. The repair is printed, never performed.
 */
const API = 'https://api.stripe.com/v1';

export const HIGH_SHARE = 0.5;   // more than half of everything created is discarded
export const WATCH_SHARE = 0.25; // worth looking at before it becomes the first number

/**
 * Classify one window of Checkout Sessions. Pure, so the thresholds are testable.
 * `lapsedOpen` counts sessions still marked open whose expires_at has passed.
 */
export function verdict(total, expired, lapsedOpen = 0) {
  if (!total) return ['no-data', 'no Checkout Sessions were created in the window'];
  const share = expired / total;
  const pct = (100 * share).toFixed(1);
  if (share >= HIGH_SHARE) {
    return ['abandoned',
      `${expired} of ${total} session(s) expired unpaid (${pct}%). More than half ` +
      'of everything created is being discarded.'];
  }
  if (lapsedOpen) {
    return ['lapsed',
      `${lapsedOpen} open session(s) are already past expires_at and have not been ` +
      `marked yet; ${pct}% expired so far.`];
  }
  if (share >= WATCH_SHARE) {
    return ['elevated',
      `${expired} of ${total} session(s) expired unpaid (${pct}%). Shorten the ` +
      'window so the lapse is visible in hours.'];
  }
  return ['normal', `${expired} of ${total} session(s) expired unpaid (${pct}%).`];
}

async function get(key, path, params = {}) {
  const url = new URL(API + path);
  for (const [k, v] of Object.entries(params)) url.searchParams.set(k, v);
  const res = await fetch(url, { headers: { Authorization: `Bearer ${key}` } });
  if (res.status === 401) {
    throw new Error('401 from Stripe: the key is wrong, or is for the other mode');
  }
  if (!res.ok) throw new Error(`${res.status} from ${url.pathname}`);
  return res.json();
}

export async function scan(key, since, cap = 5000) {
  const counts = { open: 0, complete: 0, expired: 0 };
  let total = 0;
  let lapsed = 0;
  const now = Math.floor(Date.now() / 1000);
  const params = { 'created[gte]': since, limit: 100 };
  for (;;) {
    const page = await get(key, '/checkout/sessions', params);
    const data = page.data ?? [];
    for (const cs of data) {
      total += 1;
      const state = cs.status ?? 'unknown';
      counts[state] = (counts[state] ?? 0) + 1;
      if (state === 'open' && cs.expires_at != null && cs.expires_at < now) lapsed += 1;
    }
    if (data.length === 0 || !page.has_more || total >= cap) break;
    params.starting_after = data[data.length - 1].id;
  }
  return { total, counts, lapsed };
}

async function main() {
  const key = process.env.STRIPE_API_KEY;
  if (!key) {
    console.error('set STRIPE_API_KEY (use a restricted, read-only key)');
    process.exitCode = 2;
    return;
  }

  const days = Number(process.argv[2] ?? 30);
  const since = Math.floor(Date.now() / 1000) - days * 86400;
  const { total, counts, lapsed } = await scan(key, since);
  const [state, detail] = verdict(total, counts.expired ?? 0, lapsed);

  console.log(`${state.padEnd(11)} ${detail}`);
  console.log(`  open ${counts.open ?? 0}  complete ${counts.complete ?? 0}  ` +
              `expired ${counts.expired ?? 0}  (last ${days} days)`);
  if (state === 'normal' || state === 'no-data') return;

  console.warn('  repair: create sessions with a shorter window so a lapse shows ' +
               'up in hours rather than a day:');
  console.warn(`  POST ${API}/checkout/sessions -d expires_at=<now+7200>   ` +
               '(min 30 minutes, max 24 hours)');
  console.warn('  and subscribe an event destination to checkout.session.expired ' +
               'so each lapse is recorded');
  process.exitCode = 1;
}

// Only run when invoked directly. The test file imports this module, and without
// the guard main() would run there too, fail on the missing key, and set a
// non-zero exit code that fails the whole test file even as every test passes.
if (import.meta.url === `file://${process.argv[1]}`) {
  main().catch((err) => { console.error(err.message); process.exitCode = 2; });
}

from stripe_checkout_abandonment import verdict


def test_no_sessions_is_not_a_perfect_score():
    # An empty window divided into zero expired sessions is 0% abandonment, which
    # would report "normal" on an account that has simply stopped taking payments.
    state, _ = verdict(0, 0)
    assert state == "no-data"


def test_half_expired_is_the_boundary():
    assert verdict(100, 49)[0] == "elevated"
    assert verdict(100, 50)[0] == "abandoned"


def test_a_quarter_expired_is_only_elevated():
    assert verdict(100, 24)[0] == "normal"
    assert verdict(100, 25)[0] == "elevated"


def test_lapsed_open_sessions_are_reported_even_when_the_share_is_low():
    state, detail = verdict(100, 4, 3)
    assert state == "lapsed"
    assert "3 open session(s)" in detail


def test_a_healthy_account_still_reports_the_percentage():
    state, detail = verdict(640, 118)
    assert state == "normal"
    assert "18.4%" in detail

import { test } from 'node:test';
import assert from 'node:assert/strict';
import { verdict } from './stripe-checkout-abandonment.mjs';

test('no sessions is not a perfect score', () => {
  assert.equal(verdict(0, 0)[0], 'no-data');
});

test('half expired is the boundary', () => {
  assert.equal(verdict(100, 49)[0], 'elevated');
  assert.equal(verdict(100, 50)[0], 'abandoned');
});

test('a quarter expired is only elevated', () => {
  assert.equal(verdict(100, 24)[0], 'normal');
  assert.equal(verdict(100, 25)[0], 'elevated');
});

test('lapsed open sessions are reported even when the share is low', () => {
  const [state, detail] = verdict(100, 4, 3);
  assert.equal(state, 'lapsed');
  assert.match(detail, /3 open session\(s\)/);
});

test('a healthy account still reports the percentage', () => {
  const [state, detail] = verdict(640, 118);
  assert.equal(state, 'normal');
  assert.match(detail, /18\.4%/);
});