Time	Status	User Agent
Retrieving recent requests…

Update Tier

Updates a tier. All body fields are optional. Only the fields you send are changed (partial update). Updating a DRAFT, PENDING_APPROVAL, or REJECTED tier edits it in place. Updating an ACTIVE tier creates a new versioned DRAFT that must go through the approval workflow again. Tiers in SNAPSHOT or DELETED status can't be edited.

Example request

curl -X PUT "https://eu.intouch.capillarytech.com/v3/tiers/6a2121936497e74ec3517ad8" \
  -H "Authorization: Basic <base64-encoded-credentials>" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Premium tier for top spenders — updated",
    "eligibility": {
      "kpiType": "CURRENT_POINTS",
      "threshold": 80000,
      "upgradeType": "LAZY"
    }
  }'

Prerequisites

Authentication: Basic auth or OAuth token with loyalty program management permissions.

Path parameters

Field	Type	Required	Description
`tierId`	string	Required	Tier ID. Pass the `objectId` (from the Create Tier response) to update a draft, or the `slabId` (from List All Tiers) to update a published tier. The `tierUniqueId` is not accepted on this endpoint.

Query parameters

Field	Type	Required	Description
`programId`	integer	Conditional	Required only when `tierId` is a `slabId` of a tier created outside this API. Ignored otherwise. Pass it whenever you update a published tier by `slabId`.

Body parameters

Note: The Updatable column indicates whether a field can be changed after
creation. All fields are optional. Omitted fields keep their current values.

Field	Type	Required	Description	Updatable
`name`	string	Optional	Tier name. Max 50 characters. Must not be blank when sent. Must be unique among live tiers in the program (case-insensitive).	Yes
`description`	string	Optional	Tier description. Max 500 characters.	Yes
`color`	string	Optional	Display color in hex format `#RRGGBB`.	Yes
`eligibility`	object	Optional	Object containing the conditions a customer must meet to enter this tier. Same structure and constraints as in Create Tier.	Yes
`validity`	object	Optional	Object containing the validity period and renewal configuration. Same structure and constraints as in Create Tier.	Yes

Note: The same strict-mode rules as Create Tier apply. Unknown fields, the read-only downgrade block, program-level fields, validity.endDate, and -1 sentinel values are all rejected with HTTP 400.

Example response

{
    "data": {
        "tierUniqueId": "ut-973-010",
        "objectId": "6a2aab5cb1f2f8016a6598bb",
        "name": "Super Platinum",
        "description": "Premium tier for top spenders — updated",
        "color": "#E5E4E2",
        "serialNumber": 10,
        "eligibility": {
            "kpiType": "CURRENT_POINTS",
            "threshold": 100000.0,
            "upgradeType": "LAZY"
        },
        "meta": {
            "createdBy": "75237721",
            "createdAt": "2026-06-11T12:34:36Z",
            "updatedBy": "75237721",
            "updatedAt": "2026-06-11T12:36:22Z"
        },
        "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 updated tier. When you update an `ACTIVE` tier, this is the newly created versioned `DRAFT`, not the live tier.
`.tierUniqueId`	string	Stable tier identifier.
`.objectId`	string	Unique ID of the tier record that was edited or created. Use it with Delete Tier and the approval endpoints.
`.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.
`.eligibility`	object	Object containing the conditions a customer must meet to enter this tier, after the update.
`.meta`	object	Object containing details of who created and last updated 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 made this update.
`..updatedAt`	timestamp	Date and time of this update, in ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`), returned in the server time zone.
`.status`	string	Current stage of the tier lifecycle after the update. Possible values: `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).
`.renewal`	object	Object containing the tier's validity period and renewal settings, derived from `validity`. Read-only.
`errors`	array	Error list. `null` on success.
`warnings`	array	Warning list. `null` on success.

Error & warning codes

Code	Error number	Type	Description
`TIER.NOT_FOUND`	9056	Error	No tier matches the given `tierId`. Returned also when a `tierUniqueId` is passed instead of the `objectId`. HTTP 404.
`TIER.PROGRAM_ID_REQUIRED`	9003	Error	`tierId` is the `slabId` of a tier created outside this API and the `programId` query parameter is missing. HTTP 400.
`TIER.NAME_BLANK_ON_UPDATE`	9026	Error	`name` was sent as a blank string. HTTP 400.
`TIER.NAME_TOO_LONG`	9002	Error	`name` exceeds 50 characters. HTTP 400.
`TIER.DESCRIPTION_TOO_LONG`	9008	Error	`description` exceeds 500 characters. HTTP 400.
`TIER.INVALID_COLOR_CODE`	9006	Error	`color` is not in `#RRGGBB` hex format. HTTP 400.
`TIER.INVALID_KPI_TYPE`	9004	Error	`eligibility.kpiType` or a condition `type` is not a supported value. HTTP 400.
`TIER.INVALID_UPGRADE_TYPE`	9009	Error	`eligibility.upgradeType` is not a supported value. HTTP 400.
`TIER.THRESHOLD_MUST_BE_POSITIVE`	9005	Error	`eligibility.threshold` is negative. HTTP 400.
`TIER.UPGRADE_VALUE_OUT_OF_RANGE`	9028	Error	`eligibility.threshold` exceeds 2,147,483,647. HTTP 400.
`TIER.TRACKER_ID_REQUIRED`	9029	Error	A `TRACKER` condition is missing `trackerId` or `trackerCondition`. HTTP 400.
`TIER.END_DATE_FORBIDDEN_ON_WRITE`	9048	Error	`validity.endDate` is read-only and was sent on a write request. HTTP 400.
`TIER.PROGRAM_KPI_TYPE_MISMATCH`	9043	Error	The eligibility condition type is not compatible with the program's KPI type. HTTP 400.
`TIER.THRESHOLD_NOT_MONOTONIC`	9044	Error	The tier threshold is not greater than the previous tier's threshold. HTTP 400.
`TIER_NOT_EDITABLE_IN_STATUS`	—	Error	The tier is in `SNAPSHOT` or `DELETED` status and can't be edited. HTTP 409.
`TIER_NAME_TAKEN`	—	Error	A live tier with the same name already exists in the program. HTTP 409.

Note: All validation codes listed in Create Tier (9011–9055) also apply to update requests. Conflict errors (HTTP 409) return the generic error number 999999 with a descriptive message on the wire.