A retry segment is a set of conditions together with the retry settings Chargebee uses for invoices that meet them. With retry segments, invoices on the same site can be retried differently, for example with a longer dunning period for high-value invoices or a different retry schedule for a particular payment gateway.
When an invoice enters dunning, Chargebee checks the switched-on segments in priority order and uses the first one whose criteria the invoice meets. The segment and its settings are then locked on the invoice as an invoice retry context, so later edits to the segment don't change how that invoice is retried.
The default segment
The site's default dunning settings are also published as a segment named Default segment: it has no criteria, is always enabled, and has the last priority, so it matches every invoice no other segment does. Edit its settings in the Default tab of the dunning settings. An invoice that matches no other segment locks the default segment like any other, so it too has an invoice retry context and triggers the retry_segment_assigned event.
The default segment exists once a segment has been created, or the default settings saved, after retry segments were enabled for the site. Invoices dunned before that follow the default settings live and have no invoice retry context.
Segments are created and managed in the dunning settings in Chargebee Billing. The API is read-only: use List retry segments and Retrieve a retry segment to read the segments as currently published, and List invoice retry contexts to read the settings locked on a specific invoice.
Note: Retry segments apply only to invoices in auto_collect dunning, and only when retry segments are enabled for the site.
Sample Retry segmentJSON
Retry Segment attributes
Unique identifier of the retry segment. Same value as invoice_retry_context.retry_segment_id.
Type of dunning the segment's retries apply to. Currently always auto_collect.
Retries of invoices collected automatically from a stored payment method.
Retries of invoices collected offline.
Retries of invoices collected by direct debit.
Retries of invoices collected through real-time payments.
Conditions an invoice must meet for this segment to apply. A group object with:
type: alwaysgroup.logical_operator: how theconditionsare combined.and: the invoice must meet every condition.or: the invoice must meet at least one condition.conditions: the conditions, each with:type: alwayscondition.field: the invoice attribute compared.operator: one ofin,greater_than,less_than,between.value: the value compared against. An array of values forinand forbetween(the lower and upper bound).
The fields are:
billing_frequency(in): billing frequencies, each an object withbilling_periodandbilling_period_unit(day,week,monthoryear), as on a subscription. For example,{"billing_period": 3, "billing_period_unit": "month"}is every 3 months.invoice_amount(greater_than,less_than,between): the amount to be collected on the invoice, as a number in whole major units of the invoice's currency. For example,50means $50 on a USD invoice.billing_country(in): billing address countries, as ISO 3166 alpha-2 codes.shipping_country(in): shipping address countries, as ISO 3166 alpha-2 codes.invoice_currency(in): invoice currencies, as ISO 4217 codes.payment_gateway(in): payment gateways, for examplestripe.payment_method(in): payment method types, for examplecard.decline_type(in):hardorsoft, the type of decline of the failed payment.plan(in): plan IDs.
Each field appears at most once in conditions. The default segment has no conditions: conditions is empty.
Retry settings of the segment. Only the settings configured on the segment are returned. For the default segment, these are the site's default dunning settings.
dunning_days: length of the dunning period in days, counted from the invoice due date.0means no retries: the final actions apply as soon as the payment fails.retry_mode: how retries are scheduled. One ofstandard,custom,smart,ml_powered.retry_schedule_days: days after the invoice due date on which retries are made. Returned whenretry_modeiscustom.retry_weekdays: days of the week retries are preferred on. Each value is one ofmonday,tuesday,wednesday,thursday,friday,saturday,sunday. A retry moves up to a day earlier or later to land on a selected day. When absent, retries follow the retry schedule.retry_time_window: hours of the day retries are made in, asHH:00-HH:00, optionally followed by a time zone, for example09:00-17:00 America/New_York. Without a time zone, the site's time zone applies.skip_retries_for_hard_failures: whether the remaining retries are skipped after a hard decline.flexpay: the hand-off to FlexPay.enabledis whether FlexPay retries part of the dunning period;chargebee_daysandflexpay_daysare the days retried by Chargebee and by FlexPay.final_actions: what happens when the dunning period ends without a successful payment.subscriptionis one ofretain_as_active,cancel_subscriptions,pause_subscriptions.invoiceis one ofmark_as_not_paid,mark_as_voided,write_off,reverse_the_invoice.applies_to:future_and_trial_subsis whether the settings also apply to invoices raised when future or trial subscriptions activate;onetime_invoicesis whether they also apply to one-time invoices.