# Retry Segment

> For the complete machine-readable documentation index, see [llms.txt](https://apidocs.chargebee.com/llms.txt).


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](/docs/api/v2/pcv-1/invoice_retry_contexts), so later edits to the segment don't change how that invoice is retried.

### The default segment[](#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](/docs/api/v2/pcv-1/retry_segments/list-retry-segments) and [Retrieve a retry segment](/docs/api/v2/pcv-1/retry_segments/retrieve-a-retry-segment) to read the segments as currently published, and [List invoice retry contexts](/docs/api/v2/pcv-1/invoice_retry_contexts/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 segment

```json
{
  "object": "retry_segment",
  "id": "__test__KyVkSOVWbgWtUY",
  "name": "High-value monthly invoices",
  "retry_type": "auto_collect",
  "enabled": true,
  "priority": 1,
  "criteria": {
    "type": "group",
    "logical_operator": "and",
    "conditions": [
      {
        "type": "condition",
        "field": "billing_frequency",
        "operator": "in",
        "value": [
          {
            "billing_period": 1,
            "billing_period_unit": "month"
          },
          {..}
        ]
      },
      {..}
    ]
  },
  "retry_settings": {
    "dunning_days": 15,
    "retry_mode": "custom",
    "retry_schedule_days": [
      1,
      {..}
    ],
    "retry_weekdays": [
      "monday",
      {..}
    ],
    "retry_time_window": "09:00-21:00 America/New_York",
    "skip_retries_for_hard_failures": true,
    "flexpay": {
      "enabled": true,
      "chargebee_days": 9,
      "flexpay_days": 6
    },
    "final_actions": {
      "subscription": "retain_as_active",
      "invoice": "mark_as_not_paid"
    },
    "applies_to": {
      "future_and_trial_subs": true,
      "onetime_invoices": true
    }
  }
}
```

## Retry Segment attributes

## Input Parameters

- `id` (required, string, max chars=40)
  Unique identifier of the retry segment. Same value as [`invoice_retry_context.retry_segment_id`](/docs/api/v2/pcv-1/invoice_retry_contexts).

- `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`.
  Possible 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](https://www.iso.org/iso-3166-country-codes.html) codes.
  -   `shipping_country` (`in`): shipping address countries, as ISO 3166 alpha-2 codes.
  -   `invoice_currency` (`in`): invoice currencies, as [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) 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.
  -   `plan` (`in`): plan 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.

