past_due subscriptions keep their access forever

"""Report Stripe subscriptions parked in past_due while access continues.

Read only. GET requests only, no writes: give this a RESTRICTED key with read
access to Subscriptions and Invoices. 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_past_due_subs")

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

# No retry schedule Stripe offers runs longer than a month, so an invoice older
# than this is not waiting on anything: the subscription has simply been left.
DUNNING_DAYS = 30


def verdict(sub, now, dunning_days=DUNNING_DAYS):
    """Classify one past_due subscription from its latest invoice.

    Pure, so the difference between live dunning and a parked subscription can be
    tested without a network. Needs the invoice expanded; an unexpanded id is
    reported as unknown rather than guessed at.
    """
    invoice = sub.get("latest_invoice")
    if not isinstance(invoice, dict):
        return ("unknown",
                "latest_invoice was not expanded; re-run with "
                "expand[]=data.latest_invoice")
    created = invoice.get("created")
    if not isinstance(created, (int, float)):
        return ("unknown", "latest_invoice has no created timestamp to age")
    attempts = invoice.get("attempt_count") or 0
    days = (now - created) / 86400.0
    if attempts == 0:
        return ("never-attempted",
                "invoice %.0f day(s) old with no payment attempt at all: usually no "
                "payment method resolves, so retries never run" % days)
    if days > dunning_days:
        return ("parked",
                "%d attempt(s), invoice %.0f day(s) old: past any retry schedule, so "
                "nothing further will happen to this on its own" % (attempts, days))
    return ("dunning",
            "%d attempt(s) over %.0f day(s): retries are still running and this may "
            "recover" % (attempts, days))


def get(session, path, **params):
    r = session.get(API + path, params=params, 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 page_subscriptions(session, status, limit, expand=None):
    """Walk one status page by page. Read only; every call here is a GET."""
    out = []
    params = {"status": status, "limit": 100}
    if expand:
        params["expand[]"] = expand
    while True:
        page = get(session, "/subscriptions", **params)
        out.extend(page.get("data", []))
        if not page.get("has_more") or len(out) >= limit:
            break
        params["starting_after"] = page["data"][-1]["id"]
    return out[:limit]


def main():
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("--dunning-days", type=int, default=DUNNING_DAYS,
                    help="invoice age past which retries are certainly over")
    ap.add_argument("--max", type=int, default=1000,
                    help="stop after this many subscriptions per status")
    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})

    past_due = page_subscriptions(s, "past_due", args.max, expand="data.latest_invoice")
    active = page_subscriptions(s, "active", args.max)
    if not past_due:
        log.info("no past_due subscriptions for this key's mode")
        return 0

    now = time.time()
    counts = {}
    for sub in past_due:
        state, detail = verdict(sub, now, args.dunning_days)
        counts[state] = counts.get(state, 0) + 1
        log.warning("%-15s %s  %s", state, sub.get("id", "?"), detail)
        if state == "parked":
            log.warning("  repair: close it out with POST %s/subscriptions/%s "
                        "-d cancel_at_period_end=true, or DELETE %s/subscriptions/%s "
                        "to end it now", API, sub.get("id"), API, sub.get("id"))
        elif state == "never-attempted":
            log.warning("  repair: attach a payment method first, then pay invoice %s",
                        (sub.get("latest_invoice") or {}).get("id", "in_..."))

    ratio = 100.0 * len(past_due) / max(1, len(past_due) + len(active))
    log.info("%d past_due against %d active (%.1f%%), %d parked, %d never attempted",
             len(past_due), len(active), ratio, counts.get("parked", 0),
             counts.get("never-attempted", 0))
    log.warning("entitlement check: gate on status in (active, trialing), not on "
                "status != canceled")
    log.warning("billing setting: Billing > Revenue recovery > Retries, set the "
                "post-retry action to cancel or mark unpaid")
    return 1


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

/**
 * Report Stripe subscriptions parked in past_due while access continues.
 *
 * Read only. GET requests only, no writes: give this a RESTRICTED key with read
 * access to Subscriptions and Invoices. The repair is printed, never performed.
 */
const API = 'https://api.stripe.com/v1';

// No retry schedule Stripe offers runs longer than a month, so an invoice older
// than this is not waiting on anything: the subscription has simply been left.
export const DUNNING_DAYS = 30;

/**
 * Classify one past_due subscription from its latest invoice.
 * Pure, so live dunning and a parked subscription can be told apart in a test.
 */
export function verdict(sub, now, dunningDays = DUNNING_DAYS) {
  const invoice = sub.latest_invoice;
  if (invoice === null || typeof invoice !== 'object') {
    return ['unknown',
      'latest_invoice was not expanded; re-run with expand[]=data.latest_invoice'];
  }
  const created = invoice.created;
  if (typeof created !== 'number') {
    return ['unknown', 'latest_invoice has no created timestamp to age'];
  }
  const attempts = invoice.attempt_count ?? 0;
  const days = (now - created) / 86400;
  if (attempts === 0) {
    return ['never-attempted',
      `invoice ${days.toFixed(0)} day(s) old with no payment attempt at all: ` +
      'usually no payment method resolves, so retries never run'];
  }
  if (days > dunningDays) {
    return ['parked',
      `${attempts} attempt(s), invoice ${days.toFixed(0)} day(s) old: past any ` +
      'retry schedule, so nothing further will happen to this on its own'];
  }
  return ['dunning',
    `${attempts} attempt(s) over ${days.toFixed(0)} day(s): retries are still ` +
    'running and this may recover'];
}

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();
}

async function pageSubscriptions(key, status, limit, expand) {
  const out = [];
  const q = { status, limit: 100 };
  if (expand) q['expand[]'] = expand;
  for (;;) {
    const page = await get(key, '/subscriptions', q);
    out.push(...(page.data ?? []));
    if (!page.has_more || out.length >= limit) break;
    q.starting_after = page.data[page.data.length - 1].id;
  }
  return out.slice(0, limit);
}

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 pastDue = await pageSubscriptions(key, 'past_due', 1000, 'data.latest_invoice');
  const active = await pageSubscriptions(key, 'active', 1000);
  if (pastDue.length === 0) {
    console.log("no past_due subscriptions for this key's mode");
    return;
  }

  const now = Date.now() / 1000;
  const counts = new Map();
  for (const sub of pastDue) {
    const [state, detail] = verdict(sub, now);
    counts.set(state, (counts.get(state) ?? 0) + 1);
    console.warn(`${state.padEnd(15)} ${sub.id ?? '?'}  ${detail}`);
    if (state === 'parked') {
      console.warn(`  repair: close it out with POST ${API}/subscriptions/${sub.id} ` +
        `-d cancel_at_period_end=true, or DELETE ${API}/subscriptions/${sub.id} ` +
        `to end it now`);
    } else if (state === 'never-attempted') {
      console.warn(`  repair: attach a payment method first, then pay invoice ` +
        `${sub.latest_invoice?.id ?? 'in_...'}`);
    }
  }

  const ratio = (100 * pastDue.length) / Math.max(1, pastDue.length + active.length);
  console.log(`${pastDue.length} past_due against ${active.length} active ` +
    `(${ratio.toFixed(1)}%), ${counts.get('parked') ?? 0} parked, ` +
    `${counts.get('never-attempted') ?? 0} never attempted`);
  console.warn('entitlement check: gate on status in (active, trialing), not on ' +
    'status != canceled');
  console.warn('billing setting: Billing > Revenue recovery > Retries, set the ' +
    'post-retry action to cancel or mark unpaid');
  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_past_due_subs import verdict

NOW = 1_800_000_000
DAY = 86400


def inv(days_old, attempts):
    return {"id": "in_1", "created": NOW - days_old * DAY, "attempt_count": attempts}


def test_a_fresh_invoice_with_attempts_is_live_dunning():
    state, detail = verdict({"latest_invoice": inv(3, 2)}, NOW)
    assert state == "dunning"
    assert "may recover" in detail


def test_an_old_invoice_is_parked_not_dunning():
    state, detail = verdict({"latest_invoice": inv(75, 4)}, NOW)
    assert state == "parked"
    assert "nothing further will happen" in detail


def test_zero_attempts_is_its_own_fault_not_a_retry_problem():
    # No attempt means nothing to retry: this is a missing payment method, and
    # changing the retry configuration would not touch it.
    state, detail = verdict({"latest_invoice": inv(40, 0)}, NOW)
    assert state == "never-attempted"
    assert "no payment method" in detail


def test_unexpanded_invoice_is_not_classified():
    state, detail = verdict({"latest_invoice": "in_1"}, NOW)
    assert state == "unknown"
    assert "expand" in detail


def test_invoice_without_a_timestamp_is_not_classified():
    state, _ = verdict({"latest_invoice": {"attempt_count": 3}}, NOW)
    assert state == "unknown"

import { test } from 'node:test';
import assert from 'node:assert/strict';
import { verdict } from './stripe-past-due-subs.mjs';

const NOW = 1_800_000_000;
const DAY = 86400;

const inv = (daysOld, attempts) => ({
  id: 'in_1', created: NOW - daysOld * DAY, attempt_count: attempts,
});

test('a fresh invoice with attempts is live dunning', () => {
  const [state, detail] = verdict({ latest_invoice: inv(3, 2) }, NOW);
  assert.equal(state, 'dunning');
  assert.match(detail, /may recover/);
});

test('an old invoice is parked not dunning', () => {
  const [state, detail] = verdict({ latest_invoice: inv(75, 4) }, NOW);
  assert.equal(state, 'parked');
  assert.match(detail, /nothing further will happen/);
});

test('zero attempts is its own fault not a retry problem', () => {
  const [state, detail] = verdict({ latest_invoice: inv(40, 0) }, NOW);
  assert.equal(state, 'never-attempted');
  assert.match(detail, /no payment method/);
});

test('unexpanded invoice is not classified', () => {
  const [state, detail] = verdict({ latest_invoice: 'in_1' }, NOW);
  assert.equal(state, 'unknown');
  assert.match(detail, /expand/);
});

test('invoice without a timestamp is not classified', () => {
  assert.equal(verdict({ latest_invoice: { attempt_count: 3 } }, NOW)[0], 'unknown');
});