Skip to main content
DELETE
Archive a tier
Archives a tier, the lifecycle-end action for the tier API. The key path parameter identifies which tier to archive, scoped to the program in programId. A program route only archives a program-scoped tier; it will not archive an organization-level tier that a program inherits. Archiving is one-way. An archived tier has status set to ARCHIVED and archived_at set to the time of the call, and it cannot be returned to ACTIVE. An archived tier stops all new assignment and evaluation:
  • SET_TIER rule actions targeting the tier are skipped. The event still completes.
  • Automatic qualification and period-end re-evaluation no longer assign the tier.
  • Manual assignment (PUT) and tier updates (PATCH) are rejected with 409 Conflict and code tier_archived.
Existing participant tier state is left untouched and preserved as historical. The tier and its levels remain readable through GET requests. A tier cannot be archived while any ACTIVE or SUSPENDED rule still references its key (in a SET_TIER action or a CEL condition). The request is rejected with 409 Conflict and code tier_referenced_by_rules, and the error details list the referencing rules. Archive or update those rules first; ARCHIVED rules don’t block. Returns the archived tier on success. Archiving an already-archived tier returns 409 Conflict with code tier_archived. An unknown program or tier returns 404 Not Found.
For usage patterns and examples, see the Tiers guide.

Authorizations

X-API-Key
string
header
required

API key passed in the X-API-Key header.

Path Parameters

programId
string<uuid>
required

Program ID

key
string
required

Tier key

Response

Archived tier

A tier definition with its levels, lifecycle configuration, and metadata

archived_at
string<date-time>

When the tier was archived (RFC 3339); absent while the tier is ACTIVE

Example:

"2024-03-01T00:00:00Z"

created_at
string<date-time>

When this tier was created (RFC 3339)

Example:

"2024-01-15T10:30:00Z"

display_name
string

Human-readable name

Example:

"Loyalty Status"

id
string<uuid>

Unique identifier for this tier

Example:

"550e8400-e29b-41d4-a716-446655440000"

key
string

Tier key used in API calls and rule actions

Example:

"status"

levels
object[]

Ordered list of levels within this tier

lifecycle
object

Lifecycle configuration (retention mode, qualification period, downgrade policy, counter rollover)

program_id
string<uuid>

Program this tier belongs to

Example:

"550e8400-e29b-41d4-a716-446655440001"

status
string

Lifecycle status: ACTIVE, or ARCHIVED once the tier has been archived

Example:

"ACTIVE"

updated_at
string<date-time>

When this tier was last modified (RFC 3339)

Example:

"2024-01-15T10:30:00Z"