RevGuard PayPal subscription suspended after failed payments: how to reactivate it and keep the customer
A suspended PayPal subscription is neither paying nor cancelled, and nothing changes until someone acts.
What suspended actually means
When a subscription payment fails, PayPal sends BILLING.SUBSCRIPTION.PAYMENT.FAILED and, depending on the plan's payment-failure settings, retries. Once the plan's failure threshold is reached, PayPal suspends the subscription and sends BILLING.SUBSCRIPTION.SUSPENDED. From that moment:
- PayPal stops trying to charge. No more automatic retries.
- The subscription is not cancelled. It stays suspended until it is reactivated or cancelled.
- The missed amount sits as an outstanding balance on the subscription.
If your app grants access on "not cancelled", a suspended customer keeps using the product for free. Treat suspended as unpaid in your own records the moment the webhook arrives.
Step 1: get the customer's payment working
Almost every suspension comes from the funding source: an expired card, a card the bank declined, or a PayPal balance that ran dry. Only the customer can fix that, in their own PayPal account under automatic payments. So the first move is an email, not an API call:
- Say plainly that their subscription is paused, not cancelled, and nothing is lost.
- Link straight to
https://www.paypal.com/myaccount/autopay/, where they can change the card or bank behind your subscription. - Ask them to reply once it is done, so you can switch it back on for them.
Step 2: reactivate the subscription
Once the funding source works, reactivation is one call to PayPal's Subscriptions API: POST /v1/billing/subscriptions/{id}/activate, with a short reason. The subscription goes back to ACTIVE and bills again on its normal cycle. Check the result by fetching the subscription afterwards rather than trusting the response alone.
Step 3: decide about the missed amount
The months the customer was suspended are an outstanding balance, not a lost cause. You can collect it with POST /v1/billing/subscriptions/{id}/capture. Whether you should depends on the customer: someone who kept using the product while suspended owes it; someone who lost access for weeks may be happier with a clean restart. Decide the rule once and write it into the email, so nobody is surprised by a large charge.
The sequence that brings them back
- The day of suspension: the paused-not-cancelled email with the autopay link.
- Day 3 and day 7: two short reminders. Same link, fewer words each time.
- Before every email: fetch the subscription. If it is already active, send nothing and record the recovery.
- After the last email: stop. Cancel or leave it suspended, but make the decision instead of letting it sit for months.
The traps
- Verify the webhook. Run every PayPal event through PayPal's verify-webhook-signature endpoint before acting. A forged "suspended" event should never trigger anything.
- Mint a fresh token every time. PayPal access tokens expire in hours and this sequence runs for a week.
- One email per state. A customer who gets a failed-payment email, then a suspended email, then a reminder on the same day stops reading all of them.
Running it without doing it by hand
The failure side of this, before suspension, is covered in what PayPal does when a subscription payment fails. RevGuard's PayPal recovery workflow handles both: it verifies the webhooks, sends the paused-not-cancelled sequence with the autopay link, re-checks the subscription before every email, and records each case on a dashboard. It is $59 once and runs on your own machine.