incomplete subscriptions die silently after 23 hours

"""Report Stripe subscriptions stuck in incomplete before the 23-hour deadline.

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

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

# Stripe holds an unpaid first invoice open for exactly 23 hours, then moves the
# subscription to the terminal incomplete_expired and voids the invoice.
WINDOW = 82800
# The last stretch before that, where a human can still rescue an individual one.
LAST_CHANCE = 7200


def verdict(sub, now, grace=3600):
    """Classify one incomplete subscription by how long it has sat unconfirmed.

    Pure, so the 23-hour boundary can be tested without a network. `grace` is how
    long a real customer might plausibly spend on the confirmation step; anything
    older than that was never confirmed at all.
    """
    created = sub.get("created")
    if not isinstance(created, (int, float)):
        return ("unknown", "no created timestamp, so this row cannot be aged")
    age = now - created
    if age >= WINDOW:
        return ("expired",
                "%.1f h old: past the 23 hour window, so the invoice is voided and "
                "this record cannot be revived" % (age / 3600.0))
    if age >= WINDOW - LAST_CHANCE:
        return ("expiring",
                "%.1f h old: under %.1f h left before Stripe expires it"
                % (age / 3600.0, (WINDOW - age) / 3600.0))
    if age >= grace:
        return ("stalled",
                "%.1f h old and still unconfirmed: the first PaymentIntent was "
                "never confirmed by the client" % (age / 3600.0))
    return ("pending",
            "%.0f min old: a customer may still be on the confirmation step"
            % (age / 60.0))


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_all(session, path, limit, **params):
    """Walk a list endpoint. Read only; every call here is a GET."""
    out = []
    params = dict(params, limit=100)
    while True:
        page = get(session, path, **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("--grace", type=int, default=3600,
                    help="seconds a confirmation may plausibly take (default 3600)")
    ap.add_argument("--max", type=int, default=1000,
                    help="stop after this many subscriptions")
    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})

    subs = page_all(s, "/subscriptions", args.max, status="incomplete")
    if not subs:
        log.info("no incomplete subscriptions for this key's mode")
        return 0

    now = time.time()
    counts = {}
    for sub in subs:
        state, detail = verdict(sub, now, args.grace)
        counts[state] = counts.get(state, 0) + 1
        line = "%-8s %s  %s" % (state, sub.get("id", "?"), detail)
        if state == "pending":
            log.info(line)
            continue
        log.warning(line)
        if state == "expired":
            log.warning("  repair: unrecoverable. Create a new subscription: "
                        "POST %s/subscriptions -d customer=%s -d items[0][price]=... "
                        "-d default_payment_method=...",
                        API, sub.get("customer", "cus_..."))
        else:
            log.warning("  repair: confirm the first invoice's PaymentIntent client "
                        "side before %s/subscriptions/%s expires", API, sub.get("id"))

    bad = len(subs) - counts.get("pending", 0)
    log.info("%d incomplete subscription(s), %d past the 23 hour window, %d stalled",
             len(subs), counts.get("expired", 0), counts.get("stalled", 0))
    if bad:
        log.warning("structural fix: create with payment_behavior=default_incomplete "
                    "and confirm the invoice's client secret in the same session")
    return 1 if bad else 0


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

/**
 * Report Stripe subscriptions stuck in incomplete before the 23-hour deadline.
 *
 * Read only. One GET request, no writes: give this a RESTRICTED key with read
 * access to Subscriptions. The repair is printed, never performed.
 */
const API = 'https://api.stripe.com/v1';

// Stripe holds an unpaid first invoice open for exactly 23 hours, then moves the
// subscription to the terminal incomplete_expired and voids the invoice.
export const WINDOW = 82800;
// The last stretch before that, where a human can still rescue an individual one.
const LAST_CHANCE = 7200;

/**
 * Classify one incomplete subscription by how long it has sat unconfirmed.
 * Pure, so the 23-hour boundary can be tested without a network.
 */
export function verdict(sub, now, grace = 3600) {
  const created = sub.created;
  if (typeof created !== 'number') {
    return ['unknown', 'no created timestamp, so this row cannot be aged'];
  }
  const age = now - created;
  if (age >= WINDOW) {
    return ['expired',
      `${(age / 3600).toFixed(1)} h old: past the 23 hour window, so the invoice ` +
      'is voided and this record cannot be revived'];
  }
  if (age >= WINDOW - LAST_CHANCE) {
    return ['expiring',
      `${(age / 3600).toFixed(1)} h old: under ${((WINDOW - age) / 3600).toFixed(1)} h ` +
      'left before Stripe expires it'];
  }
  if (age >= grace) {
    return ['stalled',
      `${(age / 3600).toFixed(1)} h old and still unconfirmed: the first ` +
      'PaymentIntent was never confirmed by the client'];
  }
  return ['pending',
    `${(age / 60).toFixed(0)} min old: a customer may still be on the confirmation step`];
}

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 pageAll(key, path, limit, params = {}) {
  const out = [];
  const q = { ...params, limit: 100 };
  for (;;) {
    const page = await get(key, path, 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 subs = await pageAll(key, '/subscriptions', 1000, { status: 'incomplete' });
  if (subs.length === 0) {
    console.log("no incomplete subscriptions for this key's mode");
    return;
  }

  const now = Date.now() / 1000;
  const counts = new Map();
  for (const sub of subs) {
    const [state, detail] = verdict(sub, now);
    counts.set(state, (counts.get(state) ?? 0) + 1);
    const line = `${state.padEnd(8)} ${sub.id ?? '?'}  ${detail}`;
    if (state === 'pending') { console.log(line); continue; }
    console.warn(line);
    if (state === 'expired') {
      console.warn(`  repair: unrecoverable. Create a new subscription: ` +
        `POST ${API}/subscriptions -d customer=${sub.customer ?? 'cus_...'} ` +
        `-d items[0][price]=... -d default_payment_method=...`);
    } else {
      console.warn(`  repair: confirm the first invoice's PaymentIntent client side ` +
        `before ${API}/subscriptions/${sub.id} expires`);
    }
  }

  const bad = subs.length - (counts.get('pending') ?? 0);
  console.log(`${subs.length} incomplete subscription(s), ` +
    `${counts.get('expired') ?? 0} past the 23 hour window, ` +
    `${counts.get('stalled') ?? 0} stalled`);
  if (bad) {
    console.warn('structural fix: create with payment_behavior=default_incomplete ' +
      "and confirm the invoice's client secret in the same session");
  }
  process.exitCode = bad ? 1 : 0;
}

// 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_incomplete_subs import WINDOW, verdict

NOW = 1_800_000_000


def test_a_minutes_old_subscription_is_not_an_alert():
    state, detail = verdict({"created": NOW - 1800}, NOW)
    assert state == "pending"
    assert "confirmation step" in detail


def test_hours_old_and_unconfirmed_is_the_finding():
    state, detail = verdict({"created": NOW - 5 * 3600}, NOW)
    assert state == "stalled"
    assert "never confirmed" in detail


def test_the_last_two_hours_are_called_out_separately():
    # Still rescuable by a human, which is why it is not folded into "stalled".
    state, detail = verdict({"created": NOW - (WINDOW - 3600)}, NOW)
    assert state == "expiring"
    assert "left before" in detail


def test_exactly_23_hours_is_already_expired():
    # 82800 is the boundary Stripe documents, not a rounded-off guess.
    state, detail = verdict({"created": NOW - WINDOW}, NOW)
    assert state == "expired"
    assert "cannot be revived" in detail


def test_a_row_with_no_timestamp_is_not_silently_healthy():
    state, _ = verdict({}, NOW)
    assert state == "unknown"

import { test } from 'node:test';
import assert from 'node:assert/strict';
import { verdict, WINDOW } from './stripe-incomplete-subs.mjs';

const NOW = 1_800_000_000;

test('a minutes old subscription is not an alert', () => {
  const [state, detail] = verdict({ created: NOW - 1800 }, NOW);
  assert.equal(state, 'pending');
  assert.match(detail, /confirmation step/);
});

test('hours old and unconfirmed is the finding', () => {
  const [state, detail] = verdict({ created: NOW - 5 * 3600 }, NOW);
  assert.equal(state, 'stalled');
  assert.match(detail, /never confirmed/);
});

test('the last two hours are called out separately', () => {
  const [state, detail] = verdict({ created: NOW - (WINDOW - 3600) }, NOW);
  assert.equal(state, 'expiring');
  assert.match(detail, /left before/);
});

test('exactly 23 hours is already expired', () => {
  const [state, detail] = verdict({ created: NOW - WINDOW }, NOW);
  assert.equal(state, 'expired');
  assert.match(detail, /cannot be revived/);
});

test('a row with no timestamp is not silently healthy', () => {
  assert.equal(verdict({}, NOW)[0], 'unknown');
});