Payment recovery

When a renewal (or end-of-trial charge) fails, the subscription enters past_due. Rollo emails the customer a secure billing link to update their card, and you can retry from Dashboard → Subscriptions.

Retry payment is a Dashboard action today — there is no public POST /v1/subscriptions/:id/retry_payment. Keep access in sync with the webhooks below.

Lifecycle

  1. Renewal or trial-conversion charge fails → payment.failed / subscription.updated (past_due).
  2. Customer opens the update-card link, picks their billing country, and saves a new payment method.
  3. Merchant may also click Retry payment in the dashboard.
  4. Success → payment.succeeded and subscription.updated with status active.

invoice.payment_failed

Example request

# Delivered when a renewal charge fails

Example response

{
  "id": "evt_...",
  "type": "invoice.payment_failed",
  "created": 1725680000,
  "data": {
    "id": "sub_01HXYZ...",
    "subscription": "sub_01HXYZ...",
    "message": "Card declined",
    "merchant_id": "acct_...",
    "livemode": true
  }
}

How to handle it

Mark the account past-due, notify the customer to update their card, and apply your grace policy until recovery or subscription.canceled.

invoice.paid (recovery succeeded)

Example request

# Same event as a normal renewal

Example response

{
  "id": "evt_...",
  "type": "invoice.paid",
  "created": 1725700000,
  "data": {
    "id": "pay_01HREN...",
    "subscription": "sub_01HXYZ...",
    "amount": 2900,
    "currency": "usd",
    "livemode": true
  }
}

How to handle it

Restore full access. Optionally confirm with GET /v1/subscriptions/:id.

Customer action required

Some failures need a new payment method or SCA confirmation. Subscribe to invoice.payment_action_required and guide the customer to update billing. See also Webhooks.