duplicate customers share an email and split billing

"""Report Stripe Customers that share an email address.

Read only. Paginated GETs and no writes: give this a RESTRICTED key with read
access to Customers, Subscriptions and PaymentMethods. The merge is printed,
never performed, because deleting a customer cancels its subscriptions and this
script holds a credential to a live payments account.
"""
import argparse
import logging
import os
import sys

import requests

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

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


def normalise(email):
    """Lowercase and trim an address for grouping. Pure.

    Stripe's own email filter is exact and case-sensitive, so a user who
    capitalised once and did not the next time has two records that no exact
    lookup will ever put beside each other. Grouping has to normalise even
    though the confirming API call cannot.
    """
    if not email:
        return None
    return str(email).strip().lower() or None


def verdict(records):
    """Classify one group of customers sharing an address. Pure.

    Each record is {"id": str, "has_card": bool, "has_subscription": bool},
    filled in by the caller. Returns (state, detail).
    """
    n = len(records)
    if n <= 1:
        return ("unique", "one customer for this address")

    subs = [r for r in records if r.get("has_subscription")]
    holders = [r for r in records
               if r.get("has_card") or r.get("has_subscription")]

    if len(subs) > 1:
        return ("split_billing",
                "%d records, %d with a subscription. They renew independently, "
                "so cancelling one leaves the other charging." % (n, len(subs)))
    if len(holders) > 1:
        return ("split_methods",
                "%d records, %d holding a card or a subscription. Support will "
                "answer from whichever one they find first." % (n, len(holders)))
    if holders:
        return ("shells",
                "%d records, one holding everything. The other %d are empty."
                % (n, n - 1))
    return ("empty",
            "%d records, none holding a card or a subscription. Untidy, not "
            "urgent." % n)


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 group_by_email(session, limit):
    """Return {normalised email: [customer ids]} plus the number read."""
    groups = {}
    seen = 0
    params = {"limit": 100}
    while True:
        page = get(session, "/customers", params)
        data = page.get("data", [])
        for c in data:
            seen += 1
            key = normalise(c.get("email"))
            if key is None:
                continue  # no email is a different problem
            groups.setdefault(key, []).append(c["id"])
        if not data or not page.get("has_more") or seen >= limit:
            break
        params["starting_after"] = data[-1]["id"]
    return groups, seen


def enrich(session, customer_id):
    """One record for verdict(), costing two small GETs."""
    cards = get(session, "/payment_methods",
                {"customer": customer_id, "type": "card", "limit": 1})
    subs = get(session, "/subscriptions",
               {"customer": customer_id, "status": "all", "limit": 1})
    return {"id": customer_id,
            "has_card": bool(cards.get("data")),
            "has_subscription": bool(subs.get("data"))}


def main():
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("--max-customers", type=int, default=10000,
                    help="stop paginating after this many customers")
    ap.add_argument("--max-groups", type=int, default=50,
                    help="how many duplicate groups to enrich and report")
    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})

    groups, seen = group_by_email(s, args.max_customers)
    dupes = {e: ids for e, ids in groups.items() if len(ids) > 1}
    log.info("%d customer(s), %d address(es) with more than one record",
             seen, len(dupes))
    if not dupes:
        return 0

    # Worst first: the ones with the most records are the ones support is
    # already losing time to.
    ordered = sorted(dupes.items(), key=lambda kv: -len(kv[1]))[:args.max_groups]
    bad = 0
    for email, ids in ordered:
        records = [enrich(s, cid) for cid in ids]
        state, detail = verdict(records)
        log.warning("%-14s %s  %s", state, email, detail)
        log.warning("  records: %s", ", ".join(r["id"] for r in records))
        if state in ("split_billing", "split_methods"):
            bad += 1
            keeper = records[0]["id"]
            log.warning("  merge: POST %s/payment_methods/<pm>/attach "
                        "-d customer=%s, move the subscriptions, then "
                        "DELETE %s/customers/<dupe>", API, keeper, API)
            log.warning("  deleting a customer cancels its subscriptions, so "
                        "empty the record before you delete it")
    log.warning("  prevent: GET %s/customers?email=<address>&limit=1 before "
                "creating, and store the cus_ id on your own user row", API)
    return 1 if bad else 0


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

/**
 * Report Stripe Customers that share an email address.
 *
 * Read only. Paginated GETs and no writes: give this a RESTRICTED key with read
 * access to Customers, Subscriptions and PaymentMethods. The merge is printed,
 * never performed, because deleting a customer cancels its subscriptions.
 */
const API = 'https://api.stripe.com/v1';

/**
 * Lowercase and trim an address for grouping. Pure.
 *
 * Stripe's own email filter is exact and case-sensitive, so grouping has to
 * normalise even though the confirming API call cannot.
 */
export function normalise(email) {
  if (!email) return null;
  return String(email).trim().toLowerCase() || null;
}

/**
 * Classify one group of customers sharing an address. Pure.
 * Each record is { id, has_card, has_subscription }, filled in by the caller.
 */
export function verdict(records) {
  const n = records.length;
  if (n <= 1) return ['unique', 'one customer for this address'];

  const subs = records.filter((r) => r.has_subscription);
  const holders = records.filter((r) => r.has_card || r.has_subscription);

  if (subs.length > 1) {
    return ['split_billing',
      `${n} records, ${subs.length} with a subscription. They renew ` +
      'independently, so cancelling one leaves the other charging.'];
  }
  if (holders.length > 1) {
    return ['split_methods',
      `${n} records, ${holders.length} holding a card or a subscription. ` +
      'Support will answer from whichever one they find first.'];
  }
  if (holders.length) {
    return ['shells',
      `${n} records, one holding everything. The other ${n - 1} are empty.`];
  }
  return ['empty',
    `${n} records, none holding a card or a subscription. Untidy, not urgent.`];
}

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 groupByEmail(key, limit = 10000) {
  const groups = new Map();
  let seen = 0;
  const params = { limit: 100 };
  for (;;) {
    const page = await get(key, '/customers', params);
    const data = page.data ?? [];
    for (const c of data) {
      seen += 1;
      const email = normalise(c.email);
      if (email === null) continue; // no email is a different problem
      groups.set(email, [...(groups.get(email) ?? []), c.id]);
    }
    if (data.length === 0 || !page.has_more || seen >= limit) break;
    params.starting_after = data[data.length - 1].id;
  }
  return { groups, seen };
}

async function enrich(key, customerId) {
  const cards = await get(key, '/payment_methods',
    { customer: customerId, type: 'card', limit: 1 });
  const subs = await get(key, '/subscriptions',
    { customer: customerId, status: 'all', limit: 1 });
  return {
    id: customerId,
    has_card: Boolean((cards.data ?? []).length),
    has_subscription: Boolean((subs.data ?? []).length),
  };
}

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 maxGroups = Number(process.argv[2] ?? 50);
  const { groups, seen } = await groupByEmail(key);
  const dupes = [...groups.entries()].filter(([, ids]) => ids.length > 1);

  console.log(`${seen} customer(s), ${dupes.length} address(es) with more than one record`);
  if (dupes.length === 0) return;

  // Worst first: the ones with the most records are the ones support is
  // already losing time to.
  dupes.sort((a, b) => b[1].length - a[1].length);
  let bad = 0;
  for (const [email, ids] of dupes.slice(0, maxGroups)) {
    const records = [];
    for (const id of ids) records.push(await enrich(key, id));
    const [state, detail] = verdict(records);
    console.warn(`${state.padEnd(14)} ${email}  ${detail}`);
    console.warn(`  records: ${records.map((r) => r.id).join(', ')}`);
    if (state === 'split_billing' || state === 'split_methods') {
      bad += 1;
      console.warn(`  merge: POST ${API}/payment_methods/<pm>/attach ` +
                   `-d customer=${records[0].id}, move the subscriptions, then ` +
                   `DELETE ${API}/customers/<dupe>`);
      console.warn('  deleting a customer cancels its subscriptions, so empty ' +
                   'the record before you delete it');
    }
  }
  console.warn(`  prevent: GET ${API}/customers?email=<address>&limit=1 before ` +
               'creating, and store the cus_ id on your own user row');
  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_duplicate_customers import normalise, verdict


def rec(cid, card=False, sub=False):
    return {"id": cid, "has_card": card, "has_subscription": sub}


def test_normalisation_folds_case_and_whitespace():
    assert normalise("  Ada@Example.COM ") == "ada@example.com"
    assert normalise("") is None
    assert normalise(None) is None


def test_a_single_record_is_not_a_duplicate():
    assert verdict([rec("cus_1", card=True)])[0] == "unique"


def test_two_live_subscriptions_is_the_billing_case():
    state, detail = verdict([rec("cus_1", sub=True), rec("cus_2", sub=True)])
    assert state == "split_billing"
    assert "cancelling one" in detail


def test_two_records_holding_cards_is_a_support_problem_not_a_billing_one():
    state, _ = verdict([rec("cus_1", card=True), rec("cus_2", card=True)])
    assert state == "split_methods"


def test_duplicates_holding_nothing_are_ranked_below_ones_that_do():
    assert verdict([rec("cus_1", card=True), rec("cus_2")])[0] == "shells"
    assert verdict([rec("cus_1"), rec("cus_2"), rec("cus_3")])[0] == "empty"

import { test } from 'node:test';
import assert from 'node:assert/strict';
import { normalise, verdict } from './stripe-duplicate-customers.mjs';

const rec = (id, card = false, sub = false) =>
  ({ id, has_card: card, has_subscription: sub });

test('normalisation folds case and whitespace', () => {
  assert.equal(normalise('  Ada@Example.COM '), 'ada@example.com');
  assert.equal(normalise(''), null);
  assert.equal(normalise(null), null);
});

test('a single record is not a duplicate', () => {
  assert.equal(verdict([rec('cus_1', true)])[0], 'unique');
});

test('two live subscriptions is the billing case', () => {
  const [state, detail] = verdict([rec('cus_1', false, true), rec('cus_2', false, true)]);
  assert.equal(state, 'split_billing');
  assert.match(detail, /cancelling one/);
});

test('two records holding cards is a support problem not a billing one', () => {
  assert.equal(verdict([rec('cus_1', true), rec('cus_2', true)])[0], 'split_methods');
});

test('duplicates holding nothing are ranked below ones that do', () => {
  assert.equal(verdict([rec('cus_1', true), rec('cus_2')])[0], 'shells');
  assert.equal(verdict([rec('cus_1'), rec('cus_2'), rec('cus_3')])[0], 'empty');
});