# Preferences (Beta)

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


The Preferences API is in **beta**. Its request and response specification may change in future releases, including breaking changes. Changes are announced in the [API Changelog](https://www.chargebee.com/help/api-updates/).

Preferences are the configuration values that control how your Chargebee site behaves, for example whether a cancelled subscription can be reactivated before the term ends, or whether a one-time charge is invoiced immediately. Use this resource to read and update preference values through the API.

#### Preference variants[](#preference-variants)

A variant is an alternative value for a preference. It uses the same `id` as the base preference and adds a `level` and `criteria` that determine when it applies. Variants are evaluated from the highest `level` to the lowest, and the first variant whose `criteria` match is used. If none match, the base preference value is used.

In this example, level `2` is more specific than level `1`. If both variants match a request, level `2` takes precedence. An API request matches both, so level `2` is used and the value is `allow_reactivation`. A request from the Chargebee interface matches only level `1`, so the value is `allow_only_on_payment_collection`. A request from the self-serve portal matches neither, so the base value `allow_reactivation` is used.

## Sample Preference

```json
{
  "id": "subscription_reactivation.in_term_reactivation_option",
  "preference_group": "subscription_reactivation",
  "value": "allow_reactivation",
  "allow_override_in_interface": true,
  "modified_at": 1787543613,
  "object": "preference"
}
```

## Preferences (Beta) attributes

## Input Parameters

- `id` (required, string, max chars=150)
  Identifies the preference, in the form `<preference_group>.<name>`, for example `subscription_reactivation.in_term_reactivation_option`. Pass this id to [Update preferences](/docs/api/preferences/update-preferences) to change the value, and use it to find the matching entry in [List preference definitions](/docs/api/preference_definitions/list-preference-definitions).

- `preference_group` (required, enumerated string)
  The area of Chargebee this preference belongs to. Pass this as the required `preference_group[<operator>]` filter on [List preferences](/docs/api/preferences/list-preferences) and [List preference definitions](/docs/api/preference_definitions/list-preference-definitions).
  Possible enum values:
    - `unbilled_charges`
      Preferences for whether charges from a subscription action are invoiced immediately or held as unbilled charges until the next invoice.
    - `update_subscriptions`
      Preferences applied when a subscription is updated, including plan changes and scheduled cancellations.
    - `subscription_reactivation`
      Preferences for reactivating a cancelled subscription before its current billing term ends.
    - `trial_end_actions`
      Preferences for what happens when a trial ends: the subscription is activated and billed, or it is cancelled.

- `value` (required, string, max chars=65k)
  The preference's current value, always returned as a string. Encode booleans as `"true"` or `"false"`, numbers as strings such as `"7"`, and lists as JSON arrays encoded as strings such as `"[\"a\"]"`. Use `value_schema` from [List preference definitions](/docs/api/preference_definitions/list-preference-definitions) to interpret the value and validate it before updating the preference.

- `level` (optional, integer)
  The variant's priority. Higher levels are evaluated first. A request that matches both level `2` and level `1` uses level `2`. The base preference omits this field, and variant levels start at `1`. See [Preference variants](#preference-variants).

- `allow_override_in_interface` (optional, boolean)
  Whether the preference value can be overridden for a specific operation in the Chargebee interface. Returned only when the preference definition supports interface overrides. You can change this field with [Update preferences](/docs/api/preferences/update-preferences).

- `allow_override_in_api` (optional, boolean)
  Whether the preference value can be overridden for a specific API call. Returned only when the preference definition has `overridable_in_api` set to `true`. This field is read only. [Update preferences](/docs/api/preferences/update-preferences) does not accept it.

- `modified_at` (optional, timestamp(UTC) in seconds)
  The UTC Unix timestamp, in seconds, when the preference value was last changed.

- `criteria` (optional, list of criteria)
  Defines the conditions under which this variant applies. Present only for a variant. The `operand`, `operator`, and `values` must conform to the preference’s criteria\_schema.
  - `operand` (optional, enumerated string)
    What the condition is evaluated against. The operands a preference accepts are listed as `criteria_schema` in [List preference definitions](/docs/api/preference_definitions/list-preference-definitions).
    Possible enum values:
      - `request_source`
        Where the request came from, such as the API, the Chargebee interface, or the self-serve portal.
  - `operator` (optional, enumerated string)
    How the operand is compared against `values`. The operators a preference accepts are listed as `allowed_operator` in [List preference definitions](/docs/api/preference_definitions/list-preference-definitions).
    Possible enum values:
      - `is`
        Matches when the operand equals the single value in `values`.
      - `in`
        Matches when the operand equals any one of the entries in `values`.
  - `values` (optional, string, max chars=1000)
    The values the operand is compared against. Supply exactly one entry for the `is` operator, and one or more for `in`. Where the definition lists `value_schema.allowed_values` for the operand, every entry must match one of those `value`s.

