Introducing the Chargebee CLI

Preferences (Beta)

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

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 to change the value, and use it to find the matching entry in 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 and List preference definitions.

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 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.

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.

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 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

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.