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.
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
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 PreferenceJSON
Preferences (Beta) attributes
Identifies the preference, in the form <preference_group>.<name>, for example subscription_reactivation.in_term_reactivation_option. Pass this id to Update preferences to change the value, and use it to find the matching entry in List preference definitions.
The area of Chargebee this preference belongs to. Pass this as the required preference_group[<operator>] filter on List preferences and List preference definitions.
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.
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 to interpret the value and validate it before updating the preference.
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.
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.
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 does not accept it.