get
https://{Host}/api_gateway/loyalty/v1/programs//tierAdvancedSettings
Retrieve the program-level upgrade and downgrade settings that govern tier movement.
Recent Requests
Log in to see full request history
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Loading…
Get Tier Advanced Settings
Retrieves 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, and must be configured before you create tiers. Configure them with Update Tier Advanced Settings.
Example request
curl -L 'https://eu.api.capillarytech.com/api_gateway/loyalty/v1/programs/973/tierAdvancedSettings' \
-H 'accept: application/json' \
-H 'Authorization: Basic OGQwMGM2ZmY5ZWMxNGEyYjE2YWNiYTg2MzA='Prerequisites
- Authentication: Basic auth or an OAuth token passed in the
X-CAP-API-OAUTH-TOKENheader, with loyalty program read permissions. - Pass the organization ID in the
X-CAP-API-AUTH-ORG-IDheader.
Resource information
| Pagination support | No |
| Batch support | No |
Path parameters
| Field | Type | Required | Description |
|---|---|---|---|
program_id | integer | Required | Loyalty program ID whose tier advanced settings you want to retrieve. To retrieve the program_id, use the Get Loyalty Programs API. |
Example response
{
"tierAdvancedSettings": {
"programId": 973,
"isAdvanceSetting": true,
"upgrade": {
"current_value_type": "CURRENT_POINTS",
"slab_upgrade_mode": "LAZY",
"tracker_id": null,
"tracker_condition_id": null,
"threshold_value": [
"5000",
"10000",
"15000",
"20000",
"25000",
"30000",
"50000",
"80000",
"100000",
"500000"
],
"secondary_criteria_enabled": null,
"additional_upgrade_criteria": null
},
"downgrade": {
"is_active": true,
"should_downgrade": true,
"start_date": "2026-12-31",
"condition": "FIXED",
"daily_downgrade_enabled": false,
"retain_points": false,
"is_downgrade_on_return_enabled": false,
"is_downgrade_on_partner_program_expiry_enabled": false,
"minimum_duration": "0",
"is_fixed_type_without_year": true,
"renewal_window_type": null,
"computation_window_start_value": null,
"computation_window_end_value": null
}
}
}Note: When the program has no upgrade or downgrade configuration,
upgradeanddowngradeare returned asnull, for example{"tierAdvancedSettings":{"programId":973,"isAdvanceSetting":true,"upgrade":null,"downgrade":null}}.
Response parameters
| Field | Type | Description |
|---|---|---|
tierAdvancedSettings | object | Object containing the program's 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. The array contains one entry per tier boundary — that is, one fewer than the total number of tiers in the program. |
..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. Validated independently against the same rule as upgrade.threshold_value: one entry per tier boundary, one fewer than the total number of tiers in the program. |
...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 | string | 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 |
|---|---|---|
VALIDATION_FAILED | Error | The program_id is missing or not a valid program. HTTP 400. |
INTERNAL_ERROR | Error | Internal server error. Retry after a short delay. HTTP 500. |
Invalid request. See the error codes table on this page.
Internal server error