Skip to main content
When a subscription renewal fails, PayNext moves it to past_due status. Use this guide to let customers update their payment method and reactivate their subscription.

​
Decision Flowchart

StatusWhat HappenedRecovery Options
past_dueRenewal payment failedSDK checkout (must collect payment)
cancelledSubscription endedSDK checkout or API
scheduled_for_cancellationCustomer requested cancelAPI only (no payment needed)

​
Recover Past-Due

For past_due subscriptions, you must collect payment via SDK checkout—there’s no API-only option.
1

Create a client session

Include customer and subscription—do not include plan.id:
cURL
curl -X POST https://api.paynext.com/client-session \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-API-Version: 1.0.0" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": { "id": "cus_11dfa45f-23b1-40f4-9e9b-c9d485915528" },
    "subscription": { "id": "sub_11dfa45f-23b1-40f4-9e9b-c9d485915528" },
    "options": { "payment_methods_mode": "saved_or_new" }
  }'
Do not include plan.id for recovery—PayNext uses the existing plan from the subscription.
2

Mount the SDK

Display checkout with the customer’s saved payment method:
const checkout = new PayNextCheckout()

checkout.mount('checkout-container', {
  clientToken: session.id,
  environment: 'sandbox',
  onCheckoutComplete: (result) => {
    // Subscription is now active again
    console.log('Subscription recovered:', result.payment_id)
  },
  onCheckoutFail: (error) => {
    // Customer can try a different card
  }
})
Outcomes:
  • Success: Subscription returns to active, billing cycle resets
  • Failure: Customer can switch to a different card and retry instantly

​
Reactivate Cancelled Subscription

For cancelled subscriptions, you can either collect payment via SDK checkout (above) or reactivate directly via API:
cURL
curl -X PATCH https://api.paynext.com/subscriptions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-API-Version: 1.0.0" \
  -H "Content-Type: application/json" \
  -d '{
    "subscription": {
      "id": "sub_887934f2-de1a-4b28-a288-ba8f70c71bd3",
      "status": "active"
    }
  }'
API reactivation works only for cancelled subscriptions. For past_due, you must collect payment via SDK checkout.

​
Best Practices

  1. Notify customers promptly when renewals fail—the sooner they update their card, the higher the recovery rate
  2. Use email or in-app messaging to direct customers to your recovery page
  3. Show the amount due clearly in your UI before they reach checkout