Failed payments and subscription metrics
Two things quietly decide whether a subscription business grows: the payments that fail without anyone noticing, and whether your recurring revenue figures are derived from evidence or from assumptions. This page covers how Metrivo handles both, and what it deliberately does not do.
Direct answer
Metrivo records failed payments reported by your provider's signed webhooks or the Manual Payment API, groups them by customer with the failure reason and retry count, and emails a digest to an address you choose. It never contacts your customers. Separately, it derives MRR, ARR, ARPU, churn, net-new MRR, and subscriber counts from confirmed payment events by classifying each recurring payment as new, renewal, expansion, contraction, churn, or reactivation.
Failed payments
A failed payment is recorded when a connected provider reports one. Metrivo stores the customer identity it can resolve, the amount and currency, the provider, the failure reason string as the provider gave it, the retry count, and the first and last failure timestamps. Repeated failures for the same customer collapse into a single row with a rising retry count rather than creating noise.
Failures resolve automatically. When a successful payment later arrives for the same customer, the outstanding failure is reconciled and drops out of the at-risk total, so the number you are looking at is current rather than cumulative.
- Supported providers:
stripe,razorpay,dodo,paddle,lemonsqueezy,polar, andmanual. - Read the current at-risk summary with
GET /api/failed-payments, optionally scoped withworkspaceIdandwebsiteId. - Configure the digest with
GETandPUT /api/settings/failed-payment-alerts, which controlemailDigestEnabledanddigestRecipientEmail. - The digest reports how many customers are affected and the total amount at risk in your workspace currency. It is sent to you, never to the customer.
How a recurring payment is classified
Every payment Metrivo judges to be recurring is normalised to a monthly amount using its billing interval (weekly, monthly, quarterly, annual, or yearly), then compared with that customer's previous monthly amount to produce an event type and a delta.
| Event type | Meaning |
|---|---|
new | A customer's first recurring payment on a subscription. |
renewal | A recurring payment at the same monthly amount as the previous one. |
expansion | A recurring payment above the customer's previous monthly amount. |
contraction | A recurring payment below the customer's previous monthly amount. |
churn | The subscription stopped producing payments within its expected billing window. |
reactivation | A previously churned customer started paying again. |
Each derived event keeps the evidence behind it: the originating payment, the provider and provider event identifiers, the billing interval and interval count, the previous and current monthly amounts, the resulting MRR delta, and the workspace currency with the exchange rate applied. When the recurrence evidence is too weak to classify a payment confidently, it is not silently promoted into your MRR.
Metrics API
All subscription metrics are derived from the classified event series, so they move together and reconcile with each other by construction.
| Endpoint | Returns |
|---|---|
GET /api/metrics/mrr | Monthly recurring revenue derived from classified subscription events. |
GET /api/metrics/arr | Annualised run rate from the same derived series. |
GET /api/metrics/arpu | Average revenue per paying subscriber. |
GET /api/metrics/churn | Churn measured from subscription events, not from cancellation intent. |
GET /api/metrics/net-new-mrr | New plus expansion plus reactivation, minus contraction and churn. |
GET /api/metrics/subscribers | Count of customers with an active recurring payment. |
GET /api/metrics/cohorts/customer | Customer retention by signup cohort. |
GET /api/metrics/cohorts/revenue | Revenue retention by cohort, so expansion is visible separately. |
Customer cohorts answer "how many of the people who joined in this month are still paying?" Revenue cohorts answer "how much of the money that cohort brought is still arriving?" The second can exceed 100 per cent when expansion outweighs churn, which is exactly why the two are reported separately rather than blended.
Limits worth knowing before you trust a number
- Coverage decides accuracy. Metrics are derived from the payments Metrivo has actually received. A provider connected late, or a webhook event type left disabled, produces a real gap. Backfill and recompute before comparing against your provider.
- Recent churn is provisional. Churn is inferred from a missing payment within an expected billing window, so the most recent period keeps changing until that window has fully elapsed.
- Currency conversion is a snapshot. Non-workspace currencies are converted using the rate stored with the event. Historical totals will not match a report built with today's rates, and that is intentional.
- Failed payments are not a recovery workflow. Metrivo surfaces and quantifies the risk. Retrying the charge and contacting the customer stay with your provider and your own tooling.
- Attribution is separate. Whether a failed renewal traces back to a particular traffic source depends on the same evidence rules described in attribution confidence.
Related
- Payment verification — how webhook and API payment evidence is accepted.
- Manual Payment API — reporting payments and failures from custom billing.
- Attribution confidence — how a payment is matched to a source.
- Revenue Assurance — verifying that a revenue change is real before acting on it.
Frequently asked questions
Does Metrivo email my customers when a payment fails?
No. Metrivo never contacts your customers. When a payment fails, it records the failure and sends a digest to the recipient address you configure, which is you or someone on your team. Dunning, retries, and recovery emails remain the job of your payment provider and your own lifecycle tooling. The digest email says so explicitly so nobody assumes recovery has been handled.
Which providers can report a failed payment?
Stripe, Razorpay, Dodo, Paddle, and Lemon Squeezy through their signed webhooks, plus the Manual Payment API for custom or in-house billing. A failure is only recorded when the provider actually tells Metrivo about it, so coverage depends on which webhook events you have enabled with that provider.
How is MRR calculated?
From confirmed payment events, not from plan configuration. Each recurring payment is normalised to a monthly amount using its billing interval, compared with the customer's previous monthly amount, and classified as new, renewal, expansion, contraction, churn, or reactivation. MRR is the sum of active monthly amounts. Amounts in other currencies are converted to your workspace currency and the exchange rate used is stored alongside the event.
Why does Metrivo's MRR differ from my payment provider's dashboard?
Usually because the two are counting different things. Provider dashboards often report gross charges including one-off payments, taxes, and amounts that were later refunded or disputed. Metrivo derives MRR from payments it classifies as recurring, normalised to a monthly figure. If the gap is large and unexplained, treat it as a reconciliation question and check provider coverage before trusting either number.
How is churn detected if my provider does not send a cancellation event?
By absence. A subscription that stops producing payments within its expected billing window is classified as churn. This is deliberately evidence-based rather than intent-based: a customer who clicked cancel but is still paying has not churned yet, and a customer whose card silently stopped working has, whatever the subscription record says. It also means very recent churn is provisional until the billing window has fully elapsed.
Can I recompute metrics after fixing an integration?
Yes. Subscription events are derived from stored payment evidence, so once missing payments are backfilled the derived series can be recomputed from them. This is the normal path after connecting a provider late or importing history, and it is why the classification is kept separate from the raw payment records.