Create Tier

Creates a new tier in DRAFT status for a loyalty program. The tier enters a maker-checker approval workflow: submit it with Submit Tier for Approval and publish it with Approve or Reject Tier before it becomes ACTIVE. A program can have up to 50 tiers and only one in-progress DRAFT at a time.

Example request

curl -X POST "https://eu.intouch.capillarytech.com/v3/tiers" \
  -H "Authorization: Basic <base64-encoded-credentials>" \
  -H "Content-Type: application/json" \
  -d '{
    "programId": 973,
    "name": "Platinum",
    "description": "Premium tier for top spenders",
    "color": "#E5E4E2",
    "eligibility": {
      "kpiType": "CURRENT_POINTS",
      "threshold": 75000,
      "upgradeType": "LAZY"
    },
    "validity": {
      "periodType": "SLAB_UPGRADE",
      "periodValue": 12,
      "unit": "NUM_MONTHS"
    }
  }'

Prerequisites

• Authentication: Basic auth or OAuth token with loyalty program management permissions.
• The program must have SLAB_UPGRADE and SLAB_DOWNGRADE strategies configured. If either is missing, configure them with the program-level Tier Advanced Settings endpoint (POST /programs/{programId}/updateTierAdvancedSettings) before creating tiers.

Header information

Body parameters

API quick reference

Tier
├── programId (integer)
├── name (string)
├── description (string)
├── color (string)
├── eligibility
│   ├── kpiType (enum)
│   ├── threshold (number)
│   ├── upgradeType (enum)
│   ├── expressionRelation (enum)
│   └── conditions[]
│       ├── type (enum)
│       ├── value (string)
│       ├── trackerName (string)
│       ├── trackerId (integer)
│       └── trackerCondition (integer)
└── validity
    ├── periodType (enum)
    ├── periodValue (integer)
    ├── unit (string)
    ├── startDate (string)
    ├── isFixedTypeWithoutYear (boolean)
    ├── renewalWindowType (enum)
    ├── computationWindowStartValue (integer)
    ├── computationWindowEndValue (integer)
    ├── minimumDuration (integer)
    └── renewal
        ├── criteriaType (string)
        ├── downgradeTo (enum)
        ├── shouldDowngrade (boolean)
        ├── expressionRelationAIRA (string)
        ├── expressionRelation (string)
        └── conditions
            ├── purchase (string)
            ├── numVisits (string)
            ├── points (string)
            └── tracker[]
                ├── trackerName (string)
                ├── value (string)
                ├── trackerId (integer)
                └── trackerCondition (integer)

Note: The request body is validated in strict mode. Any unknown field is rejected with HTTP 400. The following read-only or program-level fields must not be sent on create or update requests: downgrade, eligibilityCriteriaType, isActive, reminders, downgradeConfirmation, renewalConfirmation, retainPoints, dailyDowngradeEnabled, isDowngradeOnReturnEnabled, isDowngradeOnPartnerProgramExpiryEnabled, schedule, nudges, notificationConfig, and validity.endDate. Sentinel values of -1 (numeric or string) in programId, periodValue, or threshold are also rejected.

Example response

{
  "data": {
    "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

Error & warning codes

Note: Conflict errors (HTTP 409) return the generic error number 999999 with a descriptive message on the wire. The Code column shows the stable symbolic code for these cases.