stripe-check

Instant Stripe payment diagnostics — see your failure rate, lost revenue, and top decline reasons in seconds.

No server. No install. Just run it.

npx stripe-check

What it does

stripe-check pulls your last 30 days of Stripe data and tells you things your dashboard doesn't surface clearly:

• What % of payments are failing
• How much revenue you're losing
• Exactly why payments fail (decline codes)
• Which customers are affected
• Whether you have alerts configured
• And more — across 10 diagnostic modes

Every report ends with a link to striperecover.com for deeper analysis and automated recovery.

Zero config — key auto-detected

stripe-check finds your Stripe key automatically. It checks, in order:

| Source | Example | |--------|---------| | STRIPE_SECRET_KEY env var | export STRIPE_SECRET_KEY=sk_live_... | | STRIPE_API_KEY env var | export STRIPE_API_KEY=sk_live_... | | .env file in current directory | STRIPE_SECRET_KEY=sk_live_... | | .env.local / .env.development / .env.production | same format | | Stripe CLI config | ~/.config/stripe/config.toml |

If you already use the Stripe CLI or have a .env file, you don't need to do anything — just run npx stripe-check.

Or pass it directly:

npx stripe-check sk_live_xxx

10 diagnostic modes

Run the default health check, or go deeper with any mode:

npx stripe-check                  # 🚨 Overall health check (default)
npx stripe-check --loss           # 💸 Total revenue lost + week-over-week
npx stripe-check --declines       # 📊 Decline code breakdown with explanations
npx stripe-check --recovery       # 🔁 How many failed customers eventually paid
npx stripe-check --customers      # 👤 Affected customers + repeat failers
npx stripe-check --expired        # 💳 Losses from expired cards
npx stripe-check --no-retry       # 🚫 Failed payments that were never retried
npx stripe-check --spike          # ⚠️  24h failure spike vs previous 24h
npx stripe-check --silent         # 😶 Money lost with no webhook alerts
npx stripe-check --products       # 📦 Revenue lost broken down by product

Mode details

Default — npx stripe-check

  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  🚨  Stripe Payment Health Check  (last 30 days)
  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Total charges:   312
  ✅ Succeeded:    268
  ❌ Failed:       44

  Failure rate:    14.1%  ⚠️  Above healthy threshold (< 5%)
  Avg transaction: $48.00 USD

  Top failure reasons:
    ██████░░░░  42%  insufficient_funds
    ████░░░░░░  28%  card_declined
    ██░░░░░░░░  18%  expired_card

  💸 Est. lost revenue:  $2,112.00 USD

--loss — Revenue lost

Shows total lost, this-week vs last-week, and daily average burn rate.

--declines — Why payments fail

Every decline code with a plain-English explanation and how much it cost you. Flags which failures are recoverable with smart retries.

--recovery — Recovery rate

Tracks how many customers who failed eventually paid. Shows unrecovered revenue still sitting idle.

--customers — Affected customers

Unique failed customers, repeat failers (churn risk), week-over-week trend.

--expired — Expired card losses

Counts failures from expired cards, projects annual loss. These are 100% preventable.

--no-retry — Never-retried failures

Pulls payment intents with no retry attempt. Shows exactly how much is sitting unrecovered.

--spike — Failure spike

Compares failure rate in the last 24h vs the previous 24h. Alerts when rate jumps > 20%. Shows peak failure hour.

--silent — Undetected losses

Checks your Stripe webhooks. If you have no charge.failed or payment_intent.payment_failed listener, your system is blind to every failure.

--products — Losses by product

Groups failed charges by product name (from invoice line items, metadata.product_name, or charge description).

Requirements

• Node.js 18+
• A Stripe secret key (sk_live_... or sk_test_...)
• Read-only access is fine — stripe-check never writes anything

Privacy

Your Stripe key never leaves your machine. All API calls go directly to api.stripe.com. Nothing is stored or logged.

Development

git clone https://github.com/michaelmanly/stripe-check
cd stripe-check
npm install
npm test          # 60 unit tests
node bin/stripe-check.js --help

Project layout

stripe-check/
├── bin/
│   └── stripe-check.js     # CLI entry — parses flags, detects key, calls mode
├── src/
│   ├── env.js              # API key auto-detection (env vars, .env files, CLI config)
│   ├── client.js           # Stripe fetchers + shared data helpers
│   ├── output.js           # chalk helpers, CTA, formatting
│   ├── index.js            # Mode router
│   └── modes/
│       ├── check.js        # default
│       ├── loss.js         # --loss
│       ├── declines.js     # --declines
│       ├── recovery.js     # --recovery
│       ├── customers.js    # --customers
│       ├── expired.js      # --expired
│       ├── no-retry.js     # --no-retry
│       ├── spike.js        # --spike
│       ├── silent.js       # --silent
│       └── products.js     # --products
└── src/__tests__/
    ├── client.test.js      # shared helpers
    ├── env.test.js         # key detection
    ├── modes.test.js       # all 10 compute() functions
    └── helpers.js          # test data factories

Each mode exports compute(data) (pure, tested) and render(stats) (output) separately.

Publishing

npm login
npm publish --access public

License

MIT