Skip to main content
When a subscription renews, Polar advances it to the next billing cycle first, then attempts to charge the customer’s default payment method for the new order. If that charge fails, the subscription moves to past_due and enters Polar’s automated payment recovery (dunning) flow instead of being canceled straight away. This page explains exactly what happens during that window, how to give yourself breathing room before benefits are revoked, and what levers you have to help the customer recover.

​
The retry schedule

As soon as the first renewal charge fails:
  1. The subscription’s status moves from active to past_due, and past_due_at is stamped with the time of the failure.
  2. Polar emails the customer to let them know the charge failed and links them to the Customer Portal so they can update their default payment method.
  3. The renewal order stays open with next_payment_attempt_at set to the next retry time.
Polar then retries the charge on a fixed schedule, starting from the time of the first failure:
AttemptDelay from previousCumulative time from first failure
1st retry2 days2 days
2nd retry5 days7 days
3rd retry7 days14 days
4th retry7 days21 days
If any retry succeeds, the subscription returns to active and the cycle continues normally. If all four retries fail — or the payment’s decline code indicates the method will never succeed (for example, lost_card) — Polar stops retrying and revokes the subscription. Its status moves to canceled and benefits are revoked (subject to the grace period below).

​
Benefit revocation grace period

By default, benefits follow the subscription’s status strictly: the moment the subscription leaves active, benefits are revoked. For many businesses that’s harsh — a single expired card shouldn’t instantly lock a paying customer out while they update their details. Polar has an organization-level grace period that holds off benefit revocation while a subscription is in past_due. You can set it under Settings → Billing → Subscriptions → Grace period for benefit revocation. The available values are:
  • Immediately (default) — revoke benefits as soon as the subscription leaves active.
  • After 2 days
  • After 7 days
  • After 14 days
  • After 21 days — benefits stay granted for the full length of the retry schedule.
The grace period is measured from past_due_at. While it’s in effect the subscription is still past_due (so you can differentiate it in your own app), but the customer retains access to their benefits. Once the grace period expires — or the subscription is revoked for good — benefits are revoked on the next check.
The grace period only delays benefit revocation. It does not change the retry schedule, and it does not keep the subscription active. If you want to treat past-due subscribers specially (for example, with a banner or a reduced feature set), listen for the subscription.updated webhook and branch on status === "past_due".

​
Helping customers recover

The most reliable way for a customer to get back into active is to update their default payment method from the Customer Portal. As soon as the payment method is updated, Polar retries the charge immediately rather than waiting for the next scheduled attempt. Things you can do from your side:
  • Link prominently to the Customer Portal from your own app when a customer is past_due.
  • Issue a refund on the original failed order if you want to credit the customer for the lost time while keeping the subscription.
  • Reschedule the renewal to give the customer extra time before the next attempt.
  • Revoke the subscription manually if you’ve decided not to pursue recovery.