> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yuko.so/llms.txt
> Use this file to discover all available pages before exploring further.

# VIP Tier Change Object

> How VIP tier changes appear in a customer's activities in the Yuko REST API.

When a customer enters, moves up or down, or keeps a VIP tier, Yuko records it in the customer's activity log. These records are returned by [List customer activities](/developer/api/list-customer-activities) (`GET /public/customers/activities`, requires the `read:activities` scope) as [activities](/activity-object) with `source_type` set to `loyalty_tiers`. To get only tier changes, pass `source_type=loyalty_tiers`.

To read a customer's current tier instead of the history, use [Get customer tier](/developer/api/get-customer-tier).

## Properties

<ResponseField name="id" type="string<uuid>">
  Unique identifier for the tier change activity.
</ResponseField>

<ResponseField name="customer_id" type="string<uuid>">
  Yuko's internal UUID for the customer whose tier changed.
</ResponseField>

<ResponseField name="activity_type" type="enum<string>">
  The kind of tier change. One of `vip_tier_entry` (the customer reached their first tier), `vip_tier_upgrade`, `vip_tier_downgrade`, `vip_tier_retained` (the customer kept their tier at re-evaluation).
</ResponseField>

<ResponseField name="source_type" type="string">
  Always `loyalty_tiers` for tier changes.
</ResponseField>

<ResponseField name="source_id" type="string<uuid>">
  For tier changes, this is the customer's Yuko UUID.
</ResponseField>

<ResponseField name="entry_type" type="null">
  Always `null`; tier changes don't change the points balance.
</ResponseField>

<ResponseField name="points" type="integer">
  Always `0` for tier changes.
</ResponseField>

<ResponseField name="earning_type" type="null">
  Always `null` for tier changes.
</ResponseField>

<ResponseField name="metadata" type="object">
  The tier details of the change.

  <Expandable title="metadata properties">
    <ResponseField name="previous_tier" type="object | null">
      The tier the customer was in before the change. `null` when the customer had no tier (always for `vip_tier_entry`, and for a manual tier assignment to a customer with no tier).

      <Expandable title="previous_tier properties">
        <ResponseField name="uuid" type="string<uuid>">
          The tier's unique identifier.
        </ResponseField>

        <ResponseField name="name" type="string">
          The tier's name. An empty string if the tier has since been deleted.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="current_tier" type="object | null">
      The tier the customer is in after the change. `null` for a `vip_tier_downgrade` where the customer dropped out of all tiers.

      <Expandable title="current_tier properties">
        <ResponseField name="uuid" type="string<uuid>">
          The tier's unique identifier.
        </ResponseField>

        <ResponseField name="name" type="string">
          The tier's name.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created_at" type="string<date-time>">
  When the tier change was recorded (ISO 8601).
</ResponseField>

<ResponseExample>
  ```json The VIP Tier Change object theme={null}
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "customer_id": "63a2c89a-9936-4bc0-9d5f-93db46110b76",
    "activity_type": "vip_tier_upgrade",
    "source_type": "loyalty_tiers",
    "source_id": "63a2c89a-9936-4bc0-9d5f-93db46110b76",
    "entry_type": null,
    "points": 0,
    "earning_type": null,
    "metadata": {
      "previous_tier": {
        "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "Silver"
      },
      "current_tier": {
        "uuid": "7fb39c85-3a3f-4247-8333-2e05a9c8ae28",
        "name": "Gold"
      }
    },
    "created_at": "2025-12-17T12:36:33+00:00"
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.