Retry Segments
Retry Segments is a controlled beta. It is not enabled on every Chargebee site. Contact your Chargebee Technical Success Manager or Account Manager, or Chargebee Support, and ask to join the Retry Segments beta.
Retry Segments lets you apply a different payment-recovery policy to each group of failed payments. You might give annual invoices a longer recovery window, skip further retries after a hard decline, or use a different schedule for a country, product, or gateway.
Your existing retry settings stay the default. A retry segment overrides them only when an invoice matches that segment's conditions. The segment uses the same policy model as the default: you choose which invoices it covers, then how those invoices are retried and what happens when retries end.
A retry segment can define:
| Policy setting | What you define |
|---|---|
| Retry/Dunning period | How long Chargebee continues the recovery cycle. The period counts from the first failure. |
| Retry mode | Custom, Smart, or Revive (AI Retry system in beta). On the Retry mode control, Revive is labeled ML-Powered. Standard is also offered when that mode is enabled on the site. |
| Retry schedule | The day list, plus Preferred days of week, Preferred time window, and time zone. Available when the retry mode is Custom. |
| Skip retries for hard failures | Whether Chargebee skips retries for payment methods with hard declines. The custom schedule still applies to other payment methods. |
| Subscription | The subscription final action: Retain as Active, Cancel subscriptions, or Pause subscriptions. |
| Invoice | The invoice final action: Mark as Not Paid, Mark as Voided, Write-off, or Reverse the Invoice. |
| 'Future' and 'Trial' subscriptions | Whether the policy also applies when a Future or Trial subscription activates and the first payment fails. |
| One-time invoices | Whether the policy also applies to eligible one-time invoices. |
Retry Segments at a glance
| Item | Detail |
|---|---|
| Applies to | Eligible invoices that enter online dunning for cards and digital wallets. |
| Configuration level | Site. A separate configuration for each business entity is not supported in this release. Configuration is not copied between sites, because plans, product families, and gateways can differ. |
| Retry modes | Custom, Smart, and Revive (AI Retry system in beta). On the Retry mode control, Revive is labeled ML-Powered. |
| Evaluation | Active segments are evaluated from highest priority to lowest. The first match wins. Chargebee does not combine policies and does not pick the "most specific" segment. |
| Fallback | The default retry settings apply when no active segment matches. |
| Assignment | Selected once, when dunning begins, and frozen for that invoice. |
| End actions | Separate actions for the subscription and the invoice. |
| Additional coverage | Future and Trial activation invoices, and one-time invoices, when that coverage is enabled. Advance invoices participate only when dunning for advance invoices is enabled. |
| Payment schedules | Not supported in this release. |
| Customer communications | Set from Manage your retry/dunning emails from here on the left side of the retry page. Retry Segments does not send the reminder emails. |
Retry Segments terminology
| Term | Meaning |
|---|---|
| Retry (dunning) | The recovery cycle that begins after an eligible invoice payment fails. |
| Retry segment | A prioritized rule that matches a group of invoices and applies one retry policy. |
| Default policy | The site-wide retry settings used when no active segment matches. On the Segments tab this policy is labeled Baseline. |
| Segment condition | An invoice, billing, geography, payment, plan, or product attribute used to decide whether a segment matches. |
| Retry mode | How Chargebee retries: Custom, Smart, or Revive (AI Retry system in beta). On the Retry mode control, Revive is labeled ML-Powered. |
| Retry/Dunning period | The period during which Chargebee continues recovery before it applies the final actions. It counts from the first failure. |
| Final action | The action applied to the subscription, and the separate action applied to the invoice, when recovery ends without a successful payment. |
| Frozen policy | The segment conditions and retry settings saved on an invoice when dunning starts. Later configuration changes do not change that invoice. |
| Hard failure | A failure that needs customer or merchant action rather than another automatic retry. On the dunning page, hard declines are the errors that need intervention. Soft declines come from a temporary issue, such as connectivity, and can be retried. |
Choose Retry Segments instead of one site-wide policy
One retry policy rarely fits every failed payment.
- A high-value annual contract may need more time, and a gentler final action, than a low-value monthly subscription.
- Customers in different countries may respond better to retries on different days or at different times.
- Products, plans, gateways, and invoice amounts may need different recovery strategies.
Use Retry Segments when you need a different policy for a defined group of invoices. Use the default retry settings when every unmatched invoice should follow one site-wide policy. Use Manage your retry/dunning emails from here on the left side of the retry page when the difference you need is the reminder, not the retry schedule.
Retry Segments is aimed at three outcomes:
- Recover more revenue by applying a strategy that fits the payment.
- Protect customer relationships by giving important accounts an appropriate retry window and final action.
- Reduce unnecessary retries by treating recoverable and non-recoverable failures differently.
How Chargebee selects a retry segment
- Configure the site default retry settings.
- Create one or more retry segments. Each segment has matching conditions and its own recovery policy.
- Arrange the active segments in priority order. The segment at the top has the highest priority.
- When dunning starts for an invoice, Chargebee evaluates active segments from top to bottom.
- Chargebee applies the first matching segment and stops.
- If no segment matches, Chargebee uses the default retry settings.
Only one retry segment can apply to an invoice. Policies from several segments are never combined.
Chargebee selects the segment when dunning begins and stores a snapshot of its conditions and retry settings. Editing, reordering, deactivating, or deleting a segment later does not change invoices that are already in dunning. Enabling Retry Segments does not assign segments to invoices that are already in dunning. A segment is selected only when a new eligible dunning cycle begins.
If you create no retry segments, invoices keep using the default dunning policy. Integrations that do not read segment details can keep processing invoice and dunning behavior as they do today.
Example of first match
Assume the active segments are in this order:
- Annual invoices over $10,000
- Hard declines
- Monthly subscriptions
An annual invoice for $15,000 with a hard decline matches both the first and the second segment. The annual high-value segment is first, so that segment applies. Chargebee does not evaluate the remaining segments.
If the invoice matches none of the three, the default retry settings apply.
Before you configure Retry Segments
Confirm all of the following:
- Online dunning is enabled for cards and digital wallets. In the app, that page is Retry/Dunning for cards, e-wallet payments.
- The default retry settings are configured and saved.
- You know which failed-payment groups need a different policy, and why.
- The plans, product families, gateways, countries, and other values you want to match already exist on the site.
- Default Retry/Dunning is turned on. Segments are unavailable until it is.
People who only need to see which strategy an invoice used need access to that invoice and its Retry Attempts section. They do not need access to edit dunning settings.
Request access
Include this in the access request:
- Your Chargebee site URL
- Whether you want access on a Sandbox Site, a live site, or both
- Approximate monthly failed-payment or dunning volume
- The retry strategies and final actions you want to test
- The team that will validate the configuration and the results
Chargebee reviews the site and enables Retry Segments. You may be asked to validate the experience on a Sandbox Site before it is enabled on the live site.
Payments that Retry Segments can match
Retry Segments applies only to eligible invoices that enter online dunning for automatically collected card and digital-wallet payments. Conditions are evaluated against the invoice and its related payment, customer, subscription, plan, and product information.
Retry Segments is configured on Retry/Dunning for cards, e-wallet payments. That page covers customers who pay by debit card, credit card, PayPal, and other online methods on that page.
Retry Segments does not currently apply to:
- Payment schedules or installment dunning. A payment schedule is not evaluated against retry segments. Its retries keep following the payment-schedule or installment-dunning configuration.
- Direct Debit dunning
- Real Time payments
- Offline dunning
- Gateway-managed dunning
- Payment attempts or collection flows that are not tied to an eligible invoice entering online dunning
Partner retry products keep their own configuration. Retry Segments does not replace Payment Retries with FlexPay or Payment retries with Success+.
Subscription-renewal invoices and one-time invoices can use Retry Segments when the matching online-dunning coverage is enabled. Invoices created when Future or Trial subscriptions activate are covered only when dunning for those activation invoices is enabled.
Configure the default retry policy
The default policy is the fallback for every invoice that does not match an active retry segment. Save it before you rely on segment overrides.
- Log in to your Chargebee site.
- Go to Settings > Configure Chargebee > Online Dunning.
- Select Retry/Dunning for cards, e-wallet payments.
- Select the Default tab.
- Turn on Default Retry/Dunning. This enables retry for failed payments and is where you set automated retries and the final action used when recovery does not succeed.
- Set Retry/Dunning period. This is the number of days failed payments are retried. When the period ends, Chargebee applies the final actions. The period counts from the first failure. You can set the period to 0 days. See Set a zero-day retry period.
- Select a Retry mode.
- Custom: define a retry schedule for your business. This shows the retry schedule and timing preferences.
- Smart: up to 12 retries, scheduled from transaction patterns. Chargebee does not ask you for a day list. Read Smart retry for how hard and soft declines are classified.
- Standard: up to 5 retries spread across the retry/dunning period.
- ML-Powered: Revive, Chargebee's AI retry system, in beta. Retry timing is optimized with machine learning. Choosing it opens Enable Revive. Review the steps, then click Agree. Revive retries cards, Google Pay, and Apple Pay on Stripe and Braintree. Other payment gateways and methods keep using the previous retry system.
- For Custom, set the schedule and the optional timing preferences. See Schedule custom retries.
- Choose coverage:
- 'Future' and 'Trial' subscriptions also retries when payment fails on the day a Trial or Future subscription first becomes active. The same retries and final action apply.
- One-time invoices also retries failed one-time charges, such as overages. The subscription is not affected. The same retries and final action apply.
- Dunning for advance invoices enables dunning when payment collection fails on advance invoice generation.
- Dunning for scheduled payments keeps failed scheduled payments, and the invoices they belong to, in payment due. During that time you can recover the payment with automated retries, email reminders, a pay-now link, or a link to update the payment method. This setting stays on the Default tab. A segment does not override it, and a payment schedule is not matched to a segment.
- Under Final action, select the subscription action and the invoice action.
- Click Apply to publish the page. Click Discard to drop unpublished changes.
The subscription action applies to recurring invoices only. The invoice action applies when the invoice is still unpaid at the end of the retry period.
Create a retry segment
Open retry segments
- Go to Settings > Configure Chargebee > Online Dunning > Retry/Dunning for cards, e-wallet payments.
- Select the Segments tab.
- Click Create segment.
Name the segment and set conditions
In Edit segment, enter a Segment name. The name is how the segment is listed, so you can tell rules apart. Use the audience or purpose, such as "High-value annual renewals", "Hard declines", "US monthly subscriptions", or "Product A customers". Avoid a name that only describes the current schedule, because the name should still make sense if you later change the retry mode.
Under Conditions, click Add condition. Conditions decide which failed payments the segment covers. More than one condition uses one match method for the whole set. The control reads Match, then all or any, then AND or OR, then "of these N conditions".
- Match all (AND): every condition must be true.
- Match any (OR): at least one condition must be true. A missing value does not make that condition true. If none of the conditions are true, the segment does not match, and Chargebee evaluates the next segment.
Nested combinations are not supported. You cannot configure "(United States OR Canada) AND amount over $500" as one expression. Create a separate segment for each group.
Conditions that can be available on your site:
| Category | Conditions |
|---|---|
| Billing | Billing frequency, invoice amount |
| Geography | Billing country, shipping country, invoice currency |
| Payment | Payment gateway, payment method, decline type |
| Product | Product family, plan |
List conditions use is any of. Invoice amount can be is greater than, is less than, or is between. Invoice amount compares the amount still to collect on the invoice.
Decline type is Hard decline or Soft decline, taken from the payment source at the start of dunning. Payment gateway and Payment method come from that same source: the subscription's payment source when it has one, otherwise the customer's primary payment source. The gateway list is the gateways configured on the site. The payment-method list is the methods online dunning retries.
Billing country is the country on the invoice billing address. Shipping country is the country on the subscription shipping address. Billing frequency, Plan, and Product family come from that subscription. When the invoice is not for a single subscription, those three values and the shipping country are not set, and a condition that needs one of them does not match. If the product family cannot be read, a product-family condition does not match, and dunning still starts.
Product-family conditions require Product Catalog 2.0 and product families to be enabled.
Define strategy
Open Define strategy. These settings apply only to invoices that match the segment. Every other invoice follows the default.
Depending on the retry mode and the features enabled on the site, set:
- Retry/Dunning period
- Retry mode: Custom, Smart, Standard, or ML-Powered. ML-Powered is Revive (AI Retry system in beta)
- For Custom: Retry schedule, Preferred days of week, Preferred time window, time zone, and Skip retries for hard failures
- When FlexPay is enabled on the site: Retry payments via FlexPay, Chargebee retry period, and FlexPay retry period
- 'Future' and 'Trial' subscriptions
- One-time invoices
- Subscription final action
- Invoice final action
Click Save to store the segment. Click Cancel to close the dialog without saving.
Set segment priority and publish
On Segments by priority, the top segment is evaluated first. Drag a segment to reorder it. Anything that does not match falls back to the default. A new segment that you switch on is added at the top. A new segment that you leave off is added at the bottom. Turning a segment off also moves it below the active segments.
When segments overlap, the first match wins. Put narrower or business-critical segments before broader ones. A useful order is:
- Exceptional or protected accounts
- Non-recoverable or hard-decline policies
- Product, region, or gateway policies
- Broad billing-frequency policies
- The default retry settings, which are not a segment
The list can be filtered by All, Active, and Inactive. Turn a segment on with the Active control when it should be evaluated. Leave it Inactive when it should not match new invoices.
Click Apply to publish the page. Click Discard to drop unpublished changes. Save in the editor stores the segment as a draft. Chargebee matches new invoices against the published segments only.
When the site already holds as many segments as it allows, create is refused and the page tells you to edit an existing segment instead.
Schedule custom retries
Custom retry timing is optional. Chargebee uses the Retry schedule as the base schedule and tries to honor preferred days and the time window on top of it.
| Setting | What it controls | Example |
|---|---|---|
| Retry schedule | The retry days, in order, counted from the first failure. Set the retry/dunning period long enough to cap how late a retry can run. | 1,4,9 |
| Preferred days of week | Optional. Days Chargebee should prefer. You can select weekdays, weekends, or any combination. | Friday, or Monday and Thursday, or Saturday and Sunday |
| Preferred time window | Optional. Local time range for the attempt. Keep the window at least 2 hours long, or cover the whole day to allow a retry at any hour. | 09:00 to 11:00, or 15:00 to 22:00 |
| Time zone | The time zone used for the preferred day and time window. The control is on the preferred time window. | (GMT +00:00) UTC, (GMT +00:00) Europe/London, America/New_York |
On-screen help states:
- The retry schedule is the base schedule. Chargebee tries to match your day and time preferences on top of that schedule.
- A retry moves up to one day earlier or later so that it lands on a selected weekday. If neither the day before nor the day after is a selected weekday, the retry stays on its scheduled day.
- Those days follow the time zone on Preferred time window.
- Retries run only inside the preferred time window, in the time zone you select. Keep the window at least 2 hours long, or cover the whole day.
- The invoice shows that time in the site time zone.
Example custom schedule
A merchant sets:
- Retry/Dunning period: 14 days
- Retry schedule: 1, 4, 9, counted from the first failure
- Preferred day: Friday
- Preferred time window: 09:00 to 11:00
- Time zone: America/New_York
For each of those days, Chargebee moves the retry onto Friday when Friday is the day before or the day after the scheduled date. Otherwise the retry stays on day 1, 4, or 9. Each attempt is placed between 09:00 and 11:00 in New York time. The invoice shows that time in the site time zone.
Skip retries for hard failures
Skip retries for hard failures applies to custom retries. When it is on, Chargebee stops retrying a payment method the gateway says cannot work, instead of spending the rest of the schedule on it. The custom retry schedule still applies to other payment methods. On the default settings, the same control says retry attempts are skipped for payment methods with hard declines, and the words "hard declines" link to the site's error settings.
A hard classification is a signal about whether another retry is likely to help. It is not a substitute for your own review of card-network and business obligations. Choose final actions that match those obligations.
For how Chargebee classifies hard and soft declines, see Smart retry. For 3D Secure (3DS) authentication failures, see Dunning for 3DS payments. Existing handling of 3D Secure and customer-authentication failures still applies unless the segment changes a setting that is available to you.
Pause subscriptions when recovery ends
Pause subscriptions is a subscription final action. The same menu also offers Retain as Active and Cancel subscriptions.
When an invoice reaches the end of its retry period without a successful payment, Chargebee applies two independent outcomes:
- The subscription final action: Retain as Active, Cancel subscriptions, or Pause subscriptions.
- The invoice final action: Mark as Not Paid, Mark as Voided, Write-off, or Reverse the Invoice.
Retain as Active leaves the subscription running with no change, even though the invoice is unpaid.
Cancel subscriptions ends the subscription immediately. The customer must resubscribe to use it again.
Pause subscriptions pauses the subscription without ending it. Billing stops. Access can be restored by resuming, and the subscription contract stays intact. Use pause instead of cancel when you want to keep the customer without continuing to bill them.
Use Pause subscriptions when:
- The account is high-value or enterprise and should not be canceled automatically
- An annual contract needs a person to intervene after retries fail
- Access should stop until the payment is resolved
- A collections or account-management team owns the customer
- The customer may return after updating the payment method
In this release, a pause that dunning applies is indefinite. Chargebee does not automatically resume the subscription after a fixed period. After the payment or account issue is resolved, resume the subscription in Chargebee or with the Resume Subscription API. How pause and resume affect invoices, unbilled charges, and billing dates is covered in Pause Subscription.
The frozen snapshot records the subscription final action, so the invoice can show why the subscription was retained, paused, or canceled.
Review how a pause affects access, later invoices, scheduled changes, entitlements, and customer communications in your own setup before you select it. Set the invoice final action separately, so the unpaid invoice is handled the way you intend.
The invoice action works as follows:
- Mark as Not Paid leaves the invoice open. Chargebee can still attempt to collect it later.
- Mark as Voided cancels the invoice. The amount is no longer owed.
- Write-off writes off the invoice as uncollectible and creates an adjustment credit note with reason Write Off.
- Reverse the Invoice marks the invoice Paid and creates an adjustment credit note with reason Order Cancellation. Use it to cancel the charge, not to record a payment.
Set a zero-day retry period
Retry/Dunning period can be 0 days. Chargebee then runs the final action at once, and the custom schedule stays at day 1. Turn off Retry payments via FlexPay before you set 0 days. A FlexPay retry needs a period of at least 1 day.
Use 0 days when another automatic retry is unlikely to help, for example a hard decline that needs the customer or you to act. Review both final actions before you use it.
What stays the same when you enable Retry Segments
Retry Segments changes which policy is selected. It does not replace dunning itself. Unless the segment changes a setting that is available on the policy, existing behavior still applies for:
- Payment-method updates
- Collect now
- A later successful payment
- Hard failures
- 3D Secure (3DS) or other customer-authentication failures
- Pause dunning and Stop dunning on an invoice
- Final invoice processing
If no active segment matches, or you have not created any segments, the invoice uses the default retry settings. An invoice that matched a segment keeps the policy copied onto it when dunning started.
Segment states
A change you save is a draft until you click Apply. The page can show DRAFT while those edits are unpublished, including on a segment that is still Active. Draft edits are not what Chargebee uses for new invoices. After a save that is not published, the page says "Draft saved · Not live yet." Reordering a segment, or switching it on or off, is also saved as a draft until you publish.
Each segment is Active or Inactive:
- Active: evaluated, from highest priority to lowest, when dunning begins, after you publish.
- Inactive: not matched to new invoices. Chargebee skips it and continues down the list. A lower-priority segment, or the default settings, can apply instead.
The list filters are All, Active, and Inactive. There is no Draft filter.
On the Segments tab, each row has an Active or Inactive control. Turning a segment off opens Switch this segment off?
The dialog states:
- The segment stops matching once you publish.
- The segment stays on the tab, with its conditions and settings, and can be switched back on.
- Changes apply to new invoices only. Invoices already in retry/dunning finish on their current rules, even if you disable the segment.
Click Confirm to turn the segment off, or Dismiss to leave it unchanged. The off state takes effect for new dunning cycles when you publish with Apply.
An inactive segment does not block lower-priority segments. Chargebee skips it and continues down the list.
How retry-segment changes affect invoices
The invoice keeps the policy it started with, so you can explain a historical retry after the configuration changes.
| Change | Invoices already in dunning | New dunning cycles |
|---|---|---|
| Edit a segment | Keep the frozen policy | Use the updated policy after it is published |
| Reorder segments | Keep the original segment | Use the new priority order |
| Deactivate a segment | Keep the original segment policy | Fall through to the next matching active segment, or to the default |
| Edit the default settings | Segmented invoices keep their frozen segment policy | Unmatched invoices use the updated default |
Editing a segment, reordering segments, or switching a segment off does not change an invoice that is already in retry under that segment.
This freeze keeps a matched invoice from changing schedules or final actions in the middle of recovery. Chargebee does not reassign the segment if customer attributes, the invoice, the payment failure, the subscription, or the segment configuration change during that dunning cycle. Decline type can change on a later attempt, which is one reason the segment is chosen once.
How retry-segment matching works
First matching segment wins
Chargebee evaluates active segments from highest priority to lowest and stops at the first match. It does not decide which segment is most specific. If two segments match, reorder them or narrow the conditions.
Missing values do not match
If a condition needs a value that the invoice or customer does not have, that segment does not match. Chargebee continues to the next segment. If none match, it uses the default settings.
An invoice with no shipping address does not match a segment that depends on shipping country.
Plan, product family, billing frequency, and shipping country
Those values are read from the invoice's subscription. When the invoice is not for a single subscription, they are not set. A condition that needs one of them does not match, and Chargebee continues to the next segment or to the default settings.
Segment choice happens once
Chargebee resolves the segment when dunning begins. Later changes to the customer, the invoice, the payment failure, the subscription, or the segment do not move that invoice to another segment during the same dunning cycle.
Configure customer communications for payment failures
Retry Segments controls payment retries. It does not send reminder emails. On the left side of the retry page, use Manage your retry/dunning emails from here.
A retry segment and a communication rule do not have to cover the same invoices. Two groups can share a retry schedule and still receive different messages based on customer value or account ownership.
View the retry segment on an invoice
Open the invoice and find Retry Attempts. The section shows the cycle status, such as In progress, Exhausted, Stopped, or Recovered, and the attempts, including the Original attempt. View retry segment opens the Retry segment panel. When no segment matched, the panel says the invoice is retried on the default settings as they stand today.
The panel states that this is the segment the invoice started retry/dunning under, and that editing the segment later does not change how this invoice is retried.
The Retry segment panel shows:
- Segment name and segment ID
- Match logic, such as AND
- Conditions and values that matched
- Retry/Dunning period
- Retry mode
- Whether 'Future' and 'Trial' subscriptions coverage is on
- Whether One-time invoices coverage is on
- Final action on the subscription
- Final action on the invoice
When the frozen policy used them, the panel also shows Maximum retries, Retry schedule, Preferred days of week, Preferred time window, Skip retries for hard failures, Chargebee retry period, and FlexPay retry period.
The snapshot remains after the segment is edited, reordered, or switched off. Use it to answer:
- Why did this invoice use this retry schedule?
- Why did another segment not apply?
- Which conditions matched?
- Which attempts have already run?
- Which final action runs if recovery fails?
- Why was the subscription paused, retained, or canceled?
Track retry-segment assignment with events and APIs
Chargebee will shortly expose events and APIs to help you understand which retry segment was assigned to an invoice and retrieve the relevant configuration. Details about availability and how to use these capabilities will be shared when they are released.
You create, edit, reorder, and switch segments in the Chargebee site. Public API management is not available in this release.
Upcoming: Retry dashboard
Chargebee plans to introduce a retry dashboard to help you track metrics across retry segments. A/B experiments across segments are a future capability.
A dry-run that tests a segment against historical invoices is not available.
Example retry segment strategies
Adapt the timing and final actions to your business, customer commitments, and payment-network requirements. These examples are patterns, not required settings.
Give annual customers more time
Goal: protect high-value renewals from an early cancellation.
| Setting | Example |
|---|---|
| Conditions | Billing frequency is Yearly, and invoice amount is greater than $10,000 |
| Match method | Match all (AND) |
| Retry policy | A longer retry/dunning period, with retries spread across the window |
| Subscription final action | Pause subscriptions, or Retain as Active |
| Priority | Above broad annual or monthly segments |
Stop unnecessary retries for hard declines
Goal: avoid another attempt when a retry is unlikely to succeed or the customer must act.
| Setting | Example |
|---|---|
| Conditions | Decline type is Hard decline |
| Retry policy | Retry/Dunning period of 0 days |
| Final action | The invoice and subscription outcomes that match your business |
| Priority | Above general billing-frequency segments |
Retry on preferred days and time windows
Goal: line attempts up with days and local times when customers are more likely to have funds available.
| Setting | Example |
|---|---|
| Conditions | Billing country is United States, and billing frequency is Monthly |
| Retry mode | Custom |
| Retry schedule | 1, 4, 9, counted from the first failure |
| Preferred days of week | Friday |
| Preferred time window | 09:00 to 11:00 |
| Time zone | America/New_York |
| Retry/Dunning period | 14 days |
Chargebee moves a retry onto Friday when Friday is the day before or the day after the scheduled date, and places each attempt between 09:00 and 11:00 in the selected time zone. Otherwise the retry stays on its scheduled day. The invoice shows the time in the site time zone.
Use different policies by product line
Goal: protect a flagship product and use a shorter recovery cycle for a lower-value addon.
Create one segment for the flagship product family and another for the addon. If an invoice could match both, put the narrower or more important rule first.
Test retry segments before you publish them
Test new segments on a Sandbox Site before you enable them for live invoices. You can use Time Machine to move the Sandbox Site forward. See How to test dunning using Time Machine.
Check:
- Representative test data, including segment conditions, missing values, priority, and fallback to the default
- Unpublished drafts versus Active and Inactive, and that edits and reordering do not change a policy already in use
- Eligible one-time invoices and Future or Trial activation invoices, and that unsupported flows are excluded
- Retry schedule, preferred days, time window, and time zone
- Subscription and invoice final actions, including Pause subscriptions
- Invoice details, the Retry Attempts section, and webhook processing for the events you already consume
A dry-run against historical invoices is not available. Start with a narrow, low-risk segment. Watch the first invoices through a full retry cycle before you widen the conditions.
Retry Segments best practices
- Start with two or three groups that clearly need different treatment. Add a segment only when you can explain the recovery or customer-experience result you expect.
- Name the segment for the audience or the purpose. Use "High-value annual renewals", not "28-day Revive". The name should still make sense if you later change the retry mode.
- Put exceptions before broad rules. A narrow enterprise rule should usually sit before a broad annual-customer rule. Review overlap whenever you add or reorder segments.
- Treat the default policy as a complete fallback. Every invoice that misses every active segment uses it.
- Change active policies deliberately. Edits affect new dunning cycles, not invoices already in progress. Leave enough time to compare outcomes before you change the policy again.
- Compare recovery using invoice context, retry history, exports, and the reporting you already have. Weigh invoice volume and value, not only the recovery percentage, before you change a policy.
Retry Segments limitations
Which invoices are eligible
- Retry Segments applies only to eligible invoices entering online dunning for cards and digital wallets. A payment attempt or collection flow with no eligible invoice does not participate.
- Payment schedules are not supported. Installments follow the existing payment-schedule or installment-dunning settings and are not evaluated against segments.
- Direct Debit, Real Time payments, offline, gateway-managed, and installment dunning are not segmented.
- One-time invoices, advance invoices, and Future or Trial activation invoices participate only when their own dunning coverage is enabled.
How matching is limited
- Only one segment applies. Policies are not combined.
- Conditions use one Match all (AND) or Match any (OR) operator. Nested combinations are not supported.
- A condition does not match when the invoice, address, payment, subscription, plan, or product value it needs is missing. Evaluation continues.
- Plan, product-family, billing-frequency, and shipping-country conditions do not match an invoice that is not for a single subscription.
- Product-family conditions require Product Catalog 2.0 and product families.
- Selection happens once, when dunning begins. Later invoice, customer, payment-failure, subscription, or segment changes do not reassign that cycle.
How configuration is limited
- Retry Segments is configured for the site, not for each business entity. It is not copied from one site to another.
- Edits and priority changes do not affect invoices already in dunning.
- Deactivating a segment does not change an assigned invoice's frozen policy. Inactive segments are skipped and do not block lower-priority segments.
- Public API management is not available in this release. A/B experiments and a segment-performance dashboard are future capabilities. A dry-run matcher is not available.
Troubleshoot retry segment assignment
An invoice did not use the segment you expected
- Is the segment active, and is the page published with Apply?
- Is online dunning enabled for the site?
- Does the invoice use a supported payment method and automatic collection?
- Is this a regular eligible invoice, rather than a payment-schedule installment?
- If it is a one-time invoice or a Future or Trial activation invoice, is that dunning coverage enabled?
- Does the invoice contain every value the conditions require?
- Does a higher-priority segment also match?
- Is the invoice already in dunning under an earlier snapshot?
- Is the invoice not for a single subscription, while the segment depends on plan, product family, billing frequency, or shipping country?
If no active segment matches, the default retry settings apply.
An edited segment did not change an existing invoice
This is expected. Chargebee freezes the selected segment and retry policy when dunning begins. The updated policy applies to new dunning cycles after you publish it.
An inactive segment still appears on an invoice
The invoice matched that segment before you deactivated it. It keeps the frozen policy so the retry schedule and final actions do not change mid-cycle.
Two segments match the same invoice
Only the higher-priority segment applies. Reorder the segments, or narrow the conditions, if that is not the result you want.
A product or plan segment did not match
Confirm that the plan or product family exists on the site. Plan, product-family, billing-frequency, and shipping-country conditions do not match an invoice that is not for a single subscription.
A preferred day or time window was not used for every retry
A retry moves onto a preferred day only when that day is the day before or the day after the scheduled date. Otherwise it stays on the scheduled day.
A configured time window is applied in the time zone on Preferred time window. The invoice shows the time in the site time zone.
The on-screen help says the retry schedule stays the base schedule, and that retries run only inside the time window. A window shorter than 2 hours does not meet the on-screen minimum unless you cover the whole day.
Retry Segments frequently asked questions
Can more than one retry segment apply to an invoice?
No. Chargebee applies the first matching active segment and stops.
What happens when no segment matches?
The invoice uses the site's default retry settings.
Can an invoice move to another segment during dunning?
No. The selected segment and retry policy stay locked for that dunning cycle.
What happens when I deactivate a segment?
It no longer matches new dunning cycles after you publish. Invoices already assigned to it keep their frozen policies. The segment remains on the Segments tab and can be turned on again.
Can I create separate segments for Direct Debit, Real Time payments, or offline payments?
Not in this release. Retry Segments supports cards and digital wallets.
Do Retry Segments apply to payment schedules?
No. Payment schedules and their installment-dunning flow are not supported in this release. They keep their existing payment-schedule or installment-dunning configuration and are not evaluated against retry segments.
Do Retry Segments apply to one-time or activation invoices?
They can. One-time invoices are included only when online dunning for one-time invoices is enabled. Invoices generated when Future or Trial subscriptions activate are included only when dunning for those activation invoices is enabled. Advance invoices are included only when dunning for advance invoices is enabled.
Can I use both Match all and Match any inside one segment?
No. Choose one operator for the whole set of conditions. Create another segment when you need a different combination. Nested expressions are not supported.
Do Retry Segments also control reminder emails?
No. Retry Segments controls payment retries. On the left side of the retry page, use Manage your retry/dunning emails from here.
Can I manage retry segments through public APIs?
Not in this release. Create and manage segments in the Chargebee site. Events and APIs for the segment assigned to an invoice will be shared when they are released.
Can I test a segment against historical invoices before activating it?
No. A dry-run matcher is not available in this release. Use a narrow segment, review priority, and roll the segment out on a Sandbox Site first. Time Machine can move that Sandbox Site forward.