customer.tier_downgrade - Mage Loyalty Documentation

{
  "event": "customer.tier_downgrade",
  "shop": "my-store",
  "timestamp": "2026-02-18T12:00:00.000Z",
  "data": {
    "shopify_customer_id": "6789012345",
    "email": "jane@example.com",
    "previous_tier": "Gold",
    "new_tier": "Silver",
    "lifetime_points": 800
  }
}

{
  "event": "customer.tier_downgrade",
  "shop": "my-store",
  "timestamp": "2026-02-18T12:00:00.000Z",
  "data": {
    "shopify_customer_id": "6789012345",
    "email": "jane@example.com",
    "previous_tier": "Gold",
    "new_tier": "Silver",
    "lifetime_points": 800,
    "loyalty_mode": "store_credit",
    "currency": "GBP",
    "lifetime_credit": "8.00"
  }
}

Fired when a customer’s lifetime points no longer meet the threshold for their current VIP tier and they are moved to a lower one. This typically happens on a lifetime points recalcuation.

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 downgrade. 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 moved to
`lifetime_points`	integer	The customer’s all-time total earned points

Store-credit shops

On store-credit shops, lifetime_points is a minor currency unit amount, and data carries loyalty_mode (store_credit), currency, and a major-unit decimal-string companion lifetime_credit. Points-mode payloads do not include these fields. See Loyalty modes.

Example payload

{
  "event": "customer.tier_downgrade",
  "shop": "my-store",
  "timestamp": "2026-02-18T12:00:00.000Z",
  "data": {
    "shopify_customer_id": "6789012345",
    "email": "jane@example.com",
    "previous_tier": "Gold",
    "new_tier": "Silver",
    "lifetime_points": 800
  }
}

{
  "event": "customer.tier_downgrade",
  "shop": "my-store",
  "timestamp": "2026-02-18T12:00:00.000Z",
  "data": {
    "shopify_customer_id": "6789012345",
    "email": "jane@example.com",
    "previous_tier": "Gold",
    "new_tier": "Silver",
    "lifetime_points": 800,
    "loyalty_mode": "store_credit",
    "currency": "GBP",
    "lifetime_credit": "8.00"
  }
}

Common use cases

Send a re-engagement email encouraging the customer to earn more points
Update the customer’s segment or tag in your marketing platform
Offer a limited-time bonus points promotion to help them regain their tier
Log tier changes for churn analysis and reporting