billing-truth-plus

Built on affaan-m/ECC by @affaan-m (255,189 stars, MIT). All credit for the original idea to them. This fork improves and repackages it; upstream license preserved in UPSTREAM_LICENSE.

A proof-first Claude Code skill for finding the truth about sales, prices, refunds, plans, seats, and billing rules.

Made for developers, support teams, and product teams who need billing answers that match real data and code.

🔎 Why

Billing facts can live in many places.

The price page may not match checkout. A paid charge may not give access. A plan count may include trials or failed payments. A late payment event may update an account twice.

This skill helps Claude Code check the full path. It keeps facts apart from guesses. It also asks for the date range, currency, time zone, product, account, and goal before doing the work.

⚡ Install

mkdir -p ~/.claude/skills/finance-billing-ops && curl -fsSL https://raw.githubusercontent.com/OWNER/billing-truth-plus/main/skill/SKILL.md -o ~/.claude/skills/finance-billing-ops/SKILL.md

Replace OWNER with the GitHub account that hosts this repo.

🧭 Usage

Ask Claude Code a clear billing question:

Use finance-billing-ops to check why account cus_123 was charged twice in July.
Use USD and America/New_York. I want facts and a safe fix.
Check billing data and trace the checkout, payment event, and access code.
Do not issue a refund.

Expected output:

Scope
- Date range: July
- Currency: USD
- Time zone: America/New_York
- Account: cus_123
- Goal: Facts and a safe fix

Customer result
- Case type: Duplicate checkout
- Payment state: Two paid charges
- Refund action: Not taken

Product result
- Checkout requests: Two
- Payment events: One event was handled twice
- Access state: One active plan

Decision
- Fix duplicate event handling
- Review one charge for a refund
- More proof is needed before changing billing

The skill marks data as live, saved, test, or unknown. It keeps each currency apart. It tracks trials, taxes, fees, coupons, credits, refunds, failed payments, and pending checkouts on their own.

🛠️ What we changed vs upstream

• Rewrites the skill in simpler, clearer English while preserving its proof-first billing-operations purpose.
• Expands safety rules around sensitive data, authorization for billing changes, payment states, and price components.
• Adds explicit scoping requirements for date range, currency, time zone, product, account, and desired outcome.
• Makes billing analysis more rigorous by separating currencies and tracking trials, taxes, fees, coupons, credits, and MRR methodology.
• Broadens diagnostic coverage to include prorations, trial conversions, missing access, cancellation timing, plan-limit changes, and duplicate event processing.

📄 License

MIT. The upstream MIT license is preserved in UPSTREAM_LICENSE.