Update Tier Advanced Settings

post

https://{Host}/api_gateway/loyalty/v1/programs/{program_id}/updateTierAdvancedSettings

Create or update the program-level upgrade and downgrade settings that govern tier movement.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Update Tier Advanced Settings

Creates or updates the program-level upgrade and downgrade settings that govern how customers move between tiers. These settings apply to the whole program, not to a single tier. Configure them before you create tiers, because Create Tier requires the program to have upgrade and downgrade configuration in place. Calling this endpoint again replaces the existing upgrade and downgrade configuration with what you send — there's no partial merge with the previous settings. The response echoes the full saved settings.

Example request

curl -X POST "https://{Host}/api_gateway/loyalty/v1/programs/973/updateTierAdvancedSettings" \
  -H "Authorization: Basic <base64-encoded-credentials>" \
  -H "X-CAP-API-AUTH-ORG-ID: 12345" \
  -H "Content-Type: application/json" \
  -d '{
    "tierAdvancedSettings": {
      "programId": 973,
      "isAdvanceSetting": true,
      "upgrade": {
        "current_value_type": "CUMULATIVE_POINTS",
        "slab_upgrade_mode": "EAGER",
        "threshold_value": ["500", "1000", "1001", "1002", "100000", "200000"]
      },
      "downgrade": {
        "is_active": true,
        "should_downgrade": true,
        "condition": "FIXED",
        "start_date": "2026-12-31",
        "daily_downgrade_enabled": true,
        "retain_points": true,
        "minimum_duration": "11",
        "is_fixed_type_without_year": true
      }
    }
  }'

Prerequisites

Authentication: Basic auth or an OAuth token passed in the X-CAP-API-OAUTH-TOKEN header, with loyalty program management permissions.
Pass the organization ID in the X-CAP-API-AUTH-ORG-ID header.

Path parameters

Field	Type	Required	Description
`program_id`	integer	Required	Loyalty program ID whose tier advanced settings you want to update. To retrieve the `program_id`, use the Get Loyalty Programs API.

Body parameters

API quick reference

tierAdvancedSettings
├── programId (integer)
├── isAdvanceSetting (boolean)
├── upgrade
│   ├── current_value_type (enum)
│   ├── slab_upgrade_mode (enum)
│   ├── tracker_id (string)
│   ├── tracker_condition_id (string)
│   ├── threshold_value[] (string)
│   ├── secondary_criteria_enabled (boolean)
│   └── additional_upgrade_criteria[]
│       ├── threshold_value[] (string)
│       ├── current_value_type (enum)
│       ├── slab_upgrade_mode (enum)
│       ├── tracker_id (string)
│       └── tracker_condition_id (string)
└── downgrade
    ├── is_active (boolean)
    ├── should_downgrade (boolean)
    ├── condition (enum)
    ├── start_date (string)
    ├── daily_downgrade_enabled (boolean)
    ├── retain_points (boolean)
    ├── is_downgrade_on_return_enabled (boolean)
    ├── is_downgrade_on_partner_program_expiry_enabled (boolean)
    ├── minimum_duration (string)
    ├── is_fixed_type_without_year (boolean)
    ├── renewal_window_type (enum)
    ├── computation_window_start_value (integer)
    └── computation_window_end_value (integer)

Field	Type	Required	Description
`tierAdvancedSettings`	object	Required	Object containing the upgrade and downgrade configuration for the program's tiers.
`.programId`	integer	Required	Loyalty program ID. Must match the `program_id` path parameter.
`.isAdvanceSetting`	boolean	Optional	Whether advanced tier settings are enabled for the program. The response always returns `true` for this field regardless of what you send or what was previously stored.
`.upgrade`	object	Optional	Object containing the rules that move a customer to a higher tier.
`..current_value_type`	enum	Conditional	Required when `upgrade` is sent. KPI the upgrade threshold is measured against. Supported values: `CURRENT_POINTS`: customer's active points balance, `CUMULATIVE_POINTS`: customer's lifetime earned points, `CUMULATIVE_PURCHASES`: customer's lifetime spending, `TRACKER_VALUE_BASED`: custom tracker value. Case-sensitive.
`..slab_upgrade_mode`	enum	Conditional	Required when `upgrade` is sent. When upgrades are evaluated. Supported values: `EAGER`: evaluated before points/event awarding, `LAZY`: evaluated after points/event awarding. Case-sensitive.
`..tracker_id`	string	Conditional	Required when `current_value_type` is `TRACKER_VALUE_BASED`. Identifier of the tracker the upgrade is measured against.
`..tracker_condition_id`	string	Conditional	Required when `current_value_type` is `TRACKER_VALUE_BASED`. Identifier of the tracker condition.
`..threshold_value`	array of strings	Optional	Upgrade threshold for each tier boundary, passed as strings. When sent, must contain exactly one entry per tier boundary (the number of tiers in the program minus one), and each entry must be 0 or greater.
`..secondary_criteria_enabled`	boolean	Optional	When `true`, additional upgrade criteria are evaluated alongside the primary criteria. Requires a non-empty `additional_upgrade_criteria`.
`..additional_upgrade_criteria`	array	Conditional	Required and non-empty when `secondary_criteria_enabled` is `true`. List of additional upgrade criteria.
`...threshold_value`	array of strings	Conditional	Upgrade threshold for each tier boundary for this additional criterion, passed as strings. One threshold per tier boundary.
`...current_value_type`	enum	Optional	KPI for this additional criterion. Supported values: `CURRENT_POINTS`: customer's active points balance, `CUMULATIVE_POINTS`: customer's lifetime earned points, `CUMULATIVE_PURCHASES`: customer's lifetime spending, `TRACKER_VALUE_BASED`: custom tracker value. Case-sensitive.
`...slab_upgrade_mode`	enum	Optional	When this additional criterion is evaluated. Supported values: `EAGER`: evaluated before points/event awarding, `LAZY`: evaluated after points/event awarding. Case-sensitive.
`...tracker_id`	string	Conditional	Required for each additional criterion. Identifier of the tracker for this criterion.
`...tracker_condition_id`	string	Conditional	Required for each additional criterion. Identifier of the tracker condition for this criterion.
`.downgrade`	object	Optional	Object containing the rules that move a customer to a lower tier.
`..is_active`	boolean	Optional	Whether the downgrade configuration is active.
`..should_downgrade`	boolean	Optional	Whether customers are downgraded when they no longer meet the tier criteria.
`..condition`	enum	Optional	When a downgrade is triggered. Supported values: `FIXED`: evaluated against a fixed anchor date — requires `start_date`, `SLAB_UPGRADE`: evaluated relative to when the customer was last upgraded a tier, `SLAB_UPGRADE_CYCLIC`: same as `SLAB_UPGRADE`, but recurs on a cycle: when `daily_downgrade_enabled` is `true` the window is computed from the last tier-upgrade date plus `minimum_duration`; otherwise from the start of the next calendar month plus `minimum_duration`, `FIXED_CUSTOMER_REGISTRATION`: evaluated against the customer's registration date. Case-sensitive.
`..start_date`	date	Conditional	Required when `condition` is `FIXED`. Must not be sent when `condition` is `SLAB_UPGRADE` or `SLAB_UPGRADE_CYCLIC`. Format: `YYYY-MM-DD`.
`..daily_downgrade_enabled`	boolean	Optional	Whether downgrade evaluation runs daily.
`..retain_points`	boolean	Optional	Whether a customer keeps points after a downgrade.
`..is_downgrade_on_return_enabled`	boolean	Optional	Whether a return can trigger a downgrade.
`..is_downgrade_on_partner_program_expiry_enabled`	boolean	Optional	Whether a downgrade is triggered when a linked partner program expires.
`..minimum_duration`	string	Optional	Minimum number of months a customer stays in a tier before becoming eligible for downgrade, passed as a string. Must be a whole number 0 or greater.
`..is_fixed_type_without_year`	boolean	Optional	When `true`, the downgrade anchor is treated as a recurring day and month, and the year is ignored.
`..renewal_window_type`	enum	Optional	How the renewal evaluation window is interpreted. Supported values: `FIXED_DATE_BASED`: window is offset in months from a fixed date, via `computation_window_start_value`/`computation_window_end_value`, `LAST_CALENDAR_YEAR`: window is the previous calendar year; no offsets accepted, `CUSTOM_PERIOD`: window is a custom range defined by both offsets, capped at 35 months apart. Case-sensitive.
`..computation_window_start_value`	integer	Conditional	Requires `renewal_window_type`. Start offset in months. Must be between 1 and 36 when `renewal_window_type` is `FIXED_DATE_BASED`. Must not be sent when `renewal_window_type` is `LAST_CALENDAR_YEAR`.
`..computation_window_end_value`	integer	Conditional	Requires `renewal_window_type`. End offset in months. For `CUSTOM_PERIOD`, both offsets are required and their difference must be 35 or less. Must not be sent when `renewal_window_type` is `LAST_CALENDAR_YEAR`.

Note: Only the fields listed above can be modified through this endpoint. slab_upgrade_mode accepts only EAGER or LAZY; sending any other value returns HTTP 400.

Example response

{
  "tierAdvancedSettings": {
    "programId": 973,
    "isAdvanceSetting": true,
    "upgrade": {
      "current_value_type": "CUMULATIVE_POINTS",
      "slab_upgrade_mode": "EAGER",
      "tracker_id": null,
      "tracker_condition_id": null,
      "threshold_value": ["500", "1000", "1001", "1002", "100000", "200000"],
      "secondary_criteria_enabled": null,
      "additional_upgrade_criteria": [
        {
          "threshold_value": ["100", "200", "300", "350", "1000", "500"],
          "current_value_type": "CUMULATIVE_POINTS",
          "slab_upgrade_mode": "LAZY",
          "tracker_id": "110424",
          "tracker_condition_id": "647"
        }
      ],
      "expression_relation": null,
      "custom_expression": ""
    },
    "downgrade": {
      "is_active": true,
      "should_downgrade": true,
      "start_date": "2026-12-31",
      "condition": "FIXED",
      "daily_downgrade_enabled": true,
      "retain_points": true,
      "is_downgrade_on_return_enabled": true,
      "is_downgrade_on_partner_program_expiry_enabled": false,
      "minimum_duration": "11",
      "is_fixed_type_without_year": true,
      "renewal_window_type": null,
      "computation_window_start_value": null,
      "computation_window_end_value": null
    }
  }
}

Response parameters

Field	Type	Description
`tierAdvancedSettings`	object	Object containing the saved upgrade and downgrade configuration.
`.programId`	integer	Loyalty program ID these settings belong to.
`.isAdvanceSetting`	boolean	Always returned as `true`.
`.upgrade`	object	Object containing the rules that move a customer to a higher tier. `null` when no upgrade configuration exists.
`..current_value_type`	enum	KPI the upgrade threshold is measured against. Possible values: `CURRENT_POINTS`, `CUMULATIVE_POINTS`, `CUMULATIVE_PURCHASES`, `TRACKER_VALUE_BASED`.
`..slab_upgrade_mode`	enum	When upgrades are evaluated. Possible values: `EAGER` (before points/event awarding), `LAZY` (after points/event awarding).
`..tracker_id`	string	Identifier of the tracker the upgrade is measured against. `null` unless `current_value_type` is `TRACKER_VALUE_BASED`.
`..tracker_condition_id`	string	Identifier of the tracker condition. `null` unless `current_value_type` is `TRACKER_VALUE_BASED`.
`..threshold_value`	array of strings	Upgrade threshold for each tier boundary, returned as strings.
`..secondary_criteria_enabled`	boolean	Whether additional upgrade criteria are evaluated alongside the primary criteria. `null` when not set.
`..additional_upgrade_criteria`	array	List of additional upgrade criteria evaluated alongside the primary criteria.
`...threshold_value`	array of strings	Upgrade threshold for each tier boundary for this additional criterion, returned as strings.
`...current_value_type`	enum	KPI for this additional criterion. Possible values: `CURRENT_POINTS`, `CUMULATIVE_POINTS`, `CUMULATIVE_PURCHASES`, `TRACKER_VALUE_BASED`.
`...slab_upgrade_mode`	enum	When this additional criterion is evaluated. Possible values: `EAGER` (before points/event awarding), `LAZY` (after points/event awarding).
`...tracker_id`	string	Identifier of the tracker for this additional criterion.
`...tracker_condition_id`	string	Identifier of the tracker condition for this additional criterion.
`..expression_relation`	array of integer arrays	Defines how the primary and additional upgrade criteria combine. Each inner array is a group of criterion indexes, where index `1` is the primary criterion and index `2` onward refers to the entries of `additional_upgrade_criteria` in order. Criteria within a group are combined with AND, and the groups are combined with OR. For example, `[[1,2]]` requires both criteria, and `[[1],[2]]` requires either one. `null` when not set.
`..custom_expression`	string	Custom expression that combines the upgrade criteria. Empty when not set.
`.downgrade`	object	Object containing the rules that move a customer to a lower tier. `null` when no downgrade configuration exists.
`..is_active`	boolean	Whether the downgrade configuration is active.
`..should_downgrade`	boolean	Whether customers are downgraded when they no longer meet the tier criteria.
`..start_date`	date	Downgrade anchor date in `YYYY-MM-DD` format. Present when `condition` is `FIXED`.
`..condition`	enum	When a downgrade is triggered. Possible values: `FIXED` (fixed anchor date), `SLAB_UPGRADE` (relative to the last tier upgrade date), `SLAB_UPGRADE_CYCLIC` (same as `SLAB_UPGRADE`, but recurs on a cycle), `FIXED_CUSTOMER_REGISTRATION` (relative to the customer's registration date).
`..daily_downgrade_enabled`	boolean	Whether downgrade evaluation runs daily.
`..retain_points`	boolean	Whether a customer keeps points after a downgrade.
`..is_downgrade_on_return_enabled`	boolean	Whether a return can trigger a downgrade.
`..is_downgrade_on_partner_program_expiry_enabled`	boolean	Whether a downgrade is triggered when a linked partner program expires.
`..minimum_duration`	string	Minimum number of months a customer stays in a tier before becoming eligible for downgrade, returned as a string.
`..is_fixed_type_without_year`	boolean	When `true`, the downgrade anchor is treated as a recurring day and month, and the year is ignored.
`..renewal_window_type`	enum	How the renewal evaluation window is interpreted. Possible values: `FIXED_DATE_BASED` (offset in months from a fixed date), `LAST_CALENDAR_YEAR` (previous calendar year), `CUSTOM_PERIOD` (custom range defined by both offsets). `null` when not set.
`..computation_window_start_value`	integer	Start offset, in months, of the renewal evaluation window. `null` when not set.
`..computation_window_end_value`	integer	End offset, in months, of the renewal evaluation window. `null` when not set.

Error & warning codes

Code	Type	Description
`INVALID_CURRENT_VALUE_TYPE`	Error	`upgrade.current_value_type` is not a supported value. HTTP 400.
`INVALID_SLAB_UPGRADE_MODE`	Error	`upgrade.slab_upgrade_mode` is not `EAGER` or `LAZY`. HTTP 400.
`PRIMARY_TRACKER_FIELDS_REQUIRED`	Error	`tracker_id` or `tracker_condition_id` is missing when `current_value_type` is `TRACKER_VALUE_BASED`. HTTP 400.
`PRIMARY_THRESHOLD_LENGTH_MISMATCH`	Error	The number of `threshold_value` entries does not match the number of tier boundaries. HTTP 400.
`THRESHOLD_BLANK`	Error	A `threshold_value` entry is blank. HTTP 400.
`INVALID_THRESHOLD_VALUE`	Error	A `threshold_value` entry is not a valid non-negative number. HTTP 400.
`SECONDARY_ENABLED_BUT_MISSING`	Error	`secondary_criteria_enabled` is `true` but `additional_upgrade_criteria` is empty. HTTP 400.
`SECONDARY_THRESHOLD_LENGTH_MISMATCH`	Error	The number of `threshold_value` entries in an additional criterion does not match the number of tier boundaries. HTTP 400.
`ADDITIONAL_TRACKER_MISSING`	Error	`tracker_id` or `tracker_condition_id` is missing for an additional criterion. HTTP 400.
`INVALID_DOWNGRADE_CONDITION`	Error	`downgrade.condition` is not a supported value. HTTP 400.
`START_DATE_REQUIRED_FOR_FIXED`	Error	`downgrade.start_date` is missing when `condition` is `FIXED`. HTTP 400.
`START_DATE_FORBIDDEN_FOR_SLAB_UPGRADE`	Error	`downgrade.start_date` was sent when `condition` is `SLAB_UPGRADE` or `SLAB_UPGRADE_CYCLIC`. HTTP 400.
`INVALID_RENEWAL_WINDOW_TYPE`	Error	`downgrade.renewal_window_type` is not a supported value. HTTP 400.
`COMPUTATION_WINDOW_REQUIRES_RENEWAL_WINDOW_TYPE`	Error	A computation window offset was sent without `renewal_window_type`. HTTP 400.
`FIXED_DATE_OFFSET_OUT_OF_RANGE`	Error	`computation_window_start_value` is outside 1 to 36 for `FIXED_DATE_BASED`. HTTP 400.
`LAST_CALENDAR_YEAR_FORBIDS_OFFSETS`	Error	A computation window offset was sent when `renewal_window_type` is `LAST_CALENDAR_YEAR`. HTTP 400.
`CUSTOM_PERIOD_REQUIRES_BOTH_OFFSETS`	Error	`CUSTOM_PERIOD` requires both computation window offsets. HTTP 400.
`CUSTOM_PERIOD_DELTA_TOO_LARGE`	Error	The difference between the computation window offsets is more than 35 months for `CUSTOM_PERIOD`. HTTP 400.
`INVALID_COMPUTATION_WINDOW_VALUE`	Error	A computation window offset is not a valid value. HTTP 400.
`INVALID_MINIMUM_DURATION`	Error	`downgrade.minimum_duration` is not a valid whole number 0 or greater. HTTP 400.
`VALIDATION_FAILED`	Error	The request failed validation. HTTP 400.
`STRATEGY_NOT_FOUND`	Error	The `upgrade` object was sent for a program that has no existing upgrade configuration to update. HTTP 404.
`INTERNAL_ERROR`	Error	Internal server error. Retry after a short delay. HTTP 500.

Responses

400

Validation error: see the error table in the doc page

404

The upgrade object was sent for a program that has no existing upgrade configuration to update

500

Internal server error

Language

Credentials

Basic

base64

URL

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

Update Tier Advanced Settings

Example request

Prerequisites

Path parameters

Body parameters

API quick reference

Example response

Response parameters

Error & warning codes

200Settings saved