Retries
How MintCash retries failed recurring charges over time — the schedule, the customer notifications, and when a subscription is cancelled.
When a subscription renewal fails, MintCash doesn't give up on the first decline. It retries the charge on a fixed schedule, escalating customer communication along the way, and only cancels the subscription once every attempt is exhausted. This is the "dunning" loop you'd otherwise build yourself.
Retries vs. cascading
Cascading happens within a single charge attempt — try provider A, then B, then C, all in seconds. Retries happen across time — try today, fail, wait a day, try again. The two combine: each retry attempt can itself cascade across providers.
The retry schedule
| Attempt | When (from first failure) | Customer email |
|---|---|---|
| Initial charge | Day 0 (renewal due date) | "Please update your payment method" |
| 1st retry | Day +1 | "Your payment failed" |
| 2nd retry | Day +3 | "Your payment failed" |
| 3rd retry | Day +5 | "Your subscription will be cancelled" |
| 4th retry | Day +7 | Subscription cancelled, access revoked |
The day offsets are measured from the original renewal failure, not from the previous attempt.
What you see
subscription.succeeded— a charge attempt succeeded; following a failure, it means a retry recovered the subscription (back toactive).subscription.failed— a subscription charge attempt failed. You'll receive one per failed attempt in the ladder.subscription.cancelled— the subscription terminated (retries exhausted, a non-recoverable decline, or a merchant cancellation).
Each retry creates a new Payment linked to the subscription. On the first renewal failure the subscription moves to past_due and stays there through the dunning ladder, returning to active if a retry succeeds, or ending in cancelled once attempts are exhausted.
Letting the customer fix the card
Retries only ever re-charge the same card, so a card that was cancelled or reissued will fail every attempt in the ladder. The way out is a card-update link: a URL where the customer enters a new card, which settles the failed invoice, returns the subscription to active, and becomes the card future renewals bill.
There are two ways one reaches the customer:
- Automatically. Every dunning email sent while the subscription can still be saved — day 0, +1, +3 and +5 — carries its own link.
- On demand. Call
POST /subscriptions/{id}/card-updateyourself — useful when a customer contacts support before the next email goes out, or when you've turned the emails off.
A card-update link does not pause the ladder
Scheduled retries keep running on the old card while a link is live, and a failed recovery attempt does not advance the ladder or move the cancellation date. Whichever charge settles the invoice first wins. If the retries run out first, the subscription is cancelled and the link dies with it.
Links last 7 days, and an invoice accepts at most 5 submitted cards across every link it has — email and API links draw on the same budget. See Update a card on a subscription for the full behaviour and limits.
What stops the retry loop
Some failures end the loop immediately — there's no point retrying a card we know won't work.
| Resolution | Retry? | Why |
|---|---|---|
insufficient_funds | Yes | The customer may have funds later |
provider_error | Yes | Transient PSP issue |
issuer_decline | Yes | Issuer may approve a later attempt |
card_expired | No | Non-recoverable — subscription cancelled immediately |
invalid_cvv | No | Non-recoverable — subscription cancelled immediately |
lost_or_stolen_card | No | Non-recoverable — subscription cancelled immediately |
antifraud_error | No | Non-recoverable — subscription cancelled immediately |
A non-recoverable decline — expired or invalid card, lost/stolen, restricted or blocked, or a fraud flag — ends the dunning ladder on that attempt and cancels the subscription outright. There's no pause-and-resume: to restart billing, create a new subscription once the customer has a working card.
See also
- Subscriptions — the subscription state machine that retries feed into
- Emails — the dunning emails sent at each step, and how to turn them off
- Cascading — multi-provider attempts within a single retry
- Errors — which resolutions are retryable and which terminate the loop
- Update a card on a subscription — handing the customer a card-update link