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

# customer.tier_upgrade

> Fired when a customer is promoted to a higher VIP tier.

Fired when a customer accumulates enough lifetime points to move up to a higher VIP tier. The event includes both the previous and new tier names so you can tailor your response.

## Payload fields

| Field                 | Type           | Description                                                                                                                                                    |
| --------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `shopify_customer_id` | string         | The customer's Shopify customer ID                                                                                                                             |
| `email`               | string \| null | The customer's email address                                                                                                                                   |
| `previous_tier`       | string         | The tier the customer was on before the upgrade. Always a string: a tier name, or the literal string `"None"` if the customer had no prior tier (never `null`) |
| `new_tier`            | string         | The tier the customer has been promoted to                                                                                                                     |
| `lifetime_points`     | integer        | The customer's all-time total earned points                                                                                                                    |

## Example payload

<ResponseExample>
  ```json customer.tier_upgrade theme={null}
  {
    "event": "customer.tier_upgrade",
    "shop": "my-store",
    "timestamp": "2026-02-18T12:00:00.000Z",
    "data": {
      "shopify_customer_id": "6789012345",
      "email": "jane@example.com",
      "previous_tier": "Silver",
      "new_tier": "Gold",
      "lifetime_points": 1200
    }
  }
  ```

  ```json First-ever tier (no prior tier) theme={null}
  {
    "event": "customer.tier_upgrade",
    "shop": "my-store",
    "timestamp": "2026-02-18T12:00:00.000Z",
    "data": {
      "shopify_customer_id": "6789012345",
      "email": "jane@example.com",
      "previous_tier": "None",
      "new_tier": "Silver",
      "lifetime_points": 500
    }
  }
  ```
</ResponseExample>

## Common use cases

* Send a congratulatory email or SMS welcoming the customer to their new tier
* Update the customer's segment or tag in your marketing platform
* Trigger a special one-time reward or gift for reaching the new tier
* Log tier progression data for analytics and reporting