To master Klaviyo metrics for failed billing, it’s essential to understand the different types of declines: hard and soft.
Hard Declines indicate that a card needs to be updated.
Soft Declines suggest the card may be recoverable with retries.
The key to setting up Klaviyo metrics for failed billing is to use trigger splits.
Error Codes
rtx_error_code
Segmenting Soft vs Hard Declines
To properly segment customers when using Smart Dunning or the Scheduler, you'll use the rtx_error_code field to determine whether a customer falls into the soft decline or hard decline schedule.
Soft Decline Error Codes
payment_method_declined
unexpected_error
paypal_error_general
transient_error
insufficient_funds
manual_entry
inventory_allocations_not_found
card_declined
retry_declined
do_not_honor
generic_error
processing_error
cancelled_payment
transaction_limit_exceeded
merchant_account_error
invalid_payment_error
test_error
purchase_type_not_supported
invalid_purchase_type
Your split should look like this:
Insufficient_funds
While insufficient_funds can be resolved with future retries, this may not be the case depending on the funds available to the card on subsequent retries. You may want to create separate messaging for this error. However, it is essential to be sensitive to this specific error message.
Number of Failed Attempts
rtx_failed_billing_attempts
This field indicates the number of failures a subscription has experienced during a recovery. It will reset when the subscription is cancelled or is recovered.
Recommended Email Cadence
Given the frequency and number of emails that can be triggered when someone enters dunning, it is important to trigger emails at important touch points.
Smart Dunning
Our new Smart Dunning Schedules now retry up to 20 times (21 total failures). Because Stay AI retries soft declines aggressively from the very first failure, customers in dunning can end up receiving a high volume of emails if you don't segment your messaging.
For Soft Declines, we recommend triggering emails at the following rtx_failed_billing_attempts values:
5
9
13
16
18
20 (Second to Last Retry before Cancellation)
Pro-tip: Depending on your subscription program, you may also want to trigger to an email for rtx_failed_billing_attempts 1 or 2, however, it can be incredibly beneficial to silently retry the subscription before alerting the customer of a card failure as receiving a card failure message may prompt some customers to unsubscribe.
For Hard Declines, we recommend triggering emails for all failures as there are only 6 retries over an extended period.
The email messaging should indicate that the customer should update their card. Having separate messaging for rtx_failed_billing_attempts 1-7 can also help in prompting customers to update their card.
You may also want to segment messaging by specific rtx_error_code or rtx_error_message values surrounding card expiration or invalid zip code.
Scheduler
If you are using the Scheduler, it is important to remember that a retry is equal to rtx_failed_billing_attempts + 1. The segmentation above is the same.
Error Messages
rtx_error_message
To create the most robust dunning email flow, using error messages is preferable as they provide more explicit indicators of hard or soft declines.
Examples include:
“Your card was declined.”
“Your card has insufficient funds.”
credit_card_not_found
“This transaction has been declined.”
“Your card number is incorrect.”
“Agreement was canceled.”
“Your card does not support this type of purchase.”
Field: api_errors Error: credit_card_is_expired
In some cases, you can customize your flow to send specific messages about the exact reason for failure, such as an expired card or incorrect card number. For generic declines, you can use broader messaging.