get
https://{Host}/v3/tiers
Recent Requests
Log in to see full request history
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Loading…
List All Tiers
Retrieves all tiers of a loyalty program. If a published tier has an edit in progress, the response includes both versions of that tier: the live version (status LIVE) and the draft. To retrieve a single tier, use the tier query parameter.
Example request
curl -X GET "https://eu.intouch.capillarytech.com/v3/tiers?programId=973" \
-H "Authorization: Basic <base64-encoded-credentials>"Prerequisites
- Authentication: Basic auth or OAuth token with loyalty program read permissions.
Resource information
| Pagination support | No |
| Batch support | No |
Query parameters
| Field | Type | Required | Description |
|---|---|---|---|
programId | integer | Required | Loyalty program ID to list tiers for. |
tier | string | Optional | Retrieves a single tier instead of the full list. Pass the tier's slabId (published tiers) or tierUniqueId (drafts). Use this to retrieve a published tier created outside this API by its slabId. |
status | string | Optional | Not supported. Sending any value returns HTTP 400 with error 9057. |
Example response
{
"data": {
"tiers": [
{
"slabId": 25216,
"name": "Bronze",
"description": "Tier 1",
"color": "#ff900f",
"serialNumber": 1,
"tierStartDate": "2024-12-10T12:53:56Z",
"eligibility": {
"kpiType": "CURRENT_POINTS",
"upgradeType": "LAZY"
},
"communicationModeConfig": {
"upgrade": [],
"renewal": [],
"downgrade": [],
"reminders": []
},
"meta": {
"createdAt": "2024-12-10T12:53:56Z",
"updatedAt": "2024-12-10T12:53:56Z"
},
"customerCount": 350,
"countRefreshedAt": "2026-06-11T12:34:56Z",
"status": "LIVE",
"origin": "LEGACY_SQL_ONLY"
},
{
"slabId": 25220,
"name": "Silver",
"description": "Tier 2",
"color": "#C0C0C0",
"serialNumber": 2,
"tierStartDate": "2024-12-19T08:39:20Z",
"eligibility": {
"kpiType": "CURRENT_POINTS",
"threshold": 5000,
"upgradeType": "LAZY"
},
"downgrade": {
"target": "SINGLE",
"reevaluateOnReturn": false,
"dailyEnabled": false,
"conditions": {
"purchase": "-1",
"numVisits": "-1",
"points": "-1",
"tracker": []
},
"shouldDowngrade": true,
"always": false,
"renewalOrderString": []
},
"communicationModeConfig": {
"upgrade": [],
"renewal": [],
"downgrade": [],
"reminders": []
},
"meta": {
"createdAt": "2024-12-19T08:39:20Z",
"updatedAt": "2024-12-19T08:39:20Z"
},
"customerCount": 13,
"countRefreshedAt": "2026-06-11T12:34:56Z",
"status": "LIVE",
"origin": "LEGACY_SQL_ONLY",
"renewal": {
"periodType": "SLAB_UPGRADE",
"periodValue": "12",
"unit": "NUM_MONTHS",
"startDate": "2026-01-07T00:00:00+00:00",
"isFixedTypeWithoutYear": false,
"minimumDuration": 0,
"criteriaType": "Same as eligibility",
"downgradeTo": "SINGLE",
"shouldDowngrade": true,
"conditions": {
"purchase": "-1",
"numVisits": "-1",
"points": "-1",
"tracker": []
},
"always": false,
"renewalOrderString": []
}
},
{
"slabId": 25221,
"name": "Gold",
"description": "Tier 3",
"color": "#FFD700",
"serialNumber": 3,
"tierStartDate": "2024-12-19T08:39:53Z",
"eligibility": {
"kpiType": "CURRENT_POINTS",
"threshold": 10000,
"upgradeType": "LAZY"
},
"downgrade": {
"target": "SINGLE",
"reevaluateOnReturn": false,
"dailyEnabled": false,
"conditions": {
"purchase": "-1",
"numVisits": "-1",
"points": "-1",
"tracker": []
},
"shouldDowngrade": true,
"always": false,
"renewalOrderString": []
},
"communicationModeConfig": {
"upgrade": [],
"renewal": [],
"downgrade": [],
"reminders": []
},
"meta": {
"createdAt": "2024-12-19T08:39:53Z",
"updatedAt": "2024-12-19T08:39:53Z"
},
"customerCount": 16,
"countRefreshedAt": "2026-06-11T12:34:56Z",
"status": "LIVE",
"origin": "LEGACY_SQL_ONLY",
"renewal": {
"periodType": "SLAB_UPGRADE",
"periodValue": "12",
"unit": "NUM_MONTHS",
"startDate": "2026-01-07T00:00:00+00:00",
"isFixedTypeWithoutYear": false,
"minimumDuration": 0,
"criteriaType": "Same as eligibility",
"downgradeTo": "SINGLE",
"shouldDowngrade": true,
"conditions": {
"purchase": "-1",
"numVisits": "-1",
"points": "-1",
"tracker": []
},
"always": false,
"renewalOrderString": []
}
},
{
"slabId": 25222,
"name": "Sapphire",
"description": "Tier 4",
"color": "#198000",
"serialNumber": 4,
"tierStartDate": "2024-12-19T08:41:17Z",
"eligibility": {
"kpiType": "CURRENT_POINTS",
"threshold": 15000,
"upgradeType": "LAZY"
},
"downgrade": {
"target": "SINGLE",
"reevaluateOnReturn": false,
"dailyEnabled": false,
"conditions": {
"purchase": "-1",
"numVisits": "-1",
"points": "-1",
"tracker": []
},
"shouldDowngrade": true,
"always": false,
"renewalOrderString": []
},
"communicationModeConfig": {
"upgrade": [],
"renewal": [],
"downgrade": [],
"reminders": []
},
"meta": {
"createdAt": "2024-12-19T08:41:17Z",
"updatedAt": "2024-12-19T08:41:17Z"
},
"customerCount": 3,
"countRefreshedAt": "2026-06-11T12:34:56Z",
"status": "LIVE",
"origin": "LEGACY_SQL_ONLY",
"renewal": {
"periodType": "SLAB_UPGRADE",
"periodValue": "12",
"unit": "NUM_MONTHS",
"startDate": "2026-01-07T00:00:00+00:00",
"isFixedTypeWithoutYear": false,
"minimumDuration": 0,
"criteriaType": "Same as eligibility",
"downgradeTo": "SINGLE",
"shouldDowngrade": true,
"conditions": {
"purchase": "-1",
"numVisits": "-1",
"points": "-1",
"tracker": []
},
"always": false,
"renewalOrderString": []
}
},
{
"slabId": 25248,
"name": "Ruby",
"description": "Tier 5",
"color": "#d90000",
"serialNumber": 5,
"tierStartDate": "2025-02-11T05:13:26Z",
"eligibility": {
"kpiType": "CURRENT_POINTS",
"threshold": 20000,
"upgradeType": "LAZY"
},
"downgrade": {
"target": "SINGLE",
"reevaluateOnReturn": false,
"dailyEnabled": false,
"conditions": {
"purchase": "-1",
"numVisits": "-1",
"points": "-1",
"tracker": []
},
"shouldDowngrade": true,
"always": false,
"renewalOrderString": []
},
"communicationModeConfig": {
"upgrade": [],
"renewal": [],
"downgrade": [],
"reminders": []
},
"meta": {
"createdAt": "2025-02-11T05:13:26Z",
"updatedAt": "2025-02-11T05:13:26Z"
},
"customerCount": 3,
"countRefreshedAt": "2026-06-11T12:34:56Z",
"status": "LIVE",
"origin": "LEGACY_SQL_ONLY",
"renewal": {
"periodType": "SLAB_UPGRADE",
"periodValue": "12",
"unit": "NUM_MONTHS",
"startDate": "2026-01-07T00:00:00+00:00",
"isFixedTypeWithoutYear": false,
"minimumDuration": 0,
"criteriaType": "Same as eligibility",
"downgradeTo": "SINGLE",
"shouldDowngrade": true,
"conditions": {
"purchase": "-1",
"numVisits": "-1",
"points": "-1",
"tracker": []
},
"always": false,
"renewalOrderString": []
}
},
{
"slabId": 25249,
"name": "Emerald",
"description": "Tier 6",
"color": "#00d946",
"serialNumber": 6,
"tierStartDate": "2025-02-11T05:14:10Z",
"eligibility": {
"kpiType": "CURRENT_POINTS",
"threshold": 25000,
"upgradeType": "LAZY"
},
"downgrade": {
"target": "SINGLE",
"reevaluateOnReturn": false,
"dailyEnabled": false,
"conditions": {
"purchase": "-1",
"numVisits": "-1",
"points": "-1",
"tracker": []
},
"shouldDowngrade": true,
"always": false,
"renewalOrderString": []
},
"communicationModeConfig": {
"upgrade": [],
"renewal": [],
"downgrade": [],
"reminders": []
},
"meta": {
"createdAt": "2025-02-11T05:14:10Z",
"updatedAt": "2025-02-11T05:14:10Z"
},
"customerCount": 1,
"countRefreshedAt": "2026-06-11T12:34:56Z",
"status": "LIVE",
"origin": "LEGACY_SQL_ONLY",
"renewal": {
"periodType": "SLAB_UPGRADE",
"periodValue": "12",
"unit": "NUM_MONTHS",
"startDate": "2026-01-07T00:00:00+00:00",
"isFixedTypeWithoutYear": false,
"minimumDuration": 0,
"criteriaType": "Same as eligibility",
"downgradeTo": "SINGLE",
"shouldDowngrade": true,
"conditions": {
"purchase": "-1",
"numVisits": "-1",
"points": "-1",
"tracker": []
},
"always": false,
"renewalOrderString": []
}
},
{
"slabId": 25250,
"name": "Amethyst",
"description": "Tier 7",
"color": "#8e00d9",
"serialNumber": 7,
"tierStartDate": "2025-02-11T05:15:45Z",
"eligibility": {
"kpiType": "CURRENT_POINTS",
"threshold": 30000,
"upgradeType": "LAZY"
},
"downgrade": {
"target": "SINGLE",
"reevaluateOnReturn": false,
"dailyEnabled": false,
"conditions": {
"purchase": "-1",
"numVisits": "-1",
"points": "-1",
"tracker": []
},
"shouldDowngrade": true,
"always": false,
"renewalOrderString": []
},
"communicationModeConfig": {
"upgrade": [],
"renewal": [],
"downgrade": [],
"reminders": []
},
"meta": {
"createdAt": "2025-02-11T05:15:45Z",
"updatedAt": "2025-02-11T05:15:45Z"
},
"customerCount": 8,
"countRefreshedAt": "2026-06-11T12:34:56Z",
"status": "LIVE",
"origin": "LEGACY_SQL_ONLY",
"renewal": {
"periodType": "SLAB_UPGRADE",
"periodValue": "12",
"unit": "NUM_MONTHS",
"startDate": "2026-01-07T00:00:00+00:00",
"isFixedTypeWithoutYear": false,
"minimumDuration": 0,
"criteriaType": "Same as eligibility",
"downgradeTo": "SINGLE",
"shouldDowngrade": true,
"conditions": {
"purchase": "-1",
"numVisits": "-1",
"points": "-1",
"tracker": []
},
"always": false,
"renewalOrderString": []
}
},
{
"slabId": 25251,
"name": "Diamond",
"description": "Tier 8",
"color": "#b9f2ff",
"serialNumber": 8,
"tierStartDate": "2025-02-11T05:16:51Z",
"eligibility": {
"kpiType": "CURRENT_POINTS",
"threshold": 50000,
"upgradeType": "LAZY"
},
"downgrade": {
"target": "SINGLE",
"reevaluateOnReturn": false,
"dailyEnabled": false,
"conditions": {
"purchase": "-1",
"numVisits": "-1",
"points": "-1",
"tracker": []
},
"shouldDowngrade": true,
"always": false,
"renewalOrderString": []
},
"communicationModeConfig": {
"upgrade": [],
"renewal": [],
"downgrade": [],
"reminders": []
},
"meta": {
"createdAt": "2025-02-11T05:16:51Z",
"updatedAt": "2025-02-11T05:16:51Z"
},
"customerCount": 15,
"countRefreshedAt": "2026-06-11T12:34:56Z",
"status": "LIVE",
"origin": "LEGACY_SQL_ONLY",
"renewal": {
"periodType": "SLAB_UPGRADE",
"periodValue": "12",
"unit": "NUM_MONTHS",
"startDate": "2026-01-07T00:00:00+00:00",
"isFixedTypeWithoutYear": false,
"minimumDuration": 0,
"criteriaType": "Same as eligibility",
"downgradeTo": "SINGLE",
"shouldDowngrade": true,
"conditions": {
"purchase": "-1",
"numVisits": "-1",
"points": "-1",
"tracker": []
},
"always": false,
"renewalOrderString": []
}
},
{
"slabId": 25602,
"name": "Platinum",
"description": "Top-tier membership for highest spenders — updated",
"color": "#E5E4E2",
"serialNumber": 9,
"tierStartDate": "2026-06-10T06:07:29Z",
"eligibility": {
"kpiType": "CURRENT_POINTS",
"threshold": 80000,
"upgradeType": "LAZY"
},
"downgrade": {
"reevaluateOnReturn": false,
"dailyEnabled": false
},
"communicationModeConfig": {
"upgrade": [],
"renewal": [],
"downgrade": [],
"reminders": []
},
"meta": {
"createdAt": "2026-06-10T06:07:29Z",
"updatedAt": "2026-06-10T06:07:29Z"
},
"customerCount": 0,
"countRefreshedAt": "2026-06-11T12:34:56Z",
"status": "LIVE",
"origin": "LEGACY_SQL_ONLY",
"renewal": {
"periodType": "SLAB_UPGRADE",
"periodValue": "12",
"unit": "NUM_MONTHS",
"isFixedTypeWithoutYear": false,
"minimumDuration": 0,
"criteriaType": "Same as eligibility"
}
},
{
"tierUniqueId": "ut-973-010",
"objectId": "6a2aab5cb1f2f8016a6598bb",
"name": "Super Platinum",
"description": "Premium tier for top spenders",
"color": "#E5E4E2",
"serialNumber": 10,
"eligibility": {
"kpiType": "CURRENT_POINTS",
"threshold": 100000,
"upgradeType": "LAZY"
},
"meta": {
"createdBy": "75237721",
"createdAt": "2026-06-11T12:34:36Z",
"updatedBy": "75237721",
"updatedAt": "2026-06-11T12:34:36Z"
},
"status": "DRAFT",
"origin": "MONGO_ONLY",
"renewal": {
"periodType": "SLAB_UPGRADE",
"periodValue": "12",
"unit": "NUM_MONTHS",
"criteriaType": "Same as eligibility"
}
}
]
},
"errors": null,
"warnings": null
}Response parameters
| Field | Type | Description |
|---|---|---|
data | object | Object containing the response payload. |
.tiers | array | List of tier entries. Fields with null values are omitted from the response. |
..status | string | Current stage of the tier lifecycle. LIVE indicates the published version of a tier. Possible values: LIVE, DRAFT, PENDING_APPROVAL, REJECTED, ACTIVE, DELETED, SNAPSHOT, PUBLISH_FAILED. |
..origin | string | Indicates which version of the tier data this entry represents. Possible values: BOTH (published tier that also has a draft), MONGO_ONLY (draft not yet published), LEGACY_SQL_ONLY (tier created outside this API). |
..slabId | integer | Unique ID of the published tier. null until the tier is approved and published. |
..tierUniqueId | string | Unique ID assigned to a tier created through this API, returned by Create Tier. null for tiers created outside this API. |
..objectId | string | Unique ID of this tier record. Use it with Update Tier, Delete Tier, and the approval endpoints. null for tiers created outside this API. |
..name | string | Tier name. |
..description | string | Tier description. |
..color | string | Display color in hex format. |
..serialNumber | integer | Tier position in the program's tier ladder. |
..tierStartDate | timestamp | Date and time when the tier was published, in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ), returned in the server time zone. Present on LIVE entries only. |
..eligibility | object | Object containing the conditions a customer must meet to enter this tier. For published (LIVE) tiers, only kpiType, threshold, and upgradeType are returned. |
...kpiType | enum | KPI the threshold is measured against. Possible values: CURRENT_POINTS, CUMULATIVE_POINTS, CUMULATIVE_PURCHASES, TRACKER_VALUE_BASED. |
...threshold | number | KPI value at which a customer upgrades into this tier. |
...upgradeType | enum | When tier upgrades are evaluated. Possible values: EAGER, DYNAMIC, LAZY. |
..renewal | object | Object containing the tier's validity period and renewal settings. |
...periodType | enum | Defines when the tier validity period starts. Possible values: FIXED (starts on a fixed date), SLAB_UPGRADE (starts when the customer enters the tier), SLAB_UPGRADE_CYCLIC (restarts each cycle after the upgrade), FIXED_CUSTOMER_REGISTRATION (starts on the customer's registration date). |
...periodValue | string | Tier duration in months, returned as a string. |
...unit | string | Unit of periodValue. Always NUM_MONTHS. |
...startDate | timestamp | Date when the tier validity period starts, in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ), returned in the server time zone. |
...endDate | timestamp | Date when the tier validity period ends (start date plus duration), in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ), returned in the server time zone. Read-only. |
...isFixedTypeWithoutYear | boolean | When true, the validity start date repeats every year on the same day and month. |
...renewalWindowType | enum | Defines the period used to evaluate whether a customer keeps the tier at renewal. Possible values: FIXED_DATE_BASED (window measured back from the renewal date), LAST_CALENDAR_YEAR (the previous calendar year), CUSTOM_PERIOD (window set by computationWindowStartValue and computationWindowEndValue). |
...computationWindowStartValue | integer | Number of months before the renewal date at which the evaluation window starts. |
...computationWindowEndValue | integer | Number of months before the renewal date at which the evaluation window ends. |
...minimumDuration | integer | Minimum number of months a customer stays in the tier before a downgrade can happen. |
...criteriaType | string | Renewal criteria type. Always Same as eligibility. |
...downgradeTo | enum | Tier the customer moves to on downgrade. Possible values: SINGLE, THRESHOLD, LOWEST. |
...shouldDowngrade | boolean | Whether customers in this tier are downgraded automatically. |
...expressionRelationAIRA | string | Logical expression that combines the renewal conditions, in disjunctive normal form (DNF): groups of conditions joined with AND, with the groups joined by OR, for example (1 AND 2) OR 3, where each number refers to a condition. |
...expressionRelation | string | Logical expression that combines the renewal conditions, in the format used by tiers configured outside this API. When both expression fields are returned, this one applies. |
...conditions | object | Object containing the renewal trigger conditions. A value of -1 means the condition is not set. |
...always | boolean | When true, the tier renews unconditionally. |
...originalExpression | string | Original renewal expression, returned as configured. |
...renewalOrderString | string | Order in which renewal conditions are evaluated, returned as configured. |
..downgrade | object | Object containing the tier's downgrade settings. Read-only. Rejected on write requests. |
...target | enum | Tier the customer moves to on downgrade. Possible values: SINGLE, THRESHOLD, LOWEST. |
...reevaluateOnReturn | boolean | Whether downgrade is re-evaluated when the customer returns. |
...dailyEnabled | boolean | Whether daily downgrade evaluation is on. |
...conditions | object | Object containing the downgrade conditions, in the same format as the renewal conditions. |
...shouldDowngrade | boolean | Whether customers in this tier are downgraded automatically. |
..communicationModeConfig | object | Object containing the communication channels (such as SMS, email, and WhatsApp) used to notify customers about tier events. null on draft entries. |
...upgrade | array | Channels used to notify customers when they upgrade into this tier. |
...renewal | array | Channels used to notify customers when their tier renews. Set at the program level. |
...downgrade | array | Channels used to notify customers when they are downgraded from this tier. Set at the program level. |
...reminders | array | Channels used to send customers a reminder before a downgrade. Set at the program level. |
..rejectionComment | string | Reviewer's comment. Present only when status is REJECTED. Also available as meta.rejectionComment. |
..meta | object | Object containing details of who created, updated, approved, or rejected the tier, and when. |
...createdBy | string | User or till ID of the person who created the tier. |
...createdAt | timestamp | Date and time when the tier was created, in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ), returned in the server time zone. |
...updatedBy | string | User or till ID of the person who last updated the tier. |
...updatedAt | timestamp | Date and time when the tier was last updated, in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ), returned in the server time zone. |
...approvedBy | string | User ID of the reviewer who approved the tier. |
...approvedAt | timestamp | Date and time when the tier was approved, in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ), returned in the server time zone. |
...rejectedBy | string | User ID of the reviewer who rejected the tier. |
...rejectedAt | timestamp | Date and time when the tier was rejected, in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ), returned in the server time zone. |
...rejectionComment | string | Reviewer's comment on rejection. |
..customerCount | integer | Number of active customers currently in this tier. null when count data is unavailable. |
..countRefreshedAt | timestamp | Date and time when customerCount was last refreshed, in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ), returned in the server time zone. null when count data is unavailable. |
errors | array | Error list. null on success. |
warnings | array | Warning list. null on success. |
Error and warning codes
| Code | Error number | Type | Description |
|---|---|---|---|
TIER.STATUS_FILTER_NOT_SUPPORTED | 9057 | Error | The status query parameter was sent. The list endpoint doesn't support status filtering. HTTP 400. |
TIER.NOT_FOUND | 9056 | Error | The tier parameter doesn't match any tier in the program. HTTP 404. |
| — | 500 | Error | The required programId query parameter is missing. HTTP 500. |
Validation error, including error 9057 when the unsupported status filter is sent
Tier not found (error 9056) when the tier parameter matches nothing