What happens when a payment fails on Polar

Polar sells your subscriptions as merchant of record. When a subscription renewal fails, Polar handles the recovery itself: it retries the card, keeps the subscription in a recoverable state, and revokes benefits if nothing works. The rules are simple and mostly fixed, which is good to know before you design anything around them.

This guide explains the sequence step by step, the one setting you control, the webhooks to listen for, and what you can add without fighting Polar’s own flow. It sticks to Polar’s documentation: recovering failed payments, how subscriptions work, the subscription.past_due and subscription.revoked webhooks (all accessed November 2026). Where Polar’s pages disagree or stay silent, we say so.

The sequence, step by step

According to Polar’s failed payments page:

1. At renewal, Polar first advances the subscription to the next billing cycle, then attempts to charge the customer’s default payment method.
2. If the charge fails, the subscription is not canceled. It moves to past_due and enters Polar’s automated payment recovery.
3. Polar retries the payment on a fixed schedule: four attempts spread over 21 days, counted from the first failure. The schedule is set by Polar and is not configurable.
4. If the customer updates their payment method in the meantime, Polar retries the charge immediately instead of waiting for the next scheduled attempt.
5. If a retry succeeds, the subscription is back in good standing.
6. If all retries fail, or if the decline code shows the payment method will never succeed (Polar gives lost_card as an example), Polar stops retrying and revokes the subscription and its benefits.

Point 6 is worth noticing. Polar does not keep retrying a card that cannot work, which is the right behavior, and it means hard declines end much sooner than 21 days unless the customer acts.

The setting you control: the grace period

By default, Polar revokes benefits strictly. Polar offers an organization-level grace period that holds off benefit revocation while a subscription is past_due. You set it under Settings, then Subscriptions, then “Grace period for benefit revocation”.

What the grace period does and does not do, per Polar’s docs:

	During the grace period
Subscription status	Still past_due
Customer’s benefits	Kept
Retry schedule	Unchanged
Measured from	past_due_at

So the grace period is about access, not about collection. It is a good choice when benefits are things customers rely on day to day (a license key, access to a private repository, a Discord role), and losing them over a temporary card problem would make the customer leave for good.

How the customer fixes it

The fix for most hard declines is a new card. Polar’s subscriptions overview says the Customer Portal lets customers update their payment method, download invoices and cancel. Because Polar retries immediately after a payment method update, a customer who updates their card recovers the subscription right away.

Polar’s docs we checked do not detail the content or timing of any notification emails sent to customers on failure. Test it in sandbox: trigger a failure with a test card and see what reaches the customer’s inbox before you write your own messages, so you do not send duplicates.

The webhooks to listen for

Event	Meaning
subscription.past_due	A renewal failed. Polar describes this as a recoverable state: the customer can update their payment method to restore the subscription.
subscription.updated	The subscription changed, including when it recovers
subscription.revoked	The subscription was revoked, either because it was canceled or because payment retries are exhausted

One inconsistency to plan for: Polar’s subscription.revoked page says that when payment retries are exhausted the status becomes unpaid, while the failed payments page describes the subscription ending as canceled with benefits revoked. Write your handler to treat both as “no longer paying”, and log the actual status you receive.

A practical setup on Polar

1. Decide on the grace period. If benefits are part of daily work, set one. If benefits are cheap to restore, strict revocation is fine.
2. Handle subscription.past_due in your app. Show a banner with a link to the Customer Portal. Many customers never read billing emails, but they do see your product.
3. Explain what happens next. Tell the customer that Polar will try again and that updating the card fixes it right away.
4. Handle revocation gracefully. On subscription.revoked, keep the customer’s data, explain why access stopped, and give a clear way back.
5. Log every failure. Store the subscription, the amount, the date and the outcome. After a few months you will see how many recover by retry and how many only after a card update.
6. Test with sandbox cards. Run a soft decline, a hard decline and a recovery before going live.

What the timeline looks like for a customer

Putting Polar’s rules together, a typical soft decline plays out like this:

1. Renewal day: the charge fails, the subscription becomes past_due, and subscription.past_due reaches your app.
2. Over the next three weeks: Polar makes its scheduled retries. If you set a grace period, the customer keeps their benefits for that long.
3. Any time in that window: the customer updates their card in the Customer Portal, Polar retries at once, and the subscription recovers.
4. End of the window with no success: Polar revokes the subscription, and subscription.revoked reaches your app.

For a hard decline, step 2 can be skipped entirely, because Polar stops retrying a payment method that cannot succeed. That is why the in-app banner matters most for hard declines: the customer’s own action is the only path back, and the window is short.

What Polar does not cover

Polar’s recovery is intentionally simple. The parts left to you:

• Context. Polar treats every failure the same way. A failure on a long-time customer who uses the product daily deserves a different message than one on a dormant account.
• Messages in your own voice. If you want recovery messages that mention the customer’s plan, usage or team, you write them.
• Measurement. Recovered versus lost per month, per cause. See involuntary churn for the definitions and dunning email templates for message ideas.
• Prevention. Cards expiring before the next renewal are predictable. A reminder before the renewal avoids the failure entirely; see expiring cards.

Doing this with NoChurn

On Polar, payment collection, retries and the 21-day schedule stay with Polar as merchant of record; NoChurn does not change them. It reads your Polar subscriptions and failures, sends AI-written recovery emails that you review before they go out, and gives each customer a churn score from 0 to 100, enriched with your own data sent by API. Cancellations then get a cancel flow and win-back emails at day 30, 60 and 90. See NoChurn + Polar.