Introducing the Chargebee CLI

Preference Definitions (Beta)

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.

Whether a preference applies to the site

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

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 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 and List preferences.

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.

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 carries allow_override_in_interface, which you can also change. See 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 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.

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.

Enum Values
and

Every condition in applicability must hold.

or

At least one condition in applicability must hold.

applicability

Conditions that must be met for this preference to apply to the site. See Applicability.

value_schema

The values this preference accepts. Use it to validate a value before sending it to Update preferences.

criteria_schema

Request contexts in which this preference can take an alternative value. See Criteria schema.

Applicability attributes

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.

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

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.

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

The complete set of values the preference accepts. Present only for preferences restricted to a fixed set of options.

items

The values each element accepts. Present only when type is list.

Criteria schema attributes

operand
optional, enumerated string

What a variant condition can be evaluated against.

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.

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

The values this operand accepts in a variant's criteria.