TL;DR
- Problem: Disputes require explaining variance + drivers + finality of information
- Gap: Stripe shows totals, but dispute explanation is manual assembly
- Concept: "Explain" drawer per invoice line item
- Outcome: Faster credible receipts + fewer back-and-forth loops
1. Motivation and context
1.1 Online critiques that prompted me to explore usage-based billing
The direction for this memo came from a few sources of developer feedback.
1. A DEV post describing usage-billing debugging as painful when a customer disputes charges, mainly because it's hard to reconstruct how a total came to be.
"When a customer disputes a charge, good luck. Aggregation happens in Stripe's black box with zero visibility into how totals are calculated." 1
2. I encountered an OSS project (StripeMeter) on Hacker News made to help consumers answer the question "why is my bill higher than expected?" using real time tracking/projections.
"It solves the classic SaaS pain of 'why is my bill higher than expected?' by giving real-time usage tracking with live cost projections." 2
I interpreted these signals as evidence that there's room to explore a more efficient way to provide some more clarity and confidence when encountering billing disputes.
1.2 Validating this problem area
Usage-based billing quickly became an attractive area for me to explore because it's high stakes and deeply connected to trust between merchant & consumer.
- When reviewing recent product launches, it's clear Stripe is focusing energy on expanding metering + monitoring capabilities.
- Usage-based billing is increasingly common in API-first and infrastructure-style products, where value scales with consumption.
Its challenges are also well documented in Stripe's Docs under "What challenges come with usage metering?"
Stripe's analytics API is positioned as a way to build custom dashboards and reports.
This memo focuses on post-invoice disputes where trust can be fragile and teams need fast, credible explanations.
2. Current Product
How Stripe's usage billing works
- Meters define how usage gets aggregated (e.g. sum/count) and optionally by dimensions (like customer_id, project, region). Dimensions are important as information drivers - essentially tags/attributes you attach to events.
- Meter events are the usage signals merchants send over time.
- Stripe uses meter configuration + recorded usage to compute billed quantities for invoice line items.
- Stripe provides:
- Aggregated usage analytics (to query usage totals over time and by dimension)
- Threshold alerts (to catch spikes pre-invoice)
Stripe's direction (as I understand it) is: make usage billing easy to set up, record, and analyze at an aggregate level, without forcing every merchant to build metering infrastructure from scratch.
3. The Current Operator Experience
A typical dispute scenario
Scenario: A customer emails: "My January bill is $500 higher than December, why?"
- The operator (founder/support/finance/dev) opens the invoice and sees something like: API calls: 7,000 × $0.10 = $700
- That invoice line item answers what Stripe charged but not the questions the operator needs to resolve the dispute:
- What is the variance/change for the period?
- Who/what caused the change?
- Is this number final? Or is it still shifting due to processing delays?
- What can I share that a non-technical customer will accept as "receipts"?
Core Assumption: Stripe has their analytics API but during disputes, the operator would benefit from a guided explanation workflow instead of just the ability to query pieces of information.
4. Narrowing the Scope
Job To Be Done
When a customer disputes a metered invoice, I need to explain the charge credibly and close the issue.
Non-Goals:
- Event level audit log browsing
- Real time cost projection + forecasting
- Customer dashboards
5. The Gap + Opportunity
Current product intent vs. the dispute problem
Current product intent: Stripe's Meter Usage Analytics API is designed to return aggregated usage so teams can build custom dashboards and reports.
My Hypothesis: Despite the above, when disputes occur post-invoice, merchants still have to translate and debug disputes into the context of an invoice specific explanation.
The Opportunity: An operator-side, invoice native indicator that doesn't introduce new data, but standardizes how Stripe's existing primitives are assembled at the dispute moment. This way operators can respond faster and more confidently without having to stitch context across different places.
- Tied to the line item (same billing period + the meter setup used to calculate it)
- Clear about whether the numbers might still change (because usage can lag)
- Clear about what you can do next (what can be adjusted vs credit/refund)
- Shareable (export a receipt tied to the invoice)
| Customer Dashboard (built by merchant) | Proposed Fix (Stripe-native) |
|---|---|
| Helps customers understand their usage over time | Helps operators explain this billed charge on a specific invoice |
| Might show drivers/breakdowns if the merchant builds it | Starts from the line item and pulls the most available breakdowns automatically |
| Shows "last updated" like any dashboard | Makes it obvious if the total is still settling or was adjusted |
| Can't reliably tell what's correctable inside Stripe | Makes correction options clear (adjust vs credit/refund) |
Even with analytics available, teams still do manual assembly work under pressure. An "Explain" indicator could bind analytics to the invoice context and generate a "receipt" for disputes.
6. Design Intent
Concepts and principles
- Target disputes from the invoice. That is the entry point I'm targeting since that's where a dispute would start.
- Progressive disclosure. Visibility is dependent on dimensions. I'm prioritizing simple questions like "why is this bill higher than usual?" before offering deep analysis.
- Clarity embedded in the product, instead of info gathered from Stripe API docs.
7. Proposed Solution
"Explain" drawer on invoice line items
7.1 Why a drawer
- Preserves the context of the invoice screen + allows for a quick scan
- Aligns with the intent to explain each line item
7.2 Assumptions
- Most disputes can be resolved without event level logs if you can show clear variance & driver attribution.
- Investigations usually start at the invoice, not analytics
- Most merchants have at least one meaningful dimension configured that enables attribution.
- Showing adjustment context (whether usage is still processing) reduces the wrong conclusions.
7.3 Entry Point
On each metered invoice line item, add an Explain action using an icon. Clicking this opens a right side drawer.
7.4 Default drawer view
- Variance summary
- Comparison chart
- Top drivers preview
- Data status
- Export CSV
7.5 Group by dimensions
Allows operators to drill down by configured dimensions to identify specific drivers of usage changes.
7.6 Edge states
- If no dimensions are configured: Shows variance over time only. Screen displays "no dimensions are available for attribution"
- Still processing: Screen displays "Totals subject to change"
- Adjusted/Corrected: Screen displays any adjustments (although rare)
- No variance: "No unusual changes"
8. Validation
What success looks like
Hypothesis: Operators can get answers faster with an invoice native workflow rather than raw analytics alone.
Validation + Metrics
- Time-to-value: Time it takes to provide an explanation to customer
- Merchant confidence: Confidence behind answers
- Dimension usage: Which dimension breakdowns they look at first
Product Usage Signals
- % of metered invoices where 'Explain' icon is opened
- Completion rate (answering whether people get to a driver)
- Export usage rate (answering if evidence output is needed)