# Preference Definitions (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/).

A preference definition is the contract for a [preference](/docs/api/preferences/preference-object). It specifies the values the preference accepts, when it applies, whether it supports variants or overrides, and whether it can be updated through the API.

Definitions are returned by [List preference definitions](#list_preference_definitions). There is no endpoint for fetching one on its own.

Use [`preference_group`](#preference_group) to filter preferences in List preference definitions and List preferences.

**Note:** Definitions may change over time. Retrieve them when you need the current rules instead of relying on a cached definition.

#### Applicability

Applicability defines the conditions that must be met for a preference to apply to the site. Each condition names another preference, a comparison operator (`is`, `in`, or `contains`), and the values to compare. `contains` holds when a list-valued preference includes any value in `values`.

##### For example[](#for-example)

`unbilled_charges.invoicing_options.add_charge` applies only when `unbilled_charges.enabled` is `true`

If `applicability` is absent, the preference always applies. Otherwise, it applies only when its conditions are met. When multiple conditions are present, [`applicability_operator`](#applicability_operator) determines how they are evaluated: `and` requires every condition to be met, while `or` requires at least one condition to be met.

**Note:** [List preferences](/docs/api/preferences/list-preferences) returns a preference, and [Update preferences](/docs/api/preferences/update-preferences) accepts a change to it only when the preference applies.

![Whether a preference applies to the site](/images/preference_applicability.png?v=10)

#### Criteria schema

`criteria_schema` defines the request contexts that can be used to create a [preference variant](/docs/api/preferences#preference-variants). Each entry specifies an operand, the allowed operators, and valid values for that operand.

##### For example

For `subscription_reactivation.in_term_reactivation_option`, `criteria_schema` allows `request_source` as the operand, `in` as the operator, and `chargebee_interface`, `api`, and `self-serve_portal` as the values.

**Note:** If `criteria_schema` is absent, the preference does not support variants. If it is present, use [Update preferences](/docs/api/preferences/update-preferences) with both `criteria` and `level` to create a variant.

#### Overrides

Some preferences can be overridden for a specific operation without changing the site-wide value. [`overridable_in_interface`](#overridable_in_interface) indicates whether the preference can be overridden in the Chargebee interface. [`overridable_in_api`](#overridable_in_api) indicates whether it can be overridden through API calls.

`allow_override_in_interface` and `allow_override_in_api` show whether each override is enabled for your site. [Update preferences](/docs/api/preferences/update-preferences) can change `allow_override_in_interface`, but it does not accept `allow_override_in_api`.

##### For example

`unbilled_charges.invoicing_options.add_charge` supports overrides in the Chargebee interface and through API calls.

`invoice_immediately` on [Create a subscription](/docs/api/subscriptions/create-subscription-for-items) overrides `unbilled_charges.invoicing_options.create_subscription` for that call. It does not change `allow_override_in_api`.

**Note:** [List preferences](/docs/api/preferences/list-preferences) includes `allow_override_in_interface` only when `overridable_in_interface` is `true`. It includes `allow_override_in_api` only when `overridable_in_api` is `true`. Otherwise, neither field is returned. [Update preferences](/docs/api/preferences/update-preferences) accepts only `allow_override_in_interface`; it never accepts `allow_override_in_api`.

## Sample Preference-definition

```json
{
  "preference_definition": {
    "id": "subscription_reactivation.in_term_reactivation_option",
    "preference_group": "subscription_reactivation",
    "main_group": "billing_logiq",
    "sub_group": "customers_and_subscriptions",
    "description": "Defines how in-term reactivation of a cancelled subscription is handled when current-term invoices are unpaid.",
    "access_mode": "read_write",
    "overridable_in_interface": true,
    "overridable_in_api": false,
    "object": "preference_definition",
    "value_schema": {
      "type": "string",
      "object": "value_schema",
      "allowed_values": [
        {
          "value": "allow_reactivation",
          "description": "You can allow in-term reactivation of subscriptions even with current term invoices remaining unpaid.",
          "object": "allowed_value"
        },
        {
          "value": "allow_only_on_payment_collection",
          "description": "You can attempt payment collection of current term unpaid invoices and allow reactivation only on successful payment.",
          "object": "allowed_value"
        }
      ]
    },
    "criteria_schema": [
      {
        "operand": "request_source",
        "object": "criteria_schema",
        "allowed_operator": [
          "in"
        ],
        "value_schema": {
          "type": "string",
          "object": "criteria_value_schema",
          "allowed_values": [
            {
              "value": "chargebee_interface",
              "description": "The request originated from the Chargebee interface.",
              "object": "allowed_value"
            },
            {
              "value": "api",
              "description": "The request originated from the Chargebee API.",
              "object": "allowed_value"
            },
            {
              "value": "self-serve_portal",
              "description": "The request originated from the self-serve portal.",
              "object": "allowed_value"
            }
          ]
        }
      }
    ]
  }
}
```

## Preference Definitions (Beta) attributes

## Input Parameters

- `id` (required, string, max chars=150)
  Identifies the preference this definition describes, 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.

- `preference_group` (required, enumerated string)
  The area of Chargebee this preference belongs to. Pass this as the required `preference_group[<operator>]` filter on [List preference definitions](/docs/api/preference_definitions/list-preference-definitions) and [List preferences](/docs/api/preferences/list-preferences).
  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.

- `main_group` (required, string, max chars=100)
  The top-level group Chargebee uses to display this preference. Use this only for visualization. Use `preference_group` to identify or filter preferences.

- `sub_group` (required, string, max chars=100)
  The group Chargebee uses to display this preference within `main_group`. Use this only for visualization.

- `description` (required, string, max chars=65k)
  What this preference controls, in plain language.

- `access_mode` (required, enumerated string)
  Whether this preference can be changed over the API, or only read.
  Possible enum values:
    - `read_write`
      The preference can be read and updated.
    - `read_only`
      The preference can be read but not updated; attempting to change it is rejected.

- `overridable_in_interface` (required, boolean)
  Whether this preference's value may be overridden for a specific operation from the Chargebee interface, instead of always using the site-wide value. When `true`, the value returned by [List preferences](/docs/api/preferences/list-preferences) carries `allow_override_in_interface`, which you can also change. See [Overrides](#overrides).

- `overridable_in_api` (required, boolean)
  Whether this preference's value may be overridden for a specific API call by passing the equivalent parameter on the operation. For example, `invoice_immediately` on [Create a subscription](/docs/api/subscriptions/create-subscription-for-items) overrides `unbilled_charges.invoicing_options.create_subscription`. When `true`, [List preferences](/docs/api/preferences/list-preferences) returns `allow_override_in_api`. That field is read only and cannot be changed with [Update preferences](/docs/api/preferences/update-preferences). See [Overrides](#overrides).

- `applicability_operator` (optional, enumerated string)
  Present when `applicability` lists more than one condition, indicating whether all of them or any one of them must hold.
  Possible enum values:
    - `and`
      Every condition in `applicability` must hold.
    - `or`
      At least one condition in `applicability` must hold.

- `applicability` (optional, list of applicability)
  Conditions that must be met for this preference to apply to the site. See [Applicability](#applicability-rules).

- `value_schema` (optional, value_schema)
  The values this preference accepts. Use it to validate a value before sending it to [Update preferences](/docs/api/preferences/update-preferences).

- `criteria_schema` (optional, list of criteria_schema)
  Request contexts in which this preference can take an alternative value. See [Criteria schema](#criteria-schema).

## Applicability attributes

## Input Parameters

- `preference` (optional, string, max chars=150)
  The `id` of the preference this condition looks at.

- `operator` (optional, enumerated string)
  How that preference's current value is compared against `values`.
  Possible enum values:
    - `is`
      The condition holds when the preference equals the single entry in `values`.
    - `in`
      The condition holds when the preference equals any one of the entries in `values`.

- `values` (optional, string, max chars=65k)
  The values the referenced preference is compared against. Always a list. `is` uses a single entry. `in` and `contains` use one or more.

## Value schema attributes

## Input Parameters

- `type` (required, enumerated string)
  The preference's data type. Preferences that accept a fixed set of options report `string` here and list the options in `allowed_values`.
  Possible enum values:
    - `boolean`
      A true or false value. Send and receive as `"true"` or `"false"`.
    - `string`
      A string. When `allowed_values` is present, the value must be one of those options. When `max_chars` is present, the value must not exceed that length.
    - `numeric`
      A number, sent and received as `"7"`. When `min_value` or `max_value` is present, the value must fall within those bounds.
    - `timestamp`
      A Unix timestamp in seconds, sent and received as a string.
    - `date`
      A calendar date, sent and received as a string in `yyyy-MM-dd` format, for example `"2024-01-31"`.
    - `list`
      A list, encoded as a string, for example `"[\"a\"]"`. Each element's accepted values are described in `items`. Each element is encoded the same way its own type is, for example a list of booleans is sent as `"[\"true\", \"false\"]"`, not `"[true, false]"`.

- `min_value` (optional, integer)
  The smallest value accepted. Present only for numeric preferences with a lower bound.

- `max_value` (optional, integer)
  The largest value accepted. Present only for numeric preferences with an upper bound.

- `max_chars` (optional, integer)
  The maximum number of characters accepted. Present only for string preferences with a length limit.

- `allowed_values` (optional, list of allowed_value)
  The complete set of values the preference accepts. Present only for preferences restricted to a fixed set of options.
  - `value` (optional, string, max chars=250)
    The option you send as the preference's `value`.
  - `description` (optional, string, max chars=65k)
    A description of this option.

- `items` (optional, item)
  The values each element accepts. Present only when `type` is `list`.
  - `type` (optional, enumerated string)
    The data type of each element in the list.
    Possible enum values:
      - `boolean`
        A true or false value. Send and receive as `"true"` or `"false"`.
      - `string`
        A string. When `allowed_values` is present, the value must be one of those options. When `max_chars` is present, the value must not exceed that length.
      - `numeric`
        A number, sent and received as `"7"`. When `min_value` or `max_value` is present, the value must fall within those bounds.
      - `timestamp`
        A Unix timestamp in seconds, sent and received as a string.
      - `date`
        A calendar date, sent and received as a string in `yyyy-MM-dd` format, for example `"2024-01-31"`.
  - `allowed_values` (optional, list of allowed_value)
    The complete set of values each element accepts. Present only when the elements are restricted to a fixed set of options.
    - `value` (optional, string, max chars=250)
      The option you send as an element of the list.
    - `description` (optional, string, max chars=65k)
      A description of this option.

## Criteria schema attributes

## Input Parameters

- `operand` (optional, enumerated string)
  What a variant condition can be evaluated against.
  Possible enum values:
    - `request_source`
      Where the request came from, such as the API, the Chargebee interface, or the self-serve portal.

- `allowed_operator` (optional, enumerated string)
  The comparisons permitted for this operand in a variant's `criteria`.
  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`.

- `value_schema` (optional, criteria_value_schema)
  The values this operand accepts in a variant's `criteria`.
  - `type` (optional, enumerated string)
    The operand's data type. Operands that accept a fixed set of options report `string` here and list the options in `allowed_values`.
    Possible enum values:
      - `boolean`
        A true or false value. Send and receive as `"true"` or `"false"`.
      - `string`
        A string. When `allowed_values` is present, the value must be one of those options. When `max_chars` is present, the value must not exceed that length.
      - `numeric`
        A number, sent and received as `"7"`. When `min_value` or `max_value` is present, the value must fall within those bounds.
      - `timestamp`
        A Unix timestamp in seconds, sent and received as a string.
      - `date`
        A calendar date, sent and received as a string in `yyyy-MM-dd` format, for example `"2024-01-31"`.
      - `list`
        A list, encoded as a string, for example `"[\"a\"]"`. Each element's accepted values are described in `items`. Each element is encoded the same way its own type is, for example a list of booleans is sent as `"[\"true\", \"false\"]"`, not `"[true, false]"`.
  - `min_value` (optional, integer)
    The smallest value accepted. Present only for numeric operands with a lower bound.
  - `max_value` (optional, integer)
    The largest value accepted. Present only for numeric operands with an upper bound.
  - `max_chars` (optional, integer)
    The maximum number of characters accepted. Present only for string operands with a length limit.
  - `allowed_values` (optional, list of allowed_value)
    The complete set of values this operand accepts. Present only when the operand is restricted to a fixed set of options. Each entry has a `value` and a `description`.
    - `value` (optional, string, max chars=250)
      The option you send in a variant's `criteria.values` for this operand.
    - `description` (optional, string, max chars=65k)
      A description of this option.
  - `items` (optional, item)
    The values each element accepts. Present only when `type` is `list`.
    - `type` (optional, enumerated string)
      The data type of each element in the list.
      Possible enum values:
        - `boolean`
          A true or false value. Send and receive as `"true"` or `"false"`.
        - `string`
          A string. When `allowed_values` is present, the value must be one of those options. When `max_chars` is present, the value must not exceed that length.
        - `numeric`
          A number, sent and received as `"7"`. When `min_value` or `max_value` is present, the value must fall within those bounds.
        - `timestamp`
          A Unix timestamp in seconds, sent and received as a string.
        - `date`
          A calendar date, sent and received as a string in `yyyy-MM-dd` format, for example `"2024-01-31"`.
    - `allowed_values` (optional, list of allowed_value)
      The complete set of values each element accepts. Present only when the elements are restricted to a fixed set of options.
      - `value` (optional, string, max chars=250)
        The option you send as an element of the list.
      - `description` (optional, string, max chars=65k)
        A description of this option.

