Introducing the Chargebee CLI

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 settingWhat you define
Retry/Dunning periodHow long Chargebee continues the recovery cycle. The period counts from the first failure.
Retry modeCustom, 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 scheduleThe day list, plus Preferred days of week, Preferred time window, and time zone. Available when the retry mode is Custom.
Skip retries for hard failuresWhether Chargebee skips retries for payment methods with hard declines. The custom schedule still applies to other payment methods.
SubscriptionThe subscription final action: Retain as Active, Cancel subscriptions, or Pause subscriptions.
InvoiceThe invoice final action: Mark as Not Paid, Mark as Voided, Write-off, or Reverse the Invoice.
'Future' and 'Trial' subscriptionsWhether the policy also applies when a Future or Trial subscription activates and the first payment fails.
One-time invoicesWhether the policy also applies to eligible one-time invoices.

Retry Segments at a glance

ItemDetail
Applies toEligible invoices that enter online dunning for cards and digital wallets.
Configuration levelSite. 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 modesCustom, Smart, and Revive (AI Retry system in beta). On the Retry mode control, Revive is labeled ML-Powered.
EvaluationActive 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.
FallbackThe default retry settings apply when no active segment matches.
AssignmentSelected once, when dunning begins, and frozen for that invoice.
End actionsSeparate actions for the subscription and the invoice.
Additional coverageFuture 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 schedulesNot supported in this release.
Customer communicationsSet 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

TermMeaning
Retry (dunning)The recovery cycle that begins after an eligible invoice payment fails.
Retry segmentA prioritized rule that matches a group of invoices and applies one retry policy.
Default policyThe site-wide retry settings used when no active segment matches. On the Segments tab this policy is labeled Baseline.
Segment conditionAn invoice, billing, geography, payment, plan, or product attribute used to decide whether a segment matches.
Retry modeHow Chargebee retries: Custom, Smart, or Revive (AI Retry system in beta). On the Retry mode control, Revive is labeled ML-Powered.
Retry/Dunning periodThe period during which Chargebee continues recovery before it applies the final actions. It counts from the first failure.
Final actionThe action applied to the subscription, and the separate action applied to the invoice, when recovery ends without a successful payment.
Frozen policyThe segment conditions and retry settings saved on an invoice when dunning starts. Later configuration changes do not change that invoice.
Hard failureA 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:

  1. Recover more revenue by applying a strategy that fits the payment.
  2. Protect customer relationships by giving important accounts an appropriate retry window and final action.
  3. Reduce unnecessary retries by treating recoverable and non-recoverable failures differently.

How Chargebee selects a retry segment

  1. Configure the site default retry settings.
  2. Create one or more retry segments. Each segment has matching conditions and its own recovery policy.
  3. Arrange the active segments in priority order. The segment at the top has the highest priority.
  4. When dunning starts for an invoice, Chargebee evaluates active segments from top to bottom.
  5. Chargebee applies the first matching segment and stops.
  6. 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:

  1. Annual invoices over $10,000
  2. Hard declines
  3. 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.

  1. Log in to your Chargebee site.
  2. Go to Settings > Configure Chargebee > Online Dunning.
  3. Select Retry/Dunning for cards, e-wallet payments.
  4. Select the Default tab.
  1. 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.
  2. 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.
  3. 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.
  4. For Custom, set the schedule and the optional timing preferences. See Schedule custom retries.
  5. 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.
  6. Under Final action, select the subscription action and the invoice action.
  7. 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

  1. Go to Settings > Configure Chargebee > Online Dunning > Retry/Dunning for cards, e-wallet payments.
  2. Select the Segments tab.
  3. 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:

CategoryConditions
BillingBilling frequency, invoice amount
GeographyBilling country, shipping country, invoice currency
PaymentPayment gateway, payment method, decline type
ProductProduct 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:

  1. Exceptional or protected accounts
  2. Non-recoverable or hard-decline policies
  3. Product, region, or gateway policies
  4. Broad billing-frequency policies
  5. 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.

SettingWhat it controlsExample
Retry scheduleThe 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 weekOptional. Days Chargebee should prefer. You can select weekdays, weekends, or any combination.Friday, or Monday and Thursday, or Saturday and Sunday
Preferred time windowOptional. 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 zoneThe 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:

  1. The subscription final action: Retain as Active, Cancel subscriptions, or Pause subscriptions.
  2. 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.

ChangeInvoices already in dunningNew dunning cycles
Edit a segmentKeep the frozen policyUse the updated policy after it is published
Reorder segmentsKeep the original segmentUse the new priority order
Deactivate a segmentKeep the original segment policyFall through to the next matching active segment, or to the default
Edit the default settingsSegmented invoices keep their frozen segment policyUnmatched 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.

SettingExample
ConditionsBilling frequency is Yearly, and invoice amount is greater than $10,000
Match methodMatch all (AND)
Retry policyA longer retry/dunning period, with retries spread across the window
Subscription final actionPause subscriptions, or Retain as Active
PriorityAbove 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.

SettingExample
ConditionsDecline type is Hard decline
Retry policyRetry/Dunning period of 0 days
Final actionThe invoice and subscription outcomes that match your business
PriorityAbove 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.

SettingExample
ConditionsBilling country is United States, and billing frequency is Monthly
Retry modeCustom
Retry schedule1, 4, 9, counted from the first failure
Preferred days of weekFriday
Preferred time window09:00 to 11:00
Time zoneAmerica/New_York
Retry/Dunning period14 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

  1. Is the segment active, and is the page published with Apply?
  2. Is online dunning enabled for the site?
  3. Does the invoice use a supported payment method and automatic collection?
  4. Is this a regular eligible invoice, rather than a payment-schedule installment?
  5. If it is a one-time invoice or a Future or Trial activation invoice, is that dunning coverage enabled?
  6. Does the invoice contain every value the conditions require?
  7. Does a higher-priority segment also match?
  8. Is the invoice already in dunning under an earlier snapshot?
  9. 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.