Introducing the Chargebee CLI

Retry Segment

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

id
required, string, max chars=40

Unique identifier of the retry segment. Same value as invoice_retry_context.retry_segment_id.

name
optional, string, max chars=1000

Name of the retry segment. Default segment for the default segment.

retry_type
optional, enumerated string

Type of dunning the segment's retries apply to. Currently always auto_collect.

Enum Values
auto_collect

Retries of invoices collected automatically from a stored payment method.

offline

Retries of invoices collected offline.

direct_debit

Retries of invoices collected by direct debit.

real_time_payments

Retries of invoices collected through real-time payments.

enabled
required, boolean

Whether the segment is switched on. A switched-off segment is not matched against invoices. Always true for the default segment.

priority
optional, integer

Position of the segment in the priority order. 1 is matched against an invoice first. Switched-off segments are placed after the switched-on ones, and the default segment is always last.

criteria
optional, jsonobject

Conditions an invoice must meet for this segment to apply. A group object with:

  • type: always group.
  • logical_operator: how the conditions are combined. and: the invoice must meet every condition. or: the invoice must meet at least one condition.
  • conditions: the conditions, each with:
    • type: always condition.
    • field: the invoice attribute compared.
    • operator: one of in, greater_than, less_than, between.
    • value: the value compared against. An array of values for in and for between (the lower and upper bound).

The fields are:

  • billing_frequency (in): billing frequencies, each an object with billing_period and billing_period_unit (day, week, month or year), 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, 50 means $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 example stripe.
  • payment_method (in): payment method types, for example card.
  • decline_type (in): hard or soft, the type of decline of the failed payment.
  • product_family (in): product family IDs.
  • plan (in): item price IDs.

Each field appears at most once in conditions. The default segment has no conditions: conditions is empty.

retry_settings
optional, jsonobject

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. 0 means no retries: the final actions apply as soon as the payment fails.
  • retry_mode: how retries are scheduled. One of standard, custom, smart, ml_powered.
  • retry_schedule_days: days after the invoice due date on which retries are made. Returned when retry_mode is custom.
  • retry_weekdays: days of the week retries are preferred on. Each value is one of monday, 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, as HH:00-HH:00, optionally followed by a time zone, for example 09: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. enabled is whether FlexPay retries part of the dunning period; chargebee_days and flexpay_days are the days retried by Chargebee and by FlexPay.
  • final_actions: what happens when the dunning period ends without a successful payment. subscription is one of retain_as_active, cancel_subscriptions, pause_subscriptions. invoice is one of mark_as_not_paid, mark_as_voided, write_off, reverse_the_invoice.
  • applies_to: future_and_trial_subs is whether the settings also apply to invoices raised when future or trial subscriptions activate; onetime_invoices is whether they also apply to one-time invoices.