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.
A preference definition is the contract for a preference. 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. There is no endpoint for fetching one on its own.
Use 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
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 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 returns a preference, and Update preferences accepts a change to it only when the preference applies.

Criteria schema
criteria_schema defines the request contexts that can be used to create a
preference variant. 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 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 indicates whether the preference can be overridden in the Chargebee interface. 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 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 overrides unbilled_charges.invoicing_options.create_subscription for that call. It does not change allow_override_in_api.
Note: 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 accepts only allow_override_in_interface; it never accepts allow_override_in_api.
Sample Preference definitionJSON
Preference Definitions (Beta) attributes
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 to change the value.
The area of Chargebee this preference belongs to. Pass this as the required preference_group[<operator>] filter on List preference definitions and List preferences.
Preferences for whether charges from a subscription action are invoiced immediately or held as unbilled charges until the next invoice.
Preferences applied when a subscription is updated, including plan changes and scheduled cancellations.
Preferences for reactivating a cancelled subscription before its current billing term ends.
Preferences for what happens when a trial ends: the subscription is activated and billed, or it is cancelled.
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 carries allow_override_in_interface, which you can also change. See Overrides.
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 overrides unbilled_charges.invoicing_options.create_subscription. When true, List preferences returns allow_override_in_api. That field is read only and cannot be changed with Update preferences. See Overrides.
Conditions that must be met for this preference to apply to the site. See Applicability.
The values this preference accepts. Use it to validate a value before sending it to Update preferences.
Request contexts in which this preference can take an alternative value. See Criteria schema.
Value schema attributes
The preference's data type. Preferences that accept a fixed set of options report string here and list the options in allowed_values.
A true or false value. Send and receive as "true" or "false".
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.
A number, sent and received as "7". When min_value or max_value is present, the value must fall within those bounds.
A Unix timestamp in seconds, sent and received as a string.
A calendar date, sent and received as a string in yyyy-MM-dd format, for example "2024-01-31".
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]".