Retries and card updates
Dunning manages recoverable subscription payment failures. Do not implement a second independent retry loop that could charge alongside Peak's scheduled attempts.
Default recovery policy
The ordinary retry delays are 1, 3, 7 and 14 days, with a maximum of 4 retries. The final action defaults to SUSPEND, and customer notification is enabled. These are retry delays, not a promise of four successful collections or a guarantee that every decline is retryable.
| Decline category | Default retry delays (days) |
|---|---|
INSUFFICIENT_FUNDS | 3, 5, 7, 10 |
PROCESSING_ERROR | 1, 2, 4 |
SOFT_DECLINE | 1, 3, 7, 14 |
DO_NOT_HONOR | 2, 5, 9 |
When stopOnHardDecline is enabled, HARD_DECLINE, FRAUD_SUSPECTED and INVALID_CARD stop deferred retries. Retry eligibility and network limits can prevent an otherwise scheduled attempt.
Configure a location
Read GET /api/v1/locations/{locationId}/dunning-config, then write PUT to the same path with the intended complete policy:
| Field | Meaning |
|---|---|
retryIntervals | Required nonempty list of positive retry delays in days |
maxRetries | Required positive maximum retry count |
finalAction | Required: SUSPEND, CANCEL or MARK_UNCOLLECTIBLE |
notifyCustomer | Optional; send customer recovery notifications (defaults to true) |
notifyMerchant | Optional; send merchant recovery notifications (defaults to false) |
categoryRetryIntervals | Optional map of decline-category names to nonempty lists of positive day delays |
stopOnHardDecline | Optional; stop deferred retries for hard-stop categories (defaults to true) |
Monitor subscription.payment_failed and subscription.past_due, plus dunning.case_opened, dunning.case_recovered and dunning.case_exhausted. Verify signatures and deduplicate as described in subscription events.
Customer recovery link
The recovery email opens a hosted page bound to the affected subscription and its open dunning case. After successful card setup, Peak's hosted recovery flow updates that subscription's saved card on the server. This is not a general-purpose public subscription PATCH. Follow subsequent recovery/billing status rather than treating a page visit or card save as payment; saving the card does not guarantee an immediate collection.
Proactively ask for a new card
Call POST /api/v1/setup-intents/issue-link with the authorized customer/location, deliveryMode: "EMAIL", customerId and replacementPaymentMethodId. Peak sends the hosted card-update page; inspect the delivery result for confirmation.
On verified setup_intent.succeeded, read the setup intent on your server, validate its customer/location and final status, and retain its paymentMethodId. A successful bound replacement selects the resulting saved card as the customer's default and disables the old active saved method when it is a different card. This replaces a saved method; it does not rewrite existing subscriptions' saved-card references.
The public API does not support changing an existing subscription's savedPaymentMethodId with PATCH /api/v1/subscriptions/{id}. Do not issue a proactive replacement expecting it to switch an existing subscription, particularly because disabling its old method can affect later billing. For a subscription with an open dunning case, use the subscription-bound hosted recovery link above. A standalone setup link is not that recovery link, and changing a customer default is not a subscription card switch.
Account updater availability
A card account updater is not available. Peak does not automatically obtain replacement expiration dates or card numbers from an account-updater network. Use hosted card-update or recovery links instead.